| gclib 386 Communications API for Galil controllers and PLCs |

All Data Structures Files Functions Variables Typedefs Macros Pages
preprocessor.md
1 # Program Preprocessor {#preprocessor}
2
3 gclib's program downloader provides a preprocessor for DMC code. The
4 preprocessor modifies the program prior to download providing a number of
5 language features not present in pure DMC code.
6
7 The preprocessor is invoked in the following two ways.
8
9 -# With both GProgramDownload() and GProgramDownloadFile() via the
10 `preprocessor` argument. Downloading code with null for the preprocessor
11 argument uses defaults.
12 -# From within DMC code via in-band preprocessor directives.
13
14 ##The `preprocessor` argument
15
16 GProgramDownload() and GProgramDownloadFile() can be called with a string passed
17 to the `preprocessor` argument. The program will be modified based on this
18 string prior to download. See *Preprocessor Options* below for syntax.
19
20 ##In-band Operation
21
22 DMC code can be written with special markup to signal the preprocessor to take
23 actions prior to download.
24
25 For example, the following progam will invoke the in-band preprocessor. The
26 specifics are described below.
27
28 \code
29 ## Author: Zaphod Beeblebrox
30 ## Project: Total Perspective Vortex
31 //the above 4 hashmarks enable the preprocessor
32 ##option "--min 4" //use a minimum of level four compression
33 REM REM-style comments are supported at all times
34 PRA=1000
35 BGA
36 AMA
37 EN
38 \endcode
39
40 ###The `REM` Comment
41
42 Lines beginning with the string `REM` are removed prior to download. `REM`
43 comments are always removed regardless of whether the other preprocessor options
44 are enabled or not.
45
46 ###Double Hash
47
48 Most preprocessor statements begin with a double hash, `##`. When proceeded by
49 a space, the double hash acts like a `REM` comment.
50
51 When proceeded by a character other than space, `##` is interpreted as a
52 preprocessor directive. For example, see `##option` below.
53
54 \note Double hash lines are removed from the program only when the
55 preprocessor is enabled with a quad hash.
56
57 ###Quad Hash to enable
58
59 In order to enable the in-band preprocessor, the first two lines of the DMC
60 program must start with a double hash. This syntax of using two lines with
61 double hashmarks is called a *quad hash*.
62
63 Content may follow the hash marks. For example, a good code writing style is to
64 use double hash comments as a comment header showing author, project name, etc.
65
66 ###C-style comments
67
68 With the preprocessor enabled, C-style comments may be used with the `//` prefix.
69 These comments are very similar to `REM` comments. The primary advantage of
70 using this comment over `REM` is that `//` comments may occur anywhere in a
71 line. This is helpful for line comments such as the following.
72
73 \code
74 SIA= 1,25,25,0<4>1 //SSI 25 bits total, all single turn, no status
75 \endcode
76
77 Strings containing `//` are not interpreted as comments.
78
79 \note `//` comments are removed from the program only when the preprocessor
80 is enabled with a quad hash.
81
82 ### Preprocessor Directives
83
84 \note Directives are only followed when the preprocessor is enabled with a
85 quad hash.
86
87 #### `##option`
88
89 The `option` directive allows passing switches directly to the preprocessor with
90 the same syntax as the `preprocessor` argument in GProgramDownload() and
91 GProgramDownloadFile(). The syntax of the `option` directive is the following.
92
93 \code
94 ##option "{preprocessor switches}"
95 \endcode
96
97 For example, the following line will disable compression in the program.
98
99 \code
100 ##option "--max 0"
101 \endcode
102
103 See *Preprocessor Options* below for other switches.
104
105 #### `##include`
106
107 The `include` directive provides a way to include the contents of another DMC
108 file in the current program. This is useful for reusing code such as automatic
109 subroutines, homing operations, or controller initilization routines.
110
111 The contents of the file will be inserted in place of the `include` line. The
112 insertion occurs prior to code compression.
113
114 The syntax of the `include` directive is the following.
115
116 \code
117 ##include "{filename}"
118 \endcode
119
120 For example,
121
122 \code
123 ##include "c:\galil\initialize.dmc"
124 ##include "homing.dmc"
125 \endcode
126
127 To write more portable code, use the `include` directive with just the
128 file name, no absolute path. The path to find the file on the system is set
129 depending on usage.
130 1. In the <a href="http://galil.com/downloads/software/gdk">Galil Design Kit</a>,
131 specify the include path in GDK's
132 <a href="http://galil.com/sw/pub/all/doc/gdk/html/settings.html">settings</a>
133 with the `--search` or `-I` switch as defined below.
134 2. When downloading code via GProgramDownload() or GProgramDownloadFile(), use
135 the `--search` or `-I` switch in the `preprocessor` argument.
136 3. Finally, if the file is in the executable search path, the file
137 will be found. However, one of the previous two options is more reliable.
138
139 ### In-band Support
140
141 In addition to gclib,
142 <a href="http://galil.com/downloads/software/gdk">Galil Design Kit</a> supports
143 the preprocessor. Proper preprocessor usage will be colored in the Editor's
144 syntax highlighter. If the quad hash is not present, preprocessor syntax will be
145 colored differently to indicate inproper usage.
146
147 The preprocessor is not supported in software prior to GDK/gclib. DMC code
148 downloads using the in-band preprocessor in prior generation software (e.g.
149 GalilTools or SmartTerm) will fail.
150
151
152 ##Preprocessor Options
153
154 * Lines beginning with `REM` are always removed from the text prior to download.
155 * A `\` character on a line other than a preprocessor line will result in an error.
156 * Trailing semicolons are removed.
157
158 ###Compression, `--min`, `--max`
159
160 * Defaults
161 * Use maximum compression, only if needed, to fit the program.
162 * `--max` *n* provides preprocessing up to and including level *n*.
163 Only the necessary preprocessing will be performed up to level *n*.
164 * `--min` *n* will preprocess at least up to and including *n*. *n* defined as with `--max` above.
165
166 ####Compression Levels, *n*
167
168 * Level 0 (mandatory)
169 -# Comment blank lines with '.
170 -# Remove white space (space/tab) in front of # (label declarations).
171 -# Remove white space after commands.
172 -# Line ends changed to carriage return.
173 -# Replace leading tabs with double space.
174 -# Replace non-leading tabs with single space.
175 * Level 1
176 -# Remove unnecessary spaces. Strings, comments ('), and no-ops (NO) are not changed.
177 * Level 2
178 -# Remove comments (') but not no-ops (NO).
179 * Level 3
180 -# Remove no-ops (NO) too.
181 * Level 4
182 -# Break apart compound lines that are too long.
183 -# Compact lines of code to maximize line usage.
184 -# Use backtick to support long lines where applicable.
185
186 ###Code insertion, `--insert`
187 * Defaults
188 * Code download begins at line zero and overwrites anything present.
189 * `--insert` *arg* invokes the insert option of the firmware's *DL* command. *arg* can be one of the following.
190 -# Line number, e.g. `100`. Program insertion will occur on the line after the line specified.
191 -# Variable name, e.g. `myvar`. Program insertion will occur on the line after the line equal to the value of the variable.
192 -# Label callout, e.g. `#mylabel`. Program insertion will occur on the line after the label.
193 -# A lone `#` symbol. Program insertion will occur on the line after the last line in the program buffer.
194 * Compression directives `--max` and `--min` are followed.
195 * All original code following the point of insertion is cleared.
196 * Not all products support the `--insert` operation, e.g. DMC-30010.
197 See the <a href="http://www.galil.com/download/comref/comall/index.html#download.html">DL</a> command for support.
198
199
200 \warning It is the user's responsibility to ensure that the code
201 will fit in the inserted location. The preprocessor will not check line numbers
202 when executing the `--insert` option.
203
204 ### Include Search Paths, `--search`, `-I`
205 * The `##include` directive will attempt to open its string argument
206 directly. The open will succeed if the argument is the absolute path, or if
207 the argument is in the executable's path, e.g. in the same directory.
208 * `--search` *path* allows the user to specify a directory or directories
209 to be searched for the `include` file in case the first open fails.
210 * For historical reasons, `-I` is shorthand for `--search`.
211 * Multiple directories may be specified with multiple `-I` directives.
212 * For in-band code, `-I` must be specified prior to the include.
213 * A common use for `-I` is to specify only the filename in the DMC source code
214 and use the `preprocessor` argument during download to specify the path to the
215 files. This allows the files to be moved without a change to source code.
216 * Search order
217 -# The `##include` argument is checked first as-is.
218 -# Then each `-I` argument in the `preprocessor` argument, in the order specified.
219 -# Then `##option` directives in the DMC file, in the order specified.
220
221 ####In-band Example
222
223 \code
224 ##option "-I /code/dmc/homing"
225 ##option "-I /code/dmc"
226 ##include "auto.dmc"
227 //executable's directory will be checked
228 //then c:\code\dmc\homing
229 //then c:\code\dmc
230 \endcode
231
232 ### Macro Definition, `--define`, `-D`
233 * `--define` provides a way to substitute one token for another. This
234 is useful for writing code that is generic until program download. Wherever
235 the token is found in code, it is substituted by the replacement. The replacement
236 occurs right before code compression.
237 * `-D` is shorthand for `--define`.
238 * The token should consist of a starting backslash character, followed by upper
239 or lower case alphanumeric characters, underscores, and an ending backslash.
240 * The common usage for this feature is to write code with a token, and then call the
241 program download with the `-D` switch.
242
243 In this example, an axis is defined at download time. Specifying the
244 following for the preprocessor argument
245
246 \code
247 --define \ax\:A
248 \endcode
249
250 would cause the following code
251
252 \code
253 SH\ax\
254 JG\ax\=1000
255 BG\ax\
256 \endcode
257
258 to be downloaded as
259
260 \code
261 SHA
262 JGA=1000
263 BGA
264 \endcode
265
266 This causes the *A* axis to be addressed.
267
268
269 ###GDK Support
270 * See the `preprocessor` text box in the *Editor* settings page to set the
271 desired preprocessor setting for developing in GDK's editor.