TOC PREV NEXT
Fermilab CD logo Complete Guide and Reference Manual for UPS and UPD

Chapter Contents

Chapter 11: Maintaining a UPS Database
  11.1 Declare an Instance
    11.1.1 The ups declare Command
    11.1.2 Examples
  11.2 Declare a Chain
    11.2.1 The ups declare Command with Chain Specification
    11.2.2 Examples
  11.3 Remove a Chain
  11.4 Change a Chain
  11.5 Undeclare and Remove an Instance
    11.5.1 Using ups undeclare to Remove a Product
    11.5.2 Undoing Configuration Steps
  11.6 Verify Integrity of an Instance
  11.7 Modify Information in a Database File
  11.8 Determine If a Product Needs to be Updated
  11.9 Update a Table File or ups Directory
  11.10 Retrieve an Individual File
  11.11 Check Product Accessibility
  11.12 Troubleshooting


Chapter 11: Maintaining a UPS Database


This chapter assumes UPS/UPD is installed with a working database and products area. Instructions and examples are provided for performing the following functions:

To get command usage information or on-line help, use the following resources:

11.1 Declare an Instance

A product instance must exist on the system before it can be declared to a UPS database. Product declaration is done with the ups declare command. Declaring a product instance makes it known to UPS, and therefore retrievable within the UPS framework. Normally products are installed on user nodes using the upd install command which, in addition to downloading and installing the product, runs ups declare to make the initial declaration of the product to the local UPS database. If tar or FTP is used to download a product, then you'll need to declare it manually. Refer to Chapter 7: Installing Products using tar or Chapter 8: Installing Products using FTP on a UPD Distribution Node for details about installing with FTP.

If upd install is used with more than one database, refer to section 6.3 How UPD Selects the Database to see how UPD determines the database for the declaration.

11.1.1 The ups declare Command

Before declaring, make sure the product is unwound into in its final location. Also make sure that you've downloaded the table file and installed it in an appropriate directory. For an initial declaration, specify at a minimum: the product name, product version, product root directory, flavor and table file name.

The full command description and option list is in the reference section 23.5 ups declare. Here we show commonly used command options (see the notes regarding -z, -U and -M which follow):

% ups declare <product> <version> -r /path/to/prod/root/dir/ \ 
  -f <flavor> [-z /path/to/database] [-U /path/to/ups/dir] \ 
  [-m <table_name>.table] [-M /path/to/table/file/dir] \ 
  [<chainFlag>] 
  1. If the database is not specified using -z, UPS declares the product into the first listed database in $PRODUCTS (see section 27.1 Database Selection Algorithm for more information).
  2. If the product's ups directory tar file was unwound in the default location ($<PRODUCT>_DIR/ups), then -U /path/to/ups/dir is not needed. If the ups directory is located elsewhere (or named differently), this specification must be included. If specified as a relative path, it is taken as relative to the product root directory.
  3. If the product's table file was placed in either of the two default locations (under /path/to/database/<product>/ or in the product's ups directory), then -M /path/to/table/file/dir is not needed. Only use the -M option if the table file has been moved to a separate location where UPS won't otherwise find it. If specified as a relative path, it is taken as relative to the product root directory. See section 29.4 Determination of ups Directory and Table File Locations for details on how UPS finds the table file.

Unless the product you're declaring has no table file, make sure its location gets declared properly, either explicitly or by default. Otherwise, users will need to specify its name and location on the command line every time they want to run or operate on the product. If it is neither declared nor specified on the command line, UPS/UPD assumes there is no table file.

A chain to the product instance can be declared at this time or in a later declaration. To declare a chain, include the appropriate chain flag in the command. This is described in section 11.2 Declare a Chain.

11.1.2 Examples

Declaration of New Product to Non-default Database

The following command shows a fairly typical product declaration. We'll install a product called histo v4_0 onto a Linux node. We assume the product instance's ups directory is maintained under its product root directory, and that it contains the table file. We include the -z option to indicate that we want to override the default database selection. This is the first instance of this product to be declared to this database, therefore the ups declare command automatically creates the appropriate product directory under the specified database:

% ups declare histo v4_0 -f Linux -m histo.table -z $MY_DB \ 
-r /path/to/products/Linux/histo/v4_0 

We can run a ups list -l command to see all the declaration information (include -a because it's not yet declared current):

% ups list -alz $MY_DB histo 
DATABASE=/path/to/ups_database/declared 
        Product=histo   Version=v4_0    Flavor=Linux 
                Qualifiers=""   Chain="" 
                Declared="2013-04-17 22.08.30 GMT" 
                Declarer="aheavey" 
                Modified="2013-04-17 22.08.30 GMT" 
                Modifier="aheavey" 
                Home=/path/to/products/Linux/histo/v4_0 
                No Compile Directive 
                Authorized, Nodes=* 
                UPS_Dir="ups" 
                Table_Dir="" 
                Table_File="v4_0.table" 
                Archive_File="" 
                Description="" 
                Action=setup 
                        prodDir() 
                        setupEnv() 
                        addalias(histo,${UPS_PROD_DIR}/bin/histo) 
                        addalias(hsdir,${UPS_PROD_DIR}/bin/hsdir) 
                        envSet(HISTO_INC,${UPS_PROD_DIR}/include) 

Declaration of Additional Instance of a Product

In the following example we declare an additional instance of histo, of the same version, but for the flavor Linux64bit+2. Again the table file resides under the product root directory's ups subdirectory, and we override the default database. This time we declare it with the chain "test" (-t):

% ups declare histo v4_0 -tf Linux64bit+2 -m histo.table -z $MY_DB \ 
-r /path/to/products/Linux64bit+2/histo/v4_0 

Running a ups list -a to see what the database now contains for this product, we find:

% ups list -az $MY_DB histo 
DATABASE=/path/to/ups_database/declared 
        Product=histo   Version=v4_0    Flavor=Linux 
                Qualifiers=""   Chain="" 
 
        Product=histo   Version=v4_0    Flavor=Linux64bit+2 
                Qualifiers=""   Chain=test 

Declaration with Table File Located in Database

Depending on the configuration, the table file may reside in the product's subdirectory under the database (e.g., $PRODUCTS/<product>/<table_file>).

A table file for the product must be placed in its permanent location before the instance is declared to the database. Therefore, if you are declaring the first instance of a product to the database, manually create the product directory under the database and copy the table file into it before declaring the instance.

Users do not need to specify the table file location (-M option) on the ups declare command line; UPS will find it here.

11.2 Declare a Chain

Chains are described briefly in section 2.3.5 Chains, and in detail in Chapter 30: Chain Files. Chains allow users to specify the version of a product according to its status rather than by its version number. A chain can be thought of as an alias for a particular product instance. A chain can be declared when the product instance is initially declared to the database or at a later time.

11.2.1 The ups declare Command with Chain Specification

To add a chain to a product instance, use the ups declare command with a chainFlag option. The chainFlag option can be one of the standard ones: -c, -d, -n, -o, or -t. chainFlag can also be replaced by -g chainName, where chainName is either one of the standard chain names: -g current, or a user-defined one. The full command description and option list is in section 23.5 ups declare. Here are some examples:

% ups declare -c [<other options>] <product> <version>  
% ups declare -g current [<other options>] <product> <version>  
% ups declare -g my_chain [<other options>] <product> <version>  

Declaring a chain is generally allowed on any node of a cluster, however if the corresponding chain action in the table file includes any node-specific or flavor-specific functions, we strongly recommend declaring the chain from that node, or from a node of that flavor to avoid mismatches. This should be noted in the INSTALL_NOTE file if it's necessary.

To include a chain in the initial declaration, simply add a chain option to the instance declaration. To add a chain to a previously declared product instance, include only the options required to identify the product instance and the chain option:

% ups declare -c <product> <version> [-f <flavor>] [-z <database>] 

In general, this does not change any existing chain, it adds a new one. However, if an instance is already chained, and you wish to declare a new instance of a different version but the same flavor/qualifier pair to the same chain, the pre-existing chain will be removed automatically. In other words, UPS ensures that a chain for a particular flavor/qualifier pair is unique.

A couple of examples will help to clarify how this works. In these examples we assume that the product instance has previously been declared to the database either with no chain or with a different chain.

11.2.2 Examples

Declare an Instance to the Database as test

In a typical situation, a product instance is initially declared as test (-t) to the default database, to be made current at a later date. In this example, we make an initial declaration as "test" of the product histo version v4_0, flavor Linux64bit+2, located in /usr/products/Linux64bit+2/histo/v4_0, with the table file name v4_0.table:

% ups declare -tr /usr/products/Linux64bit+2/histo/v4_0 -f Linux64bit+2 \ 
-m v4_0.table histo v4_0 

We verify the declaration using ups list -l -a:

% ups list -la histo -f Linux64bit+2 
DATABASE=/path/to/ups_database/declared 
        Product=histo   Version=v4_0    Flavor=Linux64bit+2 
                Qualifiers=""   Chains=test 
                Declared="2013-04-17 22.27.16 GMT:2013-04-17 22.27.16 GMT:2013- 
                Declarer="aheavey:aheavey" 
                Modified="2013-04-17 22.27.16 GMT:2013-04-17 22.27.16 GMT:2013- 
                Modifier="aheavey:aheavey" 
                Home=/path/to/products/Linux64bit+2/histo/0 
                No Compile Directive 
                Authorized, Nodes=* 
                UPS_Dir="ups" 
                Table_Dir="" 
                Table_File="v4_0.table" 
                Archive_File="" 
                Description="" 
                Action=setup 
                        prodDir() 
                        setupEnv() 
                        addalias(histo,${UPS_PROD_DIR}/bin/histo) 
                        addalias(hsdir,${UPS_PROD_DIR}/bin/hsdir) 
                        envSet(HISTO_INC,${UPS_PROD_DIR}/include)  

Notice that DECLARED, DECLARER, MODIFIED and MODIFIER all have two values. The first value is for the declaration to the database, the second is for the test chain declaration. In the following example, these fields acquire a third value when the chain is changed.

Change instance from test to current

Once testing is complete and successful, users take the product instance out of test and declare it as current. For the product instance of the previous example, we issue the command:

% ups declare -c histo v4_0 

This adds the current chain, but it does not remove or modify the test chain. Verify using ups list:

% ups list -a histo 
        Product=histo   Version=v4_0    Flavor=Linux64bit+2 
                Qualifiers=""   Chains=test,current  

If we use the long form, we see the additional declaration and modification userid and time (output edited for brevity):

% ups list -la histo 
DATABASE=/path/to/ups_database/declared 
        Product=histo   Version=v4_0    Flavor=Linux64bit+2 
                Qualifiers=""   Chains=test,current 
                Declared="2013-04-17 22.27.16 GMT:2013-04-17 22.27.16 GMT:2013-04-18  
22.00.16 GMT 
                Declarer="aheavey:aheavey:aheavey" 
                Modified="2013-04-17 22.27.16 GMT:2013-04-17 22.27.16 GMT:2013-04-18 
 22.00.16 GMT 
                Modifier="aheavey:aheavey:aheavey"  
                ... 

Change current Chain to Point to a New Instance

Another frequently encountered situation is a version is chained to current and the user wants to declare a different version of the product as current for the same flavor. We'll use the previous example histo v4_0, and declare version v4_1 as current:

% ups declare -c histo v4_1 

The previously current instance for this flavor/qualifier pair now has no current chain. Any other chains it may have had (test, in this case) remain unchanged.

11.3 Remove a Chain

To remove a chain from a product instance, use the ups undeclare command, or simply remove the chain file, or the portion of it that relates to the instance in question. It is usually easier and less error-prone to use the ups undeclare command. The full command description and option list is in section 23.19 ups undeclare.

The ups undeclare command has a simple syntax for removing chains:

% ups undeclare <chain_flag> <product> [-f <flavor>] [<other options>]  

Do not include the version in the command; it is incompatible with including the chain, and may result in removing the product declaration! It is recommended to always include the -f <flavor> option if you have a multi-flavored database.

As an example, let's remove the current chain from the current instance of ximagetools. Running ups list before and after, we see the current chain disappear:

% ups list -K+ ximagetools 
"ximagetools" "v4_0" "NULL" "" "current" 
% ups undeclare -c ximagetools -f NULL 
% ups list -aK+ ximagetools 
"ximagetools" "v4_0" "NULL" "" "" 

If multiple flavor/qualifier pairs have the same chain and thus share the chain file in question (in which case users must specify the flavor/qualifier information on the command line), only the portion of the file relating to the specified instance will get removed; the file itself will not be deleted.

11.4 Change a Chain

In general, changing the chain to a product instance requires removing the pre-existing chain and adding a new one. There is no way to directly change a chain.

When a current instance of a product already exists, if you declare a new instance of a different version but of the same flavor/qualifier pair as current, the current.chain file contents changes to point to the new version. This is true for any chain value, not just for current.

11.5 Undeclare and Remove an Instance

To undeclare a product instance means to remove all information pertaining to it from the UPS database in question. The information that gets removed includes:

The command ups undeclare is provided for this operation. You can opt to remove the actual product in the product instance's root directory, as well, by using either the -y or -Y option. The ups undeclare command executes ups unconfigure by default (see section 4.6.1 Configuring a Product). The unconfigure process can be suppressed by using the -C option with ups undeclare, however normally this process should execute. The full ups undeclare command description and option list is in section 23.19 ups undeclare.

Before removing anything, you should find out if any other products have the product instance in question declared as a dependency. If so, reconsider removing it. Removal of the product instance may affect the operation of its parent products.

11.5.1 Using ups undeclare to Remove a Product

To remove a product instance, specify the version of the instance, not its chain, in the ups undeclare command. Specifying the chain removes only that chain, not the instance itself.

Using ups undeclare is the recommended procedure for removing product instances. Removing them manually does not ensure that all the files get deleted or that chains get updated properly, which can lead to a fragmented products area.

If you choose to completely remove the product, and you want to delete the product instance's directory tree starting from its root directory, use one of the options -y or -Y with ups undeclare (-y queries you for confirmation, -Y does not). It is recommended to always include the -f option with a multi-flavor database. Users may also need to include the -z option if they have more than one database. The command syntax is (showing commonly used options):

% ups undeclare [-f <flavor>] [-q <qualifierList>] [-y|Y] \ 
[-z <database>] <product> <version> 

Special case: If a product has a CONFIGURE action that modifies files outside of its product root directory, and if this instance is used by more than one node, flavor or file system, then you may need to run ups undeclare or ups unconfigure on all of the nodes before removing the product files on any node. The INSTALL_NOTE file should indicate if this is the case. If you're not sure, check in the product's table file.

Example 1

In this first example, we remove the product tcl v7_6a. We undeclare it and opt to remove the product root directory after query, taking a "snapshot" before and after. First, verify the declared instances of tcl in the database:

% ups list -aK+ tcl 
"tcl" "v8_0_2" "Linux64bit+2" "" "current" 
"tcl" "v7_6a" "Linux64bit+2" "" "" 

Next verify the product root directory contents (run setup to set $TCL_DIR, check contents of the tcl products area, and then list contents of $TCL_DIR):

% setup tcl v7_6a 
% cd $TCL_DIR/../ ; ls -l 
total 8 
drwxrwxr-x    9 aheavey  g020         140 Sep 15 15:29 v7_6a/ 
drwxrwxr-x    9 aheavey  g020        4096 Sep  8 15:50 v8_0_2/ 
% cd v7_6a ; ls -l 
total 40 
-rw-r--r--    1 aheavey  g020         165 May  1  2013 BUILD_INFO 
drwxrwxr-x    2 aheavey  g020          83 Sep 15 15:29 alt-ups 
drwxrwxr-x    2 aheavey  g020          40 Sep 15 15:29 bin 
... 

Now undeclare tcl v7_6a and remove its product root directory structure. The -y option queries before removing, and we respond "y" for yes (one would enter "n" for no):

% ups undeclare -f Linux64bit+2 tcl v7_6a -y 
Product home directory - 
        /export/home/t1/aheavey/upsII/products/tcl/v7_6a/ 
Delete this directory?y 

Once it finishes, verify the deletion:

% ups list -aK+ tcl 
"tcl" "v8_0_2" "Linux64bit+2" "" "current" 
% cd $TCL_DIR/../ ; ls -l 
total 8 
drwxrwxr-x    9 aheavey  g020        4096 Sep  8 15:50 v8_0_2 

We see that the declaration was removed and the v7_6a directory is gone from the tcl product area.

Example 2

The following command is a dangerous example! We include it as a caution. It finds the best flavor match using the standard instance selection algorithm (see section 27.2 Instance Matching within Selected Database) and removes that instance of the product pine version v3_91 and any chains that point to it. It also removes the product root directory for this instance of pine; it does not query for confirmation before doing so.


% ups undeclare -Y pine v3_91 

Depending on the instances in the database, you may end up removing the instance for, say, OSF1+V3 when you really wanted to remove the one for OSF1!

11.5.2 Undoing Configuration Steps

There is a ups unconfigure command for undoing configuration steps, described in section 23.18 ups unconfigure. Normally this command does not need to be run explicitly; the ups undeclare command undoes the reversible configuration operations by default. Refer to the INSTALL_NOTE file for instructions.

11.6 Verify Integrity of an Instance

The ups verify command checks the information in all the database files for the specified instance in order to determine if there are any errors or inconsistencies. The full command description and option list is in section 23.20 ups verify. Shown here with some commonly-used options, the command syntax is:

% ups verify -a <chain_flag> [-f <flavor>] <product> [<version>] 

Here is sample output for a product for which several files and directories listed in the version file were not found (-a is included to match all instances):

$ ups verify -a ifdhc
DATABASE=/fnal/ups/db 
INFORMATIONAL: Duplicate instance in TABLE file
   /fnal/ups/db/ifdhc/v1_1_rc3.table 
   key = "ifdhc" "" "ANY" "debug:e2" hash(384)
WARNING: File not found - /fnal/ups/db/etc
INFORMATIONAL: Verifying product 'ifdhc'

11.7 Modify Information in a Database File

The ups modify command allows manually editing of the database product files. It runs ups verify on the instance to perform syntax and content validation before and after the editing session. The full command description and option list is in section 23.12 ups modify. The command syntax with some commonly used options is:

% ups modify <product> [<version>] [-E <editor>] [<chainFlag>]\ 
 [-N <filename>] [-z <database>] 

ups modify performs the following steps (if you specify the file using -N, the menu will not appear):

Sample Session with (1) Unsuccessful and (2) Successful Validation

% ups modify teledata v1_0 -N $MYDB/teledata/v1_0.version 

In this example, we select the version file (via -N) for the product teledata v1_0 (default flavor, no qualifiers). Since -E is not given, UPS will use the editor set in $EDITOR, or vi if that variable is not set. First, UPS runs ups verify and produces the output:

Pre modification verification pass complete. 

No errors were detected. The version file is next displayed in the editor.

  1. To illustrate an unsuccessful validation, we add a bogus line:
  TESTKEYWORD = value 

and save and quit. UPS returns the following messages, and we opt to save the erroneous change: INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl ared/teledata/v1_0.version', line 17 INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl ared/teledata/v1_0.version', line 17 Post modification verification pass complete. Do you wish to save this modification [y/n] ? y
UPS quits, saving the file as we requested.
  1. To illustrate successful validation, we'll correct the error introduced above. We run the same ups modify command. UPS finds the error during the pre-edit validation:
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl 
ared/teledata/v1_0.version', line 17 
INFORMATIONAL: Unexpected key word 'TESTKEYWORD' in '/home/t1/aheavey/upsII/decl 
ared/teledata/v1_0.version', line 17 
Pre modification verification pass complete. 

We remove the incorrect line from the version file, then save and quit. UPS displays the following message, and we elect to save the change (y): Post modification verification pass complete. Do you wish to save this modification [y/n] ? y
UPS quits, saving the file as requested.

Sample Session with No Changes

In this example, we select the current instance of the product teledata, and (by default) request a menu of files to edit:

% ups modify teledata 
[0] /home/t1/aheavey/upsII/declared/teledata/current.chain 
[1] /home/t1/aheavey/upsII/declared/teledata/v1_0.version 
[2] /export/home/t1/aheavey/upsII/products/teledata/v1_0//ups/v1_0.table 
[3] /home/t1/aheavey/upsII/declared/.upsfiles/dbconfig 
Choose file to edit [0-3] or 'q' to quit: 1 
Pre modification verification pass complete. 

UPS starts up the editor and makes the selected file available to edit. We quit without making any changes. UPS displays the message:

No modifications, nothing to save. 

UPS then displays the menu again, and we opt to quit:

[0] /home/t1/aheavey/upsII/declared/teledata/current.chain 
[1] /home/t1/aheavey/upsII/declared/teledata/v1_0.version 
[2] /export/home/t1/aheavey/upsII/products/teledata/v1_0//ups/v1_0.table 
[3] /home/t1/aheavey/upsII/declared/.upsfiles/dbconfig 
Choose file to edit [0-3] or 'q' to quit: q 

11.8 Determine If a Product Needs to be Updated

To determine if you need to reinstall a product, use the upd install command with the -s option, as shown, while logged on to a node of the flavor to check (or use the -H option to specify a different flavor). The full command description and option list is in the reference section 24.8 upd install.

% upd install -s <product> [<version>] [-h <host>] [-H <flavor>]  

If it's ok, you'll see no output. If there's a discrepancy between what's on your node and what's on fnkits (or on the host specified using -h), you'll see output of the form:

Installing <product> 
I would make directory /path/to/<product>/<flavor>/<version> 
I would fetch directory <kitsflavor> from  
ftp://fnkits.fnal.gov//ftp/products/<product>/<version> as 
/path/to/<product>/<flavor>/<version> now 
... 

Although it says "Installing", it's only telling what it would have to do to install.

If you are interested in knowing only if the product's table file or ups directory has been changed on the server and needs an update on your machine, use the upd update -s command. It compares the MODIFIED dates in the remote and local nodes. The full command description and option list is in the reference section 24.13 upd update.

% upd update -s <product> [<version>] <component> [-H <flavor>]  

The argument <component> can take the value table_file or ups_dir, or both, colon-separated. If no update is needed, there is no output. If an update is needed, the messages will inform you.

11.9 Update a Table File or ups Directory

The upd update command is used to update a product's table file and/or ups directory. It operates on the specified product instance and its dependencies by default. It retrieves the specified components from a distribution node and downloads them to the local node, overwriting the corresponding pre-existing component(s). The full command description and option list are in section 24.13 upd update. The command syntax with some commonly used options is:

% upd update <product> [<version>] <componentList> \ 
[-f <flavor>] [-H <flavor>] [<chainFlag>] [-h <host>] [-i] [-j]  

In the following example, we overwrite the table file for the product instance xntp v3_4, flavor SunOS. This operation will succeed if the MODIFIED date in the remote version file that points to the table file on the distribution node is later than that in the comparable local version file; no overwrite will occur otherwise. Before running upd update, we compare the MODIFIED dates for the product by using a ups list command like the following:

% ups list -f SunOS -K MODIFIED xntp v3_4 
":2013-04-01 20.08.02 GMT" 

on the local node, and running upd list with similar options on the distribution node (the default fnkits is used here):

 % upd list -H SunOS -K MODIFIED xntp v3_4 
"2013-09-10 08.13.07 GMT" 

The MODIFIED date in the remote version file is later than that in the local version file, therefore we expect an update to occur.

Now we run the ups update command requesting the component table_file:

% upd update table_file xntp v3_4 -H SunOS 
updcmd::updcmd_update - Updating xntp. 
upderr::upderr_syslog - successful transfer 
ftp://fnkits.fnal.gov///ftp/upsdb/xntp/v3_4SunOS.table -> /tmp/mwmdb/xntp/v3_4.table 
upderr::upderr_syslog - successful ups touch xntp v3_4 -f SunOS -q "" -U "" 

Rerun the ups list command to verify that the MODIFIED date changed, indicating that the update took place.

To update several instances of xntp v3_4 for a list of flavors, use the -H option like this:

% upd update table_file xntp v3_4 -H OSF1:Linux 

Using -H ensures that all the dependencies are updated with the appropriate flavor rather than with the best match flavor to the local machine.

Note: When updating several instances at a time, you can exclude a particular instance from being updated by running ups touch on it. See the reference section 23.17 ups touch for more information.

11.10 Retrieve an Individual File

The upd fetch command retrieves a single file or directory maintained in a UPS distribution database, and downloads it to the user node, placing it relative to the current working directory. The -J option is used to specify the individual filename to fetch. If -J is omitted, the output is a recursive list of directories and files that are available for individual retrieval. Nothing actually is retrieved when -J is omitted. The full command description and option list is in section 24.6 upd fetch. The command syntax with some commonly used options is:

% upd fetch [-H <flavor>] [<chainFlag>] [-h <host>] [-J fileName] \ 
 <product> [<version>] 

First we issue the upd fetch command without the -J option to find out what files are available for the specified product instance (output edited for brevity):

% upd fetch -H Linux+2 rbio v9_3d 
Listing of table_dir [/ftp/products/rbio/v9_3d/Linux+2]: 
total 3172 
drwxrwx---   3 updadmin upd           512 May  7  2012 rbio_v9_3d_Linux+2 
-rw-rw-r--   1 updadmin upd          1235 May  7  2012 rbio_v9_3d_Linux+2.table 
-rw-rw----   1 updadmin upd       1597440 May  7  2012 rbio_v9_3d_Linux+2.tar 
-rw-rw-r--   1 updadmin upd         14848 May  7  2012 rbio_v9_3d_Linux+2.ups.tar 
 
rbio_v9_3d_Linux+2: 
total 6 
-rw-rw-r--   1 updadmin upd          1540 May  7  2012 README 
drwxrwsr-x   5 updadmin upd           512 May  7  2012 ups 
 
rbio_v9_3d_Linux+2/ups: 
total 28 
-rw-rw-r--   1 updadmin upd           210 May  7  2012 Version 
... 
rbio_v9_3d_Linux+2/ups/toInfo: 
total 0 
... 

Now we use upd fetch -J to retrieve the README file listed. The file will be copied to the current working directory:

% upd fetch -J README -H Linux+2 rbio v9_3d 
informational: transferred README 
 from fnkits.fnal.gov:/ftp/products/rbio/v9_3d/Linux+2/rbio_v9_3d_Linux+2 
 to ./README 

To verify the successful transfer, we check the current working directory for the new file:

% ls -l README 
-rw-rw-r--    1 aheavey  g020        1540 Sep  7 15:57 README 

As another example, you can retrieve the table files for several flavors of a product. When specifying the flavors on the remote node, be sure to use -H, not -f:

% upd fetch -H Linux+2:OSF1+V4 -J @table_file tex v3_14159 

This command retrieves the table file(s) for the best match product instances of tex v3_14159 for the listed flavor families. Depending on how the product was configured, the same table file may be used for all, or they may be separate files. The file(s) will be copied to the current working directory.

11.11 Check Product Accessibility

The ups exist command is used to test whether a setup command issued with the same command line elements is likely to succeed. It checks for a properly declared matching instance, and verifies that you have the necessary permissions to create the temporary file used by the setup command. This command is rarely used from the command line, and is more useful in scripts where a failed setup could cause the script to abort. The full command description and option list is in section 23.7 ups exist. The command syntax with some commonly used options is:

% ups exist  [-f <flavor>] [<chainFlag>] [-j] <product> [<version>] 

When issued from the command line, it returns no output if the command succeeds. In the shell ups exist sets the $? to 0 if it was able to create the temporary file, or to 1 for error.

$ ups exist tex -f Linux+2; echo $? 
0 
$ ups exist tex -f Linux+2; echo $? 
1 

To run this on a product distribution node, use the corresponding command upd exist, documented in section 24.5 upd exist.

11.12 Troubleshooting

This section provides a few hints if things don't seem to work after declaring/removing/changing a product, or otherwise modifying files in a UPS database.

     /var/tmp/aaaa00273 
  INFORMATIONAL: Name of created temp file is /var/tmp/aaaa005Mt 


TOC PREV NEXT

This page last revised in May 2014