Vortex conf/texis.ini Configuration Settings

Certain site-wide properties of Vortex can be set in the Texis configuration file conf/texis.ini. This plain ASCII text file resides in the install directory (usually "/usr/local/morph3" under Unix, or "c:\morph3" under Windows). The format of this file is similar to Windows .ini files, where a section is denoted by a name in brackets on one line, and settings for that section follow, one per line:

  [Section One]
  Setting One = value
  Setting Two = value

  [Section Two]
  Setting One = value
  Setting Two = value

Setting and section names are case- and space-insensitive. A line starting with ";" (semicolon) or "#" (pound-sign) denotes a comment. For more details on other sections' settings that apply to other programs, see the "Texis Configuration File" section of the Texis manual. Also note that many of these settings can be overridden by the Texis Web Server (vhttpd) config file; see here.

A setting value may contain any of the following special variable references, which will be replaced as noted:

• %INSTALLDIR%: The Texis installation directory.

• %BINDIR%: The Texis binaries (executables) directory, typically "c:\morph3" under Windows and "/usr/local/morph3/bin" under Unix.

• %EXEDIR%: The parent directory of the currently running executable (or the Texis binary dir, if the former cannot be determined)

• %SCRIPTROOT%: The value of the setting [Texis] Script Root. Not usable in that setting's value. This variable was added in version 6.

• %DOCUMENT_ROOT%: The active document root. Added in version 6.

• %SERVERROOT%: The active server root. Added in version 6.

Note that %DOCUMENT_ROOT% and %SERVERROOT% should only be used in Web-only settings, e.g. [Texis] Script Root, not in settings that may also be relevant to command-line invocations.

The following Vortex-specific settings appear under the [Texis] section of conf/texis.ini:

• Vortex Log     Sets the log file for errors. The default is texis/vortex.log in the install directory. When running the Texis Web Server (vhttpd), this value can be overridden in the vhttpd.conf file (here).

• Default Database     Sets the database that is used if no database is specified by the script. This is also the database used to store modules. The default is texis/testdb in the install directory.

• Default Script     Sets the script that is executed if none is specified in the URL, when Vortex is invoked from the web. The default is texis/testdb/index in the install directory.

• ErrorScript     Sets the Vortex script to run if the requested script cannot be started, when Vortex is invoked from the web. This script would be run if the requested script does not exist, cannot be compiled, or otherwise cannot be started normally. Any putmsg errors generated by the attempt to start the requested script are saved for capture by the ErrorScript's <putmsg> function. This enables the ErrorScript to control what errors are seen by the user, even for errors that other scripts can't capture. It can then take appropriate action such as generating a useful error page, redirecting to another page, notifying the site administrator, etc. Vortex is installed with the error script texis/scripts/errorscript configured as an example.

  Note that any errors generated by the requested script after it has started are capturable by that script's <putmsg>, not the ErrorScript. Hence the main script's <putmsg> function should be the first place to put error checking. ErrorScript is for fatal startup errors.

  The ErrorScript value is a file path to a Vortex script, typically /usr/local/morph3/texis/scripts/errorscript. If a relative path is specified, it is taken as relative to the web server's SERVER_ROOT directory. This allows multiple ErrorScripts to be specified across multiple web servers via the single conf/texis.ini file. (Note that the web server must set the environment variable SERVER_ROOT for relative paths to work.)

  When running the Texis Web Server (vhttpd), the ErrorScript value can be overridden in the vhttpd.conf file (here). Added in version 4.00.1018000000 20020405.

• ErrorFile     Sets the plain HTML file to send if ErrorScript is to be invoked but is unspecified or cannot be started. The string %errors% in the file is replaced with the text of any error messages. Note that this is a plain HTML file, intended as a last-ditch "fallback" if ErrorScript fails. Primary responsibility for handling errors should lie with the <putmsg> function in the main script first, then the ErrorScript script, then ErrorFile.

  The ErrorFile value is a file path to a plain HTML file, typically /usr/local/morph3/texis/scripts/errorfile. If a relative path is specified, it is taken as relative to the web server's SERVER_ROOT directory. This allows multiple ErrorFiles to be specified across multiple web servers via the single conf/texis.ini file. (Note that the web server must set the environment variable SERVER_ROOT for relative paths to work.)

  When running the Texis Web Server (vhttpd), the ErrorFile value can be overridden in the vhttpd.conf file (here). Added in version 4.00.1018000000 20020405.

