Vortex Optional Command-line Options

These Vortex command-line options modify other actions:

• -d db Use database db instead of the default/installed database path. A run-time <DB> statement in a script will override this.

• -u user Login as the given Texis user.

• -p password Login with the given password.

• var=value Assign the URL-encoded value to var on startup. Multiple assignment statements for the same variable will result in multiple values for that variable. Vortex scripts only.

• -M Output the source file:line first in error messages. This is useful in an editing/compilation environment such as Gnu emacs that can parse this output and automatically go to the source line of the error.

• -e file Log errors to file instead of the default/installed log file. A - (dash) means log to standard error. Errors are also printed in the output, unless a putmsg function (here) is defined to catch them.

• -t n Use a timeout of n seconds when running a script; -1 for no timeout. Overrides the script <timeout> (here, but not run-time timeouts via <vxcp timeout>.

• --shebang[{,| }options]

  Parse comma- or space-separated Vortex options that are part of this same argument. This may be used in Unix "shebang" scripts, where most platforms either merge space-separated arguments on the "#!" command line (after the interpreter) into one argument, or silently drop arguments after the first (e.g. Solaris), either of which would cause problems. By using --shebang, such a merged argument may be passed to Vortex such that it knows to space-separate the remainder of the argument into further options.

  Combining this option with -R enables a Vortex script to be made into a self-executing script (in Unix), and still pass Vortex options on the command line. E.g. to set the error log to standard error:

  #!/usr/local/morph3/bin/texis --shebang,-e,-,-R
        <script language="vortex">
        ...

  Note that -R is always last. The script (not Vortex) command-line arguments may be obtained with <vxinfo scriptargs> (here).

• --ignore-env-script-name{=| }value,... Override texis.ini setting [Texis] Ignore Env Script Name (here). Usually the texis.ini setting is enough, but this command-line override can be used (e.g. in the web server config) if multiple CGI environments are in simultaneous use and the setting must differ between them. Note that it will be ignored in CGI mode (like all command line options) unless permitted via [Texis] Allow Cgi Command Line Options (here). Added in version 5.01.1182304953 20070619. The non-assignment, separate-argument syntax was added in version 8.

• --pause-at-exit At program exit, pause until user presses Enter. Can be useful when running a script in a dedicated command prompt window, to avoid having the window close immediately after the script ends without having a chance to see its output. Added in version 5.01.1225327000 20081029.

• --warn-ret-loop

• --no-warn-ret-loop

  Warn (or not) during compilation if $ret is used in a loop context (without ROW behavior in effect), either directly (e.g. <loop $ret>) or indirectly (e.g. <stat nonempty ...>). This usage can cause problems for code called inside such a loop, because like any other variable, $ret cannot have its type nor number of values changed while being looped over. Thus any new $ret returned by calls inside the loop will be forced to have its type cast to the looped $ret type, will lose all but the first returned value, and the first value will be placed in the middle of $ret (i.e. the current loop value). This may result in loss of data, error messages from type conversions that fail, and unexpected return type(s).

  The default is the value of the texis.ini setting [Texis] Warn Ret Loop (yes/no); if that is unset, [Texis] Warn All is used; if that is unset, the warning defaults to "no". Added in version 7.01.1409098000 20140826 as --[no-]warn-if-ret-loop (with texis.ini setting [Texis] Warn If Ret Loop); renamed to --[no-]warn-ret-loop (for consistency with other warning options) in version 8. See also --warn-all.

  Note that in version 8 and later syntax, this warning is rarely (if ever) issued, since looping statements default to not accumulating their return values.

• --warn-unknown-pragma

• --no-warn-unknown-pragma

  Warn (or not) during compilation if an unknown pragma (here) is used. Normally, unknown pragmas are silently ignored, for back-compatibility since they are in comments.

  The default is the value of the texis.ini setting [Texis] Warn Unknown Pragma (yes/no); if that is unset, [Texis] Warn All is used; if that is unset, the warning defaults to "no". Added in version 7.07.1574459000 20191122. See also --warn-all.

• --warn-unknown-pragma-if-token

• --no-warn-unknown-pragma-if-token

  Warn (or not) during compilation if an unknown pragma if token (here) is used. Normally, unknown if tokens are silently taken as 0, for back-compatibility.

  The default is the value of the texis.ini setting [Texis] Warn Unknown Pragma If Token (yes/no); if that is unset, [Texis] Warn All is used; if that is unset, the warning defaults to "no". Added in version 8. See also --warn-all.

• --warn-all

• --no-warn-all

  Turn on (or off) all --warn-... warnings listed above. The default for each warning is its command-line or texis.ini value; if those are unset, the warning is set from the texis.ini setting [Texis] Warn All value (yes/no). Added in version 7.07.1568230000 20190911.

• --warnings-are-fatal

• --no-warnings-are-fatal

  Treat compilation warnings as fatal, i.e. fail the compile and exit non-zero. Without this flag set, some compilation messages are non-fatal if the compiler considers them benign (e.g. too few/many arguments for <fmt>): this may allow the script to finish compiling and run. In a production environment (e.g. automatic re-compilation during a script upgrade), running the script - even with potential errors - may be more important than halting execution to fix a warning in code that might not even be reached at runtime; thus this flag is off by default. During development however, it is good practice to set this flag, to catch such errors early when stopping compilation/execution is more permissible.

  The default value is the value of the texis.ini setting [Texis] Warnings Are Fatal (yes/no); if that is unset, it defaults to "no". Added in version 6.00.1306875000 20110531.

• --info-compile-reason

• --no-info-compile-reason

  If compiling a script, issue a message with the reason why. For diagnostics/debugging.

• --optimize-accum-warnings

• --no-optimize-accum-warnings

  During --translate-from-version, enable or disable an optimization that suppresses some unneeded Looping statements do not accumulate return values ... warnings. Default is enabled. Should only be needed if this optimization is found to be incorrect. Added in version 8.00.1643388779 20220128.

• --translation-header

• --no-translation-header

  During --translate-from-version, enable or disable printing of one-time code that sets syntaxversion and compatibilityversion to the targeted version (the texis executable's default version).

  This header code is normally issued to ensure the targeted version is set when the translated script is compiled and run, in case the configured default ([Texis] Compatibility Version) is different. The configured default might have been temporarily set to an earlier version than the targeted version, to aid running other legacy scripts - that may not have been translated yet - by the targeted/new texis. This lets a site's scripts be upgraded gradually. The header code is then removed by hand from translated scripts after all of a site's scripts have been translated and tested, and the [Texis] Compatibility Version setting has been removed.

  But if a site's scripts are to be translated and made live all at once, the temporary [Texis] Compatibility Version setting is not needed - nor is the extra header code. Using -no-translation-header suppresses the code, saving the effort of manually removing it. --translation-header enables printing of it, which is the default. Added in version 8.01.1706653574 20240130.

• --var-arg-decode

• --no-var-arg-decode

  URL-decode (or not) command-line variable assignment arguments (both variable name and value). The default is to decode. Added in version 7.00.1362529000 20130305.

• --compatibility-version{=| }version

  Sets Texis compatibility version to given version. See <vxcp compatibilityversion> (here) for details.

• --lib-path{=| }path

  Sets path to use when searching for Texis/Vortex shared libraries. See <vxcp libpath> (here), which can override this at run time, for details. Added in version 7.02.1408567000 20140820.

• -- Indicates end of options, i.e. what follows (if anything) is the script or SQL statement. Added in version 5.01.1182193063 20070618.