NCL Home > Documentation > HLUs > User Guide

Using resource files

Resource file hierarchy

To provide maximum flexibility in applications and reasonable default values for resources, a series of up to four resource files can exist. One is created by the software developer. The others can be set by application project managers and project staff. These files provide default resource values.

The four resource files

  1. $(NCARG_SYSRESFILE)
  2. System Application Specific Resource file.
  3. $(NCARG_USRRESFILE)
  4. Users Application Specific Resource file ("name.res")
Resource file 1 is intended for use by the designers/installers of NCAR Graphics to set resources that should apply globally at a site. For example, an NCAR Graphics site installer may decide to turn on printing of all error messages.

Resource file 2 is intended to be used by developers of multi-user applications to set resources specific to an application for all users of that application. For example, the developer may want to default the viewport resources for a particular output device.

Resource files 3 and 4 are for users; 3 allows the user to provide default resources for all HLU applications, similar to Resource file 1, $(NCARG_SYSRESFILE). 4 allows the user to provide resources on an application-specific basis, similar to Resource file 2, the System Application Specific Resource file.

The final value assigned to each resource is determined by proceeding from file 1 through file 4 with each succeeding value taking precedence over the previous one.

Resources set in the HLU code override the resource file

However, the final word concerning the value of a resource occurs in the HLU program. Resource values set in the code supersede resource values set in resource files. Thus, if you change the color of a line in a resource file, re-execute the program module, but discover that the line color does not change, inspect your HLU program to make sure that you are not setting the line color resource in your program.

Each HLU program needs an application (App) object. It is either created through an NhlOpen call, or explicitly created in your program through an NhlCreate call after an NhlInitialize call as in: 

Fortran:    call nhlfcreate(appid,'xy05',nhlfappclass,0,rlist,ierr)

C:          NhlCreate(&appid,"xy05",NhlappClass,NhlDEFAULT_APP,rlist);

The resource list, rlist, in the above examples could contain the pathnames of the system application specific resource file (file 2), and the users application specific resource file (file 4), as in: 

Fortran:    call nhlfrlsetstring(rlist,'appUsrDir','./',ierr)
Fortran:    call nhlfrlsetstring(rlist,'appFileSuffix','.res1',ierr)
Fortran:    call nhlfrlsetstring(rlist,'appSysDir','~/',ierr)

C:          NhlRLSetString(rlist,NhlNappUsrDir,"./");
C:          NhlRLSetString(rlist,NhlNappFileSuffix,".res1");
C:          NhlRLSetString(rlist,NhlNappSysDir,"~/");
Adding resource values in the rlist is simply adding them to a dynamic array that is not actually applied until the NhlFCreate or NhlCreate call. Note that we can also set the suffix of a type 4 file. The default value is .res.

These resources are also settable from the resource database; however, they cannot be specified in the application-specific resource files (2 and 4) because these resources are used to find resource files 2 and 4.

Directory locations of resource files

$NCARG_ROOT is the directory in which NCAR Graphics is installed on your system. You must put a statement of the form 

    setenv NCARG_ROOT /path/name/where/installed
in your .cshrc file. We can then locate the default resource files relative to this install location.

  1. Environment variable $(NCARG_SYSRESFILE) specifies the pathname of resource file 1. The default file $NCARG_ROOT/lib/ncarg/sysresfile will be used if $(NCARG_SYSRESFILE) is not set. We suggest that you use the default resource file that has been created for you by the developers.
  2. The appSysDir resource of an App object is used to specify the directory where resource file 2 is located. This resource defaults to the value of the $(NCARG_SYSAPPRES) environment variable. See sysappres.
  3. Environment variable $(NCARG_USRRESFILE) specifies the pathname of resource file 3. $(NCARG_USRRESFILE) defaults to ~/.hluresfile if not set by the user.
  4. The appUsrDir resource of an App object is used to specify the the directory where resource file 4 is located. This resource defaults to the value of the current working directory (./). For example, 

        NhlCreate(&appid,"ti01",NhlappClass,NhlDEFAULT_APP,rlist);
    shows the creation of an application named ti01. Thus, if the resource file suffix for this application is allowed to default to .res, the file will be named ti01.res.

The resource file pathnames can be retrieved by typing: 

	% ncargpath sysresfile
	% ncargpath sysappres
	% ncargpath usrresfile
The file usrresfile will not exist unless the user creates it.

See also: