vxcp - set Vortex control parameters

SYNOPSIS

<vxcp setting [args ...]>

DESCRIPTION
The vxcp function allows control over miscellaneous Vortex settings at run time. Most of these settings will not need to be altered by typical Vortex scripts. The setting can be one of the following:

• putmsg   Controls what action(s) to take when <putmsg>-capturable messages are generated. Takes two arguments: one of "call", "log", "print", or "all", and a boolean value. The first argument names an action (or all three), and the second argument turns the action(s) on or off.

  When a message is generated, it can be printed to the output (print), logged to the vortex.log file (log), or the <putmsg> Vortex function (if defined) can be called (call). The default actions are to log and print the message. However, if a <putmsg> Vortex function is defined, logging and printing are turned off, and the function is called. It is assumed <putmsg> will completely handle the error, including logging it (or not) as the script author desires. (See here for more on capturing errors.)

  In many scripts, however, it is desirable to not only monitor errors with <putmsg>, but to still log them normally for later perusal. Since <putmsg> turns off logging, it has to be done "manually" in <putmsg> by looping over the messages.

  With <vxcp putmsg>, logging can be turned back on without such a manual loop. Message disposition can also be changed at run-time, e.g. to log certain function's messages but ignore others'.

  In Texis version 7 and later, the log and print actions may have a third state set: exceptiononly. When exceptiononly is set, the action is enabled only for Vortex putmsg exceptions - situations where the <putmsg> script function cannot be called, e.g. an ABEND. For all other (normal) situations the action is disabled. This allows logging/printing to be turned off normally - so a <putmsg> function can handle it - yet enabled for the abnormal situations where the messages would otherwise be lost. The exceptiononly value cannot be set for the call action.

  The return value from the putmsg setting is the previous setting value(s) (2, 1 or 0 for on, exceptiononly or off) for the named action. This enables a function to change an action temporarily, and restore the old settings without side-effects to the rest of the script. (Note that the setting "all" returns 3 values, for call, log, and print, in that order.)

  See also the <PUTMSG> compiler directive (here); <vxcp putmsg> overrides it (in most cases).

• putmsgbuffersize

  Takes an integer or integer-with-size-suffix argument (e.g. "100KB") that sets the Vortex <putmsg> buffer size in bytes; the default is 16KB. This buffer is used to hold error messages generated during a Vortex statement until the end of the statement, when the messages can be transferred to Vortex variables and the script's <putmsg> function called. A statement that generates many messages (e.g. from tracing) can exceed the buffer size, causing a "Too many messages for putmsg buffer" error and loss of messages; increasing the buffer size may avert this. Returns 1 on success, 0 on error. Added in version 6.00.1332547000 20120323.

• stack Takes an integer argument defining the maximum Vortex stack depth; -1 for infinite (no limit). The default is 250.

  It is rare that a script would need to increase its stack depth. An unexpected "Stack overflow" error message usually indicates that a function was infinitely recursive, i.e. kept calling itself (directly or through other functions) without returning. Setting a large or infinite stack limit will cause such a script to rapidly consume memory and CPU, possibly taking the machine down with it.

  The return value is the previous stack limit. See also the <STACK> directive (here); <vxcp stack> overrides it.

• timeout Takes an integer (-1 for infinite) indicating the script timeout in seconds from now. Or a Texis-parseable date can be given to indicate a deadline, such as "+1 minute". Returns the previous timeout, as a date deadline, or -1 if the previous timeout was infinite. See also the <TIMEOUT> directive (here); <vxcp timeout> overrides it. Allows the script timeout to be variable at run-time or on a function-by-function basis.

• timeouttext $text

  Sets the text/HTML to print at Vortex-script timeout to $text, overriding the text set in the <TIMEOUT> directive (here). Can be used to alter the text for different parts of a script, e.g. HTML vs. XML vs. text output sections. Added in version 7. Returns 1 on success, 0 on error.

