gclib  311
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  ## Author: Zaphod Beeblebrox
29  ## Project: Total Perspective Vortex
30  //the above 4 hashmarks enable the preprocessor
31  ##option "--min 4" //use a minimum of level four compression
32  REM REM-style comments are supported at all times
33  PRA=1000
34  BGA
35  AMA
36  EN
37 
38 ###The `REM` Comment
39 
40 Lines beginning with the string `REM` are removed prior to download. `REM`
41 comments are always removed regardless of whether the other preprocessor options
42 are enabled or not.
43 
44 ###Double Hash
45 
46 Most preprocessor statements begin with a double hash, `##`. When proceeded by
47 a space, the double hash acts like a `REM` comment.
48 
49 When proceeded by a character other than space, `##` is interpreted as a
50 preprocessor directive. For example, see `##option` below.
51 
52 \note Double hash lines are removed from the program only when the
53 preprocessor is enabled with a quad hash.
54 
55 ###Quad Hash to enable
56 
57 In order to enable the in-band preprocessor, the first two lines of the DMC
58 program must start with a double hash. This syntax of using two lines with
59 double hashmarks is called a *quad hash*.
60 
61 Content may follow the hash marks. For example, a good code writing style is to
62 use double hash comments as a comment header showing author, project name, etc.
63 
64 ###C-style comments
65 
66 With the preprocessor enabled, C-style comments may be used with the `//` prefix.
67 These comments are very similar to `REM` comments. The primary advantage of
68 using this comment over `REM` is that `//` comments may occur anywhere in a
69 line. This is helpful for line comments such as the following.
70 
71  SIA= 1,25,25,0<4>1 //SSI 25 bits total, all single turn, no status
72 
73 Strings containing `//` are not interpreted as comments.
74 
75 \note `//` comments are removed from the program only when the preprocessor
76  is enabled with a quad hash.
77 
78 ### Preprocessor Directives
79 
80 \note Directives are only followed when the preprocessor is enabled with a
81 quad hash.
82 
83 #### `##option`
84 
85 The `option` directive allows passing switches directly to the preprocessor with
86 the same syntax as the `preprocessor` argument in GProgramDownload() and
87 GProgramDownloadFile(). The syntax of the `option` directive is the following.
88 
89  ##option "{preprocessor switches}"
90 
91 For example, the following line will disable compression in the program.
92 
93  ##option "--max 0"
94 
95 See *Preprocessor Options* below for other switches.
96 
97 #### `##include`
98 
99 The `include` directive provides a way to include the contents of another DMC
100 file in the current program. This is useful for reusing code such as automatic
101 subroutines, homing operations, or controller initilization routines.
102 
103 The contents of the file will be inserted in place of the `include` line. The
104 insertion occurs prior to code compression.
105 
106 The syntax of the `include` directive is the following.
107 
108  ##include "{path to file}"
109 
110 For example,
111 
112  ##include "c:\galil\initialize.dmc"
113 
114 
115 ### In-band Support
116 
117 In addition to gclib,
118 <a href="http://galil.com/downloads/software/gdk">Galil Design Kit</a> supports
119 the preprocessor. Proper preprocessor usage will be colored in the Editor's
120 syntax highlighter. If the quad hash is not present, preprocessor syntax will be
121 colored differently to indicate inproper usage.
122 
123 The preprocessor is not supported in software prior to GDK/gclib. DMC code
124 downloads using the in-band preprocessor in prior generation software (e.g.
125 GalilTools or SmartTerm) will fail.
126 
127 
128 ##Preprocessor Options
129 
130  * Lines beginning with `REM` are always removed from the text prior to download.
131  * A `\` character on a line other than a preprocessor line will result in an error.
132  * Trailing semicolons are removed.
133 
134 ##Compression
135 
136  * Defaults
137  * Use maximum compression, only if needed, to fit the program.
138  * `--max` *n* provides preprocessing up to and including level *n*.
139  Only the necessary preprocessing will be performed up to level *n*.
140  * `--min` *n* will preprocess at least up to and including *n*. *n* defined as with `--max` above.
141 
142 ###Compression Levels, *n*
143 
144  * Level 0 (mandatory)
145  -# Comment blank lines with '.
146  -# Remove white space (space/tab) in front of # (label declarations).
147  -# Remove white space after commands.
148  -# Line ends changed to carriage return.
149  -# Replace leading tabs with double space.
150  -# Replace non-leading tabs with single space.
151  * Level 1
152  -# Remove unnecessary spaces. Strings, comments ('), and no-ops (NO) are not changed.
153  * Level 2
154  -# Remove comments (') but not no-ops (NO).
155  * Level 3
156  -# Remove no-ops (NO) too.
157  * Level 4
158  -# Break apart compound lines that are too long.
159  -# Compact lines of code to maximize line usage.
160  -# Use backtick to support long lines where applicable.
161 
162 ##Code insertion
163  * Defaults
164  * Code download begins at line zero and overwrites anything present.
165  * `--insert` *arg* invokes the insert option of the firmware's *DL* command. *arg* can be one of the following.
166  -# Line number, e.g. `100`. Program insertion will occur on the line after the line specified.
167  -# Variable name, e.g. `myvar`. Program insertion will occur on the line after the line equal to the value of the variable.
168  -# Label callout, e.g. `#mylabel`. Program insertion will occur on the line after the label.
169  -# A lone `#` symbol. Program insertion will occur on the line after the last line in the program buffer.
170  * Compression directives `--max` and `--min` are followed.
171  * All original code following the point of insertion is cleared.
172  * Not all products support the `--insert` operation, e.g. DMC-30010.
173  See the <a href="http://www.galil.com/download/comref/comall/index.html#download.html">DL</a> command for support.
174 
175 
176 \warning It is the user's responsibility to ensure that the code
177 will fit in the inserted location. The preprocessor will not check line numbers
178 when executing the `--insert` option.