Skip to main content
Previous sectionNext section

Working with Routines and Include Files

A routine is the unit of execution in a Caché server; all application logic running on a Caché server is executed by invoking routines and entry points in routines. Routines are executed in a virtual machine that is built into the Caché server environment. Routines are portable to all platforms supported by Caché and automatically shareable across a Caché environment.

Include files (.inc files) contain macro definitions (or other include files) and can be included in .mac routines or class definitions. For more information on macros see the section “Using Macros” in Using Caché ObjectScript.

Routine Editor

Using the Routine Editor, you can directly create and edit the source for routines or include files. When class definitions are compiled, the class compiler generates a set of routines containing the implementation for the class. If you check to Keep Generated Source Code (on the Tools > Options dialog, Compiler, General Flags tab), you can view and edit this generated source code as well.

The Routine Editor uses syntax coloring and indicates syntax errors with a wavy red line.

Routine Source Formats

There are several kinds of routine source formats (files) in Caché. The Routine Editor provides syntax coloring and checking for each of these formats. The formats include:

  • BAS - Basic source files with a .bas extension

  • MAC - Macro source files with a .mac extension, processed by the Caché macro preprocessor to resolve macros, embedded SQL statements, and embedded HTML, which results in an .int file.

  • INT - Intermediate source files, which are compiled directly into executable Caché object (OBJ) code.

  • INC - Include files. Not routines per se, .inc files contain macro definitions that can be included by .mac routines.

By default, when you create a new ObjectScript routine, it is saved as a .mac routine. Select File > Save As to save this as a different type of routine (changing the extension from .mac to .inc for example).

Select View > View Other to display .int code corresponding to a given .mac file and vice versa.

Creating a New Routine or Include File

To create a new routine or include file, select File > New. A dialog displays the templates you can choose from. For a routine, you can choose either an ObjectScript routine or a Caché Basic routine. For an include file, select ObjectScript. This opens a new Routine Editor window with a default name, such as Untitled. You can save this with a different name with File > Save As.

Opening an Existing Routine or Include File

Open an existing routine with File > Open . In the drop-down list of Files of Type , select the file extension of interest (such as .mac, .int, or All Files) and select a routine.

When you attempt to open a previously saved routine or include file, the Open dialog uses wildcard matching (using the * (asterisk to match any number of any character) and ? (question mark to match a single character) to display a list of available routines or include files. The routine type - BAS, MAC, INT, or INC - is used as a file extension for purposes of wildcard matching.

Routine Template File

When you create a new routine in Studio, it opens a new Routine Editor window. If a Routine template file exists, it is copied into the new file. To create a Routine template file, create a file with the contents that you want in your template. Save the file asDefault.mac in the same directory as the Studio executable file (CStudio.exe).

Saving, Compiling, and Deleting Routines

You can save routines to the database using the File > Save or File > Save As. By default, saving a routine does not cause it to be compiled. You can change this behavior by checking Compile Routine on Save available from Tools > Options dialog, Compiler, Behavior.

To compile a routine directly, use Build > Compile (which also causes it to be saved).

To delete a routine, in a Workspace window, highlight the routine and select Edit > Delete. The routine and any generated files are deleted.

Save Automatically Backs Up Routines, Include, and CSP Files

When you save an existing routine (or include or CSP file), Studio automatically creates a backup file. It automatically saves up to five backup files, naming them with a ;# (semicolon number) suffix. For example, a file named setup.MAC which has been saved six times has five backup files named:

setup.MAC;1
setup.MAC;2
setup.MAC;3
setup.MAC;4
setup.MAC;5
Copy code to clipboard

Specifically, files with the following extensions are automatically backed up: .BAS, .INC, .INT, .MAC, .OBJ, .MVB, .MVI, .CSP

To see what backup files exist, use a semi-colon in the search field of the File > Open option. You can use the following syntax examples:

*.*;* displays all backup files in this folder

*.mac;* displays all backup files with a .MAC extension

setup.*;* lists all backup files named setup

These backup files can also be found using this syntax through the Management Portal on the System Explorer > Routines page using the Routines and include files box.