haver.path {Haver} | R Documentation

## Set or Query the Path to Haver Databases

### Description

`haver.path` sets, queries, and saves the path to Haver databases. A correct path setting is a prerequisite for data and metadata queries run by `haver.data` and `haver.metadata`

### Usage

    haver.path()
    haver.path(set)
    haver.path(save=TRUE)

### Arguments

`set` | is a string or a list of strings. It specifies the directory or directories where Haver databases reside. If it is a string, it is either a full directory or file path or one of the keywords ‘auto’, ‘ini’, ‘examples’, ‘restore’, or ‘saved’. See below for details.
`save` | is a logical. `haver.path(save=TRUE)` saves the current path setting to the Haver package settings file. This setting gets automatically restored whenever the Haver package is attached to the search path. Note: Saving the Haver path affects all users that access a particular package installation.

### Details

If `haver.path` is called without arguments, the current setting is returned.

If argument `set` is supplied, `haver.path(set)` sets the database path. `set` can be one of several things:

- `set` is typically a string specifying a directory. We recommend that you supply it as an absolute path, not as a path relative to some parent directory. If the supplied database path does not exist, an error occurs. If the supplied database path does not contain any Haver Analytics database, a warning is issued. You must use directory separators ‘\\’ or ‘/’. The function will fail if directories are separated by a single ‘\’. or any abbreviation thereof.
  If you supply the path as a relative file path, it is taken to be relative to the working directory, not relative to the current path setting. Since supplying a relative path may not be what you intended, a warning is issued.

- It can also be a special 'keyword': a string that is one of ‘auto’, ‘ini’, ‘examples’, ‘restore’, or ‘saved’, or any abbreviation thereof.

  - ‘auto’ tries to automatically detect the correct database path if it is unknown to the user. If successful, it will set the Haver path to the directory where the default database of the Haver data browser DLXVG3 resides. In some instances this may not work, depending on the R configuration and the DLX configuration of your machine.

  - ‘ini’ reads the main DLX INI file, which contains database paths for individual databases. These are generally the databases that you see when you open the Haver data browser DLXVG3. Databases accessed in this way do not have to reside in the same directory. See also section ‘Path Setting Details’ below.

  - ‘examples’ sets the database path to the example DLX databases that come with the Haver package. Before doing so, `haver.path()` will store the existing setting. You can re-enable this setting by issuing `haver.path('restore')`.

  - ‘restore’ restores the database path setting that was in place when `haver.path('examples')` was invoked.

  - ‘saved’ sets the path according to a previously saved state.

- `set` can also be an R list. The list element names then specify the database names. Corresponding to each of the names, the elements themselves then specify paths to directories. They are the locations where the corresponding databases resides. Such a list is sometimes referred to as a path dictionary by error messages and by this documentation, because it allows to look up the location of a database. A path dictionary permits to access databases in different locations in a single query. Codes in databases not contained in the list will not be found by queries. An example of a path dictionary is
  `list('USECON'='C:\DLX\DATA', 'G10'='C:\ELSE\WHERE')`. The lookup of database names is not case-sensitive.

- Finally, `set` can be a string specifying a path to a file that has extension ‘.ini’. This file is then taken to be an ‘INI’ file. For details on INI files, see section ‘Path Setting Details’ below.

### Value

When argument `set` is not supplied, a character string that holds the current setting of the database path; and `NULL` otherwise.

### Loading of Package

When the Haver package gets attached to the R search path, it automatically checks for and tries to restore a saved database path. If this is not successful, it tries to detect the correct setting from the DLX setup of your machine. If neither of these attempts are successful, you have to set the database path manually.

### Usage with DLX Direct

If DLX Direct mode is switched on, you can still set and query the database path. Be aware, however, that the local database path setting has no effect as long as you have DLX Direct mode turned on. See `haver.direct` for more information on accessing Haver's database servers.

### Alternatives to a Fixed Database Path

When setting the Haver path to a fixed directory, you can only access databases from that directory. Since all Haver databases typically reside in the same directory, this should be sufficient. In some situations, however, you may want to access databases from different directories. In such cases, it may be the simplest solution that you explicitly switch the Haver path from one directory to another. This may turn out to be cumbersome, however. Moreover, you would not be able to access data from databases in different directories in a single query.

