Getting Started with Clarion (Part 1)

From the Windows Start menu, go to the "Clarion 11 PE" menu folder, click on "Help Files" and click to open "Help"

In the help contents, go to the "Getting Started" page as shown here:

Read through the explanation, because all the concepts discussed there are really important. Then proceed to the next screen: "Getting Started Lessons". Read through it and at the end of the screen you will be instructed to run the Clarion IDE:

This is what the IDE should look like (see above).

If you don't see the "Start Page" then click on the "View" menu and select "View Start Page" as shown here.

Clarion is a data-centric application development tool. Businesses rely on data. That means Clarion is optimized to create business programs.
Clarion’s data-centric approach begins with the data dictionary. You create a data dictionary using the Dictionary Editor and import your desired business data. You can then create a working application based on that data with the help of the Application Wizard.

Exercise 1: Create the Dictionary

It all starts with the dictionary. Navigate to the "Dictionaries" section of the "Start Page" and click on "New Dictionary".

The "Save As" dialog box will open. Type In "GSLesson" in the file name field, and go to the "C:\Users\Public\Documents\SoftVelocity\Clarion11\Lessons\GettingStarted" folder before you click "Save"

Clarion keeps all its lessons and examples in the "Public Documents" section of Windows. Once you have clicked "Save", the Dictionary Editor (called "DCT Explorer") will open a window in the IDE. This is where we will create and edit the Clarion dictionary file.

Exercise 2: Import Your Data

Now we will import some pre-defined tables: CUSTOMER.TPS and ORDERS.TPS. Clarion's native TopSpeed database driver keeps each table in a separate file (.TPS), unlike Microsoft Access and most SQL databases, which keep all the tables in a single file. It is also advisable to name every table as a singular item (Customer) not plural (Customers).

Notice how the DCT Explorer has its own toolbar. Click on the "Add Table" button and then select the "Import Tables" menu item. This launches the Table Import Wizard:

Change the "Select Server" to "TopSpeed Files". It's the last item in the list. If you press the "End" button twice it should take you there. If not, use the drop-down arrow and scroll to the bottom of the list.
Next, click on the ellipsis (...) next to the "Select Dictionary" field to get the "Select Database" dialog box.

Click on the ellipsis next to the "Files" field.

Before you import any of the files, please rename "ORDERS.TPS" to "ORDER.TPS" and "STATES.TPS" to "STATE.TPS". Then select "CUSTOMER.TPS" and "ORDER.TPS" (hold the Ctrl key when you click on each file) and click "Open".
Once you have returned to the "Select Database" dialog box there are no other options or settings required. Those are reserved for other database drivers. Click "OK" so the Table Import Wizard can finish its work. It has imported the data definitions of the two files we selected.

That’s the basics for a file import. Of course, there are many other options and techniques that you can use to import data definitions, but we are only getting started.
To review, the dictionary will be used with the application generator to help match and locate the data that we are planning to process.
Your dictionary is auto-saved after the import, so let’s proceed to exercise 3.

Exercise 3: Relate Your Tables

Obviously, we want the "Order" table to contain the pertinent information of the "Customer". This means there must be a relationship between the two tables. In this case, one Customer can have many Orders, making this a "One to Many" relationship. To define this relationship, we must link the tables together in the data dictionary to provide the Application Generator with the information necessary to access the related records.

Click on the "Customer" table in the tables list. The "Quick View" window will display numerous properties of the table. Scroll down to find the "Keys" section.

Click on the "KEYCUSTNUMBER" key and change its properties by selecting "Primary Key", since it is the primary key for this table, and it is always best to state this explicitly. Click on the "Save Table" button (the icon looks like a 3.5" diskette below the word "Quick"). Notice how "Quick View" loses its asterisk when you save.
Scroll down to find the "Relations" section.

Right-click on the "Relations" folder and choose "Add Relationship".

For the "CUSTOMER" table make sure the relationship type is 1:MANY and the primary key is "KEYCUSTOMER". Use the Tab key to move to the next field. Choose the "ORDER" table as the foreign table and "KEYCUSTOMER" as the foreign key. Finally, click on "Map By Name" (because the field names are the same) so they relate correctly. It is a good idea to give linked fields the same name where possible.
In the Referential Integrity Constraints group box, choose "Cascade" from the "On Update" dropdown list. Choose "Restrict" from the "On Delete" dropdown list. The generated source code will automatically maintain referential integrity between the tables. Now that everything is set up, click "OK" to create the relationship.

Exercise 4: Add a Lookup Table

Clarion documentation often confuses tables and files, because with TopSpeed they are much the same. We will now look at "fine tuning" the dictionary in the Dictionary Editor. This will directly affect how our application will be generated in the final exercise.

Highlight the "Customer" table and examine the Columns list. You should notice a "State" column. In the next sequence of steps, we will create a lookup table to allow a user to select from a list of valid state abbreviations. After that, we will "notify" the "State" column that a lookup is active.

Click on the "Tables" section and then select "Add Table".

Fill in the label (Table name) and description as "State" and the prefix should be "STA". Check that the driver is "TopSpeed" and click "OK".

Click on the "Columns" section and then click on the "Add" button in the Quick View toolbar.

The column name is "State" and it is a 2 character string. Click "OK", because the remaining defaults are fine.
This creates a column named "State". This column is the link to the "State" column in the "Customer" table. Using the same column names makes it easier to link the two tables in a relationship. In the generated Clarion code, adding the table’s prefix to column labels (separated by a colon) creates unique names for columns with the same name in separate tables. Therefore, this column will actually be called "STA:State", while the column in the Customer table is called "CUS:State".

The IDE assumes you want to add more than one column, so it automatically presents you with the dialog box for the next column. We will call this column "StateName" and give it a size of 30 characters. Click "OK" when done.
Since we only want two columns in this table, click "Cancel" when the third (empty) dialog box appears.

Notice we now have created two columns. Now we need to create a primary key for the table. Click on the "Keys" section and then on the "Add" button.

Fill in the Key name "KEYSTATE" and make sure it requires unique values and is the Primary Key. Then click on the "Add" button in the form.

Click on the "State" column name and click "Select". You will be asked for another column. Click "Cancel" to close the empty dialog box.
Now click "OK" to save the completed key, followed by "Cancel" to close the empty key dialog.

Now it's time to click on the "Save" button on the main IDE toolbar, to save all your work thus far.

Continue the exercises in "Getting Started with Clarion (Part 2)".

[ Introduction to Clarion 11 ]
[ Installing Clarion 11 on Windows 10 ]