Vortex texis.ini Configuration Settings

Certain site-wide properties of Vortex can be set in the Texis configuration file conf/texis.ini. For details on the format of this file, and 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) configuration file; see here.

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

Vortex Log
Default: %LOGDIR%/vortex.log in version 8 and later (%INSTALLDIR%/texis/vortex.log in version 7 and earlier).
Sets the log file for Vortex errors. When running the Texis Web Server (vhttpd), this value can be overridden in the vhttpd.conf file (here).

Default Database
Default: %INSTALLDIR%/texis/testdb
Sets the database that is used if no database is specified by the script. This is also the database used to store modules.

Default Script
Default: %INSTALLDIR%/texis/testdb/index
Sets the script that is executed if none is specified in the URL, when Vortex is invoked from the web.

ErrorScript
Default: unset
If set, and running from the web, this script will be run if the normal (requested via URL) script does not exist, cannot be compiled, or otherwise cannot be started. 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 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
Default: unset
If set, this plain HTML file will be sent 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 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
Default: %INSTALLDIR%/texis/scripts
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 %INSTALLDIR%/texis/scripts: this helps avoid permission problems with compiling scripts, e.g. where the CGI user does not have permission to write .vsc 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 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
Default: .vs "
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. .vsc) 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.

Vortex Compiled Extension
Default: .vsc (version 7 and earlier: .vtx)
The file extension to use for Vortex compiled (object) files. Avoid using .vso (or .vtc, used in version 7 and earlier) i.e. the Vortex Lock Extension value.

Vortex Lock Extension
Default: .vso (version 7 and earlier: .vtc)
The file extension to use for Vortex lock files - temporary compilation files that are renamed to Vortex Compiled Extension when compilation is done. Avoid using .vsc (or .vtx, used in version 7 and earlier) i.e. the Vortex Compiled Extension value.

Vortex Object File Access Method
Default: memorymap under Unix, read under Windows
Method to use to access Vortex object (.vsc) files; one of memorymap or read. The default is memorymap for Unix for speed, and read for Windows to allow re-compilation of in-use object files. Reading is slightly slower and uses more memory than memory-mapping, but in practice the difference is negligible. Added in Vortex version 7.01. Previous versions were always memorymap.

Ignore Env Script Name
Default: ext-IIS-prefix, redirect_handler=texis-vortex, exe-IIS-prefix
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 ".vsc", 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, exe-IIS-prefix, 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.

Warn Ret Loop
Default: no
During compilation, whether to warn if $ret is used in a loop context, which can cause problems. Overridden by the -[no-]warn-ret-loop option; see here for details. Was Warn If Ret Loop in version 7 (which is no longer checked in version 8 and later, in favor of Warn Ret Loop). Largely irrelevant with syntaxversion 8 and later, as loop statements returning $ret are effectively ROW. See also [Texis] Warn All (here).

Warn Unknown Pragma
Default: no
During compilation, whether to warn if an unknown pragma is used. Overridden by the --[no-]warn-unknown-pragma option; see here for details. Added in version 7.07.1574459000 20191122. See also [Texis] Warn All (here).

Warn Unknown Pragma If Token
Default: no
During compilation, whether to warn if an unknown token is used with pragma if. Overridden by the --[no-]warn-unknown-pragma-if-token option; see here for details. Added in version 7.07.1574459000 20191122. See also [Texis] Warn All (here).

Warn All
Default: no
Whether to turn on all Vortex warnings. Overridden by the --[no-]warn-all option; see here for details.

Warnings Are Fatal
Default: no
Whether Vortex compile warnings are fatal (i.e. treated as errors). Overridden by the --[no-]warnings-are-fatal option; see here for details.

Allow Cgi Command Line Options
Default: unset
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 unset (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
Default: %INSTALLDIR%/etc/egd-pool
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). Overridden by the entropypipe setting of urlcp (here). Added in version 4.01.1031693207 20020910.

Charset Converter
Default: "%INSTALLDIR%/etc/iconv" -f %CHARSETFROM% -t %CHARSETTO% -c
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. Added in version 5.00.1089408421 20040709.

Charset Config
Default: %INSTALLDIR%/conf/charsets.conf
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
Default: headers
The default value for the PRINTIF flag to <header> statements. Overridden by setting PRINTIF non-empty in a <header> statement (here). Note that the default (headers) is a behavior change from prior versions (previous default was always). Added in version 5.01.1111422505 20050321.

Cookies
Default: urldecode
Whether to URL-decode incoming cookie values when initializing Vortex variables or not. The value urldecode means URL-decode the values. 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
Default: 1
If nonzero, automatically create a database if it does not exist when referenced, e.g. when used indirectly in an <if> or assignment. Added in version 5.01.1157523656 20060906.

CGI Debug
Default: 0
If nonzero, enables CGI debugging features, such as the -dump option, in CGI mode. Added in version 4.02.1047916696 20030317.

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

Array Convert
Default: on
Sets default for <sqlcp arrayconvert>; same syntax. Setting off restores pre-version-6 Vortex variable behavior with strlst etc.

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

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

Texis Defaults Warning
Default: on
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.

If legacy scripts cannot be changed after an upgrade to version 6 or later, the warning may be silenced by changing it to off. Added in Texis version 6.

Compile SQL Expressions
Default: on
Whether to compile SQL expressions into the .vsc 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.

This setting can be overridden in a script with the compilesqlexpressions pragma (here). Added in version 6.01.

Allowed Literalprint Prefix
Default: unset

If non-empty, 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 +++.

Restore Stdio Inheritance
Default: no
Under Windows, whether to restore standard I/O handles original HANDLE_FLAG_INHERIT flag state after a process is exec'd. This should be no unless set otherwise by tech support. Added in version 7.07.1581108714 20200207.


Copyright © Thunderstone Software     Last updated: Jul 17 2021
Copyright © 2021 Thunderstone Software LLC. All rights reserved.