NAME

       send-file -  (web)

PURPOSE

       Send file to client.

SYNTAX

           send-file <file> [ headers \
               [ 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

       When a client requests download of a file, you can use send-file to provide <file>, which is its location
       on the server, and is either a full path or relative to the application home directory (see directories).
       Note  however  that you can never use dot-dot (i.e. "..") in <file> - this is a security measure to avoid
       path-traversal attacks. Thus the file name should never have ".." in it, and if it does, the program will
       error out.

       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.

       COOKIES

       Any cookies set prior to send-file (see set-cookie and delete-cookie) will be sent along with the file to
       the web client.

EXAMPLES

       To send a document back to the browser and show it (i.e. display):

           send-file "/home/golf/files/myfile.jpg" headers content-type "image/jpg"

       An example to display a PDF document:

           set-string pdf_doc="/home/mydir/myfile.pdf"
           send-file pdf_doc headers content-type "application/pdf"

       If  you  want to send a file for download (with the dialog), use "download" clause. This way the document
       is not displayed but the "Save As" (or similar)  window  shows  up,  for  example  to  download  a  "PDF"
       document:

           send-file "/home/user/file.pdf" headers download content-type "application/pdf"

SEE ALSO

        Web

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

$DATE                                               $VERSION                                           GOLF(2gg)