• trap Debug setting. Takes a boolean or integer argument indicating whether to trap signals or not. Debugging/tech-support use. Returns the previous setting. Overrides the <TRAP> directive; see (here) for flag details.

• connreset Debug setting. Takes a boolean or integer argument indicating how to trap connection-reset on stdout (i.e. when the remote browser user hits the stop button early). Returns the previous setting. Overrides the <TRAP> directive; see (here) for flag details.

• tracepipe Debug setting. Takes an integer value indicating what tracing messages to issue for pipes. Value is a bitwise OR of any of the following values; the default is 0 (i.e. no tracing):

  • 0x00000001: After open(), close(), TXcreatethread(), LogonUser() etc.

  • 0x00000002: After select(), WaitForMultipleObjects()

  • 0x00000004: After reads

  • 0x00000008: After writes

  • 0x00000010: After SetEvent(), ResetEvent()

  • 0x00000020: After thread run (at soft exit in thread)

  • 0x00000040: The data read

  • 0x00000080: The data written

  • 0x00010000: Before open(), close(), TXcreatethread(), LogonUser() etc.

  • 0x00020000: Before select(), WaitForMultipleObjects()

  • 0x00040000: Before reads

  • 0x00080000: Before writes

  • 0x00100000: Before SetEvent(), ResetEvent()

  • 0x00200000: Before thread run (at start in thread)

  • 0x00400000: The data buffer before reads

  • 0x00800000: The data buffer before writes
  Values may change or be added to in future releases. Returns previous setting.

• htmlmode Takes a boolean argument indicating whether to run in HTML mode or not. This controls whether variables are HTML-escaped when printed as-is, and is on by default if there is no URL file extension (here) or it is .htm/.html. Returns the previous setting. Added in version 3.01.982400000 20010217.

• filemsg Takes a boolean argument indicating whether or not to issue a putmsg for sysutil and some syscp file-oriented actions' errors. The default is on. This setting can be turned off if a large number of sysutil calls are to be made and errors are expected but benign; this avoids the putmsg for just these functions without the hassle of a Vortex <putmsg> function. Returns the previous setting. Added in version 3.01.976200000 20001207.

• execmsg   Takes a boolean argument indicating whether or not to issue a putmsg for <EXEC> errors. The default is on. Added in version 5. Note that in version 5 and later errors are now returned in $ret.err, regardless of this setting. Thus if error-checking is being done after <EXEC> calls, execmsg can be turned off to prevent spurious messages, and $ret.err checked for errors.

• libpath Takes a single string argument, which is a colon-separated (Unix) or semicolon-separated (Windows) list of directories to search for loadable modules. Overrides the conf/texis.ini file setting [Texis] Lib Path. Loadable modules currently include the JavaScript and SSL (HTTPS) plugins. The path may include the following keywords that have special meanings:

  • %INSTALLDIR% The Texis install directory

  • %BINDIR% The Texis binary (executables) directory

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

  • %SYSLIBPATH% The system-dependent dynamic library search path (e.g. LD_LIBRARY_PATH)

  • %% A percent sign

  The default value (if libpath and the conf/texis.ini setting [Texis] Lib Path are unset) is %EXEDIR%:%BINDIR%:%SYSLIBPATH% for Unix or %EXEDIR%;%BINDIR%;%SYSLIBPATH% for Windows. %EXEDIR% was added in version 5.01.1214185000 20080622.

  In version 4.04.1073104616 20040102 and earlier, the above keywords were not supported. Instead, the entire path could be set to the single keyword bin to indicate the installed binary directory (default), or sys to indicate a system-dependent search path. Returns the previous setting.

  The libpath setting was added in version 4.01.1023500000 20020607.

