vxinfo - get miscellaneous Vortex information

SYNOPSIS

<vxinfo $what [$arg ...]>

DESCRIPTION
The vxinfo function returns miscellaneous Vortex information, depending on the $what parameter:

• outputsz Returns the number of bytes output by the script so far, as a long. This does not count redirected output, i.e. the input to CAPTURE, EXEC etc. blocks.

• db Returns the current database path used by SQL statements. This is changeable with the DB statement (here). Note: the database used by SQL statements can also be set on a per-statement basis by the DB option to SQL (here).

• globaldb Returns the global database path, which is used for the EXPORT TABLE variables, and is the default database for SQL statements unless overridden at run-time. This is settable with the DB directive (here).

• installdir Returns the directory that Texis was installed in. This is usually "/usr/local/morph3" under Unix, or "c:\morph3" under Windows, but may be a different directory depending on the user's installation. Added in version 3.01.982700000 20010220.

• bindir or executabledir Returns the Texis binaries directory, i.e. /usr/local/morph3/bin under Unix or c:\morph3 under Windows. executabledir is a deprecated synonym; it is deprecated because the returned value corresponds to %BINDIR% not %EXEDIR% in texis.ini (e.g. for Lib Path). bindir was added in version 7.07.1594235549 20200708; executabledir in version 5.01.1270583600 20100406.

• libdir Returns the Texis lib directory, i.e. /usr/local/morph3/lib under Unix or c:/morph3/lib under Windows. In version 7 and earlier, it was /usr/local/morph3/bin under Unix or c:/morph3/. under Windows. Note that this directory contains Texis and third-party run-time loaded libraries; it does not contains Texis API libraries used when linking with the API (those are still in the api subdir). Added in version 7.07.1594235549 20200708.

• logdir

  Returns the log dir, i.e. [Texis] Log Dir value or its default. Added in version 8.

  rundir

  Returns the run dir, i.e. [Texis] Run Dir value or its default. Added in version 8.

• htmlmode Returns 1 if in HTML mode, 0 if not. If in HTML mode, variables are automatically HTML-escaped when printed; this is the default if the URL file extension (here) or output MIME type (via a Content-Type header, here) indicates HTML or an HTML-like MIME type. 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. Can be changed with <vxcp htmlmode> (here). Added in version 3.01.982400000 20010217.

• platform

  Returns the platform string: the string printed by texis -platform and in parentheses on the second line by texis -version. This string is of the form cpu-vendor-os-filebits-addressbits.

• features Returns a list of platform-dependent features supported on the current platform. Currently the list may contain zero or more of:

  • RE2 if RE2 regular expressions (here) are supported in REX

  • watchpath if <watchpath> (here) is supported

  • watchpathsubtree if the <watchpath> subtree flag (here) is supported

  Added in version 7.06. See also the version and release parameters to <vxinfo>, and the SQL function hasFeature().

• version [$feature]

  Returns the version string: the second line of information printed by texis -version. If $feature is given, returns the version string for that feature, which must be one of the tokens returned by <vxinfo features>. Added in version 3.01.967148000 20000824. The $feature argument was added in version 7.06.1468274000 20160711. See also the release and features parameters to <vxinfo>.

• release [$feature]

  Returns the release date of the Vortex (texis/vhttpd) executable, or of the $feature (if given), which must be one of the tokens returned by <vxinfo features>. Added in version 3.01.980000000 20010120. The $feature argument was added in version 7.06.1468274000 20160711. See also the version and features parameters to <vxinfo>.

• buildid

  Returns the build ID of the Vortex (texis/vhttpd) executable. This is an arbitrary string that, in addition to other version information, helps identify the executable's exact release version to support staff. It is also printed as the third line of texis -version output. Added in version 7.07.1590984000 20200601.

• license $name Returns the Texis license value corresponding to $name, which can be one of the following: violationmsg, violationtime, gentime, expiretime, verifytime, verifytrytime, serial, curhits, curhitstime, maxhits, curtblrows, maxtblrows, curtblsz, maxtblsz, curdbrows, maxdbrows, curdbsz, maxdbsz, curtotrows, maxtotrows, curtotsz, maxtotsz, texismonitorpid, equivpath, uequivpath, vortexlog, defaultdb, defaultscript, vortexflags, texisflags, schemas. Added in version 3.01.985300000 20010322. In version 5.01.1242246000 20090513, the values inittime, maxversion, prevhits, highhits and flags were added. In version 6, the following values were added: fetchesToday, fetchesTodayStart (when fetchesToday count started), fetchesThisMinute, fetchRate3, fetchRate15, fetchRate60 (fetches per minute averaged over the last 3, 15 and 60 minutes), maxfetches (licensed fetch limit per day; 0 is unlimited), metamorphsToday, metamorphsTodayStart, metamorphsThisMinute, metamorphRate3, metamorphRate15, metamorphRate60, maxmetamorphs (license limit), and thisMinuteStart (when the current minute for ...thisMinute values started; if more than one minute ago, such values may be invalid). Only user-initiated, network fetches are counted (e.g. internal system fetches, format-only calls such as <fetch theUrl theData>, and automatically-fetched components such as frames and scripts, are not counted). In version 6.00.1294878413 20110112, maxversionnum was added.

• vortexlog

  Returns the current Vortex log path, or "-" if standard error. Added in version 5.01.1156453000 20060824.

• content Returns the raw content of the POST or multi-part MIME upload to the script, if any. This can be used to proxy the same POST vars to a remote script with submit. (Note that Vortex parses the POST/MIME input for variables and automatically sets them in Vortex; obtaining the raw content is only needed for re-submitting an identical request to another script, or cache systems, etc.) Added in version 3.01.990000000 20010515. Note that mulit-part MIME content may be altered (contain nuls) due to memory conservation during the potentially-large upload.