• ScriptRoot     Sets the root file directory to look for Vortex scripts, when run from the web. In old versions (4 and earlier) the default is the web server's document root (i.e. the DOCUMENT_ROOT environment variable).

  In version 5 and later, the default is the texis/scripts subdirectory of the install dir: this helps avoid permission problems with compiling scripts, e.g. where the CGI user does not have permission to write .vtx files to document root. It also prevents Web users from downloading the contents of Vortex scripts, as they are now outside the web server tree.

  The ScriptRoot value is a file directory. If a relative path is specified, it is taken as relative to the web server's SERVER_ROOT directory. This allows multiple ScriptRoots to be specified across multiple web servers via the single conf/texis.ini file. (Note that the web server must set the environment variable SERVER_ROOT for relative paths to work.)

  In version 5 and later, ScriptRoot can also be set to the special value "%DOCUMENT_ROOT%" (no prefixes/suffixes) to use the current document root as the script root. This may be for back compatibility with a version 4 installation, or where multiple web servers are being run and a different script root is desired for each server.

  When running the Texis Web Server (vhttpd), the ScriptRoot value can be overridden in the vhttpd.conf file (here).

  This setting was added in version 4.00.1017300000 20020327.

• Vortex Source Extensions     Space-separated list of file extension(s) for Vortex source files, including the period if applicable. Individual extensions may be quoted, e.g. if empty. The preferred/default extension is listed first. In version 6, the default is ".vs ''", i.e. the preferred extension is ".vs" but no-extension files are accepted for back-compatibility. In version 5 and earlier, the default was no extension. The source (or object i.e. ".vtx") extension is optional when specifying a script to run via the command-line or web, except where a mapping requires it, i.e. [Httpd] Vortex By Ext Path, vhttpd VortexByExtPath or Apache CGI by-file-extension mappings. Added in version 5.01.1158816000 20060921.

• Ignore Env Script Name     When to ignore the SCRIPT_NAME environment variable when constructing the Vortex $url variable. In some CGI environments (particularly when the CGI mapping is by-file-extension and not by-directory), SCRIPT_NAME is set incorrectly or redundantly, and concatenating it with PATH_INFO (as per CGI/1.1 spec) would result in the wrong self-referential URL; in these instances SCRIPT_NAME should be ignored. The Ignore Env Script Name setting controls when this occurs. It is a comma-separated list of any of the following:

  • ext-IIS-prefix When SCRIPT_NAME ends in one of the non-empty Vortex Source Extensions or ".vtx", and SERVER_SOFTWARE starts with "Microsoft/IIS", and SCRIPT_NAME is a prefix of PATH_INFO. This typically indicates a Microsoft IIS/6.0 application mapping, where both SCRIPT_NAME and PATH_INFO contain the Vortex script.

  • redirect_handler=action-name When the environment variable REQUEST_HANDLER is set to action-name. This may indicate an Apache 2.1+ Action/AddHandler by-file-extension mapping, where using SCRIPT_NAME would give a usable URL, but different from the request (and thus break cookies).

  • exe-IIS-prefix When SCRIPT_NAME ends in ".exe", and SERVER_SOFTWARE starts with "Microsoft/IIS", and SCRIPT_NAME is a prefix of PATH_INFO. This typically indicates a Microsoft IIS/7.0 Script Map (instead of a CGI-exe map), where both SCRIPT_NAME and PATH_INFO contain the "texis.exe" value, and PATH_TRANSLATED is incorrect. SCRIPT_NAME will actually be removed from PATH_INFO instead of being ignored, in this instance. Added in version 5.01.1229472493 20081216.

  • always Always ignore SCRIPT_NAME.
  The default value is "ext-IIS-prefix,redirect_handler=texis-vortex", which handles IIS/6.0, as well as Apache 2.1+ (if the Action is named "texis-vortex"). Added in version 5.01.1182304953 20070619.

• Allow Cgi Command Line Options     Which Vortex command-line options to enable in CGI mode. This is a space-separated list of command-line options (each optionally double-quoted). The default is empty (none) for security, since the QUERY_STRING from the user may be mapped to the command line by the web server. However, it may contain the options --ignore-env-script-name or --, if for example the former must be set differently explicitly for different CGI environments (this is an unlikely situation). In such cases, -- (end of options) should also be allowed, and any server-configured command-line options should be configured and ended with -- before any user-supplied (QUERY_STRING) options are possible. Added in version 5.01.1182042673 20070616.

