APP_USER_DIR_QUERY

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.

Syntax

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_APPVERSION=string] [, /RESTRICT_ARCH] [, /RESTRICT_FAMILY] [, /RESTRICT_FILE_OFFSET_BITS] [, /RESTRICT_IDL_RELEASE] [, /RESTRICT_MEMORY_BITS] [, /RESTRICT_OS] )

Return Value

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.

Arguments

AuthorDirname

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.

If AuthorDirname is an empty string, then the default product name will be used. This default is "idl" unless the IDL_PREF_DIR preference has been set.

AppDirname

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.

Keywords

COUNT

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).

If COUNT is not specified, and the desired directory does not exist, then IDL will automatically create the directory and return it as the result. If you only want to query if the directory exists, then you must set COUNT to a named variable.

EXCLUDE_CURRENT

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.

QUERY_APPVERSION

Set this keyword to match application user directories that have any value for the application version. To use this keyword you must also set /RESTRICT_APPVERSION.

QUERY_ARCH

Set this keyword to match application user directories that have any value for the hardware architecture. To use this keyword you must also set /RESTRICT_ARCH.

QUERY_FAMILY

Set this keyword to match application user directories that have any value for the operating system family. To use this keyword you must also set /RESTRICT_FAMILY.

QUERY_FILE_OFFSET_BITS

Set this keyword to match application user directories that have any value for the number of bits used for file offsets. To use this keyword you must also set /RESTRICT_FILE_OFFSET_BITS.

QUERY_IDL_RELEASE

Set this keyword to match application user directories that have any value for the IDL version string. To use this keyword you must also set /RESTRICT_IDL_RELEASE.

QUERY_MEMORY_BITS

Set this keyword to match application user directories that have any value for the number of bits used for memory addresses. To use this keyword you must also set /RESTRICT_MEMORY_BITS.

QUERY_OS

Set this keyword to match application user directories that have any value for the operating system. To use this keyword you must also set /RESTRICT_OS.

RESTRICT_APPVERSION

An arbitrary string giving the application version. Different application user directories will be created for different values of this keyword.

RESTRICT_ARCH

Set this keyword to match application user directories that only match your system architecture, as given by the !VERSION.ARCH system variable field.

RESTRICT_FAMILY

Set this keyword to match application user directories that only match your operating system family, as given by the !VERSION.OS_FAMILY system variable field.

If RESTRICT_OS is also specified, RESTRICT_FAMILY is ignored and has no effect.

RESTRICT_FILE_OFFSET_BITS

Set this keyword to match application user directories that only match your current IDL file-offset bits, as given by the !VERSION.FILE_OFFSET_BITS system variable field.

RESTRICT_IDL_RELEASE

Set this keyword to match application user directories that only match your current IDL version, as given by the !VERSION.RELEASE system variable field.

RESTRICT_MEMORY_BITS

Set this keyword to match application user directories that only match your current IDL memory-address bits, as given by the !VERSION.MEMORY_BITS system variable field.

RESTRICT_OS

Set this keyword to match application user directories that only match your operating system, as given by the !VERSION.OS system variable field.

Example

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:

Application version (RESTRICT_APPVERSION)
Operating system family (RESTRICT_FAMILY)

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.

Version History

6.1	Introduced