Methods

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:

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 4D:

• 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 4D Design Reference Manual as well as the chapter Form Events.

• 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 and Modify). 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 Project Methods.

• 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 chapter Database Methods.

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:

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 4D performs the task specified by the code.

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

The first element in the line, QUERY, is a command. A command is part of the 4D 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 Design 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:

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 4D 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:

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

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 description of the Form event command as well as the 4D Design Reference manual.
• Triggers, see the section Triggers.
• Project methods, see the section Project Methods.
• Database methods, see the section Database Methods.