• objectpath Returns the file path to the currently running object file (e.g. .vsc file). Added in version 6.00.1292382279 20101214.

• lockpath

  Returns the file path to the current script's lock file (e.g. .vso file). Note that this file will not normally exist for long, as it is created during compilation but renamed afterwards. Added in version 7.07.1570051606 20191002.

• cmdlnargs Vortex command-line arguments, starting with the executable. Added in version 7.01.1394752000 20140313.

• scriptargs Script command-line arguments. These are arguments after the script on the command line, and thus are only passable and available if -R is used (here). If the script is a Unix self-executing "shebang" script, these are the arguments after the "executable" script. Added in version 7.01.1394752000 20140313.

• stack dump [$N] Dumps current Vortex stack information and returns it in $ret, one level per line. Optional $N, which defaults to 0, is bitwise OR of flags:

  • 1 Dump all items, not just function calls

  • 2 Dump parameters too

  • 4 Dump full length of parameter values

  • 8 Print global variables too
  This information can be used when debugging a script, to determine where a function was called from. These flags, and the format of the output, are subject to change without notice in future versions. Added in version 3.01.987820000 20010420.

• texisconf [$section [$setting [$default]]] Returns current texis.ini configuration value for $setting in $section. The $section may be numeric, where sections are numbered from 0 in the order they appear in the file; this is useful if the same-named section occurs multiple times (e.g. Httpd Fast CGI). If $default is given, that value is returned as a default value if the setting is not present. If $setting is not given, all setting names in $section are returned. If $section is not given, all section names in the file are returned, in file order. Section and setting names are case- and space-insensitive. Added in version 4.04.1079750000 20040319.

• texisconffrom $file [$section [$setting [$default]]] Same as texisconf, but reads settings from $file instead of the active config. If $file is empty, the default texis.ini file in the install dir is used (this may still be different from the file used by texisconf, i.e. if -conf overrode the config file on the command line, the latter will be used by texisconf). Added in version 4.04.1079750000 20040319.

• texisconffile Returns the file path to the texis.ini file used by the current invocation of Vortex. Note that the file may not exist, in which case it is the file that would be used were it to exist. Added in version 5.01.1270688277 20100407.

• sourcepath

  Returns the file path to the currently running script (not module) source, including extension if applicable. More permanent than the $sourcepath variable, which could be accidentally modified by the script. Added in version 4.04.1077500000 20040222.

• sourcepathnoext

  Same as sourcepath, but without extension. Added in version 5.01.1197080000 20071207.

• scriptroot Returns the full file path to the effective Script Root, i.e. after obtaining texis.ini, conf/vhttpd.conf or default value (as appropriate via precedence) and expanding variables. May be empty if Script Root is not applicable or computable in the current invocation, i.e. if the script was run from the command line. Added in version 5.01.1268365000 20100311.

• execreadline When called from within an <EXEC> block, returns the next line of data from the program's output, without the trailing newline, blocking if needed until data is available. Returns empty (0 values) if EOF has been reached, i.e. the program exited and all data has been read. Each line read is removed from the (later) $ret return value of the closing </EXEC>.

  Normally it is easier to simply use $ret after </EXEC>. However, at </EXEC> the program's standard input has been closed and the program has exited. <vxinfo execreadline> provides a way to read data in real time from a program, while still potentially sending new input to it. This is useful for "interactive" programs, where the next line of input to the program may depend on previous output from it. Added in version 5.01.1109710555 20050301.

  In version 7.07.1606345000 20201125 and later, an optional timeout may be given after execreadline - either a numeric value of seconds or a Texis-parseable date. If specified and non-empty, the call will timeout at the earlier of the given value or the <exec timeout> value (if any), returning zero values. See execerrtoken to differentiate this return from "normal" EOF/process-end.

• execerrtoken

  When called from within an <EXEC> block, returns the current error status of the <EXEC>; one of the following tokens:

  • Ok: No errors encountered yet; process may be running, or have ended (possibly with non-zero exit code)

  • Timeout: Either the <vxinfo execreadline $timeout> or the <exec timeout>' has been reached \item \verbMaxStdoutExceeded`: <exec maxstdout> reached

  • MaxStderrExceeded: <exec maxstderr> reached

  Other error tokens may be added in the future, possibly splitting the Ok cases further. Added in version 7.07.1606345000 20201125.

• compatibilityversion

  Returns a double value for the current Texis compatibility version, i.e. the major.minor version Texis is attempting to emulate. The default (if no <vxcp compatibilityversion> set) is the Texis version number.

• timeout

  Returns the current Vortex script timeout, as a date deadline, or -1 long if no timeout. Added in version 5.01.1148484000 20060524.

• tracevortex

  Returns 1 if Trace Vortex (here) is active, 0 if not.

• tracevortex log

  Returns the Trace Vortex log file path (here).

• tracevortex forceflush

  Returns 1 if Trace Vortex force-flushing (here) is enabled, 0 if not.

• maxwatchpatheventqueuesize

  Returns the maximum Vortex watchpath (here) event queue size, in bytes (or empty string if unsupported). Added in version 8.

DIAGNOSTICS
The vxinfo function returns option-dependent value(s).

EXAMPLE
This example logs the path and size of a page after it is delivered by the script:

... print a page of results ...
<vxinfo outputsz>
<SQL NOVARS "insert into log values($REQUEST_PATH, $ret)"></SQL>
<exit>

CAVEATS
The vxinfo function was added in version 3.01.967200000 20000824.

SEE ALSO
vxcp