git.sur5r.net Git - bacula/docs/blob - docs/manuals/de/old/concepts/vars.tex

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