SAS ® Global Forum 2014 March Washington, DC

2 Paper PROC STREAM and SAS® Server Pages: Generating Custom HTML Reports Don Henderson Henderson Consulting Services, LLC

3 PROC STREAM and SAS Server Pages  What are they/What can they do?  Lots of things.  For example, very custom data driven web content.  Uses the Macro Language to conditionally and dynamically generate content.  Conceptually similar to what ASP and JSP pages do.  Can be used in batch SAS as well as SAS BI/EBI and SAS/IntrNet.

4 Some Examples (details later) A mail merge A tag cloud A clickable calendar

5 SAS Server Pages  Introduced in my SAS Press Book: Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher.  Leveraged the RESOLVE function in the DATA step to process Macro Variable references and Macro calls.  Functional, but rudimentary.  PROC STREAM greatly expands what can be done with SAS Server Pages.

6 SAS Server Pages and PROC STREAM  The DATA Step 32K limit removed.  %INCLUDE to do what JSP and ASP applications refer to as Server-Side Includes.  SAS code can be defined and executed inside of an input SAS Server Page. Both SAS code to be executed as well as markup text (such as HTML, CSV, XML, and more) can be included.  SAS and many SCL functions (e.g., OPEN, CLOSE, FETCH, GETVARC, GETVARN, and so on) to access data.

7 THE SAS MACRO LANGUAGE A TEXT PROCESSING LANGUAGE  Macro Variables for Text Substitution.  Macros for Iterative and Conditional Text Generation.  Including Text from External Files.  Generating Dynamic Content from a SAS Data Set.  Executing SAS Code in a PROC STREAM Input File.

8 Macro Variables for Text Substitution  This first example illustrates a few key features:  Macro variable references are resolved (&SYSUSERID).  The %SYSFUNC macro function is used to execute functions, including the formatting of the result.  The output, by default, is streamed to the client in such a way that line feeds, extra spaces, and so on, are not included.

9 Macro Variables for Text Substitution

10 Macro Variables for Text Substitution proc stream outfile=_webout; BEGIN Hello World Hello &sysuserid.. This welcome note generated at %sysfunc(time(),timeampm8.) on %sysfunc(date(),monname.) %sysfunc(date(),day.). ;;;; run;

11 Macro Variables for Text Substitution Add the ASIS (aka PRESCOL) option

12 Macro Variables for Text Substitution Better – use &streamDelim newline;

13 Macro Variables for Text Substitution proc stream outfile=_webout; BEGIN &streamDelim newline; Hello World &streamDelim newline; &streamDelim newline; Hello &sysuserid.. &streamDelim newline; This welcome note generated at %sysfunc(time(),timeampm8.) on %sysfunc(date(),monname.) %sysfunc(date(),day.). &streamDelim newline; &streamDelim newline; ;;;; run;

14 Macros for Iterative and Conditional Text Generation  This next example (which could be written in any scripting language) highlights:  HTML text inline along with SAS macro language statements to control the generated HTML text.  Generating HTML (table rows) using a %DO loop.  Executing SAS functions using the %SYSFUNC and %QSYSFUNC macro functions.  Providing complete control over such HTML content as colors and table attributes. Note that some of the values are hardcoded (the table cell width), while others are macro parameters.

15 Macros for Iterative and Conditional Text Generation Note the use of HTML Entities

16 Macros for Iterative and Conditional Text Generation – The PROC STREAM code proc stream outfile=_webout; BEGIN %characterSet(evenRowBGColor=white,oddRowBGColor=grey) ;;;; Note the macro call

17 Macros for Iterative and Conditional Text Generation – The characterSet Macro %macro characterSet (evenRowBGColor = grey,oddRowBGColor = white ); %local i bgcolor char;.

18 Macros for Iterative and Conditional Text Generation – The characterSet Macro Character Entity References /* Define the style to use for the table cells so that the values need not be specified for each cell. */ td {text-align:center; width:100px;} th {text-align:center; width:100px;}.

19 Macros for Iterative and Conditional Text Generation – The characterSet Macro /* Define table header information */ Decimal Value ASCII Character Numeric Character Reference as Displayed Numeric Character Reference Coded Value. Could have been Parameterized.

20 Macros for Iterative and Conditional Text Generation – The characterSet Macro /* Use a macro %DO loop to generate the values from 32 to 255. Start at 32 - unprintable values below 32 can cause problems) */ %do i = 32 %to 255; %if &bgcolor ne &oddRowBGColor %then %let bgcolor = &oddRowBGColor; %else %let bgcolor = &evenRowBGColor;. Alternating Background colors Parameterized.

21 Macros for Iterative and Conditional Text Generation – The characterSet Macro &i %let char = %qsysfunc(byte(&i)); &char &#%qsysfunc(putn(&i,z3.)); /* The “Numeric Character Reference as Displayed” column is generated by prefixing &# to the decimal value. The “Numeric Character Reference Coded Value” uses & as the prefix instead of &, so the coded valued is displayed by the browser. */ &#%qsysfunc(putn(&i,z3.)); %end;... Note the /* */ Style comments.

