USES - use a module

`USES` - use a module

SYNOPSIS

<USES [DATE=date] module[=file] [module[=file]]>

DESCRIPTION
The USES directive includes various other modules (scripts) for use in the current script. Each module named in the directive is included when compiling the script, as well as any modules that those modules include. By default the latest revision of each module is used; if the DATE option is given then the latest revision on or before that date is used. This enables a script to "freeze" its usage in time and ignore later revisions, if for example the calling syntax for some functions in the module has changed, but the script hasn't updated its usage.

An optional filename may appear after the module name with an equal sign. This indicates that the module is to be read from the named file instead of the library. It overrides any inclusion of that module by other modules. If not absolute, file paths are interpreted relative to the including script's path. By including a module directly from a file, a new revision can be tested independently without repetitive checkins on every edit, nor disturbing other live code that uses the module. Note: Once the revision is considered stable, it should be checked in to the library to speed up the script, as modules included from files must be checked for changes on every script invocation, unlike library modules.

Module functions are visible to the script according to their scope; see the discussion of function scope on here for details. Most module functions that are intended for use by other scripts should be declared EXPORT, so that other scripts can see them, but the end user cannot call them and disrupt script execution.

When any listed module is later changed, a script that <USES> the module - directly or indirectly - will be flagged for re-compilation on invocation. This ensures that scripts are kept up-to-date with respect to the modules they use, so that manual re-compilation is not needed whenever a module changes.

As it is a directive, USES must appear before the first function in the script.

For more information, see section 1.9 (here) on library modules.

EXAMPLE

<SCRIPT LANGUAGE=vortex>

<USES security>

<A NAME=main>
  <verifyuser>
  <IF $ret neq "ok">
    You are not permitted on this site.
    <exit>
  </IF>
</A>

</SCRIPT>

In the above example, a module security is included, which contains the function <verifyuser> written by the programmer. This function is called in <main> to verify the user's identity. Since <verifyuser> is in a module, any script can use it.

CAVEATS
The USES directive was added in version 2.6.936300000 19990902.

Modules included as files instead of from the library increase the script's run time slightly, since these files must be checked for modification on every run. Once testing of a file module is completed, it is advisable to check it in to the library and remove the "=file" part of the clause to avoid this check.