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's 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's 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'.

  The return value from the putmsg setting is the previous setting value(s) (1 or 0) 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).

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

• 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

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

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.

The <TIMEOUT> directive should be used in favor of <vxcp timeout> where possible.

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