Contents SAS/IntrNet 9.1: Application Dispatcher Previous Next

HTTP Headers

All output that is created by Dispatcher programs must contain an abbreviated HTTP header. This header is everything from the beginning of the output up to the first null line.

Starting with Version 8.1, the Application Server provides Automatic Header Generation.

Here is some example output, including the header:

   Content-type: text/html
   Pragma: nocache

   <HTML>
   <HEAD><TITLE>Application Server Administrative Program</TITLE></HEAD>
   <BODY>
   <H1>Administrative Program</H1>
   <P>The application server has been shut down.</P>
   <HR>
   </BODY>
   </HTML>

In this example, the HTTP header contains two lines. The minimal requirements for Dispatcher output are that the header contain Content-type or Location. The null line that terminates the HTTP header is important. You can create the null line with a PUT statement: 

   put ;

This, however, is incorrect because it produces a line containing one blank followed by carriage control: 

   put " ";

A line with one blank is not a null line and is not recognized as terminating the header.

The output that follows the HTTP header depends upon the content type. If Location is used, then no output follows the header because this header triggers the browser to redirect to another page. The most common type of output is, of course, HTML. The HTML source for the Web page follows the header when the content type is text/html.

No matter whether the program output is plain text, binary graphics, HTML code, or any other content type, all output intended for the Web browser should be sent to the fileref _WEBOUT. This special fileref is actually a TCP/IP socket connection to the Application Broker. Sending output to this socket will stream it back to the browser. Think of the socket like a pipe through which data flows. Because it behaves in this way, the fileref _WEBOUT is in a permanent append mode. It is not possible to write something to _WEBOUT and then reopen the fileref and overwrite the previous output. It all gets appended. Therefore, the mod parameter should not be used (and is not allowed) in any FILE _WEBOUT statements. Prior to Version 7 of SAS, an additional fileref _GRPHOUT was necessary on z/OS systems because of translation issues from EBCDIC to ASCII. The two filerefs _GRPHOUT and _WEBOUT were synonyms on all hosts except for z/OS under Version 6 of SAS. In SAS, Version 7 and later, these two filerefs are synonyms for all platforms including z/OS. Though no longer needed, the fileref _GRPHOUT is still present for compatibility reasons.

Automatic Header Generation

Starting with Version 8.1, the Application Server provides Automatic Header Generation. The default header is Content-type: text/html.

To add a header to the default header list or to modify a header already in the list, use the DATA step function APPSRV_HEADER.

The Application Server detects whether the user application is writing its own headers. Preexisting applications that write their own headers will continue to work as before. New applications that do not output headers will have default headers generated for them.

Applications that want to use the default headers but also want to modify them or add to them can use the APPSRV_HEADER DATA step function. For example,

   old = appsrv_header('Header name', 'Header value');

Calls to the APPSRV_HEADER function adds headers to the list of default headers when the header name does not already exist in the list of default headers. In this case, the return value of the function call will be an empty string.

If the header name passed into the APPSRV_HEADER function already exists in the list of default headers, the header value of the existing header is replaced with the new value passed in, and the old value of the header is returned as the return value of the function. If the header value passed in is an empty string, then the header is removed from the list of default headers. The old value of the header is returned as the return value of the function.

Example

With default headers of Content-type: text/html, the following calls to the APPSRV_HEADER function will modify the default headers as shown:

   rc = appsrv_header('Expires','Thu, 18 Nov 1999 12:23:34 GMT');

results in

   rc = appsrv_header('Pragma','nocache');

results in

   rc = appsrv_header('Expires','');

results in

   rc = appsrv_header('Pragma','nocache');

results in

Disabling Automatic Header Generation

To disable Automatic Header Generation completely for a request, call the APPSRVSET DATA step function, as follows:

   data _NULL_;
      rc = appsrvset("automatic headers", 0);
   run;

HTTP Output Reference

All Dispatcher output must be in the format of an HTTP header that is followed by a blank line and optional data. This section provides introductory technical information on the most common headers you will use. For detailed information about HTTP, see W3C's HTTP Protocol Area.

Content-type

The most basic HTTP header you can send is the content-type header, for example:

   Content-type: text/html

If you use ODS to generate content that is not HTML, then the header will be defined based on information from the SAS registry or the Windows registry. For example, if you use ODS PDF to generate content, the header will look like 

   Content-type: Application/PDF

This informs the browser what kind of output follows by specifying it the Internet Media type (also called MIME type). For a list of all official MIME types, see the IANA registry. An unregistered MIME type may be used; just precede it with x-. Some of the more important types are listed in the table below.

Content-type Description
application/octet-stream Unformatted binary data.
image/gif Image in the GIF (Graphics Interchange Format) format.
image/jpeg Image in the JPEG (Joint Photographic Expert Group) format.
text/html Regular HTML (Hypertext Markup Language).
text/plain Preformatted text.
text/x-comma-separated-values Spreadsheet data.
multipart/x-mixed-replace Differently formatted blocks of data (used for Netscape server push).

Expires

Sometimes browsers cache results when you intend for the Dispatcher to be reinvoked, and sometimes they reinvoke when it is unnecessary. Setting the Expires header gives you control over these conditions by specifying the date/time after which the response should be considered stale, for example:

   Expires: Thu, 01 Dec 1994 16:00:00 GMT

To mark a response as already expired, use an Expires date that is equal to or earlier than the current date. To mark a response as never expires, use an Expires date approximately one year or more from the time the response is sent. The date format should be followed exactly as given above.

Location

The location header redirects the browser immediately to a different URL. Use this as an alternative to the content-type header. There is no data after a header containing Location: but you still need the blank line at the end.

   Location: http://support.sas.com

Pragma

This header informs the browser and proxy servers to not cache the results of your program. It is similar to using the Expires: header with a date in the past but may be somewhat better supported, for example:

   Pragma: nocache

Set-Cookie

The header sends a cookie to the browser to maintain the client-side state. The format is 

   Set-Cookie: NAME=VALUE; expires=DATE; path=PATH; domain=DOMAIN_NAME; secure

For example:

   Set-Cookie: CUSTOMER=WILE_E_COYOTE; path=/cgi-bin/broker; 
      expires=Wednesday, 09-Nov-1999 23:12:40 GMT

The next time your application is run, any matching cookies are returned in HTTP_COOKIE environment variable (use Export directive to pass to application). You must parse them out in order to retrieve the information that you save. The names and values can be anything you like, but you must devise a method to encode special characters such as the equals sign (=) and the semicolon (;). The date format should be followed exactly as above, with only the GMT time zone allowed, and dashes between the day, month, and year (this is different from Expires:).

Most new browsers support cookies, but studies show that approximately 10% of users disable or disallow them. Some users are concerned about the privacy considerations of using cookies. If you use cookies, be sure to explain to your users why you need them and that they should let them pass through.


Contents SAS/IntrNet 9.1: Application Dispatcher Previous Next