• libcheckversion $module on|off Controls whether to check version of loadable $module when it is loaded. Loading the wrong version can cause aberrant behavior or an ABEND, so a version check is normally done if possible. This setting can be used to override the check, if a different version of the loadable module is being used that is known to be binary-compatible. The possible values for $module are ssl. Note that overriding the check while loading an incompatible module can cause unpredictable behavior. Added in version 4.01.1031325401 20020906.

• transferlog $file Sets the web server transfer log to use for this transaction, overriding the web server configured TransferLog value. Note that this is only possible in the integrated vhttpd environment, i.e. VortexPath, EntryScript or ExitScript. If the script is running in CGI mode (e.g. under IIS or Apache), this setting fails because Vortex has no knowledge of or access to external-server configs. The setting also fails if the AllowLogFileOverride setting (here) in the vhttpd config is false. Can be used for fine-grained control of transfer log, i.e. to split logs based on different scripts or functions, e.g. in an EntryScript (here). An empty string for $file means no log (i.e. /dev/null). If $file has no dir component, it is relative to LogDir. Otherwise, if it is not absolute, it is ServerRoot-relative. Returns 1 if success, 0 on error. Added in version 5.01.1170123063 20070129.

• errorlog $file Sets the web server error log (not Vortex log) to use for this transaction, overriding the web server configured ErrorLog value. Note that this is only possible in the integrated vhttpd environment, i.e. VortexPath, EntryScript or ExitScript. If the script is running in CGI mode (e.g. under Windows or Apache), this setting fails because Vortex has no knowledge of or access to external-server configs. The setting also fails if the AllowLogFileOverride setting (here) in the vhttpd config is false. Can be used for fine-grained control of error log, i.e. to split logs based on different scripts or functions, e.g. in an EntryScript (here). An empty string for $file means no log (i.e. /dev/null). If $file has no dir component, it is relative to LogDir. Otherwise, if it is not absolute, it is ServerRoot-relative. Returns 1 if success, 0 on error. Added in version 5.01.1170123063 20070129.

• applylicense $data $user $pass [$remoteUrl]   Applies a Texis license update via the Texis Monitor schedule/license server. May be used by the Webinator admin GUI to upgrade the license. $data contains data in license.upd format - typically obtained from Thunderstone tech support - and $user/$pass are the user/password to authorize the license update - typically the administrative account created at installation. The Texis Monitor will verify the user/pass against the [License Update] settings in conf/texis.ini and apply the license. By default, the license will be applied to the local schedule/license server address configured in the [Scheduler] section (e.g. 127.0.0.1); if the license should be applied to a different server, a URL can be specified with $remoteUrl (this server must be configured to accept outside license update requests).

  Note that most current <urlcp> settings apply, so changing settings from the default could result in an insecure transaction. E.g. tracing should be turned off, secure set to `required` (if it was changed), etc. See discussion of [License Update] settings in the Texis manual for details on requirements and caveats. Added in version 6. See also the --apply-license command-line option, here.

  The return value is a string with a result-code token followed by a human-readable error message, in the form "Err=token Message text here". On success, the return value should start with "Err=Ok". Some other possible tokens include:

  • FetchError: A network/fetch error occurred.

  • LicenseServiceDisabled: The Texis Monitor does not have the [License Update] service enabled.

  • SecureConnectionRequired: A secure (SSL) connection is required but could not be established.

  • Unauthorized: The transaction was unauthorized, e.g. the user or password was invalid.

  • InvalidLicense: The license supplied was invalid.

  • InternalError: An internal error occurred on the server.

• maxurllen $sz Sets the maximum URL length for $url/$urlq to the integer value $sz. The default is 512. This limit prevents huge URLs from being accidentally produced, e.g. if a large or large-number-of-values variable is URL-exported. Exceeding the limit may generate a message such as State URL exceeds limit of 512 bytes: truncated and state information will be lost. Added in version 5.01.1237486600 20090319. Returns previous value.

