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.