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.
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 distributed with IDL are stored in a subdirectories of .idl named exelis and 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.
Note: The organization of the .idl directory 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 .idl directory.
Directories created by APP_USER_DIR have the following features:
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.
Note: The directory and all associated README files are created if they do not exist. If the README files exit, they will be updated if the values of AppReadmeVersion and the AUTHOR_README_VERSION keyword are greater than those of the existing README files.
A string specifying the name of the author directory to be used by the calling application. The author directory names exelis and idl are reserved for use by IDL and IDL applications included in the distribution. Other authors should be careful to pick a unique name unlikely to conflict with others.
In choosing AuthorDirname, be aware of the following:
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 Exelis is “Exelis.”
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”.
Note: APP_USER_DIR modifies the AppDirname string you specify in the same way it modifies the AuthorDirname string. See AuthorDirname, above.
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.
Note: The application README file version is different from, and unrelated to, the application version (as specified via the RESTRICT_APPVERSION keyword). The README version applies only to the contents of the README file. You might want to change the text in a README file without changing the version of the application; perhaps to clarify existing information or update your contact information.
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.
Note: APP_USER_DIR requires you to supply text for the body of the application directory README file. You are not required to supply text for the author directory README file, but supplying such text is strongly recommended.
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, you should explicitly specify this keyword whenever AUTHOR_README_TEXT is used.
Note: The author README file version is different from, and unrelated to, the application version (as specified via the RESTRICT_APPVERSION keyword). The README version applies only to the contents of the README file. You might want to change the text in a README file without changing the version of the application; perhaps to clarify existing information or update your contact information.
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.
Note: The application version can be any arbitrary string. In choosing your version string, be aware that the same rules and considerations described for the AppDirname argument apply to RESTRICT_APPVERSION.
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.
Note: If RESTRICT_OS is also specified, RESTRICT_FAMILY is ignored and has no effect.
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
|
6.1 |
Introduced |
APP_USER_DIR_QUERY, FILE_MKDIR , FILE_TEST , FILEPATH , OPENR/OPENU/OPENW , !VERSION system variable