NAME

       out-header -  (web)

PURPOSE

       Output HTTP header.

SYNTAX

           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> [ , ... ] ]

DESCRIPTION

       out-header outputs HTTP header and also sends any cookies produced by set-cookie and delete-cookie. A web
       page must have an HTTP header output before any other response.

       If  out-header  is  not  used,  a  default HTTP header is sent out just before the very first output (see
       output-statement, print-out etc.) at which point any cookie updates are sent as well; this default header
       is the same as using "out-header default".

       If you use out-header multiple times, all but the very first one are ignored.

       If you wish to output a file (such as an image or a PDF document), do  not  use  out-header;  rather  use
       send-file instead which outputs its own header.

       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 no out-header is used, or 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

       The default header is typical for dynamically generated web pages, and most of the time you would use the
       default header - meaning you don't need to specify out-header statement.

       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 boolean variable <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 boolean variable <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. ETAG header is used only for send-file.

           • <status id> and <status text> are status settings for the response, as strings (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

       Sometimes you may want to output the default  header  immediately,  for  instance  if  the  first  output
       produces may take some time:

           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"

SEE ALSO

        Web

       call-web out-header send-file silent-header See all documentation

$DATE                                               $VERSION                                           GOLF(2gg)