Project

General

Profile

Table files » History » Version 1

Marc Mengel, 07/05/2016 12:00 PM
auto-upload

1 1 Marc Mengel
2 1 Marc Mengel
| [[upsv4TOC| !{width:84px;height:23px}images/navtoc.gif(TOC)!  ]] | [[functions| !{width:81px;height:23px}images/navprev.gif(PREV)!  ]] | [[extrascripts| !{width:81px;height:23px}images/navnext.gif(NEXT)!  ]] |
3 1 Marc Mengel
4 1 Marc Mengel
5 1 Marc Mengel
|.  !{width:60px;height:60px}images/CDlogo.gif(Fermilab CD logo)!  |\4. Complete Guide and Reference Manual for UPS and UPD|
6 1 Marc Mengel
7 1 Marc Mengel
8 1 Marc Mengel
h3. Chapter Contents
9 1 Marc Mengel
10 1 Marc Mengel
11 1 Marc Mengel
p<>. [[table_files#8463|Chapter 36: Table Files]] 
12 1 Marc Mengel
   [[table_files#36855|36.1 About Table Files]] 
13 1 Marc Mengel
   [[table_files#62347|36.2 When Do You Need to Provide a Table File?]] 
14 1 Marc Mengel
   [[table_files#62806|36.3 Recommendations for Creating Table Files]] 
15 1 Marc Mengel
   [[table_files#62435|36.4 Table File Structure and Contents]] 
16 1 Marc Mengel
     [[table_files#62436|36.4.1 Basic Structure]] 
17 1 Marc Mengel
     [[table_files#34894|36.4.2 Grouping Information]] 
18 1 Marc Mengel
     [[table_files#34504|36.4.3 The Order of Elements]] 
19 1 Marc Mengel
   [[table_files#72721|36.5 Product Dependencies]] 
20 1 Marc Mengel
     [[table_files#72804|36.5.1 Defining Dependencies]] 
21 1 Marc Mengel
     [[table_files#72764|36.5.2 Product Dependency Conflicts]] 
22 1 Marc Mengel
   [[table_files#36685|36.6 Keywords that can be Used in Table Files]] 
23 1 Marc Mengel
   [[table_files#73264|36.7 Table File Examples]] 
24 1 Marc Mengel
     [[table_files#62652|36.7.1 Example Illustrating Use of FLAVOR=ANY]] 
25 1 Marc Mengel
     [[table_files#62378|36.7.2 Example Showing Grouping]] 
26 1 Marc Mengel
     [[table_files#38896|36.7.3 Example with User-Defined Keywords]] 
27 1 Marc Mengel
     [[table_files#64661|36.7.4 Examples Illustrating ExeActionOpt Function]] 
28 1 Marc Mengel
     [[table_files#72433|36.7.5 Examples Illustrating Failure Return Codes]] 
29 1 Marc Mengel
30 1 Marc Mengel
31 1 Marc Mengel
h1.  %(#8463)&nbsp;% Chapter 36: Table Files
32 1 Marc Mengel
33 1 Marc Mengel
34 1 Marc Mengel
p<>. %(#33873)&nbsp;% This chapter describes table files. Table files contain product-specific, installation-independent information. Most, but not all, products require a table file. %{font-weight: bold;color: #000000}UPS% product developers are responsible for providing the table files associated with their products.
35 1 Marc Mengel
36 1 Marc Mengel
37 1 Marc Mengel
h2.  %(#36855)&nbsp;% 36.1 About Table Files
38 1 Marc Mengel
39 1 Marc Mengel
40 1 Marc Mengel
p<>. %(#62559)&nbsp;% Table files are created and maintained by product developers. Table files contain the non-system-specific and non-shell-specific information that %{font-weight: bold;color: #000000}UPS% uses for installing, initializing, and otherwise operating on product instances. For a given product, usually a single table file suffices for several instances, especially of a single version. Sometimes each instance has a separate table file. Table file names are arbitrary; we present recommendations in section [[table_files#62806|36.3 %{font-weight: normal;color: #000000}Recommendations for Creating Table Files% ]] .
41 1 Marc Mengel
42 1 Marc Mengel
p<>. %(#62561)&nbsp;% Typically, when a %{font-weight: bold;color: #000000}UPS% command is issued, %{font-weight: bold;color: #000000}UPS% finds the table location from the command line or the version file (see section [[versionfiles#35235|29.4 %{font-weight: normal;color: #000000}Determination of ups Directory and Table File Locations% ]] ). The command completes its internal processes, and then within the table file, it proceeds to:
43 1 Marc Mengel
44 1 Marc Mengel
45 1 Marc Mengel
# locate the stanza that matches the specified product instance
46 1 Marc Mengel
# find an ACTION keyword value that corresponds to the command, if any (see [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] )
47 1 Marc Mengel
# execute the functions listed underneath the corresponding ACTION keyword, if any (see [[functions#73292|Chapter 35: %{font-weight: normal;color: #000000}Functions used in Actions% ]] ), or
48 1 Marc Mengel
# reverse the functions listed underneath the ACTION corresponding to the "uncommand" (see section [[actions#62754|34.2.2 %{font-weight: normal;color: #000000}"Uncommands" as Actions% ]] )
49 1 Marc Mengel
50 1 Marc Mengel
51 1 Marc Mengel
h2.  %(#62347)&nbsp;% 36.2 When Do You Need to Provide a Table File?
52 1 Marc Mengel
53 1 Marc Mengel
54 1 Marc Mengel
p<>. %(#36604)&nbsp;% Not all products require a table file. In particular, if %{font-weight: normal;color: #000000}no% processing besides the internals and defaults needs to be done for %{font-weight: normal;color: #000000}any%  %{font-weight: bold;color: #000000}UPS% command run on a particular product, and if its %{font-family: monospace}ups% directory and documentation reside in the default areas, then the product doesn't need a table file. However, for products that do need a table file (most), at least a rudimentary table file must be in place before any instance is declared to a target %{font-weight: bold;color: #000000}UPS% database. If it's not added right away, users may see incorrect behavior before it is there.
55 1 Marc Mengel
56 1 Marc Mengel
57 1 Marc Mengel
h2.  %(#62806)&nbsp;% 36.3 Recommendations for Creating Table Files
58 1 Marc Mengel
59 1 Marc Mengel
60 1 Marc Mengel
* Although table files can have any file name, we recommend that they be named as %{font-family: monospace}<product>.table% (e.g., %{font-family: monospace}emacs.table% ) or %{font-family: monospace}<version>.table% (e.g., %{font-family: monospace}v19_34b.table% ) for easy identification. If a table file is unique to a particular version of the product (which is likely because versions of product dependencies often change along with the version of the main product) then the name should be %{font-family: monospace}<product>_<version>.table% (e.g., %{font-family: monospace}emacs_v19_34b.table% ).
61 1 Marc Mengel
* Table files should not source any %{font-family: monospace}setup.[c]sh% script unless flow control (if then else, looping, etc.) is needed. For assistance, contact %{font-weight: normal;color: #000000}uas-group@fnal.gov% .
62 1 Marc Mengel
* In most cases, "un" actions (e.g., UNSETUP, UNCURRENT) are not needed (see section [[actions#62754|34.2.2 %{font-weight: normal;color: #000000}"Uncommands" as Actions% ]] ). If an "un" action is %{font-weight: normal;color: #000000}not% specified in the table file, %{font-weight: bold;color: #000000}UPS% will undo what the corresponding action did (e.g., SETUP, CURRENT), in reverse order, provided reversible functions were used (see section [[functions#38469|35.2 %{font-weight: normal;color: #000000}Reversible Functions% ]] ).
63 1 Marc Mengel
* Individual groups or experiments at Fermilab may set standards regarding table files that members should follow; contact your group leader to find out if there are any you need to be aware of. For example, ODS prefers that table files be maintained in the %{font-weight: bold;color: #000000}UPS% database product subdirectory (e.g., %{font-family: monospace}$PRODUCTS/emacs% ) rather than in the product's %{font-family: monospace}ups% directory.
64 1 Marc Mengel
65 1 Marc Mengel
66 1 Marc Mengel
h2.  %(#62435)&nbsp;% 36.4 Table File Structure and Contents
67 1 Marc Mengel
68 1 Marc Mengel
69 1 Marc Mengel
h3.  %(#62436)&nbsp;% 36.4.1 Basic Structure
70 1 Marc Mengel
71 1 Marc Mengel
72 1 Marc Mengel
p<>. %(#62617)&nbsp;% The file starts with a header that identifies the file type and the product:
73 1 Marc Mengel
74 1 Marc Mengel
75 1 Marc Mengel
<pre>
76 1 Marc Mengel
File=Table
77 1 Marc Mengel
Product=<product>
78 1 Marc Mengel
</pre>
79 1 Marc Mengel
80 1 Marc Mengel
81 1 Marc Mengel
p<>. %(#62439)&nbsp;% The basic structure of table file contents consists of an instance identifier followed by one or more actions (described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] ). By the time %{font-weight: bold;color: #000000}UPS% accesses the table file, it has already determined the database, product name and product version. Therefore FLAVOR and QUALIFIERS together are sufficient to identify the instance.
82 1 Marc Mengel
83 1 Marc Mengel
p<>. %(#73104)&nbsp;% Here is a sample table file that illustrates the basic structure:
84 1 Marc Mengel
85 1 Marc Mengel
86 1 Marc Mengel
<pre>
87 1 Marc Mengel
File=Table
88 1 Marc Mengel
Product=exmh
89 1 Marc Mengel
90 1 Marc Mengel
FLAVOR=SunOS+5
91 1 Marc Mengel
QUALIFIERS=""
92 1 Marc Mengel
93 1 Marc Mengel
   ACTION=SETUP
94 1 Marc Mengel
      setupRequired(expect)
95 1 Marc Mengel
      setupRequired(mh)
96 1 Marc Mengel
      ...
97 1 Marc Mengel
   ACTION=UNSETUP
98 1 Marc Mengel
      ...
99 1 Marc Mengel
</pre>
100 1 Marc Mengel
101 1 Marc Mengel
102 1 Marc Mengel
p<>. %(#64726)&nbsp;% User-defined keywords, described in section [[files_intro#35506|28.2 %{font-weight: normal;color: #000000}Keywords: Information Storage Format% ]] , can also be included after an instance identifier for use within actions.
103 1 Marc Mengel
104 1 Marc Mengel
105 1 Marc Mengel
h3.  %(#34894)&nbsp;% 36.4.2 Grouping Information
106 1 Marc Mengel
107 1 Marc Mengel
108 1 Marc Mengel
p<>. %(#62624)&nbsp;% When a single table file represents multiple instances, a grouping structure can be superimposed on this basic structure to organize the information. To avoid having to repeat identical actions for a series of FLAVOR/QUALIFIER identifiers, the keyword FLAVOR can take the value ANY in table files. FLAVOR=ANY is taken as a best match, assuming all other instance identifiers match (see [[matching#8463|Chapter 27: %{font-weight: normal;color: #000000}Product Instance Matching in UPS/UPD Commands% ]] for more information on instance selection).
109 1 Marc Mengel
110 1 Marc Mengel
p<>. %(#34895)&nbsp;% Grouping information within table files is supported via the use of the following three markers:
111 1 Marc Mengel
112 1 Marc Mengel
p<>. %(#80250)&nbsp;% GROUP:
113 1 Marc Mengel
114 1 Marc Mengel
p<>. %(#80251)&nbsp;% Groups together multiple flavor/qualifier pairs. All entries subsequent to GROUP: are part of this group until an END: marker is found.
115 1 Marc Mengel
116 1 Marc Mengel
p<>. %(#80252)&nbsp;% COMMON:
117 1 Marc Mengel
118 1 Marc Mengel
p<>. %(#80253)&nbsp;% Groups together actions that apply to all instances represented in GROUP:. COMMON: is only valid within a GROUP:.
119 1 Marc Mengel
120 1 Marc Mengel
p<>. %(#80254)&nbsp;% END:
121 1 Marc Mengel
122 1 Marc Mengel
p<>. %(#80255)&nbsp;% Marks the end of a GROUP: or COMMON:. One END: marker is used to jointly end a GROUP: and an included COMMON:.
123 1 Marc Mengel
124 1 Marc Mengel
p<>. %(#34899)&nbsp;%  %{font-weight: bold;color: #000000}UPS% does not %{font-weight: normal;color: #000000}require% grouping in table files; these markers are available for convenience and for organizing information clearly. However, if GROUP: or COMMON: is used, END: must appear at the end of it, even if that is the very end of the file.
125 1 Marc Mengel
126 1 Marc Mengel
127 1 Marc Mengel
h3.  %(#34504)&nbsp;% 36.4.3 The Order of Elements
128 1 Marc Mengel
129 1 Marc Mengel
130 1 Marc Mengel
p<>. %(#34937)&nbsp;% Blank lines are ignored, and therefore can be placed anywhere.
131 1 Marc Mengel
132 1 Marc Mengel
133 1 Marc Mengel
* The first keywords after GROUP: must always be FLAVOR followed by QUALIFIERS (i.e., the instance identifiers).
134 1 Marc Mengel
* FLAVOR and QUALIFIERS %{font-weight: normal;color: #000000}cannot% be included within a COMMON: grouping.
135 1 Marc Mengel
* User-defined keywords can be defined anywhere except between GROUP: and the instance identifiers.
136 1 Marc Mengel
* Actions (described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] ) for each instance are located after the instance-identifying keywords, and often between a COMMON: and END:.
137 1 Marc Mengel
* All actions after COMMON: apply to all the FLAVOR-QUALIFIERS pairs listed above it within the current GROUP:.
138 1 Marc Mengel
* All statements apply to the most recently defined FLAVOR/QUALIFIER keywords except for the statements between COMMON: and END: (which apply to all the flavors in the current GROUP:)
139 1 Marc Mengel
* GROUP:s cannot be nested.
140 1 Marc Mengel
141 1 Marc Mengel
142 1 Marc Mengel
h2.  %(#72721)&nbsp;% 36.5 Product Dependencies
143 1 Marc Mengel
144 1 Marc Mengel
145 1 Marc Mengel
p<>. %(#40272)&nbsp;% Typically users want to setup the default current version of a product. In some projects, the only thing that needs to be specified is the product name. In other projects, each setup command must have a qualifier to ensure that the exact version and qualifiers are requested. The reason is that a default qualifier might change in a poorly documented fashion, making it difficult to reproduce results.
146 1 Marc Mengel
147 1 Marc Mengel
p<>. For example, to setup an instance of art, the command is:
148 1 Marc Mengel
149 1 Marc Mengel
150 1 Marc Mengel
<pre>
151 1 Marc Mengel
% setup -B art v1_08_09 -q+e4:+mu2e:+prof
152 1 Marc Mengel
</pre>
153 1 Marc Mengel
154 1 Marc Mengel
155 1 Marc Mengel
p<>. The version is specified as v1_08_09. Qualifiers are used to keep the bookkeeping straight for multiple builds of one version of a product. e4 in shorthand defined by the art team for a compiler version and other specifics. When another product is built with the "e4" qualifier, it can be linked against a version of art that was also built with the "e4" qualifier. The qualifier "prof" requests a version that was built with maximum optimization and with some, but not all, debugger symbols retained. The symbols retained are enough to profile the code and to get a traceback from a core dump. (But not enough to do full line by line debugging.) The name "prof" is motivated by the notion that the build retains enough debugger symbols for profiling.
156 1 Marc Mengel
157 1 Marc Mengel
p<>. %(#36386)&nbsp;% For more examples, see the reference section [[upscommands#112805|23.1 %{font-weight: normal;color: #000000}setup% ]] .
158 1 Marc Mengel
159 1 Marc Mengel
160 1 Marc Mengel
h3.  %(#72804)&nbsp;% 36.5.1 Defining Dependencies
161 1 Marc Mengel
162 1 Marc Mengel
163 1 Marc Mengel
p<>. %(#72724)&nbsp;%  %{font-weight: bold;color: #000000}UPS% product dependencies get listed in the SETUP action for the product instance in question. The %{font-weight: bold;font-family: monospace}setupRequired% and %{font-weight: bold;font-family: monospace}setupOptional% functions, described in section [[functions#38473|35.3 %{font-weight: normal;color: #000000}Function Descriptions% ]] , can be used within the SETUP action to setup the dependencies along with the main product. These two functions take the same set of options and arguments as a normal %{font-weight: bold;font-family: monospace}setup% command (see section [[upscommands#112805|23.1 %{font-weight: normal;color: #000000}setup% ]] ) in order to clearly specify the desired instance of the dependent product. We discourage specification of particular versions of products, and recommend using chains instead, e.g.,:
164 1 Marc Mengel
165 1 Marc Mengel
166 1 Marc Mengel
<pre>
167 1 Marc Mengel
ACTION=SETUP
168 1 Marc Mengel
  setupRequired("perl")
169 1 Marc Mengel
</pre>
170 1 Marc Mengel
171 1 Marc Mengel
172 1 Marc Mengel
p<>. %(#72733)&nbsp;% This example sets up the default instance of %{font-weight: bold;color: #000000}perl% , chained to current. Using chains, it is easier to keep the dependencies and the main product in sync.
173 1 Marc Mengel
174 1 Marc Mengel
p<>. %(#72816)&nbsp;% Products that are not maintained in the %{font-weight: bold;color: #000000}UPS% framework can also be designated as dependencies. You would need to use the function %{font-weight: bold;font-family: monospace}exeAccess% to locate and access a non- %{font-weight: bold;color: #000000}UPS% executable through your $PATH. For example, the action:
175 1 Marc Mengel
176 1 Marc Mengel
177 1 Marc Mengel
<pre>
178 1 Marc Mengel
ACTION=SETUP
179 1 Marc Mengel
  setupOptional(gcc)
180 1 Marc Mengel
  exeAccess(gcc)
181 1 Marc Mengel
</pre>
182 1 Marc Mengel
183 1 Marc Mengel
184 1 Marc Mengel
p<>. %(#72820)&nbsp;% tells %{font-weight: bold;color: #000000}UPS% to setup the current instance of %{font-weight: bold;color: #000000}gcc% if there is one declared; the %{font-weight: bold;font-family: monospace}exeAccess% function checks for a version of %{font-weight: bold;color: #000000}gcc% in your $PATH, even if it's not one that is managed by %{font-weight: bold;color: #000000}UPS% , and exits with an error if one is not found.
185 1 Marc Mengel
186 1 Marc Mengel
187 1 Marc Mengel
h3.  %(#72764)&nbsp;% 36.5.2 Product Dependency Conflicts
188 1 Marc Mengel
189 1 Marc Mengel
190 1 Marc Mengel
p<>. %(#72766)&nbsp;% When different dependencies include the same product via different dependency trees (and therefore may require different instances of the same product), rules have been established to determine which instance of the dependent product is selected and in which order the required products are setup.
191 1 Marc Mengel
192 1 Marc Mengel
193 1 Marc Mengel
h4.  %(#72767)&nbsp;% Selection Algorithm for Conflicting Dependencies
194 1 Marc Mengel
195 1 Marc Mengel
196 1 Marc Mengel
p<>. %(#72768)&nbsp;% The rules are as follows:
197 1 Marc Mengel
198 1 Marc Mengel
199 1 Marc Mengel
# First level product dependencies, defined as those products listed as dependencies in the table file of the main product instance, take precedence over lower level dependencies when selecting which instance of the required product to set up.
200 1 Marc Mengel
# Dependencies listed later in the table file take precedence over those listed earlier.
201 1 Marc Mengel
202 1 Marc Mengel
203 1 Marc Mengel
h4.  %(#72771)&nbsp;% Example of Dependency Selection and Order of Setup
204 1 Marc Mengel
205 1 Marc Mengel
206 1 Marc Mengel
p<>. %(#72773)&nbsp;% We'll take you through an example that illustrates how the dependencies are selected and in what order they are setup. Our sample dependency structure starts with the product %{font-weight: bold;color: #000000}A% as the parent product. It has two dependencies, which in turn have dependencies of their own. %{font-family: monospace}B b1% refers to product %{font-weight: bold;color: #000000}B% , version b1, and so on. (We recommend that developers avoid using specific version dependencies in general; we use them in our example for illustrative purposes.) Some of the dependencies are conflicting:
207 1 Marc Mengel
208 1 Marc Mengel
p<>. %(#72774)&nbsp;% In %{font-weight: bold;color: #000000}A% 's table file:
209 1 Marc Mengel
210 1 Marc Mengel
211 1 Marc Mengel
<pre>
212 1 Marc Mengel
product A
213 1 Marc Mengel
setupRequired(B b1)
214 1 Marc Mengel
setupRequired(C c1)
215 1 Marc Mengel
</pre>
216 1 Marc Mengel
217 1 Marc Mengel
218 1 Marc Mengel
p<>. %(#72778)&nbsp;% In %{font-weight: bold;color: #000000}B b1% 's table file:
219 1 Marc Mengel
220 1 Marc Mengel
221 1 Marc Mengel
<pre>
222 1 Marc Mengel
product B b1
223 1 Marc Mengel
setupRequired(C c2)
224 1 Marc Mengel
setupRequired(D d1)
225 1 Marc Mengel
</pre>
226 1 Marc Mengel
227 1 Marc Mengel
228 1 Marc Mengel
p<>. %(#72782)&nbsp;% In %{font-weight: bold;color: #000000}C c2% 's table file:
229 1 Marc Mengel
230 1 Marc Mengel
231 1 Marc Mengel
<pre>
232 1 Marc Mengel
product C c2
233 1 Marc Mengel
setupRequired(D d3)
234 1 Marc Mengel
</pre>
235 1 Marc Mengel
236 1 Marc Mengel
237 1 Marc Mengel
p<>. %(#72785)&nbsp;% In %{font-weight: bold;color: #000000}C c1% 's table file:
238 1 Marc Mengel
239 1 Marc Mengel
240 1 Marc Mengel
<pre>
241 1 Marc Mengel
product C c1
242 1 Marc Mengel
setupRequired(D d2)
243 1 Marc Mengel
</pre>
244 1 Marc Mengel
245 1 Marc Mengel
246 1 Marc Mengel
p<>. %(#72788)&nbsp;% The tree is traversed starting at %{font-weight: bold;color: #000000}A% , then going down each dependency branch. So the order in which the products are encountered is:
247 1 Marc Mengel
248 1 Marc Mengel
249 1 Marc Mengel
#  %{font-weight: bold;color: #000000}A% (no conflict)
250 1 Marc Mengel
#  %{font-weight: bold;color: #000000}A% 's dependencies %{font-weight: bold;color: #000000}B b1% and %{font-weight: bold;color: #000000}C c1% are selected since they are the highest level dependencies.
251 1 Marc Mengel
# Start down %{font-weight: bold;color: #000000}B b1% branch: find %{font-weight: bold;color: #000000}C c2% (version %{font-weight: bold;color: #000000}c1% already selected by rule 1; %{font-weight: bold;color: #000000}C c2% ignored)
252 1 Marc Mengel
# Completing the %{font-weight: bold;color: #000000}B b1% branch, find %{font-weight: bold;color: #000000}D d1% . It is examined, and ultimately passed over (by rule 2) because %{font-weight: bold;color: #000000}D d2% , a dependency of %{font-weight: bold;color: #000000}C c1% and therefore also a second-level dependency of %{font-weight: bold;color: #000000}A% , is encountered later.
253 1 Marc Mengel
254 1 Marc Mengel
255 1 Marc Mengel
h2.  %(#36685)&nbsp;% 36.6 Keywords that can be Used in Table Files
256 1 Marc Mengel
257 1 Marc Mengel
258 1 Marc Mengel
p<>. %(#73265)&nbsp;% 
259 1 Marc Mengel
260 1 Marc Mengel
|_.  %{font-weight: normal;color: #000000}Keyword and%   %{font-weight: normal;color: #000000}Keyword and%  Default Value (if any) Default Value (if any) |_. Description and Description and Notes (if any) Notes (if any) |
261 1 Marc Mengel
|ACTION ACTION |defines an action (described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] ), i.e., groups together a list of functions associated with a command (e.g., ACTION=SETUP) defines an action (described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] ), i.e., groups together a list of functions associated with a command (e.g., ACTION=SETUP) |
262 1 Marc Mengel
|CATMAN_SOURCE_DIR CATMAN_SOURCE_DIR Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toman/catman% directory Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toman/catman% directory |location of catman files (formatted man page files) included with instance location of catman files (formatted man page files) included with instance |
263 1 Marc Mengel
|COMMON: COMMON: |groups together actions that apply to all instances represented in "GROUP:"; groups together actions that apply to all instances represented in "GROUP:"; COMMON: is only valid within a GROUP: COMMON: is only valid within a GROUP: |
264 1 Marc Mengel
|DESCRIPTION DESCRIPTION |product description product description |
265 1 Marc Mengel
|END: END: |marks the end of a "GROUP:" or "COMMON:"; one "END:" marker is used to jointly end a "GROUP:" and an included "COMMON:" marks the end of a "GROUP:" or "COMMON:"; one "END:" marker is used to jointly end a "GROUP:" and an included "COMMON:" |
266 1 Marc Mengel
|FILE FILE |type of file (possible values: DBCONFIG, UPDCONFIG, CHAIN, VERSION, TABLE) type of file (possible values: DBCONFIG, UPDCONFIG, CHAIN, VERSION, TABLE) |
267 1 Marc Mengel
|FLAVOR FLAVOR |product instance flavor product instance flavor Note: To easily accommodate flavor-neutral %{font-weight: bold;font-family: monospace}setup% functions in a table file, FLAVOR can take the value ANY, but %{font-weight: normal;color: #000000}only% in a table file. Note: To easily accommodate flavor-neutral %{font-weight: bold;font-family: monospace}setup% functions in a table file, FLAVOR can take the value ANY, but %{font-weight: normal;color: #000000}only% in a table file. |
268 1 Marc Mengel
|GROUP: GROUP: |groups together multiple instances; all entries subsequent to this "GROUP:" are part of it until an "END:" marker is reached groups together multiple instances; all entries subsequent to this "GROUP:" are part of it until an "END:" marker is reached |
269 1 Marc Mengel
|INFO_SOURCE_DIR INFO_SOURCE_DIR Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toInfo% directory Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toInfo% directory |location of Info files included with instance location of Info files included with instance |
270 1 Marc Mengel
|MAN_SOURCE_DIR MAN_SOURCE_DIR Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toman/man% directory Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toman/man% directory |location of unformatted man page files included with instance location of unformatted man page files included with instance |
271 1 Marc Mengel
|PRODUCT PRODUCT |product name product name |
272 1 Marc Mengel
|QUALIFIERS QUALIFIERS |additional instance specification information often used to indicate compilation options used by developer additional instance specification information often used to indicate compilation options used by developer Notes: appears immediately after a FLAVOR in these files, and is coupled with it to complete the instance identification (see [[matching#37834|27.2.3 %{font-weight: normal;color: #000000}Qualifiers: Use in Instance Matching% ]] ) Notes: appears immediately after a FLAVOR in these files, and is coupled with it to complete the instance identification (see [[matching#37834|27.2.3 %{font-weight: normal;color: #000000}Qualifiers: Use in Instance Matching% ]] ) |
273 1 Marc Mengel
|UPS_DB_VERSION UPS_DB_VERSION | %{font-weight: bold;color: #000000}UPS% database version  %{font-weight: bold;color: #000000}UPS% database version |
274 1 Marc Mengel
|USER USER |current username current username |
275 1 Marc Mengel
|VERSION VERSION |product version product version |
276 1 Marc Mengel
|_UPD_OVERLAY _UPD_OVERLAY |main product name for overlaid product main product name for overlaid product Note: This keyword is user-defined from %{font-weight: bold;color: #000000}UPS% 's point of view. It is included here because it is configured and used by %{font-weight: bold;color: #000000}UPD% . Its use with overlaid products is described in section [[files_intro#65610|28.6.6 %{font-weight: normal;color: #000000}_UPD_OVERLAY% ]] . Note: This keyword is user-defined from %{font-weight: bold;color: #000000}UPS% 's point of view. It is included here because it is configured and used by %{font-weight: bold;color: #000000}UPD% . Its use with overlaid products is described in section [[files_intro#65610|28.6.6 %{font-weight: normal;color: #000000}_UPD_OVERLAY% ]] . |
277 1 Marc Mengel
278 1 Marc Mengel
279 1 Marc Mengel
h2.  %(#73264)&nbsp;% 36.7 Table File Examples
280 1 Marc Mengel
281 1 Marc Mengel
282 1 Marc Mengel
h3.  %(#62652)&nbsp;% 36.7.1 Example Illustrating Use of FLAVOR=ANY
283 1 Marc Mengel
284 1 Marc Mengel
285 1 Marc Mengel
p<>. %(#62698)&nbsp;% Below is a sample table file for the product %{font-weight: bold;color: #000000}exmh% version v1_6_6 which uses FLAVOR=ANY. For the %{font-weight: bold;color: #000000}exmh% instances whose version files point to this table file, all except those with qualifiers share the same stanza:
286 1 Marc Mengel
287 1 Marc Mengel
288 1 Marc Mengel
<pre>
289 1 Marc Mengel
File=Table
290 1 Marc Mengel
Product=exmh
291 1 Marc Mengel
#*************************************************
292 1 Marc Mengel
# Starting Group definition
293 1 Marc Mengel
Group:
294 1 Marc Mengel
Flavor=ANY
295 1 Marc Mengel
Qualifiers=""
296 1 Marc Mengel
297 1 Marc Mengel
Common:
298 1 Marc Mengel
   Action=setup
299 1 Marc Mengel
      setupRequired(expect)
300 1 Marc Mengel
      setupRequired(mh)
301 1 Marc Mengel
      setupOptional(glimpse)
302 1 Marc Mengel
      setupOptional(www)
303 1 Marc Mengel
      setupOptional(mimetools)
304 1 Marc Mengel
      setupOptional(ispell)
305 1 Marc Mengel
      setupOptional(popclient)
306 1 Marc Mengel
      prodDir()
307 1 Marc Mengel
      setupEnv()
308 1 Marc Mengel
      pathPrepend(PATH,${UPS_PROD_DIR}/bin)
309 1 Marc Mengel
   Action=configure
310 1 Marc Mengel
      execute(${UPS_PROD_DIR}/ups/configure,UPS_ENV)
311 1 Marc Mengel
End:
312 1 Marc Mengel
</pre>
313 1 Marc Mengel
314 1 Marc Mengel
315 1 Marc Mengel
p<>. %(#62688)&nbsp;% Actions, functions and variables as used in this example are described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] , section [[functions#38473|35.3 %{font-weight: normal;color: #000000}Function Descriptions% ]] and section [[functions#34716|35.6 %{font-weight: normal;color: #000000}Local Read-Only Variables Available to Functions% ]] , respectively.
316 1 Marc Mengel
317 1 Marc Mengel
p<>. %(#62715)&nbsp;% You'll notice that there are no functions specified for %{font-weight: bold;font-family: monospace}unsetup% in this table file. Due to the defaults that %{font-weight: bold;color: #000000}UPS% has in place, when %{font-weight: bold;font-family: monospace}unsetup% is run all of the %{font-weight: bold;font-family: monospace}setup% functions will be reversed (the required products will get unsetup, the defined environment variables will get undefined, and the product's %{font-family: monospace}bin% directory will be dropped from $PATH. See sections [[actions#62754|34.2.2 %{font-weight: normal;color: #000000}"Uncommands" as Actions% ]] and [[functions#38469|35.2 %{font-weight: normal;color: #000000}Reversible Functions% ]] .
318 1 Marc Mengel
319 1 Marc Mengel
320 1 Marc Mengel
h3.  %(#62378)&nbsp;% 36.7.2 Example Showing Grouping
321 1 Marc Mengel
322 1 Marc Mengel
323 1 Marc Mengel
p<>. %(#62694)&nbsp;% Grouping is illustrated in the following example:
324 1 Marc Mengel
325 1 Marc Mengel
326 1 Marc Mengel
<pre>
327 1 Marc Mengel
FILE=Table
328 1 Marc Mengel
PRODUCT=exmh
329 1 Marc Mengel
#*************************************************
330 1 Marc Mengel
# Starting Group definition
331 1 Marc Mengel
GROUP:
332 1 Marc Mengel
FLAVOR=IRIX+5
333 1 Marc Mengel
QUALIFIERS=""
334 1 Marc Mengel
335 1 Marc Mengel
FLAVOR=IRIX+5
336 1 Marc Mengel
QUALIFIERS="mips2"
337 1 Marc Mengel
338 1 Marc Mengel
COMMON:
339 1 Marc Mengel
   ACTION=SETUP
340 1 Marc Mengel
      setupOptional(expect)
341 1 Marc Mengel
      ...
342 1 Marc Mengel
   ACTION=CONFIGURE
343 1 Marc Mengel
      execute(${UPS_PROD_DIR}/ups/configure,UPS_ENV)
344 1 Marc Mengel
   ...
345 1 Marc Mengel
END:
346 1 Marc Mengel
#*************************************************
347 1 Marc Mengel
# Starting Group definition
348 1 Marc Mengel
GROUP:
349 1 Marc Mengel
FLAVOR=ANY
350 1 Marc Mengel
QUALIFIERS=""
351 1 Marc Mengel
352 1 Marc Mengel
COMMON:
353 1 Marc Mengel
   ACTION=SETUP
354 1 Marc Mengel
      setupRequired(expect)
355 1 Marc Mengel
      ...
356 1 Marc Mengel
   ACTION=CONFIGURE
357 1 Marc Mengel
      execute(${UPS_PROD_DIR}/ups/configure,UPS_ENV)
358 1 Marc Mengel
   ...
359 1 Marc Mengel
END:
360 1 Marc Mengel
</pre>
361 1 Marc Mengel
362 1 Marc Mengel
363 1 Marc Mengel
p<>. %(#73026)&nbsp;% The second group (defined by %{font-family: monospace}FLAVOR=ANY% ) matches all the instances not matched in the first group, except those with qualifiers.
364 1 Marc Mengel
365 1 Marc Mengel
366 1 Marc Mengel
h3.  %(#38896)&nbsp;% 36.7.3 Example with User-Defined Keywords
367 1 Marc Mengel
368 1 Marc Mengel
369 1 Marc Mengel
p<>. %(#64711)&nbsp;% User-defined keywords are described in section [[files_intro#35506|28.2 %{font-weight: normal;color: #000000}Keywords: Information Storage Format% ]] . All user-defined keywords must have underscore ( %{font-family: monospace}_% ) as the initial character (e.g., %{font-family: monospace}_dest_arch% ). The following example illustrates their use in a table file:
370 1 Marc Mengel
371 1 Marc Mengel
372 1 Marc Mengel
<pre>
373 1 Marc Mengel
File=Table
374 1 Marc Mengel
Product=vxboot
375 1 Marc Mengel
#*************************************************
376 1 Marc Mengel
# Starting Group definition
377 1 Marc Mengel
Group:
378 1 Marc Mengel
Flavor=NULL
379 1 Marc Mengel
Qualifiers="narrow29"
380 1 Marc Mengel
   _dest_arch=ppc
381 1 Marc Mengel
   _dest_env=VxWorks-5.3
382 1 Marc Mengel
   _dest_type=MVME2301
383 1 Marc Mengel
...
384 1 Marc Mengel
Common:
385 1 Marc Mengel
   Action=setup
386 1 Marc Mengel
      setupEnv()
387 1 Marc Mengel
      envSet (VXB_DEST_ARCH,${_dest_arch})
388 1 Marc Mengel
      envSet (VXB_DEST_ENV,${_dest_env})
389 1 Marc Mengel
      envSet (VXB_DEST_TYPE,${_dest_type})
390 1 Marc Mengel
...
391 1 Marc Mengel
</pre>
392 1 Marc Mengel
393 1 Marc Mengel
394 1 Marc Mengel
h3.  %(#64661)&nbsp;% 36.7.4 Examples Illustrating ExeActionOpt Function
395 1 Marc Mengel
396 1 Marc Mengel
397 1 Marc Mengel
h4.  %(#72558)&nbsp;% Example 1
398 1 Marc Mengel
399 1 Marc Mengel
400 1 Marc Mengel
p<>. %(#72633)&nbsp;% In this example, there are actions for the first two instance identifiers, but not for the third. We want to execute the XYZ action at setup time if it's there, but continue processing if it's not. To do this, we must call the action using the %{font-weight: bold;font-family: monospace}exeActionOpt% function.
401 1 Marc Mengel
402 1 Marc Mengel
403 1 Marc Mengel
<pre>
404 1 Marc Mengel
FILE=Table
405 1 Marc Mengel
PRODUCT=fred
406 1 Marc Mengel
#*************************************************
407 1 Marc Mengel
# Starting Group definition
408 1 Marc Mengel
GROUP:
409 1 Marc Mengel
FLAVOR=SunOS+6
410 1 Marc Mengel
QUALIFIERS=""
411 1 Marc Mengel
   ACTION=XYZ
412 1 Marc Mengel
      fileTest(/, -w, "You must be root to run this command.")
413 1 Marc Mengel
414 1 Marc Mengel
FLAVOR=IRIX+6
415 1 Marc Mengel
QUALIFIERS=""
416 1 Marc Mengel
   ACTION=XYZ
417 1 Marc Mengel
      fileTest(/, -w, "You must be root to run this command.")
418 1 Marc Mengel
419 1 Marc Mengel
FLAVOR=IRIX+6
420 1 Marc Mengel
QUALIFIERS="mips2"
421 1 Marc Mengel
#  No XYZ action
422 1 Marc Mengel
423 1 Marc Mengel
COMMON:
424 1 Marc Mengel
   ACTION=SETUP
425 1 Marc Mengel
      exeActionOpt(XYZ)
426 1 Marc Mengel
427 1 Marc Mengel
 END:
428 1 Marc Mengel
...
429 1 Marc Mengel
</pre>
430 1 Marc Mengel
431 1 Marc Mengel
432 1 Marc Mengel
h4.  %(#72563)&nbsp;% Example 2
433 1 Marc Mengel
434 1 Marc Mengel
435 1 Marc Mengel
p<>. %(#72650)&nbsp;% In this example, we use the %{font-weight: bold;font-family: monospace}exeActionOpt% function to instruct %{font-weight: bold;color: #000000}UPS% to execute one action or another, depending on whether the user supplies an option on the %{font-weight: bold;font-family: monospace}setup% command line.
436 1 Marc Mengel
437 1 Marc Mengel
438 1 Marc Mengel
<pre>
439 1 Marc Mengel
FILE=Table
440 1 Marc Mengel
PRODUCT=fred
441 1 Marc Mengel
#*************************************************
442 1 Marc Mengel
# Starting Group definition
443 1 Marc Mengel
GROUP:
444 1 Marc Mengel
FLAVOR=ANY
445 1 Marc Mengel
QUALIFIERS=""
446 1 Marc Mengel
447 1 Marc Mengel
   ACTION=SETUP
448 1 Marc Mengel
      exeActionOpt(XYZ_${UPS_OPTIONS})
449 1 Marc Mengel
450 1 Marc Mengel
   ACTION=XYZ_
451 1 Marc Mengel
      function_1()
452 1 Marc Mengel
   ACTION=XYZ_FULL_LICENSE
453 1 Marc Mengel
      function_2()
454 1 Marc Mengel
...
455 1 Marc Mengel
</pre>
456 1 Marc Mengel
457 1 Marc Mengel
458 1 Marc Mengel
p<>. %(#72433)&nbsp;% If you run:
459 1 Marc Mengel
460 1 Marc Mengel
461 1 Marc Mengel
<pre>
462 1 Marc Mengel
% setup fred
463 1 Marc Mengel
</pre>
464 1 Marc Mengel
465 1 Marc Mengel
466 1 Marc Mengel
p<>. %(#72612)&nbsp;% you'll execute ACTION XYZ_. To execute ACTION XYZ_FULL_LICENSE, you need to run:
467 1 Marc Mengel
468 1 Marc Mengel
469 1 Marc Mengel
<pre>
470 1 Marc Mengel
% setup fred -O FULL_LICENSE
471 1 Marc Mengel
</pre>
472 1 Marc Mengel
473 1 Marc Mengel
474 1 Marc Mengel
h3.  %(#65661)&nbsp;% 36.7.5 Examples Illustrating Failure Return Codes
475 1 Marc Mengel
476 1 Marc Mengel
477 1 Marc Mengel
p<>. Users may want to propagate a failure through a ups build script, so that the ups build doesn't exit with success when something failed. If you want a ups action to fail and exit if any of the individual commands fail, you can:
478 1 Marc Mengel
479 1 Marc Mengel
480 1 Marc Mengel
<pre>
481 1 Marc Mengel
Execute(set -e, NO_UPS_ENV)
482 1 Marc Mengel
</pre>
483 1 Marc Mengel
484 1 Marc Mengel
in your ups action, and the first command that fails will fail the action, or if you want to check particular steps, you can
485 1 Marc Mengel
486 1 Marc Mengel
<pre>
487 1 Marc Mengel
Execute( some_command || exit 1 , NO_UPS_ENV)
488 1 Marc Mengel
</pre>
489 1 Marc Mengel
490 1 Marc Mengel
It will fail if some_command fails.
491 1 Marc Mengel
p<>. For example:
492 1 Marc Mengel
493 1 Marc Mengel
494 1 Marc Mengel
<pre>
495 1 Marc Mengel
----------------------
496 1 Marc Mengel
File    = table
497 1 Marc Mengel
Product = foo
498 1 Marc Mengel
499 1 Marc Mengel
Flavor=ANY
500 1 Marc Mengel
Qualifiers=
501 1 Marc Mengel
502 1 Marc Mengel
action = build
503 1 Marc Mengel
      Execute(/bin/true  || exit 1, NO_UPS_ENV)
504 1 Marc Mengel
      Execute(/bin/false || exit 2, NO_UPS_ENV)
505 1 Marc Mengel
      Execute(/bin/true  || exit 3, NO_UPS_ENV)
506 1 Marc Mengel
----------------------
507 1 Marc Mengel
</pre>
508 1 Marc Mengel
509 1 Marc Mengel
A "ups build -m foo.table foo" will fail with an exit code of 2, because /bin/false fails. Note: don't exit during a setup script unless you want to log the user out, which is probably not a good idea.
510 1 Marc Mengel
511 1 Marc Mengel
<pre>
512 1 Marc Mengel
or in the "set -e"  case:
513 1 Marc Mengel
------------------------
514 1 Marc Mengel
File    = table
515 1 Marc Mengel
Product = foo
516 1 Marc Mengel
517 1 Marc Mengel
Flavor=ANY
518 1 Marc Mengel
Qualifiers=
519 1 Marc Mengel
520 1 Marc Mengel
action = build
521 1 Marc Mengel
      Execute(set -e, NO_UPS_ENV)
522 1 Marc Mengel
      Execute(echo first, NO_UPS_ENV)
523 1 Marc Mengel
      Execute(/bin/false, NO_UPS_ENV)
524 1 Marc Mengel
      Execute(echo second, NO_UPS_ENV)
525 1 Marc Mengel
------------------------
526 1 Marc Mengel
527 1 Marc Mengel
if you do:
528 1 Marc Mengel
--------------
529 1 Marc Mengel
% ups build -m foo.table foo
530 1 Marc Mengel
first
531 1 Marc Mengel
ERROR: Error in call to system: error from subprocess
532 1 Marc Mengel
--------------
533 1 Marc Mengel
</pre>
534 1 Marc Mengel
535 1 Marc Mengel
it returns an exit code of 1, and does not do the "echo second".
536 1 Marc Mengel
p<>. In any other case, the ups action yeilds the exit code of the *last* command in the action.
537 1 Marc Mengel
538 1 Marc Mengel
p<>. %(#32782)&nbsp;% 
539 1 Marc Mengel
540 1 Marc Mengel
p<>. %(#72619)&nbsp;% 
541 1 Marc Mengel
542 1 Marc Mengel
| [[upsv4TOC| !{width:84px;height:23px}images/navtoc.gif(TOC)!  ]] | [[functions| !{width:81px;height:23px}images/navprev.gif(PREV)!  ]] | [[extrascripts| !{width:81px;height:23px}images/navnext.gif(NEXT)!  ]] |
543 1 Marc Mengel
544 1 Marc Mengel
545 1 Marc Mengel
p<>. **Last revised on September 2014** 
546 1 Marc Mengel
547 1 Marc Mengel
| [[upsv4TOC| !{width:84px;height:23px}images/navtoc.gif(TOC)!  ]] | [[functions| !{width:81px;height:23px}images/navprev.gif(PREV)!  ]] | [[extrascripts| !{width:81px;height:23px}images/navnext.gif(NEXT)!  ]] |
548 1 Marc Mengel
549 1 Marc Mengel
550 1 Marc Mengel
|.  !{width:60px;height:60px}images/CDlogo.gif(Fermilab CD logo)!  |\4. Complete Guide and Reference Manual for UPS and UPD|
551 1 Marc Mengel
552 1 Marc Mengel
553 1 Marc Mengel
h3. Chapter Contents
554 1 Marc Mengel
555 1 Marc Mengel
556 1 Marc Mengel
p<>. [[table_files#8463|Chapter 36: Table Files]] 
557 1 Marc Mengel
   [[table_files#36855|36.1 About Table Files]] 
558 1 Marc Mengel
   [[table_files#62347|36.2 When Do You Need to Provide a Table File?]] 
559 1 Marc Mengel
   [[table_files#62806|36.3 Recommendations for Creating Table Files]] 
560 1 Marc Mengel
   [[table_files#62435|36.4 Table File Structure and Contents]] 
561 1 Marc Mengel
     [[table_files#62436|36.4.1 Basic Structure]] 
562 1 Marc Mengel
     [[table_files#34894|36.4.2 Grouping Information]] 
563 1 Marc Mengel
     [[table_files#34504|36.4.3 The Order of Elements]] 
564 1 Marc Mengel
   [[table_files#72721|36.5 Product Dependencies]] 
565 1 Marc Mengel
     [[table_files#72804|36.5.1 Defining Dependencies]] 
566 1 Marc Mengel
     [[table_files#72764|36.5.2 Product Dependency Conflicts]] 
567 1 Marc Mengel
   [[table_files#36685|36.6 Keywords that can be Used in Table Files]] 
568 1 Marc Mengel
   [[table_files#73264|36.7 Table File Examples]] 
569 1 Marc Mengel
     [[table_files#62652|36.7.1 Example Illustrating Use of FLAVOR=ANY]] 
570 1 Marc Mengel
     [[table_files#62378|36.7.2 Example Showing Grouping]] 
571 1 Marc Mengel
     [[table_files#38896|36.7.3 Example with User-Defined Keywords]] 
572 1 Marc Mengel
     [[table_files#64661|36.7.4 Examples Illustrating ExeActionOpt Function]] 
573 1 Marc Mengel
     [[table_files#72433|36.7.5 Examples Illustrating Failure Return Codes]] 
574 1 Marc Mengel
575 1 Marc Mengel
576 1 Marc Mengel
h1.  %(#8463)&nbsp;% Chapter 36: Table Files
577 1 Marc Mengel
578 1 Marc Mengel
579 1 Marc Mengel
p<>. %(#33873)&nbsp;% This chapter describes table files. Table files contain product-specific, installation-independent information. Most, but not all, products require a table file. %{font-weight: bold;color: #000000}UPS% product developers are responsible for providing the table files associated with their products.
580 1 Marc Mengel
581 1 Marc Mengel
582 1 Marc Mengel
h2.  %(#36855)&nbsp;% 36.1 About Table Files
583 1 Marc Mengel
584 1 Marc Mengel
585 1 Marc Mengel
p<>. %(#62559)&nbsp;% Table files are created and maintained by product developers. Table files contain the non-system-specific and non-shell-specific information that %{font-weight: bold;color: #000000}UPS% uses for installing, initializing, and otherwise operating on product instances. For a given product, usually a single table file suffices for several instances, especially of a single version. Sometimes each instance has a separate table file. Table file names are arbitrary; we present recommendations in section [[table_files#62806|36.3 %{font-weight: normal;color: #000000}Recommendations for Creating Table Files% ]] .
586 1 Marc Mengel
587 1 Marc Mengel
p<>. %(#62561)&nbsp;% Typically, when a %{font-weight: bold;color: #000000}UPS% command is issued, %{font-weight: bold;color: #000000}UPS% finds the table location from the command line or the version file (see section [[versionfiles#35235|29.4 %{font-weight: normal;color: #000000}Determination of ups Directory and Table File Locations% ]] ). The command completes its internal processes, and then within the table file, it proceeds to:
588 1 Marc Mengel
589 1 Marc Mengel
590 1 Marc Mengel
# locate the stanza that matches the specified product instance
591 1 Marc Mengel
# find an ACTION keyword value that corresponds to the command, if any (see [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] )
592 1 Marc Mengel
# execute the functions listed underneath the corresponding ACTION keyword, if any (see [[functions#73292|Chapter 35: %{font-weight: normal;color: #000000}Functions used in Actions% ]] ), or
593 1 Marc Mengel
# reverse the functions listed underneath the ACTION corresponding to the "uncommand" (see section [[actions#62754|34.2.2 %{font-weight: normal;color: #000000}"Uncommands" as Actions% ]] )
594 1 Marc Mengel
595 1 Marc Mengel
596 1 Marc Mengel
h2.  %(#62347)&nbsp;% 36.2 When Do You Need to Provide a Table File?
597 1 Marc Mengel
598 1 Marc Mengel
599 1 Marc Mengel
p<>. %(#36604)&nbsp;% Not all products require a table file. In particular, if %{font-weight: normal;color: #000000}no% processing besides the internals and defaults needs to be done for %{font-weight: normal;color: #000000}any%  %{font-weight: bold;color: #000000}UPS% command run on a particular product, and if its %{font-family: monospace}ups% directory and documentation reside in the default areas, then the product doesn't need a table file. However, for products that do need a table file (most), at least a rudimentary table file must be in place before any instance is declared to a target %{font-weight: bold;color: #000000}UPS% database. If it's not added right away, users may see incorrect behavior before it is there.
600 1 Marc Mengel
601 1 Marc Mengel
602 1 Marc Mengel
h2.  %(#62806)&nbsp;% 36.3 Recommendations for Creating Table Files
603 1 Marc Mengel
604 1 Marc Mengel
605 1 Marc Mengel
* Although table files can have any file name, we recommend that they be named as %{font-family: monospace}<product>.table% (e.g., %{font-family: monospace}emacs.table% ) or %{font-family: monospace}<version>.table% (e.g., %{font-family: monospace}v19_34b.table% ) for easy identification. If a table file is unique to a particular version of the product (which is likely because versions of product dependencies often change along with the version of the main product) then the name should be %{font-family: monospace}<product>_<version>.table% (e.g., %{font-family: monospace}emacs_v19_34b.table% ).
606 1 Marc Mengel
* Table files should not source any %{font-family: monospace}setup.[c]sh% script unless flow control (if then else, looping, etc.) is needed. For assistance, contact %{font-weight: normal;color: #000000}uas-group@fnal.gov% .
607 1 Marc Mengel
* In most cases, "un" actions (e.g., UNSETUP, UNCURRENT) are not needed (see section [[actions#62754|34.2.2 %{font-weight: normal;color: #000000}"Uncommands" as Actions% ]] ). If an "un" action is %{font-weight: normal;color: #000000}not% specified in the table file, %{font-weight: bold;color: #000000}UPS% will undo what the corresponding action did (e.g., SETUP, CURRENT), in reverse order, provided reversible functions were used (see section [[functions#38469|35.2 %{font-weight: normal;color: #000000}Reversible Functions% ]] ).
608 1 Marc Mengel
* Individual groups or experiments at Fermilab may set standards regarding table files that members should follow; contact your group leader to find out if there are any you need to be aware of. For example, ODS prefers that table files be maintained in the %{font-weight: bold;color: #000000}UPS% database product subdirectory (e.g., %{font-family: monospace}$PRODUCTS/emacs% ) rather than in the product's %{font-family: monospace}ups% directory.
609 1 Marc Mengel
610 1 Marc Mengel
611 1 Marc Mengel
h2.  %(#62435)&nbsp;% 36.4 Table File Structure and Contents
612 1 Marc Mengel
613 1 Marc Mengel
614 1 Marc Mengel
h3.  %(#62436)&nbsp;% 36.4.1 Basic Structure
615 1 Marc Mengel
616 1 Marc Mengel
617 1 Marc Mengel
p<>. %(#62617)&nbsp;% The file starts with a header that identifies the file type and the product:
618 1 Marc Mengel
619 1 Marc Mengel
620 1 Marc Mengel
<pre>
621 1 Marc Mengel
File=Table
622 1 Marc Mengel
Product=<product>
623 1 Marc Mengel
</pre>
624 1 Marc Mengel
625 1 Marc Mengel
626 1 Marc Mengel
p<>. %(#62439)&nbsp;% The basic structure of table file contents consists of an instance identifier followed by one or more actions (described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] ). By the time %{font-weight: bold;color: #000000}UPS% accesses the table file, it has already determined the database, product name and product version. Therefore FLAVOR and QUALIFIERS together are sufficient to identify the instance.
627 1 Marc Mengel
628 1 Marc Mengel
p<>. %(#73104)&nbsp;% Here is a sample table file that illustrates the basic structure:
629 1 Marc Mengel
630 1 Marc Mengel
631 1 Marc Mengel
<pre>
632 1 Marc Mengel
File=Table
633 1 Marc Mengel
Product=exmh
634 1 Marc Mengel
635 1 Marc Mengel
FLAVOR=SunOS+5
636 1 Marc Mengel
QUALIFIERS=""
637 1 Marc Mengel
638 1 Marc Mengel
   ACTION=SETUP
639 1 Marc Mengel
      setupRequired(expect)
640 1 Marc Mengel
      setupRequired(mh)
641 1 Marc Mengel
      ...
642 1 Marc Mengel
   ACTION=UNSETUP
643 1 Marc Mengel
      ...
644 1 Marc Mengel
</pre>
645 1 Marc Mengel
646 1 Marc Mengel
647 1 Marc Mengel
p<>. %(#64726)&nbsp;% User-defined keywords, described in section [[files_intro#35506|28.2 %{font-weight: normal;color: #000000}Keywords: Information Storage Format% ]] , can also be included after an instance identifier for use within actions.
648 1 Marc Mengel
649 1 Marc Mengel
650 1 Marc Mengel
h3.  %(#34894)&nbsp;% 36.4.2 Grouping Information
651 1 Marc Mengel
652 1 Marc Mengel
653 1 Marc Mengel
p<>. %(#62624)&nbsp;% When a single table file represents multiple instances, a grouping structure can be superimposed on this basic structure to organize the information. To avoid having to repeat identical actions for a series of FLAVOR/QUALIFIER identifiers, the keyword FLAVOR can take the value ANY in table files. FLAVOR=ANY is taken as a best match, assuming all other instance identifiers match (see [[matching#8463|Chapter 27: %{font-weight: normal;color: #000000}Product Instance Matching in UPS/UPD Commands% ]] for more information on instance selection).
654 1 Marc Mengel
655 1 Marc Mengel
p<>. %(#34895)&nbsp;% Grouping information within table files is supported via the use of the following three markers:
656 1 Marc Mengel
657 1 Marc Mengel
p<>. %(#80250)&nbsp;% GROUP:
658 1 Marc Mengel
659 1 Marc Mengel
p<>. %(#80251)&nbsp;% Groups together multiple flavor/qualifier pairs. All entries subsequent to GROUP: are part of this group until an END: marker is found.
660 1 Marc Mengel
661 1 Marc Mengel
p<>. %(#80252)&nbsp;% COMMON:
662 1 Marc Mengel
663 1 Marc Mengel
p<>. %(#80253)&nbsp;% Groups together actions that apply to all instances represented in GROUP:. COMMON: is only valid within a GROUP:.
664 1 Marc Mengel
665 1 Marc Mengel
p<>. %(#80254)&nbsp;% END:
666 1 Marc Mengel
667 1 Marc Mengel
p<>. %(#80255)&nbsp;% Marks the end of a GROUP: or COMMON:. One END: marker is used to jointly end a GROUP: and an included COMMON:.
668 1 Marc Mengel
669 1 Marc Mengel
p<>. %(#34899)&nbsp;%  %{font-weight: bold;color: #000000}UPS% does not %{font-weight: normal;color: #000000}require% grouping in table files; these markers are available for convenience and for organizing information clearly. However, if GROUP: or COMMON: is used, END: must appear at the end of it, even if that is the very end of the file.
670 1 Marc Mengel
671 1 Marc Mengel
672 1 Marc Mengel
h3.  %(#34504)&nbsp;% 36.4.3 The Order of Elements
673 1 Marc Mengel
674 1 Marc Mengel
675 1 Marc Mengel
p<>. %(#34937)&nbsp;% Blank lines are ignored, and therefore can be placed anywhere.
676 1 Marc Mengel
677 1 Marc Mengel
678 1 Marc Mengel
* The first keywords after GROUP: must always be FLAVOR followed by QUALIFIERS (i.e., the instance identifiers).
679 1 Marc Mengel
* FLAVOR and QUALIFIERS %{font-weight: normal;color: #000000}cannot% be included within a COMMON: grouping.
680 1 Marc Mengel
* User-defined keywords can be defined anywhere except between GROUP: and the instance identifiers.
681 1 Marc Mengel
* Actions (described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] ) for each instance are located after the instance-identifying keywords, and often between a COMMON: and END:.
682 1 Marc Mengel
* All actions after COMMON: apply to all the FLAVOR-QUALIFIERS pairs listed above it within the current GROUP:.
683 1 Marc Mengel
* All statements apply to the most recently defined FLAVOR/QUALIFIER keywords except for the statements between COMMON: and END: (which apply to all the flavors in the current GROUP:)
684 1 Marc Mengel
* GROUP:s cannot be nested.
685 1 Marc Mengel
686 1 Marc Mengel
687 1 Marc Mengel
h2.  %(#72721)&nbsp;% 36.5 Product Dependencies
688 1 Marc Mengel
689 1 Marc Mengel
690 1 Marc Mengel
p<>. %(#40272)&nbsp;% Typically users want to setup the default current version of a product. In some projects, the only thing that needs to be specified is the product name. In other projects, each setup command must have a qualifier to ensure that the exact version and qualifiers are requested. The reason is that a default qualifier might change in a poorly documented fashion, making it difficult to reproduce results.
691 1 Marc Mengel
692 1 Marc Mengel
p<>. For example, to setup an instance of art, the command is:
693 1 Marc Mengel
694 1 Marc Mengel
695 1 Marc Mengel
<pre>
696 1 Marc Mengel
% setup -B art v1_08_09 -q+e4:+mu2e:+prof
697 1 Marc Mengel
</pre>
698 1 Marc Mengel
699 1 Marc Mengel
700 1 Marc Mengel
p<>. The version is specified as v1_08_09. Qualifiers are used to keep the bookkeeping straight for multiple builds of one version of a product. e4 in shorthand defined by the art team for a compiler version and other specifics. When another product is built with the "e4" qualifier, it can be linked against a version of art that was also built with the "e4" qualifier. The qualifier "prof" requests a version that was built with maximum optimization and with some, but not all, debugger symbols retained. The symbols retained are enough to profile the code and to get a traceback from a core dump. (But not enough to do full line by line debugging.) The name "prof" is motivated by the notion that the build retains enough debugger symbols for profiling.
701 1 Marc Mengel
702 1 Marc Mengel
p<>. %(#36386)&nbsp;% For more examples, see the reference section [[upscommands#112805|23.1 %{font-weight: normal;color: #000000}setup% ]] .
703 1 Marc Mengel
704 1 Marc Mengel
705 1 Marc Mengel
h3.  %(#72804)&nbsp;% 36.5.1 Defining Dependencies
706 1 Marc Mengel
707 1 Marc Mengel
708 1 Marc Mengel
p<>. %(#72724)&nbsp;%  %{font-weight: bold;color: #000000}UPS% product dependencies get listed in the SETUP action for the product instance in question. The %{font-weight: bold;font-family: monospace}setupRequired% and %{font-weight: bold;font-family: monospace}setupOptional% functions, described in section [[functions#38473|35.3 %{font-weight: normal;color: #000000}Function Descriptions% ]] , can be used within the SETUP action to setup the dependencies along with the main product. These two functions take the same set of options and arguments as a normal %{font-weight: bold;font-family: monospace}setup% command (see section [[upscommands#112805|23.1 %{font-weight: normal;color: #000000}setup% ]] ) in order to clearly specify the desired instance of the dependent product. We discourage specification of particular versions of products, and recommend using chains instead, e.g.,:
709 1 Marc Mengel
710 1 Marc Mengel
711 1 Marc Mengel
<pre>
712 1 Marc Mengel
ACTION=SETUP
713 1 Marc Mengel
  setupRequired("perl")
714 1 Marc Mengel
</pre>
715 1 Marc Mengel
716 1 Marc Mengel
717 1 Marc Mengel
p<>. %(#72733)&nbsp;% This example sets up the default instance of %{font-weight: bold;color: #000000}perl% , chained to current. Using chains, it is easier to keep the dependencies and the main product in sync.
718 1 Marc Mengel
719 1 Marc Mengel
p<>. %(#72816)&nbsp;% Products that are not maintained in the %{font-weight: bold;color: #000000}UPS% framework can also be designated as dependencies. You would need to use the function %{font-weight: bold;font-family: monospace}exeAccess% to locate and access a non- %{font-weight: bold;color: #000000}UPS% executable through your $PATH. For example, the action:
720 1 Marc Mengel
721 1 Marc Mengel
722 1 Marc Mengel
<pre>
723 1 Marc Mengel
ACTION=SETUP
724 1 Marc Mengel
  setupOptional(gcc)
725 1 Marc Mengel
  exeAccess(gcc)
726 1 Marc Mengel
</pre>
727 1 Marc Mengel
728 1 Marc Mengel
729 1 Marc Mengel
p<>. %(#72820)&nbsp;% tells %{font-weight: bold;color: #000000}UPS% to setup the current instance of %{font-weight: bold;color: #000000}gcc% if there is one declared; the %{font-weight: bold;font-family: monospace}exeAccess% function checks for a version of %{font-weight: bold;color: #000000}gcc% in your $PATH, even if it's not one that is managed by %{font-weight: bold;color: #000000}UPS% , and exits with an error if one is not found.
730 1 Marc Mengel
731 1 Marc Mengel
732 1 Marc Mengel
h3.  %(#72764)&nbsp;% 36.5.2 Product Dependency Conflicts
733 1 Marc Mengel
734 1 Marc Mengel
735 1 Marc Mengel
p<>. %(#72766)&nbsp;% When different dependencies include the same product via different dependency trees (and therefore may require different instances of the same product), rules have been established to determine which instance of the dependent product is selected and in which order the required products are setup.
736 1 Marc Mengel
737 1 Marc Mengel
738 1 Marc Mengel
h4.  %(#72767)&nbsp;% Selection Algorithm for Conflicting Dependencies
739 1 Marc Mengel
740 1 Marc Mengel
741 1 Marc Mengel
p<>. %(#72768)&nbsp;% The rules are as follows:
742 1 Marc Mengel
743 1 Marc Mengel
744 1 Marc Mengel
# First level product dependencies, defined as those products listed as dependencies in the table file of the main product instance, take precedence over lower level dependencies when selecting which instance of the required product to set up.
745 1 Marc Mengel
# Dependencies listed later in the table file take precedence over those listed earlier.
746 1 Marc Mengel
747 1 Marc Mengel
748 1 Marc Mengel
h4.  %(#72771)&nbsp;% Example of Dependency Selection and Order of Setup
749 1 Marc Mengel
750 1 Marc Mengel
751 1 Marc Mengel
p<>. %(#72773)&nbsp;% We'll take you through an example that illustrates how the dependencies are selected and in what order they are setup. Our sample dependency structure starts with the product %{font-weight: bold;color: #000000}A% as the parent product. It has two dependencies, which in turn have dependencies of their own. %{font-family: monospace}B b1% refers to product %{font-weight: bold;color: #000000}B% , version b1, and so on. (We recommend that developers avoid using specific version dependencies in general; we use them in our example for illustrative purposes.) Some of the dependencies are conflicting:
752 1 Marc Mengel
753 1 Marc Mengel
p<>. %(#72774)&nbsp;% In %{font-weight: bold;color: #000000}A% 's table file:
754 1 Marc Mengel
755 1 Marc Mengel
756 1 Marc Mengel
<pre>
757 1 Marc Mengel
product A
758 1 Marc Mengel
setupRequired(B b1)
759 1 Marc Mengel
setupRequired(C c1)
760 1 Marc Mengel
</pre>
761 1 Marc Mengel
762 1 Marc Mengel
763 1 Marc Mengel
p<>. %(#72778)&nbsp;% In %{font-weight: bold;color: #000000}B b1% 's table file:
764 1 Marc Mengel
765 1 Marc Mengel
766 1 Marc Mengel
<pre>
767 1 Marc Mengel
product B b1
768 1 Marc Mengel
setupRequired(C c2)
769 1 Marc Mengel
setupRequired(D d1)
770 1 Marc Mengel
</pre>
771 1 Marc Mengel
772 1 Marc Mengel
773 1 Marc Mengel
p<>. %(#72782)&nbsp;% In %{font-weight: bold;color: #000000}C c2% 's table file:
774 1 Marc Mengel
775 1 Marc Mengel
776 1 Marc Mengel
<pre>
777 1 Marc Mengel
product C c2
778 1 Marc Mengel
setupRequired(D d3)
779 1 Marc Mengel
</pre>
780 1 Marc Mengel
781 1 Marc Mengel
782 1 Marc Mengel
p<>. %(#72785)&nbsp;% In %{font-weight: bold;color: #000000}C c1% 's table file:
783 1 Marc Mengel
784 1 Marc Mengel
785 1 Marc Mengel
<pre>
786 1 Marc Mengel
product C c1
787 1 Marc Mengel
setupRequired(D d2)
788 1 Marc Mengel
</pre>
789 1 Marc Mengel
790 1 Marc Mengel
791 1 Marc Mengel
p<>. %(#72788)&nbsp;% The tree is traversed starting at %{font-weight: bold;color: #000000}A% , then going down each dependency branch. So the order in which the products are encountered is:
792 1 Marc Mengel
793 1 Marc Mengel
794 1 Marc Mengel
#  %{font-weight: bold;color: #000000}A% (no conflict)
795 1 Marc Mengel
#  %{font-weight: bold;color: #000000}A% 's dependencies %{font-weight: bold;color: #000000}B b1% and %{font-weight: bold;color: #000000}C c1% are selected since they are the highest level dependencies.
796 1 Marc Mengel
# Start down %{font-weight: bold;color: #000000}B b1% branch: find %{font-weight: bold;color: #000000}C c2% (version %{font-weight: bold;color: #000000}c1% already selected by rule 1; %{font-weight: bold;color: #000000}C c2% ignored)
797 1 Marc Mengel
# Completing the %{font-weight: bold;color: #000000}B b1% branch, find %{font-weight: bold;color: #000000}D d1% . It is examined, and ultimately passed over (by rule 2) because %{font-weight: bold;color: #000000}D d2% , a dependency of %{font-weight: bold;color: #000000}C c1% and therefore also a second-level dependency of %{font-weight: bold;color: #000000}A% , is encountered later.
798 1 Marc Mengel
799 1 Marc Mengel
800 1 Marc Mengel
h2.  %(#36685)&nbsp;% 36.6 Keywords that can be Used in Table Files
801 1 Marc Mengel
802 1 Marc Mengel
803 1 Marc Mengel
p<>. %(#73265)&nbsp;% 
804 1 Marc Mengel
805 1 Marc Mengel
|_.  %{font-weight: normal;color: #000000}Keyword and%   %{font-weight: normal;color: #000000}Keyword and%  Default Value (if any) Default Value (if any) |_. Description and Description and Notes (if any) Notes (if any) |
806 1 Marc Mengel
|ACTION ACTION |defines an action (described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] ), i.e., groups together a list of functions associated with a command (e.g., ACTION=SETUP) defines an action (described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] ), i.e., groups together a list of functions associated with a command (e.g., ACTION=SETUP) |
807 1 Marc Mengel
|CATMAN_SOURCE_DIR CATMAN_SOURCE_DIR Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toman/catman% directory Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toman/catman% directory |location of catman files (formatted man page files) included with instance location of catman files (formatted man page files) included with instance |
808 1 Marc Mengel
|COMMON: COMMON: |groups together actions that apply to all instances represented in "GROUP:"; groups together actions that apply to all instances represented in "GROUP:"; COMMON: is only valid within a GROUP: COMMON: is only valid within a GROUP: |
809 1 Marc Mengel
|DESCRIPTION DESCRIPTION |product description product description |
810 1 Marc Mengel
|END: END: |marks the end of a "GROUP:" or "COMMON:"; one "END:" marker is used to jointly end a "GROUP:" and an included "COMMON:" marks the end of a "GROUP:" or "COMMON:"; one "END:" marker is used to jointly end a "GROUP:" and an included "COMMON:" |
811 1 Marc Mengel
|FILE FILE |type of file (possible values: DBCONFIG, UPDCONFIG, CHAIN, VERSION, TABLE) type of file (possible values: DBCONFIG, UPDCONFIG, CHAIN, VERSION, TABLE) |
812 1 Marc Mengel
|FLAVOR FLAVOR |product instance flavor product instance flavor Note: To easily accommodate flavor-neutral %{font-weight: bold;font-family: monospace}setup% functions in a table file, FLAVOR can take the value ANY, but %{font-weight: normal;color: #000000}only% in a table file. Note: To easily accommodate flavor-neutral %{font-weight: bold;font-family: monospace}setup% functions in a table file, FLAVOR can take the value ANY, but %{font-weight: normal;color: #000000}only% in a table file. |
813 1 Marc Mengel
|GROUP: GROUP: |groups together multiple instances; all entries subsequent to this "GROUP:" are part of it until an "END:" marker is reached groups together multiple instances; all entries subsequent to this "GROUP:" are part of it until an "END:" marker is reached |
814 1 Marc Mengel
|INFO_SOURCE_DIR INFO_SOURCE_DIR Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toInfo% directory Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toInfo% directory |location of Info files included with instance location of Info files included with instance |
815 1 Marc Mengel
|MAN_SOURCE_DIR MAN_SOURCE_DIR Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toman/man% directory Default: under the %{font-family: monospace}${UPS_UPS_DIR}/ toman/man% directory |location of unformatted man page files included with instance location of unformatted man page files included with instance |
816 1 Marc Mengel
|PRODUCT PRODUCT |product name product name |
817 1 Marc Mengel
|QUALIFIERS QUALIFIERS |additional instance specification information often used to indicate compilation options used by developer additional instance specification information often used to indicate compilation options used by developer Notes: appears immediately after a FLAVOR in these files, and is coupled with it to complete the instance identification (see [[matching#37834|27.2.3 %{font-weight: normal;color: #000000}Qualifiers: Use in Instance Matching% ]] ) Notes: appears immediately after a FLAVOR in these files, and is coupled with it to complete the instance identification (see [[matching#37834|27.2.3 %{font-weight: normal;color: #000000}Qualifiers: Use in Instance Matching% ]] ) |
818 1 Marc Mengel
|UPS_DB_VERSION UPS_DB_VERSION | %{font-weight: bold;color: #000000}UPS% database version  %{font-weight: bold;color: #000000}UPS% database version |
819 1 Marc Mengel
|USER USER |current username current username |
820 1 Marc Mengel
|VERSION VERSION |product version product version |
821 1 Marc Mengel
|_UPD_OVERLAY _UPD_OVERLAY |main product name for overlaid product main product name for overlaid product Note: This keyword is user-defined from %{font-weight: bold;color: #000000}UPS% 's point of view. It is included here because it is configured and used by %{font-weight: bold;color: #000000}UPD% . Its use with overlaid products is described in section [[files_intro#65610|28.6.6 %{font-weight: normal;color: #000000}_UPD_OVERLAY% ]] . Note: This keyword is user-defined from %{font-weight: bold;color: #000000}UPS% 's point of view. It is included here because it is configured and used by %{font-weight: bold;color: #000000}UPD% . Its use with overlaid products is described in section [[files_intro#65610|28.6.6 %{font-weight: normal;color: #000000}_UPD_OVERLAY% ]] . |
822 1 Marc Mengel
823 1 Marc Mengel
824 1 Marc Mengel
h2.  %(#73264)&nbsp;% 36.7 Table File Examples
825 1 Marc Mengel
826 1 Marc Mengel
827 1 Marc Mengel
h3.  %(#62652)&nbsp;% 36.7.1 Example Illustrating Use of FLAVOR=ANY
828 1 Marc Mengel
829 1 Marc Mengel
830 1 Marc Mengel
p<>. %(#62698)&nbsp;% Below is a sample table file for the product %{font-weight: bold;color: #000000}exmh% version v1_6_6 which uses FLAVOR=ANY. For the %{font-weight: bold;color: #000000}exmh% instances whose version files point to this table file, all except those with qualifiers share the same stanza:
831 1 Marc Mengel
832 1 Marc Mengel
833 1 Marc Mengel
<pre>
834 1 Marc Mengel
File=Table
835 1 Marc Mengel
Product=exmh
836 1 Marc Mengel
#*************************************************
837 1 Marc Mengel
# Starting Group definition
838 1 Marc Mengel
Group:
839 1 Marc Mengel
Flavor=ANY
840 1 Marc Mengel
Qualifiers=""
841 1 Marc Mengel
842 1 Marc Mengel
Common:
843 1 Marc Mengel
   Action=setup
844 1 Marc Mengel
      setupRequired(expect)
845 1 Marc Mengel
      setupRequired(mh)
846 1 Marc Mengel
      setupOptional(glimpse)
847 1 Marc Mengel
      setupOptional(www)
848 1 Marc Mengel
      setupOptional(mimetools)
849 1 Marc Mengel
      setupOptional(ispell)
850 1 Marc Mengel
      setupOptional(popclient)
851 1 Marc Mengel
      prodDir()
852 1 Marc Mengel
      setupEnv()
853 1 Marc Mengel
      pathPrepend(PATH,${UPS_PROD_DIR}/bin)
854 1 Marc Mengel
   Action=configure
855 1 Marc Mengel
      execute(${UPS_PROD_DIR}/ups/configure,UPS_ENV)
856 1 Marc Mengel
End:
857 1 Marc Mengel
</pre>
858 1 Marc Mengel
859 1 Marc Mengel
860 1 Marc Mengel
p<>. %(#62688)&nbsp;% Actions, functions and variables as used in this example are described in [[actions#62841|Chapter 34: %{font-weight: normal;color: #000000}Actions and ACTION Keyword Values% ]] , section [[functions#38473|35.3 %{font-weight: normal;color: #000000}Function Descriptions% ]] and section [[functions#34716|35.6 %{font-weight: normal;color: #000000}Local Read-Only Variables Available to Functions% ]] , respectively.
861 1 Marc Mengel
862 1 Marc Mengel
p<>. %(#62715)&nbsp;% You'll notice that there are no functions specified for %{font-weight: bold;font-family: monospace}unsetup% in this table file. Due to the defaults that %{font-weight: bold;color: #000000}UPS% has in place, when %{font-weight: bold;font-family: monospace}unsetup% is run all of the %{font-weight: bold;font-family: monospace}setup% functions will be reversed (the required products will get unsetup, the defined environment variables will get undefined, and the product's %{font-family: monospace}bin% directory will be dropped from $PATH. See sections [[actions#62754|34.2.2 %{font-weight: normal;color: #000000}"Uncommands" as Actions% ]] and [[functions#38469|35.2 %{font-weight: normal;color: #000000}Reversible Functions% ]] .
863 1 Marc Mengel
864 1 Marc Mengel
865 1 Marc Mengel
h3.  %(#62378)&nbsp;% 36.7.2 Example Showing Grouping
866 1 Marc Mengel
867 1 Marc Mengel
868 1 Marc Mengel
p<>. %(#62694)&nbsp;% Grouping is illustrated in the following example:
869 1 Marc Mengel
870 1 Marc Mengel
871 1 Marc Mengel
<pre>
872 1 Marc Mengel
FILE=Table
873 1 Marc Mengel
PRODUCT=exmh
874 1 Marc Mengel
#*************************************************
875 1 Marc Mengel
# Starting Group definition
876 1 Marc Mengel
GROUP:
877 1 Marc Mengel
FLAVOR=IRIX+5
878 1 Marc Mengel
QUALIFIERS=""
879 1 Marc Mengel
880 1 Marc Mengel
FLAVOR=IRIX+5
881 1 Marc Mengel
QUALIFIERS="mips2"
882 1 Marc Mengel
883 1 Marc Mengel
COMMON:
884 1 Marc Mengel
   ACTION=SETUP
885 1 Marc Mengel
      setupOptional(expect)
886 1 Marc Mengel
      ...
887 1 Marc Mengel
   ACTION=CONFIGURE
888 1 Marc Mengel
      execute(${UPS_PROD_DIR}/ups/configure,UPS_ENV)
889 1 Marc Mengel
   ...
890 1 Marc Mengel
END:
891 1 Marc Mengel
#*************************************************
892 1 Marc Mengel
# Starting Group definition
893 1 Marc Mengel
GROUP:
894 1 Marc Mengel
FLAVOR=ANY
895 1 Marc Mengel
QUALIFIERS=""
896 1 Marc Mengel
897 1 Marc Mengel
COMMON:
898 1 Marc Mengel
   ACTION=SETUP
899 1 Marc Mengel
      setupRequired(expect)
900 1 Marc Mengel
      ...
901 1 Marc Mengel
   ACTION=CONFIGURE
902 1 Marc Mengel
      execute(${UPS_PROD_DIR}/ups/configure,UPS_ENV)
903 1 Marc Mengel
   ...
904 1 Marc Mengel
END:
905 1 Marc Mengel
</pre>
906 1 Marc Mengel
907 1 Marc Mengel
908 1 Marc Mengel
p<>. %(#73026)&nbsp;% The second group (defined by %{font-family: monospace}FLAVOR=ANY% ) matches all the instances not matched in the first group, except those with qualifiers.
909 1 Marc Mengel
910 1 Marc Mengel
911 1 Marc Mengel
h3.  %(#38896)&nbsp;% 36.7.3 Example with User-Defined Keywords
912 1 Marc Mengel
913 1 Marc Mengel
914 1 Marc Mengel
p<>. %(#64711)&nbsp;% User-defined keywords are described in section [[files_intro#35506|28.2 %{font-weight: normal;color: #000000}Keywords: Information Storage Format% ]] . All user-defined keywords must have underscore ( %{font-family: monospace}_% ) as the initial character (e.g., %{font-family: monospace}_dest_arch% ). The following example illustrates their use in a table file:
915 1 Marc Mengel
916 1 Marc Mengel
917 1 Marc Mengel
<pre>
918 1 Marc Mengel
File=Table
919 1 Marc Mengel
Product=vxboot
920 1 Marc Mengel
#*************************************************
921 1 Marc Mengel
# Starting Group definition
922 1 Marc Mengel
Group:
923 1 Marc Mengel
Flavor=NULL
924 1 Marc Mengel
Qualifiers="narrow29"
925 1 Marc Mengel
   _dest_arch=ppc
926 1 Marc Mengel
   _dest_env=VxWorks-5.3
927 1 Marc Mengel
   _dest_type=MVME2301
928 1 Marc Mengel
...
929 1 Marc Mengel
Common:
930 1 Marc Mengel
   Action=setup
931 1 Marc Mengel
      setupEnv()
932 1 Marc Mengel
      envSet (VXB_DEST_ARCH,${_dest_arch})
933 1 Marc Mengel
      envSet (VXB_DEST_ENV,${_dest_env})
934 1 Marc Mengel
      envSet (VXB_DEST_TYPE,${_dest_type})
935 1 Marc Mengel
...
936 1 Marc Mengel
</pre>
937 1 Marc Mengel
938 1 Marc Mengel
939 1 Marc Mengel
h3.  %(#64661)&nbsp;% 36.7.4 Examples Illustrating ExeActionOpt Function
940 1 Marc Mengel
941 1 Marc Mengel
942 1 Marc Mengel
h4.  %(#72558)&nbsp;% Example 1
943 1 Marc Mengel
944 1 Marc Mengel
945 1 Marc Mengel
p<>. %(#72633)&nbsp;% In this example, there are actions for the first two instance identifiers, but not for the third. We want to execute the XYZ action at setup time if it's there, but continue processing if it's not. To do this, we must call the action using the %{font-weight: bold;font-family: monospace}exeActionOpt% function.
946 1 Marc Mengel
947 1 Marc Mengel
948 1 Marc Mengel
<pre>
949 1 Marc Mengel
FILE=Table
950 1 Marc Mengel
PRODUCT=fred
951 1 Marc Mengel
#*************************************************
952 1 Marc Mengel
# Starting Group definition
953 1 Marc Mengel
GROUP:
954 1 Marc Mengel
FLAVOR=SunOS+6
955 1 Marc Mengel
QUALIFIERS=""
956 1 Marc Mengel
   ACTION=XYZ
957 1 Marc Mengel
      fileTest(/, -w, "You must be root to run this command.")
958 1 Marc Mengel
959 1 Marc Mengel
FLAVOR=IRIX+6
960 1 Marc Mengel
QUALIFIERS=""
961 1 Marc Mengel
   ACTION=XYZ
962 1 Marc Mengel
      fileTest(/, -w, "You must be root to run this command.")
963 1 Marc Mengel
964 1 Marc Mengel
FLAVOR=IRIX+6
965 1 Marc Mengel
QUALIFIERS="mips2"
966 1 Marc Mengel
#  No XYZ action
967 1 Marc Mengel
968 1 Marc Mengel
COMMON:
969 1 Marc Mengel
   ACTION=SETUP
970 1 Marc Mengel
      exeActionOpt(XYZ)
971 1 Marc Mengel
972 1 Marc Mengel
 END:
973 1 Marc Mengel
...
974 1 Marc Mengel
</pre>
975 1 Marc Mengel
976 1 Marc Mengel
977 1 Marc Mengel
h4.  %(#72563)&nbsp;% Example 2
978 1 Marc Mengel
979 1 Marc Mengel
980 1 Marc Mengel
p<>. %(#72650)&nbsp;% In this example, we use the %{font-weight: bold;font-family: monospace}exeActionOpt% function to instruct %{font-weight: bold;color: #000000}UPS% to execute one action or another, depending on whether the user supplies an option on the %{font-weight: bold;font-family: monospace}setup% command line.
981 1 Marc Mengel
982 1 Marc Mengel
983 1 Marc Mengel
<pre>
984 1 Marc Mengel
FILE=Table
985 1 Marc Mengel
PRODUCT=fred
986 1 Marc Mengel
#*************************************************
987 1 Marc Mengel
# Starting Group definition
988 1 Marc Mengel
GROUP:
989 1 Marc Mengel
FLAVOR=ANY
990 1 Marc Mengel
QUALIFIERS=""
991 1 Marc Mengel
992 1 Marc Mengel
   ACTION=SETUP
993 1 Marc Mengel
      exeActionOpt(XYZ_${UPS_OPTIONS})
994 1 Marc Mengel
995 1 Marc Mengel
   ACTION=XYZ_
996 1 Marc Mengel
      function_1()
997 1 Marc Mengel
   ACTION=XYZ_FULL_LICENSE
998 1 Marc Mengel
      function_2()
999 1 Marc Mengel
...
1000 1 Marc Mengel
</pre>
1001 1 Marc Mengel
1002 1 Marc Mengel
1003 1 Marc Mengel
p<>. %(#72433)&nbsp;% If you run:
1004 1 Marc Mengel
1005 1 Marc Mengel
1006 1 Marc Mengel
<pre>
1007 1 Marc Mengel
% setup fred
1008 1 Marc Mengel
</pre>
1009 1 Marc Mengel
1010 1 Marc Mengel
1011 1 Marc Mengel
p<>. %(#72612)&nbsp;% you'll execute ACTION XYZ_. To execute ACTION XYZ_FULL_LICENSE, you need to run:
1012 1 Marc Mengel
1013 1 Marc Mengel
1014 1 Marc Mengel
<pre>
1015 1 Marc Mengel
% setup fred -O FULL_LICENSE
1016 1 Marc Mengel
</pre>
1017 1 Marc Mengel
1018 1 Marc Mengel
1019 1 Marc Mengel
h3.  %(#65661)&nbsp;% 36.7.5 Examples Illustrating Failure Return Codes
1020 1 Marc Mengel
1021 1 Marc Mengel
1022 1 Marc Mengel
p<>. Users may want to propagate a failure through a ups build script, so that the ups build doesn't exit with success when something failed. If you want a ups action to fail and exit if any of the individual commands fail, you can:
1023 1 Marc Mengel
1024 1 Marc Mengel
1025 1 Marc Mengel
<pre>
1026 1 Marc Mengel
Execute(set -e, NO_UPS_ENV)
1027 1 Marc Mengel
</pre>
1028 1 Marc Mengel
1029 1 Marc Mengel
in your ups action, and the first command that fails will fail the action, or if you want to check particular steps, you can
1030 1 Marc Mengel
1031 1 Marc Mengel
<pre>
1032 1 Marc Mengel
Execute( some_command || exit 1 , NO_UPS_ENV)
1033 1 Marc Mengel
</pre>
1034 1 Marc Mengel
1035 1 Marc Mengel
It will fail if some_command fails.
1036 1 Marc Mengel
p<>. For example:
1037 1 Marc Mengel
1038 1 Marc Mengel
1039 1 Marc Mengel
<pre>
1040 1 Marc Mengel
----------------------
1041 1 Marc Mengel
File    = table
1042 1 Marc Mengel
Product = foo
1043 1 Marc Mengel
1044 1 Marc Mengel
Flavor=ANY
1045 1 Marc Mengel
Qualifiers=
1046 1 Marc Mengel
1047 1 Marc Mengel
action = build
1048 1 Marc Mengel
      Execute(/bin/true  || exit 1, NO_UPS_ENV)
1049 1 Marc Mengel
      Execute(/bin/false || exit 2, NO_UPS_ENV)
1050 1 Marc Mengel
      Execute(/bin/true  || exit 3, NO_UPS_ENV)
1051 1 Marc Mengel
----------------------
1052 1 Marc Mengel
</pre>
1053 1 Marc Mengel
1054 1 Marc Mengel
A "ups build -m foo.table foo" will fail with an exit code of 2, because /bin/false fails. Note: don't exit during a setup script unless you want to log the user out, which is probably not a good idea.
1055 1 Marc Mengel
1056 1 Marc Mengel
<pre>
1057 1 Marc Mengel
or in the "set -e"  case:
1058 1 Marc Mengel
------------------------
1059 1 Marc Mengel
File    = table
1060 1 Marc Mengel
Product = foo
1061 1 Marc Mengel
1062 1 Marc Mengel
Flavor=ANY
1063 1 Marc Mengel
Qualifiers=
1064 1 Marc Mengel
1065 1 Marc Mengel
action = build
1066 1 Marc Mengel
      Execute(set -e, NO_UPS_ENV)
1067 1 Marc Mengel
      Execute(echo first, NO_UPS_ENV)
1068 1 Marc Mengel
      Execute(/bin/false, NO_UPS_ENV)
1069 1 Marc Mengel
      Execute(echo second, NO_UPS_ENV)
1070 1 Marc Mengel
------------------------
1071 1 Marc Mengel
1072 1 Marc Mengel
if you do:
1073 1 Marc Mengel
--------------
1074 1 Marc Mengel
% ups build -m foo.table foo
1075 1 Marc Mengel
first
1076 1 Marc Mengel
ERROR: Error in call to system: error from subprocess
1077 1 Marc Mengel
--------------
1078 1 Marc Mengel
</pre>
1079 1 Marc Mengel
1080 1 Marc Mengel
it returns an exit code of 1, and does not do the "echo second".
1081 1 Marc Mengel
p<>. In any other case, the ups action yeilds the exit code of the *last* command in the action.
1082 1 Marc Mengel
1083 1 Marc Mengel
p<>. %(#32782)&nbsp;% 
1084 1 Marc Mengel
1085 1 Marc Mengel
p<>. %(#72619)&nbsp;% 
1086 1 Marc Mengel
1087 1 Marc Mengel
| [[upsv4TOC| !{width:84px;height:23px}images/navtoc.gif(TOC)!  ]] | [[functions| !{width:81px;height:23px}images/navprev.gif(PREV)!  ]] | [[extrascripts| !{width:81px;height:23px}images/navnext.gif(NEXT)!  ]] |
1088 1 Marc Mengel
1089 1 Marc Mengel
1090 1 Marc Mengel
p<>. **Last revised on September 2014** 
1091 1 Marc Mengel