• tracevortexlog $file

  Sets the Trace Vortex log file. The default is the Vortex script path (without extension), with .vstrace appended. Setting it to empty restores the default value. Returns the previous value. See the Trace Vortex appendix (here) for details on tracing Vortex scripts.

• tracevortex on|off

  Turns Trace Vortex logging on or off. See the Trace Vortex appendix (here) for details on tracing Vortex scripts.

• compatibilityversion $version  

  Sets Texis compatibility version to $version, which is a Texis version string of the form "major[.minor[.release]]", where major is a major version integer, minor is a minor version integer, and release is a release integer (i.e. the format used in texis -version. This will attempt to make Texis compatible with the given version - i.e. change behavior to match it - so that scripts written for an earlier Texis version might be able to run with the current Texis version. Note that not all earlier versions are supported, and even if supported, not all behavior changes may be rolled back. Also, as this is a run-time setting, properties and settings initialized from conf/texis.ini may be changed. A version that is supported currently may not always be supported in the future, though generally at least one major version prior to the current one will be; e.g. version 7 supports setting compatibility to 6. As this setting may have many side effects and change many other settings, it should generally only ever be called once, at the start of a script, and before any other setings. Returns "Ok" on success, otherwise a human-readable error message. Added in version 7. See also the --compatibility-version command-line option.

  In version 7, setting compatibilityversion to 6 causes the following changes to restore version 6 behavior. For details on these and other version 7 changes, see the Texis 7 Features and Changes appendix (here):

  • inmode is set to intersect

  • strlst relational operators (less-than, greater-than etc.) with a varchar operand does not promote the varchar to strlst via create mode

  • strlst comparisons do not use stringcomparemode

  • Multi-item (strlst) index results are not de-duplicated

  • multivaluetomultirow defaults to off

  • <sum> behavior determined by args not format

  • <sql output="xml"> parses HTML entities

  • The default Metamorph index type is non-inverted (wordpositions off)

  • varbyte conversions to/from varchar in Texis hexify/unhexify bytes

  • varchartostrlstsep is set to lastchar, and in future settings the builtindefault value becomes equivalent to lastchar

  • Converting an empty string to strlst when varchartostrlstsep is create yields a one-empty-string strlst (not a zero-item strlst)

  • The putmsg exceptiononly state cannot be set

  • <getvar> and <setvar> will not issue messages about illegal/unsettable variables

  • <vxcp putmsg> value of exceptiononly added

  The following version 7 changes are not rolled back when setting compatibilityversion 6:

  • Trace Vortex script tracing

  • REX does not return redundant empty hits

  • <sandr> does not infinite-loop, and matches like <rex>

  • <fmt> %l/, %l: codes changed

  • Empty-element Vortex statement tags allowed

  • Vortex pragma stacks

  • <write> output, flags, skiponfail options added

  • <vxcp> timeouttext, compatibilityversion added

  • HTTP cookie acceptance relaxed

  • xmlTreeXPathSetContext() added to XML API

  • ret.size is int64 on all platforms

  • New SQL operators SUBSET and INTERSECT added

  • ALTER INDEX, CREATE INDEX ... WITH options SQL syntax added

DIAGNOSTICS
The vxcp function returns setting-dependent value(s).

EXAMPLE

<A NAME=dosomething PRIVATE>
<LOCAL prev>
  <vxcp putmsg all off>
  <$prev = $ret>
  <FunctionThatCausesErrors>
  <vxcp putmsg all $prev>
</A>

This function completely disables any messages generated by <FunctionThatCausesErrors> that we do not care about, avoiding clutter in the log. However, we do care about errors from other functions in the script, so the previous putmsg action settings are saved and restored.

CAVEATS
The vxcp function was added in version 3.0.947100000 20000105.

It is inadvisable to set a large stack limit unless a script explicitly needs to make use of deep recursion.

Turning signals off with trap can cause aberrant behavior.

SEE ALSO
sqlcp, apicp, urlcp, PUTMSG, TIMEOUT, STACK, TRAP