Custom controls are also known as OLE controls and ActiveX controls. They have also been called OCXs because they often have the .ocx file name extension. In C/SIDE, the term custom control is used, for example, in the Tools menu. When you want to use a control, you define a variable (global or local) of type OCX and reference the control as the subtype of this variable.
Prerequisites
To complete this walkthrough, you will need:
-
Microsoft Dynamics NAV installed with a developer license.
-
The CRONUS International Ltd. demo data company installed.
About This Walkthrough
In this walkthrough, you will build a simple form that uses the C/FRONT OCX to connect to a server, open a database, open a company, and count the number of records that exist in a table that you specify. This form will have access to the functions and properties supported by the C/FRONT OCX.
Installing and Registering the
Control
A control must be physically installed on the computer before you can use it. But a control must also be registered with the operating system before it can be used.
If the control has been installed physically by copying it to the hard disk, but has not yet been registered, follow this procedure to register the control from within C/SIDE.
To install and register the control
-
Copy the control from the distribution media to the hard disk. The C/FRONT folder contains a readme.txt file with more information.
-
Click Tools, and then click Custom Controls to open the Custom Controls window.
-
Click the Control button, and select Browse to open a standard Windows dialog that you use to locate the OCX that you want to register.
-
When you have located the control, select it, and then click Open.
-
The control is now registered. You receive a confirmation message after the registration is complete. Click OK to return to the Custom Controls window and the control you have just added appears in the list.
Using the Control in C/AL
The control must be declared as either a global or a local variable before you can access its methods and properties from C/AL. After you have done this, you can use the methods and set the properties, and you can see the methods and the properties in the Symbol Menu.
Declaring the Control as a Variable
Next you need to declare the control as a variable.
To declare the control as a variable
-
In Object Designer, create a new blank form that is not based on any table.
-
Click View, and then click C/AL Globals to open the C/AL Globals window.
-
In the Name field enter cfront, and in the DataType field select OCX.
-
In the Subtype field, click the AssistButton to open the Custom Control List window.
-
Locate the control that you just installed on the list, select it, and then click OK.
-
Declare the following additional variables.
Name Data type Length TableNo
Integer
MyCompany
Text
50
MyDatabase
Text
50
MyServerName
Text
50
Driver
Option
-
Select the Driver variable and open the Properties window.
-
In the Value field of the OptionString property enter NDBCS,NDBCN.
Adding Text Constants
The next step is to create the text constants that this form will use.
To add text constants
-
In the C/AL Globals window, click the Text Constants tab.
-
In the Name field, enter text001, and in the ConstValue field enter CRONUS International Ltd. Go to the next line.
-
In the Name field, enter text002,and in the ConstValue field enter The "%2" table contains %1 records.
-
Save and close the C/AL Globals window.
Designing the Form
The first step in designing the form is to add the fields that you want the form to contain.
To design the form
-
In Form Designer, open Toolbox, and then add four text boxes and two option buttons to the form.
-
Add labels to the text boxes and the first option button, Name them Server, Database, Company, Table Number, and Server Type, respectively.
-
Select the server text box, click View, and then click Properties to open the Properties window.
-
In the Value field for the SourceExpr property, click the AssistButton to open the C/AL Symbol Menu window.
-
Select MyServerName, ensure that the Paste Arguments check box is not selected, and and then click OK.The text box on the form should now contain the following text.
<=MyServerName> -
Repeat this procedure for the other three text boxes adding the MyDatabase, MyCompany, and TableNo variables to the corresponding text box.
-
Select the first option button and in the Properties window enter the following values.
Property Value Caption
SQL
SourceExpr
Driver
OptionValue
NDBCS
-
Select the second option button and in the Properties window enter the following values.
Property Value Caption
Dynamics NAV
SourceExpr
Driver
OptionValue
NDBCN
Adding Code to the Form
Now that you have created the basic form you need to add the code that will make it work. In this example, you will place most of the code in the OnPush trigger of a command button at the bottom of the form.
To add code to the form
-
Open the form in Form Designer and add a command button to the form.
-
Select the command button, open the Properties window, and then enter Connect as the Name and the Caption.
-
Select the command button, click View, and then click C/AL Code to open the C/AL Editor.
-
In the
OnPushtrigger, enter the following lines of code.
Copy CodeCLEAR(cfront); cfront.ConnectServerAndOpenDatabase(FORMAT(Driver),MyServerName,'tcp ',MyDatabase,0,FALSE,TRUE,'',''); cfront.OpenCompany(MyCompany); IF cfront.OpenTable(TableNo,TableNo) THEN MESSAGE(text002,cfront.RecCount(TableNo),cfront.TableName(TableNo)); cfront.CloseTable(TableNo); MESSAGE('Table closed'); cfront.CloseCompany(); MESSAGE('Company Closed'); cfront.DisconnectServer(); MESSAGE('Disconnect')
 Note |
|---|
|
To enter the C/FRONT functions, open the C/AL Symbol Menu window and select the method or property that you want to use. Ensure that there is a check mark in the Paste Arguments check box and click OK. The C/FRONT function is then pasted into the C/AL Editor, so all you have to do is adjust the parameters. |
This code uses the C/FRONT functions to connect to a server and open a database that you specify in the form. It uses the TCPIP protocol. It then opens the company that you specify in the MyCompany field. Next, it opens the table whose number you specify and counts the number of records that the table contains. It then displays a message showing how many records the table contains. When you click OK in the message window it closes the table, the company, and disconnects from the server.
| Note |
|---|
|
This form only uses Windows Authentication to connect to the
server. This is specified in the 7th parameter of the
|
Handling Exceptions
You cannot use the exception-handling mechanisms that are described in, for example, Using COM Technologies in C/SIDE. The samples in the C/OCX Samples show you how to handle exceptions but only for controls that you create yourself. The C/OCX samples are installed as part of the SDK/C/FRONT installation.
The control has two properties that are used for exception handling: Error and ErrorCode. Every time a method is called, the Error property (a Boolean) is used to flag errors; it is set to true if an error occurred and false if no error occurred. An error is defined by the methods in the control. In the control in the C/OCX Samples, one error is that an arithmetic operation caused numeric overflow, another error is that an illegal (out of range) value was passed as a parameter.
When an error occurs and Error is set to true, the ErrorCode is set to a numeric code that can be used by the caller to decide what action to take (for example to display an appropriate message to the user).
Calls to methods in the control can then be wrapped like this in C/AL.
IF (Fin.Error) THEN
// Do error handling.
ErrorHandlerFunction(Fin.ErrorCode)
ELSE
// Continue processing.
See Also
© 2010 Microsoft Corporation. All rights reserved.