Methods

version 2003 (Modified)

In order to make the commands, operators, and other parts of the language work, you put them in methods. There are several kinds of methods: Object methods, Form methods, Table methods (Triggers), Project methods, and Database methods. This section describes features common to all types of methods.

A method is composed of statements; each statement consists of one line in the method. A statement performs an action, and may be simple or complex. Although a statement is always one line, that one line can be as long as needed (up to 32,000 characters, which is probably enough for most tasks).

For example, the following line is a statement that will add a new record to the [People] table:

   ADD RECORD([People])

A method also contains tests and loops that control the flow of the execution. For a detailed discussion about the control flow programming structures, see the section Control Flow.

Note: The maximum size of a method is limited to 2 GB of text or 32 000 lines of command. Beyond these limits, a warning message appears, indicating that the extra lines will not be displayed.

There are five types of methods in 4th Dimension:

• Object methods: An object method is a property of an object. It is usually a short method associated with an active form object. Object methods generally "manage" the object while the form is displayed or printed. You do not call an object method—4D calls it automatically when an event involves the object to which the object method is attached.

• Form methods: A form method is a property of a form. You can use a form method to manage data and objects, but it is generally simpler and more efficient to use an object method for these purposes. You do not call a form method—4D calls it automatically when an event involves the form to which the form method is attached.

For more information about Object methods and Form methods, see the 4th Dimension Design Reference Manual as well as the section Form event.

• Table methods (Triggers): A Trigger is a property of a table. You do not call a Trigger. Triggers are automatically called by the 4D database engine each time that you manipulate the records of a table (Add, Delete, Modify and Load). Triggers are methods that can prevent "illegal" operations with the records of your database. For example, in an invoicing system, you can prevent anyone from adding an invoice without specifying the customer to whom the invoice is billed. Triggers are a very powerful tool to restrict operations on a table, as well as to prevent accidental data loss or tampering. You can write very simple triggers, and then make them more and more sophisticated.

For detailed information about Triggers, see the section Triggers.

• Project methods: Unlike object methods, form methods, and triggers, which are all associated with a particular object, form, or table, project methods are available for use throughout your database. Project methods are reusable, and available for use by any other method. If you need to repeat a task, you do not have to write identical methods for each case. You can call project methods wherever you need them—from other project methods or from object or form methods. When you call a project method, it acts as if you had written the method at the location where you called it. Project methods called from other methods are often referred to as "subroutines." A project method that returns a result can also be called a function.

There is one other way to use project methods—associating them with menu commands. When you associate a project method with a menu command, the method is executed when the menu command is chosen. You can think of the menu command as calling the project method.

For detailed information about Project methods, see the section Project Methods.

• Database methods: In the same way that object and form methods are called when events occur in a form, there are methods associated with the database that are called when a working session event occurs. These are the database methods. For example, each time you open a database, you may want to initialize some variables that will be used during the whole working session. To do so, you use the On Startup Database Method, automatically executed by 4D when you open the database.

For more information about Database Methods, see the section Database Methods.

You can skip these compatibility notes if you work with new databases created with version 6 of 4th Dimension.

1. Version 6 introduces many new object and form events (such as On Double Clicked, On Getting Focus, and so on) that replace the execution cycles from the previous versions. If you have converted a version 3 database to version 6, your forms have been converted in order to preserve the "expected behavior" of your forms and objects. If you want to take advantage of the new events for forms and objects created with a previous version of 4D, you must enable the new events in the Property List window for the forms and the objects.

2. Table methods, also called triggers, are a new type of method introduced in version 6. In previous versions of 4th Dimension, table methods (called file procedures) were executed by 4D only when a form for a table was used for data entry, display, or printing. They were rarely used. Note that triggers execute at a much lower level that the old file procedures. No matter what you do to a record via user actions (like data entry) or programmatically (like a call to SAVE RECORD), the trigger of a table will be called by 4D. Triggers are truly quite different from the old file procedures. If you have converted a version 3 database to version 6, and if you want to take advantage of the new Trigger capability, you must deselect the Use V3.x.x File Procedure Scheme property in the Preferences dialog box (shown in this section).

3. Database methods are a new type of method introduced in version 6. In previous versions of 4th Dimension, there was only one method (procedure) that 4D automatically executed when you opened a database. This procedure had to be called STARTUP (US English INTL version) or DEBUT (French version) in order to be invoked. If you have converted a version 3 database to version 6, and if you want to take advantage of the new On Startup Database Method capability, you must deselect the Use V3.x.x Startup Method Scheme property in the Preferences dialog box (shown in this section). This property only affects the STARTUP/On Startup Database Method alternative. If you do not deselect this property and add, for instance, an On Exit Database Method, this latter will be called by 4D.

All methods are fundamentally the same—they start at the first line and work their way through each statement until they reach the last line (i.e., they execute sequentially). Here is an example project method:

   QUERY ([People])   ` Display the Query editor
   If (OK=1)   ` The user clicked OK, not cancel
      If (Records in selection([People])=0)   ` If no record was found…
         ADD RECORD([People])   ` Let the user add a new record
      End if
   End if  ` The end

Each line in the example is a statement or line of code. Anything that you write using the language is loosely referred to as code. Code is executed or run; this means that 4th Dimension performs the task specified by the code.

We will examine the first line in detail and then move on more quickly:

   QUERY([People]) ` Display the Query editor

The first element in the line, QUERY, is a command. A command is part of the 4th Dimension language—it performs a task. In this case, QUERY displays the Query editor. This is similar to choosing Query from the Records menu in the User environment.

The second element in the line, specified between parantheses, is an argument to the QUERY command. An argument (or parameter) is data required by a command in order to complete its task. In this case, [People] is the name of a table. Table names are always specified inside square brackets ([…]). In our example, the People table is an argument to the QUERY command. A command can accept several parameters.

The third element is a comment at the end of the line. A comment tells you (and anyone else who might read your code) what is happening in the code. It is indicated by the reverse apostrophe (`). Anything (on the line) following the comment mark will be ignored when the code is run. A comment can be put on a line by itself, or you can put comments to the right of the code, as in the example. Use comments generously throughout your code; this makes it easier for you and others to read and understand the code.

Note: A comment can be up to 32 000 characters long.

The next line of the method checks to see if any records were found:

   If (Records in selection([People]) = 0) ` If no record was found…

The If statement is a control-of-flow statement—a statement that controls the step-by-step execution of your method. The If statement performs a test, and if the statement is true, execution continues with the subsequent lines. Records in selection is a function—a command that returns a value. Here, Records in selection returns the number of records in the current selection for the table passed as argument.

Note: Notice that only the first letter of the function name is capitalized. This is the naming convention for 4th Dimension functions.

You should already know what the current selection is—it is the group of records you are working on at any given time. If the number of records is equal to 0 (in other words, if no records were found), then the following line is executed:

   ADD RECORD([People]) ` Let the user add a new record

The ADD RECORD command displays a form so that the user can add a new record. 4th Dimension formats your code automatically; notice that this line is indented to show you that it is dependent on the control-of-flow statement (If).

   End if  ` The end

The End if statement concludes the If statement's section of control. Whenever there is a control-of-flow statement, you need to have a corresponding statement telling the language where the control stops.

Be sure you feel comfortable with the concepts in this section. If they are all new, you may want to review them until they are clear to you.

To learn more about:

• Object methods and Form methods, see the section Form event.

• Triggers, see the section Triggers.

• Project methods, see the section Project Methods.

• Database methods, see the section Database Methods.

Arrays, Constants, Control Flow, Data Types, Database Methods, Identifiers, Operators, Pointers, Triggers, Variables.