The APP_USER_DIR function provides access to the IDL application user directory. The application user directory is a location where IDL, and applications written in IDL, can store user-specific data that will persist between IDL sessions. For example, the IDL iTools store user-specified preferences, styles, and macros in the application user directory.
The application user directory is created automatically by IDL as a subdirectory (named
.idl) of the user's home directory. (For additional information on the location of the user's home directory on different platforms, see HOME in Environment Variables Used by IDL.)
To prevent unrelated applications from encountering each other's files, the
.idl directory is organized into subdirectories with names specified by the application author. For example, files used by applications created by RSI are stored in subdirectories of the
.idl directory named
idl. Inside each author's subdirectory, files are organized by application and (optionally) by a combination of attributes of the IDL version that creates the directory.
.idldirectory is opaque to both users and authors of IDL applications. Application authors are expected to manage the directory exclusively using the APP_USER_DIR function, and application users generally do not need to manually modify the files it contains.
APP_USER_DIR simplifies cross-platform application development by providing a well-defined location for IDL applications to store their resource files, regardless of the platform or version of IDL. The uniform organization it enforces is also a benefit for IDL users, since it makes it easier for them to understand the meaning and importance of the files found in their
Directories created by APP_USER_DIR have the following features:
.idldirectory. Different authors do not share space with each other, or with RSI.
APP_USER_DIR performs the following operations, in order:
Other than the README file, the contents of an application directory are entirely up to the application author. The APP_USER_DIR function does not manage the content, only its location. The FILEPATH function can be used to construct filenames within the application directory, and IDL's many input/output and file manipulation routines can be used to create and manage application specific content within it.
Result = APP_USER_DIR(AuthorDirname, AuthorDesc, AppDirname, AppDesc, AppReadmeText, AppReadmeVersion [, AUTHOR_README_TEXT=string array] [, AUTHOR_README_VERSION=integer] [, RESTRICT_APPVERSION=string] [, /RESTRICT_ARCH] [, /RESTRICT_FAMILY | /RESTRICT_OS] [, /RESTRICT_FILE_OFFSET_BITS] [, /RESTRICT_IDL_RELEASE] [, /RESTRICT_MEMORY_BITS] )
Returns a string containing the path to the directory to be used by the calling application.
A string specifying the name of the author directory to be used by the calling application. The author directory names
idl are reserved for use by IDL and IDL applications created by RSI. Other authors should be careful to pick a unique name unlikely to conflict with others. (See Advice for Library Authors for advice on selecting a unique prefix for a library; the same advice applies when selecting an author directory name.)
In choosing AuthorDirname, be aware of the following:
_) when creating the directory name:
- ) ( . : > <as well as space and tab.
A string containing a one-line description of the author in human-readable form. This string is used for the header of the README file within the author directory. For example, the AuthorDesc for IDL applications written by RSI is "Research Systems, Inc."
A string specifying the name of the application directory to be used by the calling application. For example, the IDL iTools application uses the application directory name "itools".
A string giving a brief description of the application in human-readable form. This string is used for the header of the README file within the application directory. For example, the AppDesc for the IDL iTools application is "IDL Intelligent Tools (iTools)".
A string or string array containing the text used as the body of the README file within the application directory. The README text is for the benefit of IDL users who are trying to understand what the directory is for, and is expected to supply the following information:
An integer specifying the version number to be associated with the README file. AppReadmeVersion must be greater than zero.
Initially, AppReadmeVersion should be set to one. Every time you modify the text supplied as the AppReadmeText argument, you should increment the value of AppReadmeVersion by one. APP_USER_DIR uses this information to ensure that existing README files are automatically updated to the latest version.
Set the AUTHOR_README_TEXT keyword equal to a string or string array to supply README text for the author directory. Authors with multiple IDL applications should consider providing application-independent contact information here.
If you include this keyword, use the AUTHOR_README_VERSION keyword to supply a version number for the README file.
Set this keyword equal to an integer that specifies the version number for the author README file. The specified value must be greater than zero.
Initially, AUTHOR_README_VERSION should be set equal to one. Every time you modify the text supplied as the AUTHOR_README_TEXT keyword, you should increment the value of AUTHOR_README_VERSION by one. APP_USER_DIR uses this information to ensure that existing author README files are automatically updated to the latest version. If AUTHOR_README_VERSION is not supplied, a default version of 1 is used. However, RSI recommends that you explicitly specify this keyword whenever AUTHOR_README_TEXT is used.
By default, APP_USER_DIR creates an application user directory that will be shared by all instances of the application. You can use RESTRICT keywords to specify that the directory only be used by a specified version of the application, or when running on a version of IDL with specified attributes such as release, operating system, hardware platform, etc. The RESTRICT keywords allow you to ensure that instances of your application running in different IDL, hardware, and operating system environments store their user data separately, when appropriate.
In deciding whether to use the RESTRICT keywords for your application, you should consider the following issues:
In many environments, user home directories are kept on network accessible devices, and are mounted on many different systems. These systems may be running different IDL versions, different operating systems, and different hardware.
The advantages of the networked home directory are easier system administration, and the fact that no matter which computer you use, your files are always available without the need to copy them between systems. APP_USER_DIR is designed to work in such an environment. Concerning yourself with such heterogeneous network environments may seem like overkill if you are using a system with its own dedicated home directory, but you should remember that your users may be using a highly networked environment, and as such your application needs to take these issues into consideration.
Experience shows that many application authors do not plan adequately for cross-version compatibility. This lack of planning may cause few problems at first, but as new versions of the application are released, incompatibilities surface. Consider the following when designing your application to simplify later upgrades:
Set this keyword to a string specifying the application version. Different application user directories will be created for different values of this keyword.
Set this keyword to specify that different application user directories be created when your application runs on systems with different hardware architectures, as reported by the !VERSION.ARCH system variable field.
Set this keyword to specify that different application user directories be created when your application runs on systems running different operating system families, as reported by the !VERSION.OS_FAMILY system variable field.
Set this keyword to specify that different application user directories be created when your application runs on versions of IDL that use a different number of file offset bits, as reported by the !VERSION.FILE_OFFSET_BITS system variable field.
Set this keyword to specify that different application user directories be created when your application runs under different versions of IDL, as specified by the !VERSION.RELEASE system variable field.
Set this keyword to specify that different application user directories be created when your application runs on versions of IDL that use a different number of memory address bits, as reported by the !VERSION.MEMORY_BITS system variable field.
Set this keyword to specify that different application user directories be created when your application runs on systems running different operating systems, as reported by the !VERSION.OS system variable field.
The following function demonstrates how APP_USER_DIR can be used efficiently to create an application user directory for an IDL application supporting the "Amazing" Grill System (AGS), a product of the fictional Acme Widgets, Inc. We assume that each AGS application user directory should only be shared between instances of the same version of the application that are running under the same operating system family. The use of the RESTRICT keywords causes the AGS software to create a different application user directory for each unique combination of these two attributes. The rest of the application can call this function as many times as desired. It ensures that the necessary directory exists on the first call, and then simply returns the path string on subsequent calls:
FUNCTION acme_grill_config_dir COMMON acme_grill_common, config_dir IF (N_ELEMENTS(config_dir) NE 1) THEN BEGIN ; Increment if author_readme_text is changed author_readme_version = 1 author_readme_text = $ ['This is the user configuration directory for', $ 'IDL based products from Acme Widgets, Inc:', $ '', $ ' Acme Widgets, Inc.', $ ' 1234 Amazing Way', $ ' Grill Valley, NV, 12345', $ ' USA', $ '', $ 'Thank you for using products from Acme Widgets, Inc.' ] ; Increment if app_readme_text is changed app_readme_version = 1 app_readme_text = $ ['This is the configuration directory for the', $ 'Acme "Amazing" Grill System. It is used to', $ 'remember grill settings in between grill', $ 'invocations.', $ '', $ 'It is safe to remove this directory, as it', $ 'will be recreated on demand. Note that all', $ 'settings (e.g. smoke injection depth, juicitron', $ 'angle, etc.) will revert to their default settings.', $ '', $ 'Thank you for using the Acme "Amazing" Grill System.'] config_dir = APP_USER_DIR('acme', 'Acme Widgets, Inc.', $ 'acme_grill', 'The Acme "Amazing" Grill System', $ app_readme_text, app_readme_version, $ AUTHOR_README_TEXT=author_readme_text, $ AUTHOR_README_VERSION=author_readme_version, $ RESTRICT_APPVERSION='1.0', /RESTRICT_FAMILY) ENDIF RETURN, config_dir END
APP_USER_DIR_QUERY, FILE_MKDIR, FILE_TEST, FILEPATH, OPEN, !VERSION system variable