Full Syntax

The full syntax of a Vortex URL is (optional parts in []):

/cgi-bin/texis/myVortexScript[/+state][/function.mime][/+/userpath]

/cgi-bin/texis is the CGI path of the Vortex executable (if CGI mapping by directory). /myVortexScript is the (ScriptRoot-relative) path of the Vortex script. It must not contain any path elements that begin with a + sign (due to possible confusion with other parts of the URL syntax). In versions prior to version 6, it should not contain a file extension. In version 6 and later, the Vortex source (.vs) or object (.vsc) extensions may be present (e.g. for CGI mapping by file extension).

If no script path is given, the Vortex script index in the default database (see here) is run, if it exists and Vortex was invoked in the CGI environment. This allows a default script to be run if Vortex is invoked without a path.

If the script is EXPORTing any variables (see here), then encoded state information may appear as another "filename" after the script name (i.e. the /+state part). This information is generated automatically by the $url variable (see here), which will contain all of the URL up through and including any state information. Only the function, MIME extension and user path, if desired, need be appended by the programmer in scripts.

The optional function name and MIME extension come next. If these are given, the function name becomes the start function of the script, instead of the default main. This makes it easier to re-enter a script on subsequent invocations, without cluttering up main with logic to call the right function. A non URL-safe function name (e.g. containing spaces or /) must be URL-encoded.

The .mime extension is an extension which indicates the MIME type to set in the Content-Type output header, e.g. .gif for "image/gif". It also provides a clue to Web browsers and end users what type of information the URL will return: a .gif URL is expected to yield a GIF, etc. The default if no extension is given is HTML.

Note that the function name and MIME extension, if given, must both be present. The MIME extension should be one of the following recognized extensions:

.au, .bmp, .css, .doc, .dvi, .eps, .gif, .gz, .htm, .html, .ief, .jpe, .jpeg, .jpg, .latex, .mov, .mpe, .mpeg, .mpg, .pbm, .pdf, .pgm, .png, .pnm, .ppm, .ps, .qt, .ram, .ras, .rgb, .rtf, .snd, .tex, .texi, .texinfo, .tiff, .txt, .wbmp, .wml, .wmlc, .wmls, .wmlsc, .xbm, .xls, .xml, .xpm, .xwd, .Z, .zip

If the MIME extension is given but not one listed above, the Content-Type will be "application/octet-stream". (Note: this list can be altered in the Texis Web Server; see the TypesConfig setting (here.)

The MIME extension bin is special: if it is given, then no headers are printed by Vortex. Normally, a Content-Type and other HTTP headers are printed by Vortex at the start of execution. When the MIME extension bin is used, however, the Vortex script is responsible for correctly printing all HTTP headers. Note that in Vortex version 2.6.913000000 19981207 and later, the header function (here) is preferred for handling headers, as it is more flexible.

The /userpath comes last, though it is rarely used. At the end of the URL (i.e. after $url and function/MIME info), "/+" followed by an arbitrary, user-defined absolute path may be given. This path will be assigned to the special variable $userpath at script start. This syntax provides a way to attach an arbitrary path to the URL, much like $PATH_INFO does for ordinary CGI programs (but $PATH_INFO has been usurped for Vortex use). It is only used, in combination with server aliases, in circumstances where the entire URL must truly "look" like a path. The user path, if given, must start with "/".

Query-string variables may also be appended to the URL, after a "?" character. These can either be set explicitly, or indirectly from EXPORT QUERY variables with $urlq (see here).

The URL syntax is designed to keep the information it holds, i.e. script name, state information, start function and MIME type, in a logical format. To Web users viewing the URLs, everything appears as a "file tree" beneath the Vortex executable. Each function is a "file" in the "directory" of its script.


Copyright © Thunderstone Software     Last updated: Apr 15 2024
Copyright © 2024 Thunderstone Software LLC. All rights reserved.