HTTP Headers

Stored process streaming output is always accompanied by an HTTP header. The HTTP header consists of one or more header records that identify the content type of the output and can provide other information such as encoding, caching, and expiration directives. A streaming stored process client is free to use or ignore the HTTP header as desired. The SAS Stored Process Web Application forwards the HTTP client on to the Web browser (or other HTTP client).

HTTP headers are defined by the HTTP protocol specification (RFC 2616), which can be found at the World Wide Web Consortium. Each header record is a single text line consisting of a name and a value separated by a colon (:). The following is an example of records in an HTTP header:

   Content-type: text/html; encoding=utf-8
   Expires: Wed, 03 Nov 2004 00:00:00 GMT
   Pragma: nocache

You can set any HTTP record for your stored process output by calling the STPSRV_HEADER function. The following DATA step function calls generate the previous example header records:

   old = stpsrv_header("Content-type", 
      "text/html; encoding=utf-8");
   old = stpsrv_header("Expires", 
      "Wed, 03 Nov 2004 00:00:00 GMT");
   old = stpsrv_header("Pragma", "nocache");

You can also call this function directly from SAS macro code outside a DATA step. Note that string parameters are not enclosed in quotation marks and macro characters such as semicolon (;) must be masked in this case:

   %let old = %sysfunc(stpsrv_header(Content-type, 
      text/html%str(;) encoding=utf-8);
   %let old = %sysfunc(stpsrv_header(Expires, 
      Wed, 03 Nov 2004 00:00:00 GMT));
   %let old = %sysfunc(stpsrv_header(Pragma, nocache));

Commonly Used Headers

The following are few commonly used HTTP header records:

• Content-type
• Expires
• Pragma
• Set-Cookie

Note: The Location header record does not currently work with stored processes because the HTTP status code cannot be set.

Content-type

The Content-type header record is generated automatically for you. The value is set based on the ODS destination that you use in your stored process. The value is determined by looking up the ODS destination in the file types section of the SAS and, if appropriate, the Windows registry. If you do not use ODS to generate the output, Content-type defaults to text/html. Use the STPSRV_HEADER function if you want to override the default value. Override the value of Content-type when you want to do any of the following:

• specify the encoding of the data. This might be important in Web applications where the client (typically a Web browser) might expect a different encoding than the stored process output. Examples:

     Content-type: text/xml; encoding=utf-8
     Content-type: text/plain; encoding=iso-8859-1
     Content-type: text/html; encoding=windows-1252
  

• direct the output to a specific content handler. For example, HTML output can be directed to Microsoft Excel (in later versions of Microsoft Office) by setting the Content-type to application/vnd.ms-excel.

• override the default text/html value. This typically occurs if you are using ODS custom tagsets or you are not using ODS at all to generate the output.

Commonly used Content-type values include the following:

Content-type values are also known as MIME types. For a list of all official MIME types, see the IANA registry. An unregistered MIME type or subtype can be used; the value should be preceded with x-.

Expires

Web clients frequently cache HTML and other content. Accessing the same URL might return the cached content instead of causing the output to be regenerated by the server. This is often desirable and reduces server and network loads, but can lead to unexpected or stale data. The Expires header record enables you to control how long a Web client will cache the content.

The Expires header record requires that the expiration time be specified in Greenwich Mean Time (GMT) and in a particular format. A SAS picture format can be used to create this value. Use PROC FORMAT to create a custom format:

   proc format;
      picture httptime (default=29)
         other='%a, %0d %b %Y %0H:%0M:%0S GMT' 
                 (datatype=datetime);
   run;

This format can be created one time and saved in a global format library, or you can create it dynamically as needed in your stored process. The format generates a date in the form

   Sun, 24 AUG 2003 17:13:23 GMT

DATA step functions can then be used to set the desired expiration time, adjust to GMT and format, as shown in the following examples:

   /* Expire this page in six hours */
   data _null_;
      exptime = datetime() + '6:00:00't;
      old = stpsrv_header('Expires', 
             put(exptime - gmtoff(), httptime. ));
      run;

   /* Expire this page at the beginning of next 
      week (Sunday, 00:00 local time) */
   data _null_;
      exptime = intnx('dtweek', datetime(), 1);
      old = stpsrv_header('Expires', 
             put(exptime - gmtoff(), httptime. ));
      run;

Specifying an expiration time in the past causes caching to be disabled for your output. It is recommended that you also use the Pragma: nocache header record in this case. Specify an expiration time far in the future if you want your content to be cached indefinitely.

Pragma

The Pragma header record is used to specify information not formally defined in the HTTP specification. The most commonly used value is nocache. This value disables Web client caching of content for most Web browsers.

Set-Cookie

The Set-Cookie header record sends a cookie to the Web client to maintain client-side state. The format is

   Set-Cookie: name=value; name2=
      value2; ...; expires=date;
      path=path; domain=domain_name; secure

where EXPIRES, PATH, DOMAIN, and SECURE are all optional. The date must be specified in the HTTP GMT format described in the section on the Expires header record.

For example:

   old = stpsrv_header("Set-Cookie",
      "CUSTOMER=WILE_E_COYOTE; path=/SASStoredProcess/do; " ||
      "expires=Wed, 06 Nov 2002 23:12:40 GMT");

The next time your application is run, any matching cookies are returned in the _HTCOOK environment variable, assuming this variable has been enabled in your SAS Stored Process Web Application environment. You must parse the cookie string to retrieve the information that you saved in the cookie. Use the scan DATA step function to split the name/value pairs on the semicolon (;) delimiters; then split the name/value pairs on the equals sign (=) delimiter.

Most Web browsers support cookies, but some users disable them due to privacy concerns, site policies, or other issues. If you use cookies, explain to your users why you need them and if they must be enabled to use your application. Some Web clients might not support cookies at all.