git.sur5r.net Git - bacula/docs/blob - docs/manual-fr/vars.tex

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