22 Macros for Iterative and Conditional Text Generation – The characterSet Macro %mend characterSet; Close out the HTML and the Macro.

23 Including Text from External Files  The examples shown so far have used inline text to be processed by PROC STREAM inline. Typically, however, the input text will be in an external file. The syntax for including an external file is: &streamDelim; %include [file-specification];  Revised PROC STREAM call: proc stream outfile=_webout; BEGIN &streamDelim; %include srvrpgs(characterSet.html); ;;;; A Best Practice: Aggregate Syntax

24 Including Text from External Files Scroll bars.

25 Generating Dynamic Content from a SAS Data Set  So far, we have used the %SYSFUNC/%QSYSFUNC macro functions to execute SAS or SCL functions.  They can be used to access SAS data sets.  Allows SAS code and specifically SAS macros used in the input stream to PROC STREAM to access data set information (both attributes and data).  Thus, PROC STREAM can generate data-driven HTML content without requiring the generation of any SAS DATA or PROC step code.

26 Generating Dynamic Content from a SAS Data Set /* use a macro variable to define the subset of data to be read */ %let subsid = Addis Ababa; proc stream outfile=_webout quoting=single; BEGIN %delimited (data=sashelp.shoes,where=subsidiary=:"&subsid" ) ;;;; run;

27 Generating Dynamic Content from a SAS Data Set

28 Generating Dynamic Content from a SAS Data Set  This example highlights several other (beyond accessing SAS data) important features of PROC STREAM:  QUOTING=SINGLE option treats ' as a character and does not consider it to be the delimiter for a quoted string.  The program uses &streamDelim newline; to start each row of data on a new line. New lines are important in text files such as CSV files.  The importance of utility macros (defined in an autocall library) that perform common functions.

29 Generating Dynamic Content from a SAS Data Set  Admittedly, there are tons of ways to generate CSV files in SAS. The reason for generating a CSV file in this example was to highlight that any text file could be created.  For example, you could write a macro the generate a SAS program that is then saved.  Lots more examples in my SAS Press e-book and blog.

30 Executing SAS Code in a PROC STREAM Input File  The facility to include SAS code that is to be executed by PROC STREAM can be an important feature.  An additional level of abstraction incorporates generic routines (aka macro calls) within a SAS Server Page to perform specific types of functions.  For example creating a data set of distinct values for a column in a SAS data set in order to create a dynamic selection list.  A PROC STREAM program (e.g., a macro or stored process) with different input files (e.g., using %INCLUDE) where the name of the input file is macro variable/parameter.

31 Executing SAS Code in a PROC STREAM Input File  Consider an example of generating a selection list. proc stream outfile=_webout quoting=both; BEGIN Select Products proc sql noprint; select distinct '<input type="checkbox" name="product" value="' |strip(product)||'">'||strip(product) into:checkboxes separated by ' ' from sashelp.shoes; quit; &checkboxes ;;;; run;

32 Executing SAS Code in a PROC STREAM Input File  Output is not what we expected/wanted  PROC STREAM treated the SAS code as text to be included in the output file.

33 Executing SAS Code in a PROC STREAM Input File  Need to use the new DOSUB/DOSUBL function.  DOSUB: a single argument that is a fileref that contains SAS code to be executed.  DOSUBL: a single character argument that is the SAS code to be executed. %let rc = %sysfunc(dosubl( SAS Code - potentially spanning multiple lines ));  Best Practice: Use a macro call or %include instead of a long string of text which is the SAS Code.

34 Executing SAS Code in a PROC STREAM Input File  Changes to the previous PROC STREAM input stream.. %let rc =%sysfunc(dosubl( proc sql noprint;. quit; ));

35 Selected Examples  A sample mail-merge application.  Creating a custom (clickable) calendar.  Displaying data graphically, e.g., the use of Tag Clouds as an alternative to bar or pie charts.  Numerous additional examples are available in my:  SAS Press book: SAS Server Pages: Generating Dynamic ContactSAS Server Pages: Generating Dynamic Contact  Blog: Jurassic SAS® in the BI/EBI World”Jurassic SAS® in the BI/EBI World

36 A sample mail-merge application  Generate custom content for each defined subset of data, usually each observation in a data set. Such observations can be individual observations in a SAS data set or aggregated summary statistics for each value of a class variable, e.g.,  a custom formatted report for each department or product.  a case report form for clinical trials data.  and more.  This example: create a i.e., a letter as an HTML file for each observation in the sashelp.class data set.

37 A sample mail-merge application

38 A sample mail-merge application  The input SAS Server Page: &Name %sysfunc(date(),worddate.) Dear Parents : As &name's teacher I wanted to make you aware of a project we are doing this year. Every month we will be collecting your &age year old &sex's height and weight and recording it. At year end, &name will be asked to produce a chart of their growth over the school year.... The macro variables have the same name, by convention, as the corresponding variables in the data set %sysfunc is used with the date function to produce the text for the date.

