Lesson 10 - Procedure Basics

Top  Previous  Next

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.

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 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.

 

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.

 

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.

 

 

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  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 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  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 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.

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 Report Designer lesson for more information.

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  Data / Tables Pad.

or

Press the F12 Key

This opens the Data / Tables Pad dialog.

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 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