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 p.  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, eg. 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 (p. ); <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, ie. 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 (p. ); <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 (p. ); <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. Unsupported/internal use. Returns the previous setting. Overrides the <TRAP> directive (p. ).

• connreset
  Debug setting. Takes a boolean or integer argument indicating how to trap connection-reset on stdout (ie. when the remote browser user hits the stop button early). Returns the previous setting. Overrides the <TRAP> directive (p. ).

• 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 (p. ) 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 texis.cnf 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 (eg. LD_LIBRARY_PATH)

  • %% A percent sign

  The default value (if libpath and the texis.cnf 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, ie. VortexPath, EntryScript or ExitScript. If the script is running in CGI mode (eg. 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 (p. ) in the vhttpd config is false. Can be used for fine-grained control of transfer log, ie. to split logs based on different scripts or functions, eg. in an EntryScript (p. ). An empty string for $file means no log (ie. /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, ie. VortexPath, EntryScript or ExitScript. If the script is running in CGI mode (eg. 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 (p. ) in the vhttpd config is false. Can be used for fine-grained control of error log, ie. to split logs based on different scripts or functions, eg. in an EntryScript (p. ). An empty string for $file means no log (ie. /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.

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 don't 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 functions; PUTMSG, TIMEOUT, STACK, TRAP directives