• Entropy Pipe     The path to the prngd daemon's Unix socket. This is only required for Unix systems, and only if using SSL (e.g. in <fetch>) and there is no random device (e.g. /dev/random). The default is %INSTALLDIR%/etc/egd-pool. Overridden by the entropypipe setting of urlcp (here). Added in version 4.01.1031693207 20020910.

• Charset Converter     The program and arguments to run for translating character sets (e.g. when <fetch>ing pages.) It should take stdin in one charset and output stdout in another requested charset. The variables %CHARSETFROM% and %CHARSETTO% will be replaced with the input and output (requested) charsets, respectively. Embedded-space arguments may be double-quoted. The default is "%INSTALLDIR%/etc/iconv" -f %CHARSETFROM% -t %CHARSETTO% -c. Added in version 5.00.1089408421 20040709.

• Charset Config     The charset config file. See the charsetconfigfromfile setting of <urlcp> (here) for details on the file format. If unset, the default charset config file is conf/charsets.conf in the install dir. If the config file cannot be found, an internal default config is used. Added in version 6.

• Default Header Printif     The default value for the PRINTIF flag to <header> statements. Overridden by setting PRINTIF non-empty in a <header> statement (here). The default value is headers. Note that this default is a behavior change from prior versions (previous default was always). Added in version 5.01.1111422505 20050321.

• Cookies     Whether to URL-decode incoming cookie values when initializing Vortex variables or not. The value urldecode means URL-decode the values, and is the default. The value asis means leave values as-is, i.e. do not decode. Can be overridden in a script with the <COOKIES> directive (here). Added in version 5.01.1121884376 20050720 (default urldecode in previous versions).

• Auto Create Db   If nonzero, automatically create a database if it does not exist when referenced, e.g. when used indirectly in an <if> or assignment. The default is 1. Added in version 5.01.1157523656 20060906.

• CGI Debug     Controls whether to enable CGI debugging features, such as the -dump option, in CGI mode. Off (0) by default. Added in version 4.02.1047916696 20030317.

• Default Vortex Sort Shortest   Nonzero: the default for <sort>/<uniq> should be SHORTEST, not LONGEST. Default is 0 (i.e. LONGEST). Added in version 5.01.1189552000 20070911. Previously all <sort>s were SHORTEST.

• Array Convert     Sets default for <sqlcp arrayconvert>; same syntax. Default is on; can be set to off to restore pre-version-6 Vortex variable behavior with strlst etc.

• Vortex Add Trailing Slash     Whether to add a trailing-slash (via a redirect) to "directory" script URLs - those without a function/MIME-extension or user-path. The default is no. See also the <addtrailingslash> directive (here), which overrides this. Added in version 5.01.1227568000 20081124.

• Exec Quote Args     Sets default for <exec quoteargs> flag (here). Default is 1 (on). Added in version 6.

• Texis Defaults Warning     Whether to issue a warning message when <apicp texisdefaults> is set, as in version 6 and later texisdefaults is deprecated, since Texis defaults have changed to match Vortex defaults. The texisdefaults setting still takes effect, but as it may be removed in a future release, a warning is issued to encourage its removal in scripts. The setting <apicp querysettings texis5defaults> should be used instead.

  The default for Texis Defaults Warning is on. However, if legacy scripts cannot be changed, the warning may be silenced by changing it to off. Added in Texis version 6.

• Compile SQL Expressions     Whether to compile SQL expressions into the .vtx object file where possible, rather than interpret them on the fly at run-time. SQL expressions are used in parenthetical variable assignments (e.g. <x = (y + 5)>) and complex <if> statements, amongst other places. Compiling them speeds up script execution, as the original expression then does not need to be re-interpreted by the SQL engine every time the statement is run.

  The default is on, and can be overridden in a script with the compilesqlexpressions pragma. Added in version 6.01.

• Allowed Literalprint Prefix     When using <!-- pragma literalprint off -->, lines that begin with this prefix are still allowed to be printed. Useful for defining a project-wide debug syntax for quick output, but can easily be verified that it's removed by compiling with this cleared.

  E.g. Allowed Literalprint Prefix = +++ will allow lines starting with `+++'. The default is empty/unset/off.