Working with Routines and Include Files
A routine is the unit of execution in an InterSystems IRIS® server; all application logic running on an InterSystems IRIS server is executed by invoking routines and entry points in routines. Routines are executed in a virtual machine that is built into the InterSystems IRIS server environment. Routines are portable to all platforms supported by InterSystems IRIS and automatically shareable across an InterSystems IRIS 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 ObjectScript.
Using the Routine Editor, you can directly create and edit the source for routines or include files. The Routine Editor uses syntax coloring and indicates syntax errors with a wavy red line.
When class definitions are compiled, the class compiler generates a set of routines containing the implementation for the class. If you want to view and edit this generated source code, you must specify that the compiler should keep a copy of the generated code. To keep a copy of the generated code:
Select Tools > Options.
Navigate to Compiler > Flags & Optimization in the left-hand pane.
Select Keep Generated Source Code.
Routine Source Formats
There are several kinds of routine source formats (files) in InterSystems IRIS. The Routine Editor provides syntax coloring and checking for each of these formats. The formats include:
MAC - Macro source files with a .mac extension, processed by the InterSystems IRIS 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 InterSystems IRIS 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 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 as Default.mac in the same directory as the Studio executable file (CStudio.exe).
Saving, Compiling, and Deleting Routines
You can save routines to the database by selecting File > Save or File > Save As. By default, saving a routine does not cause it to be compiled. To change this behavior so the routine is compiled every time it is saved:
Select Tools > Options.
Navigate to Compiler > Behavior in the left-hand pane.
Select Compile Routine on Save.
To compile a routine directly, select 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 and Include Files
When you save an existing routine (or include 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
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.*;*||Displays all backup files named setup.|
You can use this syntax to find backup files when you are opening routine and include files from the Management Portal. To open backup files from the Management Portal:
Select Management Portal from the InterSystems IRIS launcher.
Select System Explorer > Routines.
Enter the backup file syntax in the Routines and Include Files search box in the left-hand pane.