If you want to specify database paths on a per-database basis, there are two possibilities:

1. You can supply a path dictionary as described above to `Haver.path()`, i.e., a list with database names as list element names and database locations as list elements.

2. You can specify database paths in a so-called INI file. This functionality is most often used to read the main INI file of your DLX installation, which gives you access to all of your institution's databases. You may also create your own, customized INI file.

In both cases `Haver.path()` will store the information provided in an R list. Querying the current Haver path via `Haver.path()` will return this list, or ‘path dictionary’. Its information will be used in queries. As far as path management is concerned, a path dictionary setting behaves like a regular, fixed path setting: It is saved in between R sessions, it can be restored after switching to examples databases via the keyword ‘restore’, etc.

The rest of this section elaborates on the usage and creation of INI files. INI files are DLX configuration files that contain lines that specify database locations on a per-database basis. The keyword ‘ini’ supplied as argument `set` to `Haver.path()` will use the main INI file of the DLX installation on your computer. This file should always be present, so executing

      haver.path('ini')

should always work and give you access to all databases of your DLX installation. It is therefore a good alternative to

      haver.path('auto')

which will set the Haver path to the directory where the default database of the Haver data browser DLXVG3 resides.

In some rare instances, it may even be useful to create an INI file yourself. Relevant entries are composed as:

      DBID [_someword_=] _dbpath_\_dbname_

These mimic entries in the main INI file. Lines that do not comply with the above pattern are ignored. More specifically, the first word of an INI entry must start with the string literal ‘DBID’, followed by some whitespace. The optional _someword_= may be any non-empty string that ends in ‘=’ and does not contain ‘=’ anywhere else. It is present in real DLX configuration files but can be omitted for R purposes. _dbpath_ is the path to the directory containing the database. It must be an absolute path, not a path relative to some parent directory. _dbname_ must be the name of the database, without any file extension. Casing does not matter. Finally, you can comment out lines using ‘!’. A file containing the four lines

        ! my first database location file
        DBID   c:\dlx\data\USECON
        ! DBID   c:\dlx\data\WEEKLY
        DBID   d:\some\other\path\EMERGE

would give you access to databases USECON and EMERGE. WEEKLY will not be found since its line, like the first line, is taken to be a comment.

Note that such customized files only work with R. You cannot use these files with any other component of DLX. Therefore, if you create such customized INI files, we recommend naming them accordingly, e.g., ‘Haver_R_databases.ini’. It is always required that the file extension be ‘.ini’ (casing does not matter).

### Preservation of the Path Setting between R Sessions

Normally you never have to worry about setting the Haver path, as the Haver package will typically apply the correct path setting automatically. Should this mechanism fail, however, you have to set the database path manually. After doing this, you can use `haver.path(save=TRUE)` to save this setting. That way it will get automatically restored upon package import and you do not have to manually set that Haver path repeatedly, e.g. in new R sessions.

WARNING: Be aware that, in an environment where multiple users share the same Haver package installation, saving a path setting affects all users. This is not true for any other path operations: They only affect a single user.

### Running ‘Examples’ Sections of Help Entries of the Haver Package

At the top of the examples section in each help entry the database path is set to point to the example databases:
`> haver.path("examples")`.
At the end of each examples section, the previous setting is restored:
`> haver.path("restore")`.

If you re-set the Haver database path manually after issuing `haver.path("examples")`, a call to `haver.path("restore")` will not change this setting anymore.

If you quit R or unload Haver before restoring the setting to the actual Haver Analytics databases, Haver will still set the path to the actual Haver Analytics databases when R is invoked (i.e. when Haver is attached).

### See Also

See Haver_package for all help entries related to the Haver package.

### Examples

    ## query the current setting
    ex_origpath <- haver.path()

    ## let 'haver.path' try to determine the correct setting automatically
    haver.path("auto")

    ## set to examples databases
    haver.path("examples")

    ## restore previous setting
    haver.path("restore")

    ## manually restore to setting before running examples section
    if (!is.null(ex_origpath)) haver.path(ex_origpath)

    ## Not run:
    ## manually set the database path to an explicitly given directory
    haver.path("c:/dlx/data")

    ## End(Not run)

[Package Haver version 3.2 Index]