Out header

18.4.0 released Sep 25, 2023

Out header

Purpose: Output HTTP header.

out-header default

out-header use \
    [ content-type <content type> ] \
    [ download [ <download> ] ] \
    [ etag [ <etag> ] ] \
    [ file-name <file name> ] \
    [ ( cache-control <cache control> ) | no-cache ] \
    [ status-id <status id> ] \
    [ status-text <status text> ] \
    [ custom <header name>=<header value> [ , ... ] ]

A web page must have an HTTP header output before any other response. Note that while cookies may be set after out-header, they still must be set before outputting the data. If your application uses out-header multiple times, all but the very first one are ignored.

If out-header is not called prior to the actual output, either the header or the output itself (or both) may not be output, and you might get an error. Be sure to always first use out-header prior to any output for a request.

Use out-header for dynamically generated web pages. If you wish to output a file (such as an image or a PDF document), do not use this statement; rather use send-file instead.

The HTTP header is sent back to a client who initiated a request. You can specify any custom headers with "use" clause.

Default header

If "default" clause is in place, a default header is constructed, which uses a status of 200/OK and content type of

text/html;charset=utf-8

and cache control of

Cache-Control:max-age=0, no-cache; Pragma: no-cache

and also sends any cookies produced by set-cookie and delete-cookie. The default header is typical for dynamically generated web pages, and most of the time you would use the default header.

Headers

The following are subclauses that allow setting any custom header:

<content type> is content type (such as "text/html" or "image/jpg" etc.) If you are sending a file to a client for download and you don't know its content type, you can use "application/octet-stream" for a generic binary file.
If "download" is used without optional boolean expression <download>, or if <download> evaluates to true, then the file is sent to a client for downloading - otherwise the default is to display file in client.
<file name> is the name of the file being sent to a client. This is not the local file name - it is the file name that client will use for its own purposes.
<cache control> is the cache control HTTP header. "no-cache" instructs the client not to cache. Only one of "cache-control" and "no-cache" can be used. An example of <cache control>:
```
send-file "somepic.jpg" headers cache-control "max-age: 3600"
```
If "etag" is used without optional boolean expression <etag>, or if <etag> evaluates to true, then "ETAG" header will be generated (a timestamp) and included, otherwise it is not. The time stamp is of last modification date of the file (and typically used to cache a file on client if it hasn't changed on the server). "etag" is useful to let the client know to download the file only once if it hasn't changed, thus saving network and computing resources.
<status id> and <status text> are status settings for the response (such as "425" for "status-id" and "Too early" for "status-text").
To set any type of generic HTTP header, use "custom" subclause, where <header name> and <header value> represent the name and value of a single header. Multiple headers are separated by a comma. There is no limit on the maximum number of such headers, other than of the underyling HTTP protocol. You must not use "custom" to set headers already set elsewhere (such as "etag" for instance), as that may cause unpredictable behavior. For instance this sets two custom headers:
```
out-header use custom "CustomOption3"="CustomValue3", "Status"="418 I'm a teapot"
```
"custom" subclause lets you use any custom headers that exist today or may be added in the future, as well as any headers of your own design.

You can use silent-header before output-header in order to suppress its output.

Examples

To output the default HTTP header for a dynamically generated page (a typical usage):

out-header default

To set a custom header for a web page that changes cache control and adds two new headers:

out-header use content-type "text/html" cache-control "max-age:3600" custom "some_HTTP_option"="value_for_some_HTTP_option", "some_HTTP_option_1"="value_for_some_HTTP_option_1"