program call command

Syntax

program call s <keyword ...>

Process the specified data file(s).

Note

As with all program commands, use of the command word program is optional; program call and call are both valid.

If the file name s is supplied without an extension, then the code will look for the string both with the “.dat” extension and with the code specific extension (“.f3dat” for FLAC3D).

A file that is called with a relative rather than an explicit path will be searched for first in the folder containing the data file currently being processed, then in the current directory.[1] [this is something that should be its own topic *somewhere*, and once it is this will be changed to a link to that topic.]

Any series of input instructions can be placed in a data file. Additional files may, in turn, be called from a data file; there is no limit to the levels of nesting. However, files must not call each other recursively (e.g., file “ABC” calls file “DEF,” which then calls file “ABC”).

The program pause and program return commands can be used to interrupt data file processing; the program continue command can be given at the command prompt in the console to resume processing. See those commands for details, particularly with regard to the call stack. Pressing Shift + Esc terminates input from data files and returns program control to the command prompt, no matter to what level calls have been nested.

call s <keyword ...>

Using two or more call keywords allows multiple files to be called on one line. The called files will processed in the order that they appear in the command, from last to first. Multiple-file calls each start with the program call command word — the multiple-file call is, in effect, a string of individual calls. The keywords available for each are the same as allowed for the program call command.

line i

If the line keyword is specified, then the data file starts reading at the line i. If the line is past the end of the file, the file returns instantly, as if you had processed to the end of the file. This cannot be used with the label option.

label sl

If the label keyword is specified, then the data file starts reading at the label sl. To place a label in a data file, use the syntax “:label” (where the colon must be the first character in the line). The data file will be read starting with the first line after the label. Lines containing a label are ignored (as if the colon were a comment). If the label is not found in the data file, an error is indicated. This cannot be used with the line option.

suppress

If the optional keyword suppress is added once in a command, then the command processor will not echo the contents of the called file(s) to the screen while it processes the file(s) (and any files called by it/them).

Usage Example

The example file “call_use.dat” below shows a number of possible program call commands. It uses two data files, “table_w1.dat” and “table_w2.dat” — which are shown below for reference. In reviewing the example, it is important to observe that “table_w2.dat” calls “table_w1.dat” in its fourth line.

;call_use.dat

;basic calls:
program call 'table_w2.dat'                                 ;(a)    
;call 'table_w2'                                     (b) 
;call 'c:\projects\flac3d\examples\table_w2'         (c)
;call 'c:\\projects/flac3d//examples\table_w2.dat'   (d)   
;call 'folder\table_w2.dat'             -- ERROR!!   (e)

;using line keyword
new
program call 'table_w1' call 'table_w2' line 5                ;(f)
new
program call 'table_w2' line 5                              ;(g)

;using suppress keyword
new
program call 'table_w1' suppress call 'table_w2' line 5       ;(h)

The section of the file marked “basic calls” shows five uses of program call. The first four are valid ways to call the file “table_w2.dat”, assuming the current directory is the path “c:\projects\flac3d\examples” as shown in (c) and (d). The fifth use (e) produces an error because the supplied relative path is incorrect. Case (c) illustrates that file paths may be demarcated using any of “", “/”, “\”, or “//” interchangeably.

The next group is marked ;using line keyword. Usage (f) achieves the same result as the basic calls in cases (a-d). First “table_w2.dat” is processed (starting at line 5, after its own call to “table_w1.dat” in line 4), then “table1.dat”. Note the variance in the processing order means that the “world” tables are created first, therefore they have lower indices and are listed first when the final program list table command is processed in “table_w2.dat”. Case (g) uses the line keyword to bypass the call in “table_w2.dat” to “table_w1.dat”, so in this case only the tables that spell out “world” are created.

The last usage (h) illustrates the suppress keyword. Its call procedure is the same as usage (f), however, the console only shows the results of the program list commands with this usage.

;table_w1.dat

table letter_h 2,12 2,8 2,10, 4,10 4,12 4,8
table letter_e 7,12 5,12 5,10 7,10 5,10 5,8 7,8
table letter_l1 8,12 8,8 10,8
table letter_l2 11,12 11,8 13,8
table letter_o1 15,12 14,11 14,9 15,8 16,8 17,9 17,11 16,12 15,12

list table

;table_w2.dat

new
program call 'table_w1'

table letter_w 2,7 3,3 4,7 5,3 6,7
table letter_o2 8,7 7,6 7,4 8,3 9,3 10,4 10,6 9,7 8,7
table letter_r 11,3 11,7 12,7 13,6 12,5 11,5 13,3
table letter_l3 14,7 14,3 16,3
table letter_d 17,7 17,3 19,3 20,4 20,6 19,7 17,7

list table

plot create
plot clear
plot item create chart-table table '1' table '2' table '3' table '4' ...
                             table '5' table '6' table '7' table '8' ...
                             table '9' 10 ...
                             xaxis log off ...
                             minimum 0 maximum 22 label "X-Axis" inside on ...
                             yaxis log off ...
                             minimum 0 maximum 14 label "Y-Axis" inside on

Endnotes

[1]

The current directory is defined as: the folder containing the current project file, unless a project file is not in use, in which case it is the folder containing the program, unless the program is in a folder secured by Windows (such as the “program files” folder, which is common), in which case it is the folder where the application data was copied, unless the application data has not been copied, in which case it is the base folder for the profile of the current user on the computer (the location of this folder differs among the versions of Windows available) Using the program directory command will override any of the above to the location specified in the command. Use list directory to determine the current directory.