4 \section*{Variable Expansion}
5 \label{_ChapterStart50}
6 \index[general]{Variable Expansion }
7 \index[general]{Expansion!Variable }
8 \addcontentsline{toc}{section}{Variable Expansion}
10 Please note that as of version 1.37, the Variable Expansion
11 is deprecated and replaced by Python scripting (not yet
14 Variable expansion is somewhat similar to Unix shell variable expansion.
15 Currently (version 1.31), it is used only in format labels, but in the future,
16 it will most likely be used in more places.
18 \subsection*{General Functionality}
19 \index[general]{Functionality!General }
20 \index[general]{General Functionality }
21 \addcontentsline{toc}{subsection}{General Functionality}
23 This is basically a string expansion capability that permits referencing
24 variables, indexing arrays, conditional replacement of variables, case
25 conversion, substring selection, regular expression matching and replacement,
26 character class replacement, padding strings, repeated expansion in a user
27 controlled loop, support of arithmetic expressions in the loop start, step and
28 end conditions, and recursive expansion.
30 When using variable expansion characters in a Volume Label Format record, the
31 format should always be enclosed in double quotes ({\bf "}).
33 For example, {\bf \$\{HOME\}} will be replaced by your home directory as
34 defined in the environment. If you have defined the variable {\bf xxx} to be
35 {\bf Test}, then the reference {\bf \$\{xxx:p/7/Y/r\}} will right pad the
36 contents of {\bf xxx} to a length of seven characters filling with the
37 character {\bf Y} giving {\bf YYYTest}.
39 \subsection*{Bacula Variables}
40 \index[general]{Bacula Variables }
41 \index[general]{Variables!Bacula }
42 \addcontentsline{toc}{subsection}{Bacula Variables}
44 Within Bacula, there are three main classes of variables with some minor
45 variations within the classes. The classes are:
50 \index[dir]{Counters }
51 Counters are defined by the {\bf Counter} resources in the Director's conf
52 file. The counter can either be a temporary counter that lasts for the
53 duration of Bacula's execution, or it can be a variable that is stored in
54 the catalog, and thus retains its value from one Bacula execution to another.
55 Counter variables may be incremented by postfixing a plus sign ({\bf +} after
58 \item [Internal Variables]
59 \index[dir]{Internal Variables }
60 Internal variables are read-only, and may be related to the current job (i.e.
61 Job name), or maybe special variables such as the date and time. The
62 following variables are available:
65 \item [Year] -- the full year
66 \item [Month] -- the current month 1-12
67 \item [Day] -- the day of the month 1-31
68 \item [Hour] -- the hour 0-24
69 \item [Minute] -- the current minute 0-59
70 \item [Second] -- the current second 0-59
71 \item [WeekDay] -- the current day of the week 0-6 with 0 being Sunday
72 \item [Job] -- the job name
73 \item [Dir] -- the Director's name
74 \item [Level] -- the Job Level
75 \item [Type] -- the Job type
76 \item [JobId] -- the JobId
77 \item [JobName] -- the unique job name composed of Job and date
78 \item [Storage] -- the Storage daemon's name
79 \item [Client] -- the Client's name
80 \item [NumVols] -- the current number of Volumes in the Pool
81 \item [Pool] -- the Pool name
82 \item [Catalog] -- the Catalog name
83 \item [MediaType] -- the Media Type
86 \item [Environment Variables]
87 \index[dir]{Environment Variables }
88 Environment variables are read-only, and must be defined in the environment
89 prior to executing Bacula. Environment variables may be either scalar or an
90 array, where the elements of the array are referenced by subscripting the
91 variable name (e.g. {\bf \$\{Months[3]\}}). Environment variable arrays are
92 defined by separating the elements with a vertical bar ({\bf |}), thus {\bf
93 set Months="Jan|Feb|Mar|Apr|..."} defines an environment variable named
94 {\bf Month} that will be treated as an array, and the reference {\bf
95 \$\{Months[3]\}} will yield {\bf Mar}. The elements of the array can have
99 \subsection*{Full Syntax}
100 \index[general]{Syntax!Full }
101 \index[general]{Full Syntax }
102 \addcontentsline{toc}{subsection}{Full Syntax}
104 Since the syntax is quite extensive, below, you will find the pseudo BNF. The
105 special characters have the following meaning:
110 ( ) grouping if the parens are not quoted
111 | separates alternatives
112 '/' literal / (or any other character)
113 CAPS a character or character sequence
114 * preceding item can be repeated zero or more times
115 ? preceding item can appear zero or one time
116 + preceding item must appear one or more times
120 And the pseudo BNF describing the syntax is:
126 | INDEX_OPEN input INDEX_CLOSE (loop_limits)?
128 variable ::= DELIM_INIT (name|expression)
129 name ::= (NAME_CHARS)+
130 expression ::= DELIM_OPEN
132 (INDEX_OPEN num_exp INDEX_CLOSE)?
135 command ::= '-' (TEXT_EXP|variable)+
136 | '+' (TEXT_EXP|variable)+
137 | 'o' NUMBER ('-'|',') (NUMBER)?
139 | '*' (TEXT_EXP|variable)+
140 | 's' '/' (TEXT_PATTERN)+
141 '/' (variable|TEXT_SUBST)*
142 '/' ('m'|'g'|'i'|'t')*
143 | 'y' '/' (variable|TEXT_SUBST)+
144 '/' (variable|TEXT_SUBST)*
147 '/' (variable|TEXT_SUBST)*
149 | '%' (name|variable)+
150 ('(' (TEXT_ARGS)? ')')?
154 | operand ('+'|'-'|'*'|'/'|'%') num_exp
155 operand ::= ('+'|'-')? NUMBER
159 loop_limits ::= DELIM_OPEN
160 (num_exp)? ',' (num_exp)? (',' (num_exp)?)?
162 NUMBER ::= ('0'|...|'9')+
163 TEXT_PATTERN::= (^('/'))+
164 TEXT_SUBST ::= (^(DELIM_INIT|'/'))+
165 TEXT_ARGS ::= (^(DELIM_INIT|')'))+
166 TEXT_EXP ::= (^(DELIM_INIT|DELIM_CLOSE|':'|'+'))+
167 TEXT ::= (^(DELIM_INIT|INDEX_OPEN|INDEX_CLOSE))+
174 NAME_CHARS ::= 'a'|...|'z'|'A'|...|'Z'|'0'|...|'9'
178 \subsection*{Semantics}
179 \index[general]{Semantics }
180 \addcontentsline{toc}{subsection}{Semantics}
182 The items listed in {\bf command} above, which always follow a colon ({\bf :})
183 have the following meanings:
187 - perform substitution if variable is empty
188 + perform substitution if variable is not empty
189 o cut out substring of the variable value
190 # length of the variable value
191 * substitute empty string if the variable value is not empty,
192 otherwise substitute the trailing parameter
193 s regular expression search and replace. The trailing
194 options are: m = multiline, i = case insensitive,
195 g = global, t = plain text (no regexp)
196 y transpose characters from class A to class B
197 p pad variable to l = left, r = right or c = center,
199 % special function call (none implemented)
200 l lower case the variable value
201 u upper case the variable value
205 The {\bf loop\_limits} are start, step, and end values.
207 A counter variable name followed immediately by a plus ({\bf +}) will cause
208 the counter to be incremented by one.
210 \subsection*{Examples}
211 \index[general]{Examples }
212 \addcontentsline{toc}{subsection}{Examples}
214 To create an ISO date:
218 DLT-${Year}-${Month:p/2/0/r}-${Day:p/2/0/r}
222 on 20 June 2003 would give {\bf DLT-2003-06-20}
224 If you set the environment variable {\bf mon} to
228 January|February|March|April|May|...
229 File-${mon[${Month}]}/${Day}/${Year}
233 on the first of March would give {\bf File-March/1/2003 }