Clarion Community Help

| **Navigation:**  [[welcome to my product .htm|User's Guide and Tutorials]] > The Application >====== Lesson 10 - Procedure Basics ====== | [[lesson 9 exploring the report procedure.htm|{{btn_prev_n.gif|Previous page}}]][[welcome to my product .htm|{{btn_home_n.gif|Return to chapter overview}}]][[lesson 11 global application properties.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

**This lesson explores the fundamental properties common to all procedures.**

__**Setting Procedure Properties**__

After you choose the procedure type, you can define the procedure's properties'these properties include:

·a **description** of the procedure

·the procedure **prototype**

·the **module** containing the generated source code

·whether to **export** the procedure

·whether to **declare** the procedure **globally**

·**parameters** passed to the procedureT

·**return values** from the procedureT

·**INI file settings** used by the procedureT

·**tables** accessed by the procedure

·the **WINDOW** displayed by the procedure, including its size, shape, appearance and functionality

·the **REPORT** generated by the procedure

·**data** items (columns and variables) used by the procedure

·**procedures** called by the procedure

·custom source code **embedded** within the procedure

·**formulas** used by the procedure

·template generated **extensions** to the procedure

These prompts are provided by the Procedure templates, therefore their presence or absence depends on the particular template that generates the procedure.

You need not define every property for every procedure. In many cases, the default property definition is appropriate. When a default property is already established, a special icon appears beside its command button in the Application Tree. For example, the Browse procedure template contains a predefined window; therefore, an icon appears next to the **Window** button for procedures with this template.

{{procdefaults.jpg|ProcDefaults.jpg}}

For the properties you do define, you may use a **Wizard** and you may use the **Procedure Properties** dialog and its subordinate dialogs and Designers to set them. This section is primarily concerned with the **Procedure Properties** dialogs (see [[lesson 2 the power of the application wizard.htm|Lesson 2]] for more information on Procedure Wizards).

__**Application Generator Properties (Prompts)**__

The properties discussed in this section are common to all //Procedure Properties// dialogs because they are managed by the Application Generator. You define these properties by completing the entry boxes and using the command buttons on the //Application Tree//.

__**Template Properties (Prompts)**__

In addition to the Application Generator properties, the //Procedure Properties// dialog displays and manages the template prompts for the templates in the procedure.

__**To set the procedure properties**__

From the Application Tree, select a procedure then press the **Properties** button to access the //Procedure Properties// dialog. Alternatively, DOUBLE-CLICK on the procedure, or RIGHT-CLICK the procedure, then choose **Properties** from the popup menu.

**This opens the ****//Procedure Properties//**** dialog, which displays the following prompts.**

{{procprops.jpg|ProcProps.jpg}}

**Procedure Name**

The **Procedure Name** is displayed here. Press the ellipsis button to change the name if desired. You will be prompted for a New Procedure Name, and the ability to Accept or Discard your changes.

**Template**

The base template type used by this procedure is displayed here. You can change the template type by pressing the ellipsis button to the right. The //Select Procedure Type// dialog is displayed for a new selection if needed.

{{notebox.jpg|NoteBox.jpg}}

Changing procedure template types can result in "orphaned" embed code. Be careful when using this function.

**Description**

A short text description for the procedure, which appears next to the procedure name in the //Application Tree// dialog.

Press the ellipsis (...) button or the ALT + F2 key to edit a longer (up to 1000 characters) description.

**Category**

A category is used to help you group procedures together when the **Category** Tree Mode is active.

{{categoryview.jpg|CategoryView.jpg}}

**Module Name**

Specify which module (.CLW) file contains the source code for the procedure by selecting from the drop-down list. By default, the Application Generator names modules by taking the first five characters of the .APP file name, then adding a three digit number for each module. You may specify your own module names by choosing **Application** {{blttria.jpg|BLTTRIA.jpg}} **Insert Module** from the IDE menu.

**Prototype**

Optionally specify a custom procedure prototype which the Application Generator places in the MAP section. If you specify nothing, the Application Generator provides the correct prototype for the selected procedure template. See the //Procedure Prototyping// in the Language Reference and //Prototyping and Parameter Passing// below for more information. For example:

**(SHORT ID,STRING Name)**

**Declare Globally**

Check this box to generate the procedure's prototype into the PROGRAM's MAP, rather than the MODULE's MAP. This makes the procedure callable from any other procedure, but it also forces a recompile of all program modules whenever you change the prototype.

**Export procedure**

Visible when the Application's Destination Type is set to DLL. Check this box to add the procedure to the application's automatically generated export (.EXP) file, so the procedure can be called by other executables. See //Module Definition Files// in the core help and [[development and deployment strategies.htm|Development and Deployment Strategies]] for more information. This prompt is only available when you specify //Dynamic Link Library (.DLL//) or //Static Link Library (.LIB)// as the **Destination Type** in the //Application Properties// dialog.

__**Procedure Tables**__

**By default, table data (data maintained by your application) are available to any procedure within the entire application; however, you must tell the Application Generator which tables are used by the procedure so it can provide source code for reading (and writing) the tables.**

From the IDE Menu, select **View** {{blttria.jpg|BLTTRIA.jpg}} **Data / Tables Pad**.

or

Press the **F12** Key

**This opens the ****//Data / Tables Pad//**** dialog.**

To add a table to the table schematic, select a control template <;To Do> item, a control template file, or //OTHER TABLES//, and then press the **Add** button. Next, choose a table from the //Select a Table// dialog.

When you select a <;To Do> item for the control template, you add a "primary" table from among all the tables in your data dictionary. When you select an existing control template table, you add a "secondary" or "child" table from a list of related tables only. Clarion's templates //automatically// generate all the code needed to open, read, and close both the primary and any secondary tables. The templates also generate any code needed to update the primary table.

Select //OTHER TABLES// when you want to access a table that is already open and positioned to the appropriate record, or when you want to hand code the table access. The templates automatically generate code to open (if not already open) and close //OTHER TABLES //, but any other processing is up to you.

To delete an item from the table schematic, highlight it and press the **Delete** button.

**Sorting**

To specify the sort sequence of a table, select it in the //Tables// list, then press the **Change** button. Choose a key from the //Change Access Key// dialog.

**Views and Joins**

To specify an "inner join" or a custom join instead of the default "left outer join" for the generated JOIN structure, select the secondary (child) table, then press the **Change** button to open the //Table Relationship// dialog.

**Dictionary**

Choose this to generate a VIEW that reflects the table relationship as defined in the Data Dictionary. For example:

**   VIEW(Customer)**

**    PROJECT(CUS:LastName)**

**    PROJECT(CUS:FirstName)**

**    PROJECT(CUS:ID)**

**    JOIN(PH:CustomerIDKey,CUS:ID) !default JOIN**

**    END**

**   END**

**Custom**

Choose this to enter a custom JOIN expression for the generated VIEW. See **JOIN** in the Language Reference topic for more information. For example:

**   VIEW(Customer)**

**    PROJECT(CUS:LastName)**

**    PROJECT(CUS:FirstName)**

**    PROJECT(CUS:ID)**

**    JOIN(Phone,'PH:CustomerID,CUS:ID') !custom JOIN**

**    END**

**   END**

**Inner**

Check this box so that only those primary table rows with related secondary table rows are retrieved. Inner joins are normally more efficient than outer joins. See **INNER** in the Language Reference for more information. For example:

**   VIEW(Customer)**

**    PROJECT(CUS:LastName)**

**    PROJECT(CUS:FirstName)**

**    PROJECT(CUS:ID)**

**    JOIN(Phone,'PH:CustomerID,CUS:ID'),INNER !custom inner JOIN**

**    END**

**   END**

__**Procedure Windows**__

To access any procedure's window:

CLICK on the procedure, and press the **Window** button in the //Application Tree// dialog.

or

RIGHT-CLICK the procedure in the //Application Tree//, then choose **Window** from the popup menu.

or

In the //Procedure Properties// window, select the //Window// tab control to access the Window Editor and Designer.

The Window Designer lets you visually design the size, shape, menus, controls and functionality for the window in this procedure. See the [[lesson 4 the window formatter.htm|Window Designer]] lesson for details on how to define your window.

In the Window Editor, the **Edit as Text** button allows you to edit the WINDOW or APPLICATION structure at the source code level. Clarion allows you to easily switch back and forth between editing the window graphically, and editing the source code that describes it.

{{tipbox.jpg|TipBox.jpg}}

You may notice some non-language keywords such as #FREEZE, #ORIG, or #SEQ in this source code. Do not remove or change these keywords. The Application Generator uses them to manage source code generation, but does not include them in the generated source. The #LINK keyword ties an input control to its associated PROMPT control and can be safely deleted.

__**Procedure Reports**__

To access any procedure's report:

CLICK on the procedure, and press the **Report** button in the //Application Tree// dialog.

or

RIGHT-CLICK the procedure in the //Application Tree//, then choose **Report** from the popup menu.

or

In the //Procedure Properties// window, select the //Report// tab control to access the Report Editor and Designer.

The Report Designer lets you visually design the size, shape, content, layout, and functionality for the report in this procedure. See the [[lesson 8 the report formatter.htm|Report Designer]] lesson for more information.

{{tipbox.jpg|TipBox.jpg}}

The **Edit as Text** button in the Report Editor lets you edit the source code declaring the REPORT structure. You may notice some non-language keywords such as #LINK or #ORIG in this source code. Do not remove or change these keywords. The Application Generator uses them to manage source code generation, but does not include them in the generated source.

__**Procedure Data**__

Procedures may access several classes of data. These include table or column data, GLOBAL data, MODULE data, and LOCAL data.

LOCAL data are defined in the data section of a procedure, and may only be accessed by the procedure that defines them. MODULE data are defined in the data section of a module. A module is simply a source file that may contain several procedures. Module data may be accessed by any procedures contained in the source file where the module data are defined. GLOBAL data may be accessed by any procedure in the entire application. See the Language Reference section on //Data Declarations and Memory Allocation// for more information.

**Accessing LOCAL Data**

In the Application Tree, select your target procedure.

From the IDE Menu, select **View** {{blttria.jpg|BLTTRIA.jpg}} **Data / Tables Pad**.

or

Press the **F12** Key

**This opens the ****//Data / Tables Pad//**** dialog.**

{{localdata.jpg|LocalData.jpg}}

Local Data is displayed in this dialog. If any local variables already exist, they appear in the list.

To define a new data item, press the **Add **button.

This opens the //Column Properties// dialog. Type in the variable name, choose the variable type, and set any additional attributes, including screen attributes. See [[lesson 3 column properties.htm|The Dictionary Editor'Adding or Modifying Columns]] for more information on this dialog.

**MODULE Data**

Defining Module data is exactly like defining Local data with one exception'you must select a module rather than a procedure in the Application Tree. To define MODULE data (memory variables available to several procedures in a single source file):

1.From the //Application Tree// dialog, select the //Module// **Tree Mode** view.

2.Highlight a module (folder), not a procedure.

3.In the Data / Tables Pad, highlight Module Data and press the **Add** button.

4.This opens the //Column Properties// dialog. This is the same dialog used to set column properties in the data dictionary.

**Unlike LOCAL data, MODULE data is not automatically cleared when a procedure closes. You, the developer, must take care to initialize the MODULE data as required by your various procedures.**

__**Calls to Other Procedures**__

Press the **Calls** tab in the //Procedures Properties// dialog to identify procedures called within embedded source code.

Procedures may call other procedures. Procedure calls specified with template prompts are automatically added to the Application Tree; however, the Application Generator cannot "see" procedures called from embedded source code.

Identifying these embedded procedure calls is important to project management and to source code generation. When you use the **Calls** tab to identify procedures called within embedded source code, the Application Generator can properly display the procedures within the Application Tree hierarchy, and the Application Generator can generate the appropriate local MAP structure for the source module.

To identify procedures called from embedded source, press the **Calls** tab to open the //Called Procedures// dialog. This dialog lists all procedures in the application. Mark the called procedure by clicking on its name.

**Next:** [[lesson 11 global application properties.htm|Lesson 11 - Global Application Properties]]