CODE YOUR FIRST DYNAMIC WEB APPLICATION USING HTMSQL Karen L. Wyland, Decision Support Systems, Sodexho, San Bruno, CA
ABSTRACT Servers: Are you familiar with Base SAS, SAS/Macros, and Proc SQL? Do You’ll need two servers running to use htmSQL -- you have SAS/IntrNet running on a server? Would you like to use SAS/Share and a Web server. these tools to build dynamic applications for your website users? If yes, then we have a simple tutorial to get you on your way today! You’ll need to configure various software and system files. First, use the package documentation and SAS’s website on When we first began with htmSQL at Sodexho, the Decision Support installing, configuring, and troubleshooting these web Systems (DSS) team was a bit perplexed. Although we read a lot technologies. (See htmSQL, Documentation below.) about the SAS/IntrNet Web Tools, we had some difficulty putting all the pieces in the logical order for htmSQL. So, we put together a But, we want to help you further. We’ve provided sections tutorial to help our team. Now we’d like to share it with you. below on each of the components. Remember, we’re just hitting the high points but they will be invaluable. We start with a discussion of htmSQL components and their configurations. We use SAS 6.12, SAS/IntrNet 1.2, SAS/htmSQL A. SAS/SHARE 2.0, Apache2 Web Server, and Notepad or Microsoft FrontPage. SAS product to access and update SAS data using SQL Certainly, you aren’t limited to these.
Services File: We use a sample application and sample SAS data to build dynamic SAS/Share uses the TCP protocol to communicate with web pages from start to finish. Once completed, you’ll have a solid SAS and your web server. This means editing the foundation for putting “dynamic” into every web application. ‘services’ file. Find your services file by doing a search since different Windows versions store it differently. You INTRODUCTION set your own port number for SAS/Share and use a port What is htmSQL? It’s SAS Institute’s CGI program allowing a web higher than 1000 that the operating system reserves. author to embed data from SAS datasets into a web page. An Add a line similar to this to your services file. htmSQL input file contains HTML with SQL queries and statements shr1 5555/tcp #SAS Share embedded in it to return data dynamically to the web browser.
Often you want information returned to the browser when the user Your SAS Session: enters or opens that page. Based on htmSQL queries and directives Before you launch your SAS/Share session (below), you’re behind the scenes in that page, you can create content based on the going to want to make sure that the SAS session you begin latest data on the SAS server. This alone is an invaluable tool. has available to it all the libraries, datasets, and precompiled formats you’ll need for any web applications. There are also, times where you want to perform some simple logic or calculations upon the data returned. On the other hand, maybe Launching SAS/Share: you want to let the user update SAS datasets from a web page. Create a SAS program to launch a SAS/Share session. These are the minimum commands necessary. We use pages that include htmSQL to get users started and then pass their selections to SAS/IntrNet broker for more complex logic. options comamid=tcp; proc server serverid=shr1; run; The purpose here is to help you build your first dynamic htmSQL web application from start to finish. It will be simple but give you a B. SAS htmSQL good foundation for developing your own unique applications. CGI Application for SQL on the Web
COMPONENTS AND CONFIGURATIONS Documentation: Not so difficult – We keep It Simple.... If you don’t already have the htmSQL cgi software, you
can find it on the SAS Website at Let’s start by discussing the software components you need and http://www.sas.com/apps/demosdownloads/setupcat.jsp?cat pointing out several key configuration steps for each. =SAS/IntrNet+Software.
Software: Once you’ve installed the download, look at the readme Operating System: Windows 2000, SAS System: v6.12, file. At first, the terminology can seem confusing just Web server: Apache, v2, htmSQL: Version 2, Browser: Internet because it’s a new procedure to you. Remember, for this Explorer, v5.5. paper, we’re only using the very basic functionality so you quickly develop your application.
1 Make htmSQL available to your web server. Editing and the .hsql opens quickly in Notepad so you can Executables: make and save changes easily. Locate the directory where you installed htmSQL, \Intrnet\htmSQL. Copy htmSQL.exe, htmSQL.cfg, and sasSQL.dll to your Web E. OKAY - Let’s Test it Out! server's CGI program directories, usually /cgi-bin. If your web server Hold onto your seats.... doesn’t have this directory, then simply add it. 1. Launch your Web Server.
2. Launch SAS/Share. Samples/Documentation: Also, copy the \Intrnet\htmSQL\samples directory as a sub-directory 3. Launch your Web Browser. under your web server’s htdocs directory. We even copied the 4. Access this URL: \Intrnet\htmSQL\doc sub-directory as well for easy access to http://localhost/cgi-bin/htmSQL/samples/autovars.hsql reference docs from the browser. htmSQL Configuration: Voila! There’s a listing in the browser of all automatic Good news! You don’t need to edit the configuration file to begin variables available to you in your SAS Session. J testing. You can actually use something in its default state Alas, if you’re having trouble, we suggest going back to the Later you may want to ‘uncomment’ and use the datasource documentation, the troubleshooting section on the SAS definitions. With them, you customize sessions with advanced website, and SAS Technical Support. Don’t waste time parameters and usage but you can read up on that functionality later. trying to tweak a line here or there. You want to be spending your time with the next section. Windows and htmSQL If you’re using your own computer and Windows as the server, then LET’S GET STARTED! rename the htmsql.exe to htmsql so that each time you refer to it you What are we going to do today? won’t have to add that extra .exe to each call. We’ll explore several tasks: C. Web Server – Main Configuration File • Run a SAS supplied sample to make sure We’re using Apache2 as it is free! everything is working properly. (Just did it!) • Design a very simple webpage to return values of Configuration: a sample dataset you’ll create. (see Sample Data) To perform the basic tasks here, you only need to edit or add two • Add various design and data enhancements in a lines to your web server’s configuration file. We’ll show you what to systematic approach, adding htmSQL queries and do for Apache. It should be similar for other web servers. directives to return values to the webpage dynamically from SAS data. Server Name: • We’ll test it after each change to see results. Find the http.conf file (Apache) in the conf sub-directory and open it • Finally, discuss ways that you can continue to into any text editor. Find the directive “ServerName” and edit it for build on these sample applications. localhost with port 80 for http. Note1: Steps are progressive. We don't repeat all code and ServerName localhost:80 comments in subsequent steps. So, do follow in order. htmSQL Handling: Note2: You can copy, save, and process the sample code. Find the directive “Action” and add a line so that the server knows And, all hyperlinks are live throughout the paper as long how to handle hsql extensions. you set your servers as instructed in the previous section. Action htmSQL /cgi-bin/htmSQL A. Sample Data Let’s Explore the Dataset. Save your newly edited configuration file and that’s all you need! We'll use sample data containing five hierarchical, two D. Two Last Things.... categorical, and three financial variables. You create this Check Firewall and Other Application Conflicts data by running the program on the last page. In this way, you can run all the sample web pages in the paper. You may need to configure various applications running in memory under Windows. For example, if you have a Personal Firewall Below is a modified contents to help familiarize you with application running, edit it to allow the htmSQL executable and the data you’ll use for the sample web pages. SAS/Share for traffic on the http ports (consult your individual manuals). Also, check Anti-Spam and Anti-Virus software. Data Set Name: WORK.DATA # Variable Type Len Pos Format Label Set Application for Edit in Internet Explorer 1 SVP Num 8 0 Z3. Hierarchy 1 2 DVP Num 8 8 Z3. Hierarchy 2 Open your browser and click on Tools -> Internet Options. Click on 3 RVP Num 8 16 Z3. Hierarchy 3 4 DM Num 8 24 Z3. Hierarchy 4 the Programs tab. For the HTML Editor, choose Notepad. You can 5 LOCATION Char 10 32 $10. Hierarchy 5 reset this any time you like of course. By doing this, when you’re in 6 I Char 1 42 $1. Category 1 the browser and want to edit the web page, click on the Icon for 7 DESC Char 15 43 $15. Category 2
2 8 THISYTD Num 8 58 COMMA13. Financial 1 1. Query server statement includes your domain name and 9 BUDGYTD Num 8 66 COMMA13. Financial 2 10 LASTYTD Num 8 74 COMMA13. Financial 3 port number you assigned in the services file. “localhost” means it will run on our local operating system, using port The order of the variables is the same as the logical business 5555 which is set in the ‘services’ file to use SAS/Share. presentation of this data. In other words, a columnar report would match col 1 with var 1 and col 10 with var 10. The labels indicate 2. SQL statement queries the work.data dataset. the types of variables. There’s also a small format procedure. 3. Eachrow will return your query results to the browser. 4. Eachrow must have an ‘end’ (/) statement. So, now that you “KNOW YOUR DATA”. Let’s have fun! 5. Query must have an ‘end’ (/) statement.
Action: Save this code as sample1.hsql in your htdocs B. General Usage Rules (Very Important) directory and test it out. Get to know htmSQL and the 'How-To' http://localhost/cgi-bin/htmSQL/sample1.hsql
We use these rules for all samples and you’ll see them applied as you
move through the steps: {query server="localhost:5555"}• Save all webpages that use SAS/htmSQL with an extension {sql} of .hsql so htmSQL will recognize them as cgi and process select * from work.data them correctly. {/sql} • Save all webpages to your web server’s htdocs directory or
| SVP to htmSQL and SAS as macro variables. | DVP • Enclose all macro variables in your webpage inside of | RVP | DM 'squiggly' parentheses so they resolve correctly and | Location processed. | Desc • To test the SAS supplied samples, you’ll have to edit the | ThisYTD | BudgYTD .hsql pages with your server name. | LastYTD • To access the .hsql pages, you need to tell the browser that |
|---|---|---|---|---|---|---|---|---|
| {&svp} cgi-bin/htmSQL | {&dvp} • If you want to pass parameters to htmSQL, then you need | {&rvp} to add a ‘?’ after the .hsql and use an ‘&’ before the where | {&dm} clause. For example: localhost/cgi-bin/htmSQL/samples/ | {&location} | {&desc} retail1.hsql?¶m=1990 | {&thisytd} | {&budgytd} C. Ready to Start? Let’s Build One from Scratch | {&lastytd} | Working with our Sample Data
Part A – Process Data and Restart Server SVP DVP RVP DM Location Desc 1. Maximize the SAS/Share that is running. 001 024 028 751 2256789001 01.Sales 2. Press Ctrl-Break to stop the Share Server. 001 024 028 751 2256789001 02.Food 3. Copy the last page of this paper now and submit the SAS code to create the sample data, work.data. Part C – Subset the Results Returned 4. Restart the SAS/Share server by running proc operate as you did Now let’s pass this same dataset some parameters to subset on page 1, Launching SAS Share. the data returned to the browser. In htmSQL, parameters
passed from the URL in the browser, become macro Part B – Simply Return some Data variables to SAS. This webpage is very basic. You’ll notice there is NO html Code Comments: formatting to make your output ‘pretty’. But don’t worry, we’ll enhance it as we go along. 1. You choose the name of the variables to pass. We
choose to call the macro variables svp and amt. Take special notice of the bolded sections. This is code we comment 2. Notice the ‘&’ and ‘squiggly’ parentheses. on or want to emphasize. Or, it may be just to show you what has changed from the pervious step. Action: Add a where clause to the sql statements, save as Code Comments: sample2.hsql, and test it out.
3 http://localhost/cgi- bin/htmSQL/sample2.hsql?&svp=2&amt=1369000 Results: Error: Processing not permitted for input file C:\Program Files\Apache {sql} Group\Apache2\htdocs\sample2.hsql&svp=1 select * from work.data where svp = {&svp} and thisytd > {&amt} 2. You may not know it, but you left out the ‘?’ at the end {/sql} of the .hsql. Now try it again: http://localhost/cgi-bin/htmSQL/sample3.hsql?&svp=1 Results: Your results will be similar to above only subset by the parameter values you passed in the URL. Results: Error: Prepare failed for query select * from work.data where svp = 1 and thisytd > {&amt} Part D – Output looks UGLY.... 3. Oops! You got the ‘?’ and the syntax looks good, but Now its time to add some formatting. The table is pretty plain, the notice in Error message where it shows {&amt}. It’s columns not align correctly, and we could format some variables to indicating that you forgot to pass a parameter that the make them more easily understood. htmSQL in the webpage is expecting. Try one more time: http://localhost/cgi- Action: Add the formatting code as highlighted below, save as bin/htmSQL/sample3.hsql?&svp=1&amt=1369000 sample3.hsql, and test. http://localhost/cgi-bin/htmSQL/sample3.hsql?&svp=2&amt=136900 4. Bingo, results are now correct.
Let htmSQL Help Debug {query server="localhost:5555"} 1. What was the query? Use an htmSQL statement within the webpage to output the query that you passed. If there {sql} are errors, it will try to indicate where the problem is. Add select *, put(svp,_svp.) as svpname from work.data where svp = {&svp} and thisytd > {&amt} this line of code to one of your webpages and see how it {/sql} shows the query. Make sure you add it somewhere after the {/sql} and before the {/query} statements.| SVP This is the query produced: {&sys.query}
| DVP | RVP 2. What if there are no results? | DM Use an htmSQL statement within the webpage to output a | Location message if there are no rows found. Add this code to the | Desc | ThisYTD sample3.hsql and save it as sample4.hsql. | BudgYTD | LastYTD {norows}NO data found...Please try again.{/norows} |
|---|---|---|---|---|---|---|---|---|
| {&svpname} that you know does not exist in the dataset to see the results | {&dvp} of no rows found. | {&rvp} http://localhost/cgi- | {&dm} | {&location} bin/htmSQL/sample4.hsql?&svp=9&amt=1369000 | {&desc} | {&thisytd} CONCLUSION | {&budgytd} | {&lastytd} Sometimes when you’re just beginning to learn new ways | of doing things, you are ‘stopped in your tracks’ by
Part E – Debugging I hope that you’ll have great success with our samples and become very excited with all the possibilities the world of What do you do when you run into trouble? Until you get used to htmSQL will bring to your web applications. how htmSQL works and what it returns when there is an error, here are some helpful tips. Basic Errors
1. Here’s an example error based on the sample3.hsql page you’ve created in these samples: http://localhost/cgi-bin/htmSQL/sample3.hsql&svp=1
4 ACKNOWLEDGMENTS CONTACT INFORMATION - As always, my mentor, boss, and best friend, Nick Thaler. Your comments and questions are valued and encouraged. - SAS Institute Technical Support with a special thanks to Karen L. Wyland Bubba Talley and Jude Redmon Sodexho, Decision Support Systems - Finally, our endusers who keep us on our toes. 883 Sneath Lane, Suite 213 San Bruno, CA 94066 Work Phone: 650-742-7630 REFERENCES E-mail Address: [email protected] - SAS Institute Website for Web Technologies, ® SAS/IntrNet Software
- SUGI 27, Paper 38: Karen L.Wyland
Ask DSS … Using HTML, JavaScript, htmSQL, and SAS® to
Create Dynamic Web Applications
CODE TO CREATE SAMPLE DATA Simply copy this code and paste into the SAS editor. data work.data; attrib svp dvp rvp dm format=z3. location format=$10. i format=$1. desc format=$15. thisytd budgytd lastytd format=comma13.; input svp dvp rvp dm location i desc thisytd budgytd lastytd; cards;
001 024 028 751 2256789001 1 01.Sales 2350505 2637167 4967621 001 024 028 751 2256789001 2 02.Food 853410 1084628 1793946 001 024 028 751 2256789001 3 03.Labor 1063182 1190121 2102943 001 024 028 751 2256789001 4 04.Control 221608 132829 533428 001 024 028 751 2256789001 5 05.Non-Ctrl 66154 108738 291291 001 024 028 751 2256789001 6 06.OPC 146151 120851 246013 001 035 045 181 2239305001 1 01.Sales 402972 490390 492202 001 035 045 181 2239305001 2 02.Food 164917 179284 194828 001 035 045 181 2239305001 3 03.Labor 208135 247725 246406 001 035 045 181 2239305001 4 04.Control 34321 34716 34607 001 035 045 181 2239305001 5 05.Non-Ctrl 12689 13088 15335 001 035 045 181 2239305001 6 06.OPC -17091 15577 1026 002 051 051 214 2201750001 1 01.Sales 804313 744310 810896 002 051 051 214 2201750001 2 02.Food 159563 172663 164492 002 051 051 214 2201750001 3 03.Labor 276522 247274 248178 002 051 051 214 2201750001 4 04.Control 46499 40196 40923 002 051 051 214 2201750001 5 05.Non-Ctrl 210995 201598 238692 002 051 051 214 2201750001 6 06.OPC 110735 82579 118610 002 052 075 673 2294310001 1 01.Sales 853191 898730 1038201 002 052 075 673 2294310001 2 02.Food 231286 245794 251013 002 052 075 673 2294310001 3 03.Labor 399587 410264 426912 002 052 075 673 2294310001 4 04.Control 57280 53648 60479 002 052 075 673 2294310001 5 05.Non-Ctrl 17731 35010 17151 002 052 075 673 2294310001 6 06.OPC 147306 154014 282646 002 053 064 039 2201220001 1 01.Sales 9257923 8988186 8657352 002 053 064 039 2201220001 2 02.Food 3411930 3272070 3191010 002 053 064 039 2201220001 3 03.Labor 3319762 3213379 3083602 002 053 064 039 2201220001 4 04.Control 1298772 1178830 1172880 002 053 064 039 2201220001 5 05.Non-Ctrl 538825 514716 522887 002 053 064 039 2201220001 6 06.OPC 688634 809191 686973 003 330 337 791 4478578001 1 01.Sales 305739 304528 293337 003 330 337 791 4478578001 3 03.Labor 115443 120483 107958 003 330 337 791 4478578001 4 04.Control 26709 24912 28708 003 330 337 791 4478578001 5 05.Non-Ctrl 31102 29880 27402 003 330 337 791 4478578001 6 06.OPC 132485 129253 129269 003 340 311 050 2291202001 1 01.Sales 483841 449292 456322 003 340 311 050 2291202001 2 02.Food 238051 203634 231859 003 340 311 050 2291202001 3 03.Labor 178571 183042 161935 003 340 311 050 2291202001 4 04.Control 19148 16236 18892 003 340 311 050 2291202001 5 05.Non-Ctrl 27708 8136 10397 003 340 311 050 2291202001 6 06.OPC 20363 38244 33240 ; run; proc format; value _svp 1=‘Corporate’ 2=’Campus’ 3=‘HealthCare’; run; proc contents data=work.data; run;
5