Testing your setup

Once you have DCAL installed and have selected an editor you will want to check your installation to be sure that it is working correctly.

Open up your editor and type in the following code:

 

For now, don't worry about what this code means. We will look at that in the next lesson.

Save this text file as Test.dcs and make a note of where you save it. A good practice is to create a subdirectory in either the DCAL directory or another directory of your choice to store all your source code. When you get into more involved macros you will want to create separate subdirectories for each macros source code.

Let's assume you put the Test.dcs source code in the directory C:\DataCAD 12\DCAL\Source\Test

Next, open up a Command Prompt.

Note:  In Windows XP you can launch the command prompt by going to either Start, All Programs, Accessories, Command Prompt or Start, Run, cmd.

At the DOS prompt, switch to the directory where you saved your Test.dcs source code.

In our example this is C:\DataCAD 12\DCAL\Source\Test

Once you are at the correct location type the following:

C:\DataCAD 12\DCAL\Source\Test>dcc1 test

If all goes well you will see something like:

Next, type the following:

C:\DataCAD 12\DCAL\Source\Test>dcc2 test

If all goes well you will see something like:



The important part here is the last line 'No errors detected.' If you see anything else your code contains errors. We will get to that issue in a minute but what if you don't even see this text?

If you receive an error such as:

'dcc1' is not recognized as an internal or external command, operable program or batch file.

Then you have not correctly set your paths and the operating system is unable to locate the compiler. Go back and check your settings to make sure the compilers (DCC1.EXE and DCC2.EXE) are in a directory that appears in your path. For more information review the setup section of this lesson. The message may vary based on your using different flavors of windows. If you receive any other system errors, consult your operating system help for more info.
|
OK, so your compiler ran but you saw something like this:

The first thing to notice here is the last line 'Compilation Errors.' This is the compiler telling you that there are errors in your source code. To generate this error we intentionally modified the code. Here is the line we changed:

wrterr (Hello World!');

Notice that the Hello World! string is not enclosed in single quotes ( ' ) as in the original listing. Your error may vary but we are interested in what the compiler tells us more than the nature of the error.

The process of compiling your source, reviewing the compiler messages and adjusting your source code is called debugging. It is critical that you are comfortable debugging your code. Your macros will almost never compile on the first try. It is a fundamental law of programming that you will make mistakes. Fortunately, the compiler will catch your mistakes and try to explain them to you. Think of the compiler as your translator AND in the debugging process as your proofreader.

Studying the compiler output will help us find the error:

The first line of this piece of code tells you which module the compiler is working on. In our example there is only one module (Test.dcs) so naturally the only one the compiler bothers with is Test.

The next line is the first error line. The first number on this line is the line in your source code where this error occurs. The line under this line has a ( ^ ) symbol that will attempt to point out the specific location on the line above where the error occurs. Notice that all we did was remove one single quote from the code to trigger 5 separate error messages. Now you can begin to see how a simple omission or error can lead to troublesome compiler errors.

The compiler will try to find the errors and point them out to you, but it is not perfect. Look at the compiler errors making a note of the lines where the error occurs, then return to your source code. Often the compiler will point out an error on one line when the problem lies on another. For this reason you will need to review your source code rather than the code pieces shown in the compiler errors. As you can see in the example above there is nothing wrong with line 5 but the compiler flags it since the error on line 4 is making problems for the rest of the code. Often the compiler will not even show the line where the actual error occurs. Always work with the source code. Relying on the lines of code the compiler flags to spot the errors will not always work and you will waste a lot of time looking. Always try to start at the first line it points out as incorrect (in our case line 4) then work up or down until you spot the error.

The ( ^ ) character will try to point out the problem but may not be able to narrow it down. In our case since we have confused the compiler, it is unable to point out exactly where the error occurs and it simply points to the beginning of the line. Since the compiler will read through your code from top to bottom it will often flag the line below the error. We will cover debugging in more detail in future lessons. For now use the hints the compiler gives to spot the error and fix it. After fixing the error recompile the source. Repeat this step as often as needed.

Once you have gotten the code to compile correctly you will need to link it. If your macro was composed of more than one module you would want to join all the code together to form one macro. In our example there is only one module (Test.dcs).

If you were to look in the directory where you are compiling your code you should see a file called Test.dco. This file is an object file and was generated by the compiler. The object file is a compiled file but must be linked with other optional modules before it can be understood by DataCAD.

To link our sample macro type:

C:\DataCAD 12\DCAL\Source\Test>dcl test;

You should see an output such as:

Since there are no errors and this is such a small program you will not see much more of interest. If your output looks like this:

You did not put the semi-colon at the end of the line. In this case the linker is waiting for you to tell it the name of the next module to link. If you are done (as you are in our example) simply enter the semi-colon and press enter. We will cover the linker more in future lessons.

A directory listing in our source directory should now show something like:

Directory of C:\DataCAD 12\DCAL\Source\Test

01/01/2001 12:01 AM 4,096 Test.dco
01/01/2001 12:02 AM 93 Test.dcs
01/01/2001 12:03 AM 4,096 Test.dcx

By now you should be getting familiar with these file types. The Test.dco file is the compiled unlinked object file. The Test.dcs file is your original source code. The Test.dcx is the compiled macro. This last file is the one that DataCAD can run as a macro.

Now you can copy this file to your macro directory (normally C:\DataCAD 12\Macros) or you can change directories while in the toolbox menu to point to your source directory in order to run this macro.

Open up DataCAD and go into the Toolbox menu. Depending on whether you copied the Test.dcx file to your default macro directory or not you may need to change the path to locate your new macro. Select this macro and DataCAD will execute it.

If you look toward the bottom of the screen you should see the message "Hello World!." You will not be able to do anything in DataCAD until the macro is done running since we put in a pause statement in order for you to see your message. Your macro should show your message for 5 seconds then exit.

Congratulations, you have just written your first DCAL macro! Now of course this macro doesn't do much but the concepts you learned here will carry over into every macro you write from this point forward.

Before proceeding on to the next lesson play with the code for this macro. Try changing the message or the pause delay. Save the file with different names, etc. It is critical that you understand these basic steps before you try to move on to more advanced lessons.

If you wish more challenging exercises look in your SAMPLES directory for sample macros that ship with your DCAL kit. Try to compile some of these macros. Start with the very simple ARROW sample and see if you can get it to run. See if you can debug any errors you receive. Don't worry if you can't do much with many of the samples yet. We will cover more advanced compilation and linking issues in later lessons.

END of Lesson 1 -- The Basics

< Previous   |   Continue >

Table of Contents