39 A sample mail-merge application  The input SAS Server Page:... For your information, here are the measurements that we just collected: Height: &height inches. Weight: &weight pounds. Please don't hesitate to contact me if you have any questions, Regards, &name's teacher

40 A sample mail-merge application  The SAS Program: proc format; /* create a format that maps the value of sex to daughter/son */ value $gender 'F' = 'daughter' 'M' = 'son' ; run;.

41 A sample mail-merge application  The SAS Program: %macro generateDocument; %local numDocuments obsToRead; /* get the number of letters (i.e., observations to use) to generate */ %let numDocuments=0; /* ensure a default value */ proc sql noprint; select count(*) into:numDocuments from sashelp.class; quit;.

42 A sample mail-merge application  The SAS Program: %do obsToRead = 1 %to &numDocuments; data _null_; /* Read the observation and create macro variables for that observation. The vvalue function is used to cause the formatted values to be used. */ set sashelp.class (firstobs=&obsToRead obs=&obsToRead);.

43 A sample mail-merge application  The SAS Program: /* associate the formats with sex and age*/ format sex $gender. age words12.; call symputx('Name',vvalue(Name),'L'); call symputx('Sex',vvalue(Sex),'L'); call symputx('Age',vvalue(Age),'L'); call symputx('Height',vvalue(Height),'L'); call symputx('Weight',vvalue(Weight),'L'); run;.

44 A sample mail-merge application  The SAS Program: filename sspout "&root\output\&Name..html" lrecl = 32767; proc stream outfile=sspout quoting=single; /* use %include for input SAS Server Page */ BEGIN &streamDelim;%include srvrpgs(class.html); ;;;; run; %end; %mend generateDocument; %generateDocument

45 A sample mail-merge application  Alternatives available in my SAS Press e-book and blog:  Generating a Word document (e.g., RTF file) instead of HTML.  Use DOSUBL in the data step to read one observation at a time and generate a letter (instead of macro looping): DOSUB and DOSUBL - Data Driven Development DOSUB and DOSUBL - Data Driven Development

46 Creating a custom (clickable) calendar

47 Creating a custom (clickable) calendar  This example illustrates using resources found on Web.  And the Web, with the help of a Google search, provides a rich source of samples and starting points to create their own SAS Server Pages that can do most anything.  The FullCalendar plugin for JQuery is used. Creating a SAS Server Page to do that is discussed in the blog entry Leveraging JQuery Widgets - An Events Calendar.FullCalendarJQueryLeveraging JQuery Widgets - An Events Calendar  PROC JSON, new in SAS 9.4, is used to produce the JSON input (JavaScript Object Notation) used by the FullCalendar JQuery plugin. JSON

48 Creating a custom (clickable) calendar  The SAS Program: proc stream outfile=sspout quoting=single; /* use %include to define the input SAS Server Page */ BEGIN &streamDelim; %include srvrpgs(blogCalendarProcJson.html); ;;;; run;

49 Creating a custom (clickable) calendar  The events data set:

50 Displaying data graphically - Tag Clouds  Tag clouds are commonly used in blog entries to highlight keywords and other data.  They can also a great way to display BI data  Lets Compare a Tag cloud with a pie chart and a bar chart.  Seems pretty clear that Tag clouds are visually more appealing and easier to read and interpret.

51 Displaying data graphically - Tag Clouds  This example is fully discussed in the following blog entries and those details will not be repeated here:  Tag Cloud SAS Server Page Components - Part 1 Tag Cloud SAS Server Page Components - Part 1  Tag Cloud SAS Server Page Components - Part 2 (of 2) Tag Cloud SAS Server Page Components - Part 2 (of 2)  Tag Clouds vs. Pie vs. Bar Charts Tag Clouds vs. Pie vs. Bar Charts  SAS Server Pages in Batch? Absolutely! SAS Server Pages in Batch? Absolutely!  SAS Server Pages in Batch - Adding a BY variable to the tagCloud macro SAS Server Pages in Batch - Adding a BY variable to the tagCloud macro

52 In Summary  PROC STREAM is a very powerful new facility that extends the output that can be generated by SAS & facilitates for leveraging other web & HTML based facilities.  The examples here only scratch the surface of what can be done with PROC STREAM (and SAS Server Pages).  And check out the companion paper which addresses using PROC STREAM and SAS Server Pages in BI environments: PROC STREAM and SAS Server Pages: Generating Custom User Interfaces – 9am Wednesday Chesapeake 7 Theater 42.PROC STREAM and SAS Server Pages: Generating Custom User Interfaces

53 More on PROC STREAM  Also Check Out:  ebook SAS Server Pages: Generating Dynamic Content.SAS Server Pages: Generating Dynamic Content  blog: Jurassic SAS® in the BI/EBI World.Jurassic SAS® in the BI/EBI World  The full text for both of my papers can be found at My Papers and Presentations on sasCommunity.org.My Papers and PresentationssasCommunity.org  Watch those pages (requires a sasCommunity.org userid – which is free) if you want to be notified of changes or updates, e.g.,  Downloading the code from this presentation.

54 Papers and Presentations on sasCommunity.org