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 (meaning all actions), and a boolean value. The first argument names an action, and the second argument turns the action 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 somewhere) 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.

  • putmsgflags $flags [$flags ...] $onOff

    Sets given $flags value(s) on or off. Flags are:

    • pid Show PID in parentheses in logged and printed putmsgs.

    • threadid Show thread ID/name (if not main) after the PID (if shown) and a colon, in same parentheses as PID, in logged and printed putmsgs.

    • printtime Print timestamp when printing putmsgs; normally only shown when logging.

    The $onOff value is a parallel array of boolean values to set the corresponding flags to; if fewer values given than flags, last value is re-used. Returns previous value(s) of given flags. putmsgflags, threadid and printtime were added in version 7.06.1479841000 20161122; pid in version 7.07.1559836000 20190606. In version 8 and later, pid, threadid, and printtime are always on for consistency, and attempts to turn them off are silently ignored.

  • 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 [$hdrNames $hdrValues]

    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.

    In version 7.06.1541109000 20181101 and later, an optional $hdrNames $hdrValues pair of arguments may be given: these are parallel header names and values to print during the timeout as well. Like the text, these will take effect only on timeout. Additionally, these headers will only be printed if no content has been printed yet at the time of timeout. These can be used to set a different content type and/or status for a timeout vs. the main script output. If no $hdrNames $hdrValues arguments are given, no additional/different headers will be printed on timeout.

  • 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.

  • tracealarm

    Debug setting. Takes an integer value indicating what tracing messages to issue for alarms; same bit flags as the -tracealarm command-line option (here). Flags may change or be added to in future releases. Returns previous setting. Added in version 7.06.1477338000 20161024.

  • tracelib

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

    • 0x01: libpath expansion

    • 0x02: Library file search and loading

    • 0x04: Symbol/function lookup
    Values may change or be added to in future releases. Returns previous setting. Added in version 7.00.1372360000 20130627.

  • 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.

  • tracewatchpath

    Debug setting. Takes an integer whose bits are flags indicating what trace messages to issue for <watchpath>:

    • 0x00001: open/close watch/events

    • 0x00002: select()/Wait...() after

    • 0x00100: <sleep> notifications (open/close/read/write)

    • 0x00200: worker thread begin/end

    • 0x20000: select()/Wait...() before

    Values may change or be added to in future releases. Returns previous setting. Added in version 7.06.1478747000 20161109 (note that <watchpath> was added in version 8).

  • 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 if an HTML or an HTML-like MIME type is set for output, either explicitly via header or implicitly via URL extension. In version 7.01.1390866000 20140127 and later, the MIME types text/xml, application/xml and application/xhtml+xml are also recognized HTML-like MIME types; previous versions only recognized text/html and text/vnd.wap.wml. 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.

  • execendiotimeout N

    Sets the timeout (in seconds) for terminating <exec> I/O threads under Windows. The default is 10 seconds. Returns previous value. Added in version 5.01.1153260000 20060718.

  • 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 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

    • %LIBDIR% The Texis library directory (typically the lib subdir of the Texis install dir); added in version 8

    • %LOGDIR%

      The log directory, i.e. [Texis] Log Dir value. For log files. Added in version 8.

    • %RUNDIR%

      The run directory, i.e. [Texis] Run Dir value. For run-time-only files, e.g. PID files etc. Added in version 8.

    • %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 texis.ini setting [Texis] Lib Path are unset) is %EXEDIR%:%LIBDIR%:%SYSLIBPATH in version 8+, or %EXEDIR%:%BINDIR%:%SYSLIBPATH in version 7-. Under Windows the values are semicolon-separated, not colon-separated. %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. See also the --lib-path option (here).

  • 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 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 or $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, or State query string exceeds limit of 512 bytes: truncated at value 0 of variable $query, and state information will be lost. Added in version 5.01.1237486600 20090319. Returns previous value. Note that the limit applies to $url and $urlq separately, since they are invoked at separate times. Thus with a maxurllen of 512 bytes, a combined $url/$urlq URL could reach 1024 bytes before truncation.

  • tracevortex log $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.

  • tracevortex forceflush on|off

    When Trace Vortex logging is on, force a flush to the log file after every write. This may help ensure the current (or most recent) statement is written to the log if the Texis executable hangs or ABENDs during tracing. Note that it is highly inefficient to enable such constant flushing, and so forceflush should not be enabled normally.

  • 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 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; and the [Texis] Compatibility Version setting for texis.ini, which this setting defaults to.

    In version 7 or later, 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

    Caveat: In Texis version 8 or later, changing the compatibility version (e.g. via texis.ini) may cause Vortex scripts to be automatically recompiled upon next run, because the default syntax version is the compatibility version.

  • vardebugprintstyle always|once

    Print CSS style for $? variable debug syntax always (i.e. whenever the syntax is used), or only once after first use. Returns 0 on error.


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

Copyright © Thunderstone Software     Last updated: Apr 15 2024

 

Copyright © 2024 Thunderstone Software LLC. All rights reserved.