The APP_USER_DIR_QUERY function is used to locate existing application user directories previously created by the APP_USER_DIR function. An IDL application can use APP_USER_DIR_QUERY to locate the directories that were used by other (presumably older) versions of itself. A newly installed version can use this information to migrate application settings or data from another version in order to preserve the user’s customizations.
To use APP_USER_DIR_QUERY, your application should call it with the same values of the AuthorDirname and AppDirname arguments, and the exact set of RESTRICT keywords, used to call APP_USER_DIR. In this configuration, APP_USER_DIR_QUERY will return the same application user directory returned by APP_USER_DIR. To search for other related application user directories, use the QUERY keywords to specify which of the attributes specified in the call to APP_USER_DIR should be allowed to take on any value.
As an example, suppose your application creates user application directories that depend on the version of the application and on the operating system in use. You might want to locate all directories created for a specific application version, regardless of the operating system in use when the directory was created.
Tip: The application user directory for the current system is always one of the values returned by APP_USER_DIR_QUERY. In the common example of an application that wants to migrate data from a different version, the path for the current system is not desired. Use the EXCLUDE_CURRENT keyword to suppress it from the results.
Result = APP_USER_DIR_QUERY(AuthorDirname, AppDirname [, COUNT=variable] [, /EXCLUDE_CURRENT][, /QUERY_APPVERSION] [, /QUERY_ARCH] [, /QUERY_FAMILY] [, /QUERY_FILE_OFFSET_BITS] [, /QUERY_IDL_RELEASE] [, /QUERY_MEMORY_BITS] [, /QUERY_OS] [RESTRICT Keywords] )
Returns a string array containing all application user directories that match the query criteria. If no matching application user directories exist, a null scalar string is returned.
A string specifying the name of the author directory to be used by the calling application. For APP_USER_DIR_QUERY to work correctly, AuthorDirname must be set to the same value used in the call to APP_USER_DIR. See APP_USER_DIR for details.
A string specifying the name of the application directory to be used by the calling application. For APP_USER_DIR_QUERY to work correctly, AppDirname must be set to the same value used in the call to APP_USER_DIR. See APP_USER_DIR for details.
Set this keyword equal to a named variable that will contain the number of matching application user directories found. If no matching directories are found, the specified variable will contain the value 0 (zero).
By default, APP_USER_DIR_QUERY includes the application user directory that matches the current system (the directory that would be returned by APP_USER_DIR) in Result. Set this keyword to exclude the directory returned by APP_USER_DIR from the Result.
APP_USER_DIR_QUERY accepts the same RESTRICT keywords documented for APP_USER_DIR. For APP_USER_DIR_QUERY to work correctly, you must specify the same RESTRICT keywords as were specified to APP_USER_DIR. See the documentation for APP_USER_DIR for full details.
There is a subtle difference in the meaning of the RESTRICT keywords between APP_USER_DIR and APP_USER_DIR_QUERY. In the case of APP_USER_DIR, specifying one of the RESTRICT keywords causes IDL to create a directory whose name incorporates information about the value of the specified attribute on the current platform. In the case of APP_USER_DIR_QUERY, specifying one of the RESTRICT keywords tells IDL that the directory name must contain information about the specified attribute; if the corresponding QUERY keyword is also specified, directory names that contain any value for the specified attribute will be matched.
A minimally correct call to APP_USER_DIR_QUERY consists of specifying the same AuthorDirname argument, AppDirname argument, and RESTRICT keywords as the corresponding call to APP_USER_DIR. Such a call will return a single string containing the path returned by APP_USER_DIR. Using APP_USER_DIR_QUERY in this manner is not particularly interesting; in order to locate other application user directories in addition to the one that applies to the current platform, you must add one or more QUERY keywords.
Each QUERY keyword corresponds to one of the RESTRICT keywords. The presence of a QUERY keyword tells APP_USER_DIR_QUERY to search for application user directories that satisfy all of the RESTRICT keywords while allowing any value for the attribute specified by the QUERY keyword.
Set this keyword to match application user directories that have any value for the application version. This keyword is quietly ignored if the RESTRICT_APPVERSION keyword is not set.
Set this keyword to match application user directories that have any value for the hardware architecture. This keyword is quietly ignored if the RESTRICT_ARCH keyword is not set.
Set this keyword to match application user directories that have any value for the operating system family. This keyword is quietly ignored if the RESTRICT_FAMILY keyword is not set.
Set this keyword to match application user directories that have any value for the number of bits used for file offsets. This keyword is quietly ignored if the RESTRICT_FILE_OFFSET_BITS keyword is not set.
Set this keyword to match application user directories that have any value for the IDL version string. This keyword is quietly ignored if the RESTRICT_IDL_RELEASE keyword is not set.
Set this keyword to match application user directories that have any value for the number of bits used for memory addresses. This keyword is quietly ignored if the RESTRICT_MEMORY_BITS keyword is not set.
Set this keyword to match application user directories that have any value for the operating system. This keyword is quietly ignored if the RESTRICT_OS keyword is not set.
In the discussion of the APP_USER_DIR function, we give the example of an IDL application supporting the “Amazing” Grill System, a product of the fictional Acme Widgets, Inc. The application user directory created for that application is dependent on two attributes:
When a new version of IDL runs this application for the first time, the application code will find that its newly created application directory is empty. In such a situation, the application might wish to offer the user a choice between starting over with the application defaults or migrating settings and data from an older version of the application.
The following call to APP_USER_DIR_QUERY can be used to locate application user directories that are for other versions of the application, but for the same operating system family. The QUERY_APPVERSION keyword causes the function to match all application versions, while the EXCLUDE_CURRENT keyword tells it to exclude the application user directory for the current system:
old_appdirs = APP_USER_DIR_QUERY('acme', 'acme_grill', $
RESTRICT_APPVERSION='1.0', /RESTRICT_FAMILY, $
/QUERY_APPVERSION, /EXCLUDE_CURRENT)
Note that APP_USER_DIR_QUERY may return more than one directory. It is up to the application to decide which one to use. Applications that intend to migrate information between versions should include information in their application user directories that will facilitate such migration.
|
6.1 |
Introduced |