IDL

APP_USER_DIR

APP_USER_DIR

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:

  • Each author of IDL applications has a unique area underneath the .idl directory. Different authors do not share space with each other, or with IDL distribution files.
  • By default, an application directory is shared by all instances of the application. The application author 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.
  • A README file is automatically generated for each author and application directory, following a standard format. The application author is required to supply the body text for the application README file. (Text for the author README file is optional, but recommended.) The text is expected to explain the purpose of the directory, and supply contact information for the author. Each README file has a version associated with it, allowing APP_USER_DIR to automatically update the file as necessary.

APP_USER_DIR performs the following operations, in order:

  1. If the specified author directory does not exist, it is created.
  2. If the specified author directory does not have a standard README file, it is created. If there is an existing README file with a version number that is lower than the specified number, the file is replaced.
  3. If the specified application subdirectory does not exist within the author directory, it is created.
  4. If the specified application directory does not have a standard README file, it is created. If there is an existing README file with a version number that is lower than the specified number, the file is replaced.
  5. The path to the application directory is returned as the value of the APP_USER_DIR function.

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.

Syntax


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

Return Value


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.

Arguments


AuthorDirname

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:

  1. AuthorDirname is case insensitive, regardless of the operating system platform. APP_USER_DIR will convert the name to lower case before creating the directory or returning its path string.
  2. You should attempt to keep the name short, to minimize the chance that the full directory name is longer than the maximum supported length on the current platform.
  3. The following characters are automatically converted to underscores (_) when creating the directory name: - ) ( . : > < as well as space and tab.

AuthorDesc

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 VIS is “Exelis VIS.”

AppDirname

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.

AppDesc

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

AppReadmeText

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:

  • The identity of the author, and author contact information.
  • A brief description of what the application is, and what it does.
  • Any special rules governing if and when the user is allowed to delete the directory and its contents.

AppReadmeVersion

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.

Keywords


AUTHOR_README_TEXT

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.

AUTHOR_README_VERSION

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.

RESTRICT Keywords


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:

Network Installations

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.

Application Version Compatibility

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:

  1. Can you imagine that a future version of your application might want to structure its data in a different way, or that changes for a new version might confuse older versions that also use the same data? If so, you should specify the RESTRICT_APPVERSION keyword to give your application a version. If in doubt, specify a version of ‘1.0’. You will never be required to change the version number, but you will have the flexibility to do so if your application user directories include application version information.
  2. Carefully consider how platform-specific your application is, and apply any of the other RESTRICT keywords that are necessary.
  3. If versioning is important to your application, you will eventually face the situation in which your users are upgrading to a new version. In such cases, you may want to offer them the option of migrating their configuration data from the older version. The APP_USER_DIR_QUERY function can be used to locate the application user directories for these older versions. Note that your application data must be designed in such a way that such migrations are possible. In particular, any versioning information needed to select the best migration candidate must be present.

RESTRICT_APPVERSION

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.

RESTRICT_ARCH

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.

RESTRICT_FAMILY

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.

RESTRICT_FILE_OFFSET_BITS

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.

RESTRICT_IDL_RELEASE

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.

RESTRICT_MEMORY_BITS

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.

RESTRICT_OS

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.

Examples


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

Version History


6.1

Introduced

See Also


APP_USER_DIR_QUERY, FILE_MKDIR, FILE_TEST, FILEPATH, OPENR/OPENU/OPENW, !VERSION system variable



Notes


This page has no user notes yet. Be the first one!


This information is not subject to the controls of the International Traffic in Arms Regulations (ITAR) or the Export Administration Regulations (EAR). However, it may be restricted from transfer to various embargoed countries under U.S. laws and regulations.
© 2014 Exelis Visual Information Solutions