Smart Card Shell 3

Locating Files

When calling load() to execute ECMAScripts, then the file name can be given with either an absolute or a relative path. An absolute path starts at the root of the file system, e.g. "C:\" on Windows or "/" on a UNIX like system. It uniquely identifies the file on the host system and requires no additional processing. However, specifying a relative file path allows a more flexible setup of script files and directories, in particular if scripts shall be reused or run on systems with different directory configurations.

The shell maintains 3 different directories

a current working directory (CWD)
a workspace directory (USR)
and a system directory (SYS)

When a relative file name given, then the file is first searched relative to the current working directory. If it can not be found, then the workspace directory and finally the system directory is examined. If it can not be found in either location, then an error is returned.

The system directory (SYS) is determined by the location of the shell executable file and does not change once the shell is started. The location of the executable is usually selected during installation (Installation directory, e.g. "c:\Program Files\CardContact\Smart Card Shell 3") and read/only for users that do not have administration privileges.

The workspace directory (USR) is selected by the user when the shell is started. This directory usually contains the initial CONFIG.JS file, which provides for the initial shell configuration.

The GUI version of the shell provides a dialog to select the workspace, in the command line version the workspace directory is determined by the directory from which the shell is executed (Not to confuse with the system directory, which is the location of the executable itself !)

Initially the current working directory (CWD) is set to the workspace directory (USR). Before a script file is loaded and executed, the current working directory is changed to the directory where the script was found. When calling a script from within another script, the location of the subordinate script is again determined by a search for the file in the current working directory, the workspace directory and the system directory. After the script terminated, the previous current working directory is restored.

Locating modules

Modules are scripts included with the require() statement as defined in the modules specification of CommonJS

A module id is translated into a file name by adding ".js" and searching the three directories CWD, USR and SYS

If a module is found, then the script is loaded and executed, but in contrast to scripts executed mit load(), the current working directory is not changed, but remains the CWD of the last script executed with load().

Common pitfalls

Care should be taken when script files have the same name but reside in different directories. File name resolution for a relative file path always starts with the current working directory, which is determined by the location of the script that is containing the load() statement. Therefore a script executed from the system directory has the current working directory set to the system directory and will therefore find files in this location first. Only if the included file can not be found in the current working directory, then the user and system directories are searched in turn. Overwriting a file in the system directory with a file of the same name in the user directory has no effect, if this file is included from a script in the system directory.

If you want to select a specific file, you should use the GPSystem.mapFilename() method to obtain an absolute path for use in the load() statement.