Tutorial > Creating PV-WAVE Applications > Compiling
  

Compiling
This section describes some of the issues you will need to consider when compiling:
* Compiling Procedures and Functions
* System Limits
* Using the ..LOCALS Compiler Directive
Compiling Procedures and Functions
There are three ways procedures and functions can be compiled:
* Using .RUN with a Filename
* Compiling Automatically
* Compiling with Interactive Mode
Using .RUN with a Filename
Procedures and functions can be compiled using the executive command .RUN. The format of this command is:
.RUN file1, file2, ..., file11
From one to eleven files, each containing one or more program units, can be compiled with the .RUN command. Consult the PV‑WAVE Reference for more information on the .RUN command.
Compiling Automatically
Generally, however, you create a procedure or function file with a filename that matches the actual procedure or function name. When a program unit is compiled, PV-WAVE saves the results, which are in the PATH of the compiled code in PV-WAVE’s memory. This eliminates the need to recompile each time the program unit is called.. The procedure or function automatically compiles when first called. For example, a function named CUBE which calculates the cube of a number has the file name cube.pro. The file looks like this:
FUNCTION CUBE, NUMBER
RETURN, NUMBER ^ 3
END
When the function is initially used within a PV‑WAVE session the file is compiled. A compilation message displays on the screen. For example, using the function for the first time at the WAVE> prompt results in:
WAVE> z = cube(4) & print, z
% Compiled module: CUBE
64
If you change the source file of a routine that is compiled and saved in memory, then you have to explicitly recompile it with .RUN or .RNEW.
Compiling with Interactive Mode
You can enter the procedure or function text directly at the keyboard using .RUN. Rather than executing statements immediately after they are entered, PV‑WAVE compiles the program unit as a whole.
Procedure and function definition statements cannot be entered in single statement mode but must be prefaced by either .RUN or .RNEW.
The first non-empty line the compiler reads determines the type of the program unit: procedure, function, or main program. If the first non-empty line is not a procedure or function definition, the program unit is assumed to be a main program.
The name of the procedure or function is given by the identifier following the keyword Pro or Function. If a program unit with the same name is already compiled, it is replaced by the newer program unit.
Note Regarding Functions
User-defined functions must be compiled using the .RUN command before the first reference to the function is made. There only exception is:
*As discussed previously in "Compiling Automatically", if the filename is the same as the function name and is located in the current working directory or in !Path, the file, and every procedure and function in the file automatically compiles.
Otherwise the function must be compiled using .RUN because the compiler is unable to distinguish between a reference to a subscripted variable and a call to a presently undefined user function with the same name. For example, in the statement:
A = XYZ(5)
it is impossible for PV-WAVE to tell if XYZ is an array or a function by context alone.
Always compile, or arrange in the .pro file, the lowest-level (those that call no other functions) first, then higher-level functions, and finally procedures. PV‑WAVE searches the current directory and then the !Path for function definitions when encountering references that may either be a function call or a subscripted variable.
System Limits
When a program is compiled (using .RUN, for example) internal instruction codes are stored in the code area, and symbols for variables, common blocks, and keywords are strored in the data area. If these areas become full, the compile is halted, and you will see one of the following messages:
Program code area full.
Program data area full.
Methods of handling these errors are discussed in the following sections.
Program Code Area Full
This indicates that the code area (a block of memory allocated for use by the compiler to store instruction codes) has been exceeded. As a result, the compile cannot be completed. The method used to correct this condition depends on the type of program you are compiling.
If You are Compiling a Procedure or Function
There are two solutions:
*Break the procedure or function into smaller procedures or functions.
*Use the .SIZE executive command to increase the original size of the code area. The .SIZE command is described in the PV‑WAVE Reference.
If You are Compiling Main Programs
If you use .RUN or .RNEW to compile a file that contains statements that are not inside a function or procedure, and you receive the Program code area full message, you have these options:
*Use the .SIZE executive command to increase the original size of the code area. The .SIZE command is described in the PV‑WAVE Reference.
*Place the statements to execute at the $MAIN$ level—those not contained in a procedure or function—into a file that does not contain procedure or function definitions, then execute the program as a command file using the @ command. For example:
@filename
*The @ command compiles and executes the commands in the file one at a time, which does not require much code area space.
Program Data Area Full
This indicates that the data area (a block of memory allocated for use by the compiler to store symbolic names of variables and common blocks) has been exceeded. As a result, the compile cannot be completed. The method used to correct this condition depends on the type of program you are compiling.
If You are Compiling a Procedure or Function
There are three solutions:
*Break the procedure or function onto smaller procedures or functions.
*Use the .SIZE executive command to increase the original size of the data area. The .SIZE command is described in the PV‑WAVE Reference.
*Use the .LOCALS executive command to increase the original size of the data area. The .LOCALS command is described in the PV‑WAVE Reference.
If You are Using the EXECUTE Function in a Program
The EXECUTE function uses a string containing a PV‑WAVE command as its argument. The command passed to EXECUTE is not compiled until EXECUTE itself is executed. At that time, you may see the Program data area full message if the data area is already full and EXECUTE tries to create a new variable or common block.
If this occurs, you have the following options:
*If the program is a main program, then use .SIZE or .LOCALS to increase the size of the data area.
*If the program is a function or procedure, then it is necessary to use the ..LOCALS compiler directive in the function or procedure. The ..LOCALS compiler directive creates additional data area space at runtime.
 
note
In general, if you use EXECUTE to create variables or common blocks in a function or procedure, then it is likely that you will need to use ..LOCALS. This is because the data area is compressed immediately after compiling to accommodate only the symbols that are known at compile time. Thus, if EXECUTE is used to create variables or common blocks, there may not be space for any new symbols to be created. The ..LOCALS command is discussed in the next section.
Using the ..LOCALS Compiler Directive
The syntax of the ..LOCALS compiler directive is:
..LOCALS local_vars  common_symbols
This command is useful when you want to place the EXECUTE function inside a procedure or function. EXECUTE takes a string parameter containing a PV‑WAVE command. This command argument is compiled and executed at runtime, allowing the possibility for command options to be specified by the user. Because the data area is compressed after compiling, there may not be enough room for additional local variables and common block symbols created by EXECUTE. The ..LOCALS command provides a method of allocating extra space for these additional items.
The ..LOCALS compiler directive is similar to the .LOCALS executive command, except for the following:
*..LOCALS is only used inside procedures and functions.
*Its arguments specify the number of additional local variables and common block symbols that will be needed at “interpreter” time (when the already-compiled instructions are interpreted).
*It is used in conjunction with the EXECUTE function, which can create new local variables and common block symbols at runtime.

Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.