Wednesday, August 21, 2013

SAS Server Pages in Batch? Absolutely!

The origins of SAS Server Pages, and thus the name, as discussed in this blog posting, was to simplify the generation of HTML in Stored Processes and SAS/IntrNet Application Dispatcher programs.

When I started work on my my eBook, SAS Server Pages: Generating Dynamic Content, I was presented with a conflict. SAS Server Pages could also be used in batch processing that did not involve any of the SAS web applications or tools. So, do I try come up with a new/better name???? After consulting colleagues who were using SAS Server Pages, the consensus was no. Just make sure to provide examples that show their use in batch processing. What I decided to do in the book and now in this blog entry (and more blog entries to follow), was to take their advice and provide batch examples.

But first let me be clear about what I mean by in batch:
  • jobs run on a scheduled or ad-hoc basis in the background (e.g., overnight job to produce reports).
  • code submitted interactively by a SAS user/programmer in SAS Display Manager.
  • code submitted interactively by a SAS user/programmer in SAS Enterprise Guide.

The example here is a Tag Cloud example and uses basically the same SAS Server Page components as discussed in Tag Cloud SAS Server Page Components. The SAS Server Page shown here has some changes/improvements over what was shown there for a number of reasons:
  • to leverage the environment in which the code is being run.
  • to highlight some features of PROC STREAM.
  • and, of course, whenever you revisit some code, it is quite common to come up with ideas to improve it.

The code has been packaged as a macro. There isn't any conditional or iterative processing (though in my post I will add conditional and iterative capabilities to the macro in order to support a BY variable). Plus, as a Best Practice I like to use macros to simply package and parameter code.

So producing this tag cloud output:

was accomplished by calling the following macro (stored in a macro autocall library).

As a convention I typically use _webout for the fileref even in batch programs. By doing that, any of my programs can easily be used in a Stored Process or SAS/IntrNet Application Dispatcher program.

filename _webout "&root\Output\TagCloud.html";
%tagCloud(data =
         ,word = Subsidiary
         ,weight = Sales

So once the macro is made available via an autocall library, anyone can use it to create graphical displays of BI data as a tag cloud.

Lets now look at the macro. As stated above most of the SAS code and HTML was discussed in Tag Cloud SAS Server Page Components. This blog post will focus on the changes.
  • I provide default values for all the parameters. This is done for demo purposes only.
  • Note that anyone who wants to use this in their environment may want to add some validation of the parameters (e.g., the data set and variables exist).
  • Two macro parameters have been added to control the region size for the tag cloud.

%macro tagCloud(data = /* input data */
               ,where = 1            /* subset where clause */
               ,word = Subsidiary    /* class variable */
               ,weight = Sales       /* analysis variable */
               ,statistic = Sum      /* statistics to calculate */
               ,outfile = _webout    /* output fileref */
               ,width = 600px        /* width of the tag cloud */
               ,height = 450px       /* height of the tag cloud */

As seen below, a macro variable is created to make the input SAS Server Page less cluttered. In this case the nl macro variable will contain the value of the streamDelim macro variable with the newline argument.

 %local nl;

Next we summarize the data. In the Stored Process example. this was embedded in the SAS Server Page using the dosubl function. While we could do that here, there is no need to. You could also add an option to the macro to specify that the data set has already been summarized.

 proc summary data = &data nway;
  class &word;
  var &weight;
  output out = cloud(drop=_type_ _freq_) &statistic = ;

Next call PROC STREAM with the desired options. Note that the BEGIN keyword is required as the first token after the PROC STREAM statement. Also note that instead of using %INCLUDE to include the SAS Server Page text, it is included inline. While I typically use %INCLUDE in order to maximize re-use, I wanted to illustrate this technique.

 proc stream outfile = &outfile quoting = both; 

As mentioned above, assign the value for the nl macro variable so it can be used on each line of the input SAS Server Page text in order to have the raw HTML more nicely formatted. Note however that this is only really needed here to make the source more readable for debugging purposes.

%let nl = &streamDelim newline;

Just some standard HTML header.

&nl; <head>
&nl;  <title>Tag Cloud for the &statistic of &weight by &word</title>

Just as for the Stored Process example, we point to a Google api library for the JQuery pieces and we use the readfile facility to just copy the JQCloud JavaScript and Cascading Style Sheet into the generated output.

Note the use of the GoogleApiLib macro variable. That is set in my environment so that I can easily update the value and have the new value propagated without having to update all of my programs and SAS Server Pages.

&nl;  <script src="&GoogleApiLib/jquery/1.10.1/jquery.min.js"></script>
&nl;  <script src="&GoogleApiLib/jqueryui/1.10.3/jquery-ui.min.js"></script>
&nl; <style>
&nl; &streamDelim readfile srvrpgs(jqcloud.css);
&nl; </style>
&nl; <script>
&nl; &streamDelim readfile srvrpgs(jqcloud-1.0.3.js);
&nl; </script>
&nl; </head>
&nl; <body>

The fieldset tag is used the to provide the nice border with embedded text (on the border). So I need a div tag to specify the size of the region.

&nl;<div style = "float:left; width:&width; height:&height;">
&nl;<legend style="font-size:70%;">
Tag Cloud for the &statistic of &weight by &word

Now just as in the Stored Process example, define the region to contain the generated tag cloud.

&nl;<div id="cloudCanvas" style="width:&width; height:&height;"></div>

End the fieldset.


And  since this is a batch process, lets use the generatedAt macro to provide a footnote showing when the output was created.

&nl;<div style="clear:both; font-size:70%;">%generatedAt()</div>

And finally, create the JSON text that populates the tag cloud - again, just as in the Stored Process example.

&nl; var tagCloud =
&nl; %tagCloudJSON(data=cloud
&nl; $(function() {
&nl;   $("#cloudCanvas").jQCloud(tagCloud);
&nl; });
&nl; </body>
%mend tagCloud;

That's really all there is to it.

And for those of you who want to download the code, I have a few more examples to blog about. Once I do that, I will package up all the pieces and parts (e.g., the AJAX container, the tag clouds SAS Server Pages, the macros, etc.) as a zip file.

And in case you had not noticed, I updated by blog template to make the text area wider so that the code is easier to read/follow. I hope you like the new format.