header - print HTTP header

SYNOPSIS

<header NAME=$name [VALUE=$value] [options]>

<header COOKIE=$name [VALUE=$value] [options] [cookie-options]>

DESCRIPTION
The header function prints an HTTP header. Normally Vortex takes care of printing headers, such as Content-Type, before the script begins, so that all of the script's output is part of the body. However, in some circumstances it is desirable for a script to print additional headers, override default Vortex headers, or change headers at run-time. In such cases the header function can be used.

It is important to note that since headers are only valid before the body/content of the output, the header function, if used, should be called before any content is generated. Otherwise the output of header may be suppressed, lose its effect, and/or be visible to the user (see the PRINTIF option for more info).

If the NAME option is given, a generic header will be printed. Its value will be VALUE. This form can be used to print a Location header to redirect the user, for example.

If the COOKIE option is given, a Set-Cookie header will be printed. The name of the cookie will be $name, and its value will be $value, URL-encoded so that non-ASCII characters are safe. This provides a way to export "permanent" or "session" data in Vortex, since HTTP cookies are automatically URL-decoded and imported into variables (of the same name as the cookie) on future script invocations. It also provides a cross-script method of exporting data, since cookies are not inherently part of the URL.

Options valid for named headers as well as COOKIEs:

• PRINTIF=$flags Only print header if conditions specified by zero or more space-separated values in $flags are met. If $flags is empty or unset, the value of [Texis] Default Header Printif (here) from texis.ini is used. If that is unset, the value headers is used. A protocol and a content condition are tested; both conditions must be true for the header (or Secure flag) to be printed:

  • http (protocol) True if running under CGI with HTTP

  • https (protocol) True if running under CGI with HTTPs

  • cmdline (protocol) True if running from command line

  • headers (content) True if CGI and still printing headers

  • content (content) True if command line, or CGI and past headers

  • always (protocol and content) Always true
  Multiple flags of the same type are or'ed together. The protocol condition defaults to true if no protocol flags are given. The content condition defaults to headers if no content flags are given. Added in version 5.01.1111422310 20050321.

Several additional options are valid for COOKIEs only:

• DOMAIN=domain Specifies a domain to restrict the cookie to. Normally a browser will return the cookie only to the single host it was received from. To make the browser return it to all hosts in a given domain, e.g. x.com, set DOMAIN to ".x.com. (Note: see RFC 2109 for more on the syntax of DOMAIN.) Added in version 3.0.957500000 20000504.

• MAX-AGE=seconds Specifies a maximum age for the cookie, in seconds. After the given number of seconds, the user's browser is to discard the cookie, no longer returning it in future requests. A MAX-AGE of 0 means to discard the cookie immediately. If no MAX-AGE or EXPIRES time is given, the cookie is a session cookie, and will be discarded when the browser is closed.

• EXPIRES=time An alternate method of specifying the maximum age of the cookie. The time is a Texis-parseable date/time, such as "+1 week".

• PATH=path Gives the valid root path for the cookie. This is the subset of URLs for which the cookie is to be returned by the browser. If not specified it defaults to /, which means that all URLs for the host will be returned the cookie. A longer path could be given to restrict the cookie to a smaller URL tree.

• SECUREIF=$flags

  If given, and conditions specified by $flags are met, print Secure flag with cookie, which instructs browsers to only return the cookie over a secure (e.g. HTTPs) connection. Syntax and defaults are the same as for PRINTIF, except that there is no texis.ini value checked as a fallback, and the additional condition exists that the SECUREIF option must also be given explicitly for Secure to be printed (in addition to protocol and content conditions). Note also that the content condition default changed in version 7.07.1619560502 20210427 (see footnote under PRINTIF).

• HTTPONLY Set HttpOnly flag in header. If the browser/user-agent supports it, this flag will prevent access or modification of the cookie by client-side scripts, which may help prevent cross-site-scripting (XSS) attacks by malicious scripts. If the browser does not support the flag, it will typically be ignored. Added in version 5.01.1244880000 20090613.

Use of the header function is preferred over the old method of setting the URL extension to .bin, since it is more flexible. The script can print some, all, or none of its headers, even override Vortex headers such as Content-Type.

DIAGNOSTICS
header returns nothing.

EXAMPLE

<a name=look>
  <if $MagicCookie != "MagicValue">
    <header name="Location"
        value="http://www.example.com/login.html">
    Your login is incorrect.
    Please <a href="/login.html">login</a>.
    <exit>
  </if>
  <!-- Proceed with top of HTML: -->
  <body>
  <h2>My Site</h2>
</a>

This function checks the user's (previous) login cookie: if it is incorrect, they are redirected to a login page. This function could be called at the top of any start function to verify the user.

CAVEATS
The header function was added in version 2.6.913000000 19981207. It must be called before any body output is printed for the header to be interpreted properly.

The header function controls headers printed by Vortex in CGI output. It does not control headers sent to other servers via <fetch>; see <urlcp header> (here) instead.

Web servers may insert, modify, or delete headers printed by CGI programs such as Vortex, including those printed with header. This behavior is beyond Vortex's control. In some cases it is necessary, as with the Location header: the server must parse it to change the HTTP response code to 302, because the HTTP response is printed before the Location header.

The header function does not yet work properly in conjunction with the .bin URL extension syntax.

Printing a Content-Type header may affect the default HTML-encoding of output variables, if the type is changed to/from text/html. If a Content-Type header is not printed, one will be added to the headers as usual.

The returning of cookies on future requests, to the proper URLs, and their disposal at the MAX-AGE time is entirely up to the user's browser. If the user deletes their cookie cache, the browser does not or cannot accept cookies, or has a faulty implementation, cookies may not be returned as expected.

Although COOKIE values are automatically URL-encoded and decoded, they are sent as plain-ASCII values, so type information is lost. Upon receipt, cookies have the same type as if they were form variables: string or integer.

SEE ALSO
URL syntax, EXPORT, RFC 2109 (cookie specification)