Building Web Applications With SAS IntrNet: A Guide to the Application Dispatcher

This template allows the user to select which library contains the data to be paged through. After clicking Get List of Data Sets, the user is given a choice of data sets in the selected library. X Select the Library: Y %generateOptionTag(data=sashelp.vslib,var=libname,where=upcase(libname) not in ("APSWORK" "MAPS" "SASHELP" "WORK"))) Z

The option tag above was generated by embedding a macro call:

    %generateOptionTag(data=sashelp.vslib, var=libname,where=upcase(libname) not in ("APSWORK" "MAPS" "SASHELP" "WORK"))) [

in the template. This macro generates no SAS code. Instead the macro is used as simple text generation tool to generate an option tag containing the values from the input data set.

in the template. This macro generates no SAS code. Instead the macro is used as simple text generation tool to generate an option tag containing the values from the input data set.

The WHERE parameter is used to exclude certain libraries that will typically not be of interest.

X Macro variable references will resolve the values defined by the Application Server. Type specifies a catalog entry for the server. Y A macro (discussed below) that generates the HTML for a select list will be executed. This produces a list of available SAS data libraries from SASHELP.VSLIB. Z The WHERE parameter is used to exclude certain libraries that will typically not be of interest.

Chapter 7: Various Techniques to Generate HTML 119

[ As explained in the template text, another format for HTML entities (  for a nonbreakable space and % for a % sign) is used to prevent SAS from attempting to resolve the HTML entity   (a non-breakable space) as well as forcing %generateOptionTag to be seen as text rather than a macro call. Note: Virtually all of the text in this page is HTML (and could have been created with an HTML editor). It can be edited to include any necessary macro variable references and macro calls and then stored as a SAS Server Page.

Figure 7.9 List of Available Libraries Generated Using SAS Server Pages

7.6.3 A Macro to Generate Data-Driven SELECT Tags The generateOptionTag macro was used in the above SAS Server Page in order to generate a list of available libraries. This simple macro can be used to generate an HMTL select list based on the values in any SAS data set. The parameters for the macro are as follows:

ƒ

DATA the name of the data set which contains the values to be displayed.

ƒ

VAR the name of the variable containing the values.

ƒ

LABEL the name of the variable containing the labels for the values. If not provided, the label defaults to the value specified for Var.

ƒ

NAME the name for the SELECT tag. If no value is provided, the name defaults to the value of Var.

120 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

ƒ

WHERE an optional WHERE clause to subset the values included in the SELECT tag.

ƒ

SELECTED an optional value that is compared to the values from the data set to set the selected option.

ƒ

otherOptions a parameter whose value is used as-is in the SELECT tag. This parameter allows the SELECT tag to be customized as needed (e.g., an onClick or size attribute, etc.)

The macro source is described below: %macro generateOptionTag (data=, var=, label=, name=, where=, selected=, otherOptions= ); %local dsid varnum varlabel value display; %if %length(&where) ne 0 %then %let where = (where = (&where)); %if %length(&name) = 0 %then %let name = &var; %let dsid = %sysfunc(open(&data&where)); X %let varnum = %sysfunc(varnum(&dsid,&var)); %if %length(&label) gt 0 %then %let varlabel = %sysfunc(varnum(&dsid,&label)); %else %let varlabel = &varnum; %let vartype1 = %sysfunc(vartype(&dsid,&varnum)); %let vartype2 = %sysfunc(vartype(&dsid,&varlabel)); <select name = "&name" &otherOptions> %do %while(%sysfunc(fetch(&dsid)) = 0); %let value = %qsysfunc(getvar&vartype1(&dsid,&varnum)); %let display = %qsysfunc(getvar&vartype2(&dsid,&varlabel)); &display %end; Y %let dsid = %sysfunc(close(&dsid)); %mend generateOptionTag;

Note: This macro is provided as an example only. It is not intended to be used as a robust tool (e.g., it does no error checking to verify that the data set or variable exists). However, it can be used as the foundation for a macro tool that meets your application needs. X The %SYSFUNC function is used to enable access to data via the SCL data access functions. Y The only text generated by the macro is the <select> and tags that surround the loop that reads all the observations in the data set as well as an tag for each value in the data set.

Chapter 7: Various Techniques to Generate HTML 121

7.6.4 Sample Server Page: List the Data Sets in the Selected Library The next SAS Server Page lists the data sets in the selected library and is displayed as a result of the user clicking the Submit button after selecting a data library. The selected data library is available as a macro variable (the value of the SELECT tag from the previous page). See Figure 7.10. X <TITLE>Sample SAS Server Page Application Demonstrate Use of SAS Server Pages Demonstrates how macro can be used inside of HTML text to customize it to include data values.

This template allows the user to select the data set from a previously selected library. When the user clicks Submit Variables, he is allowed to select the variables to display, along with the number of observations to display at a time. Y Select the Data Set from &libname: %generateOptionTag(data=sashelp.vstable,var=memname,name=data, where=libname="&libname") Z

X As in the prior SAS Server Page, virtually all of the text in this page is HTML. Y As in the template above, macro variable references will resolve the values defined by the Application Server. Type specifies a catalog entry for the SAS Server Page and template is name of the next SAS Server Page (to select the variables). Z The generateOptionTag macro generates a select list of the available data sets in the selected library. The WHERE clause subsets the data to just the observations in sashelp.vstable for the previously selected library.

122 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 7.10 List of Available Data Sets in the Selected Library Generated Using SAS Server Pages

7.6.5 Sample Server Page: List the Variables in the Selected Data Set The final SAS Server Page in the example application displays a list of variables and allows users to select which variables they wish to see. When the Submit button is clicked, a modified version of the data set paging program is executed. See Figure 7.11.

Chapter 7: Various Techniques to Generate HTML 123

<TITLE>Sample SAS Server Page Application Demonstrate Use of SAS Server Pages Demonstrates how macro can be used inside of HTML text to customize it to include data values.

This template allows the user to define which variables to include. After clicking Page through..., the user is allowed to page through the selected data set. X Select Variables from Data Set &libname..&data %getVarsAsCheckbox(data=&libname..&data) Y

All variables included if none are selected. Number of Observations Per Page 5 Z 10 15 20 25

X The %programName macro points to the program which will run PROC PRINT, allowing the user to page through the data. Y Another macro (discussed below) generates checkboxes for the variables in the selected SAS data set. Z HTML for a radio box is included to specify the number of observations to display at a time.

124 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 7.11 List of Variables in the Selected Data Set Generated Using SAS Server Pages

7.6.6 A Macro to Generate Checkboxes for Variables in a SAS Data Set The getVarsAsCheckbox macro generates HMTL checkbox tags for all the variables in a specified SAS data set. The parameters for the macro are as follows:

ƒ

DATA the name of the data set.

ƒ

NAME the name for the generated checkboxes. If no value is provided, the name defaults to the value of Var.

ƒ

CHECKED a non-blank value indicates that the checkboxes are to be selected by default. The default value for this parameter is blank.

The macro source is described below: %macro getVarsAsCheckbox (data=, name=var, checked=) );

Chapter 7: Various Techniques to Generate HTML 125

%local dsid nvars varname varlabel i br; %if %length(&checked) ne 0 %then %let checked = checked; %let dsid = %sysfunc(open(&data)); n %let nvars = %sysfunc(attrn(&dsid,NVARS)); %do i = 1 %to &nvars; %let varname = %sysfunc(varname(&dsid,&i)); %let varlabel = %sysfunc(varlabel(&dsid,&i)); %if %length(&varlabel) = 0 %then %let varlabel = &varname; &br&varlabel %let br =
; o %end; %let dsid = %sysfunc(close(&dsid)); %mend getVarsAsCheckbox;

Note: This macro is provided as an example only. It is not intended to be used as a robust tool (e.g., it does no error checking to verify that the data set or variable exists). However, it can be used as the foundation for a macro tool that meets your application needs. n The %SYSFUNC function is used to enable access to data via the SCL data access functions. The variable names and labels are determined. If there is no label, the variable name is used. o The only text generated by the macro is the tags for each variable in the data set. The variable name is used as the value and label is the display value. The checkbox tags each start on a new line (because of the
tag).

7.6.7 Program to Page Through the Selected Data Set The final component of this sample is the program that pages through the selected data set. It is substantially the same as what was discussed in Section 7.5. The complete program is included below with the changes annotated. The results of running this program can be seen in Figure 7.12. %setDefaultValue(firstobs,1) %setDefaultValue(atATime,5) %setDefaultValue(data,sashelp.class) %multipleNames(names=var,singleList=y) X %setDefaultValue(Var,_All_) %let obs = %sysfunc(max(&firstobs + &atATime - 1,1)); %let previous = %sysfunc(max(%eval(&firstobs - &atATime),1)); %let next = %eval(&firstobs + &atATime); data _null_; /* this step is used to just make sure the maximum obs is not exceeded */ if 0 then set &data nobs=nobs; call symput('datasetObs',compress(put(nobs,8.))); obs = min(&obs,nobs); call symput('Obs',compress(put(obs,8.))); stop; run;

126 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

ods listing close; /* no listing output*/ ods html file = _webout (title="Observations &firstobs-&obs of &datasetObs from &data") style = sasweb; proc print data = &data(firstobs=&firstobs obs=&obs) label noobs; var &var; Y title "Observations &firstobs-&obs of &datasetObs from &data"; run; ods html close; %externalHTML(type=catalog, Z source=saspress.template7.paging_form_controls.source) )

X The multipleNames macro collapses all the selected values for VAR into a single name. The setDefaultValue macro assigns a default, _All_ if none were selected. Y The only change to the PROC PRINT is the addition of the VAR statement. Z The template to generate the form controls, including one for VAR, is used.

Figure 7.12 Paging Through PROC PRINT Output

This example, like the one described in Section 7.5.1, can serve as the foundation for a general purpose tool that allows users to page through any SAS data set.

Chapter 7: Various Techniques to Generate HTML 127

7.7 SAS Design-Time Controls The SAS Design-Time Controls (DTCs) are ActiveX controls that are designed to be run inside selected HTML editors. They provide a point-and-click interface that enables you to add SAS content to HTML pages. Note: SAS DTCs were originally designed for the Version 6 Application Dispatcher and were updated for Version 8. They are considered stable and will not be updated in future releases of SAS software. If the current controls meet the needs of an application, their use should be considered. The user interface of the HTML editor is used to insert a control into an HTML page. The controls present dialog boxes that offer choices and settings. After the choices are made and the dialog box is closed, the DTC writes the appropriate content or instructions. The controls can be used to insert the content at build time (i.e., when the developer is building the page in the editor) or at browse time (i.e., when a user requests the page via a link). The controls are needed only when the page is built; users who browse the pages using their browser do not need to have the controls locally installed. For more information about SAS DTCs, see support.sas.com/pubs. Note: SAS DTCs provide functionality similar to the SAS Server Pages discussed in Section 7.6. The key difference is that the SAS DTCs can invoke any SAS/IntrNet Application Dispatcher SAS program to generate content, and the HTML programs that use the controls reside on the Web server. They are not limited to macros that generate only HTML text. However, they do require either ASP or JSP functionality on the Web server in order to generate the content at browse time. Here is a list of available SAS DTCs:

ƒ ƒ ƒ ƒ ƒ ƒ ƒ

SAS Critical Success Factor SAS MDDB Report SAS Stored Program SAS Table SAS Tabular Report (i.e., PROC TABULATE) SAS Thin-Client Graphics (versions that generate HTML for either Java applets or ActiveX objects) SAS TreeView

To run this example, go to the sample environment and select Chapter 7. Then select SAS Design Time Controls, which shows a sample page built with the SAS DTCs. (If you are running the sample environment locally, this assumes that your Web server supports ASP processing and the SAS DTCs have been installed.) Figure 7.13 shows this page in the Microsoft FrontPage HTML editor. Figure 7.14 shows the output in a browser.

128 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 7.13 HTML Editor (FrontPage) View SAS Design-Time Controls

Figure 7.14 Output of the SAS Design-Time Controls

Chapter 7: Various Techniques to Generate HTML 129

The Stored Program Control is of particular note. It can be used to run (virtually) any Application Dispatcher program. The user interface for this DTC allows you to specify the program to run as well as a query string that contains all the name/value pairs to be passed to it. Since any program can be run by this control, it can be used, in conjunction with ASP or JSP pages, to deliver SAS content as part of the page. In other words, it can be used to assemble output from multiple programs into a single HTML page. Note: Consult SAS OnlineDoc at support.sas.com/onlinedoc for any restrictions on the use of SAS Design-Time Controls. The Stored Program Design-Time Control generates ASP code that defines and then invokes a function that connects to an Application Server, causing the function to generate HTML, which is then inserted into the HTML in place of the function call.

Comparably, in a JSP page: { appserver.AppServer IappServer = new appserver.AppServer(); IappServer.setURL(null); IappServer.setURL("http://localhost/scripts/broker.exe"); String queryString = "_service=appdisp&_debug=0&_program=bbu.chapter7.initial.source&data=sashelp.c lass&atATime=7"; java.io.OutputStream os = IappServer.getOutputStream(); os.write(queryString.getBytes()); os.close(); String HTML = IappServer.getHTML(); int responseCode = IappServer.getResponseCode(); if (responseCode >= 200 && responseCode < 300) out.println(HTML); else if (responseCode == 401) {

130 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

HTML = "

ERROR: Authenticated sites are not supported.

Printable (PDF)'; [ put '   '; put 'Editable (PDF)'; put ''; run;

X Use the catalog access method to define filenames in the _tmpcat catalog for the PDF and RTF output. Y Generate multiple ODS statements: one for each content type desired. ODS will format the output as HTML, and direct it to _webout. ODS will also format the output as PDF and direct the output to a catalog entry. Finally, ODS will format the output as RTF and direct the output to a catalog entry. The program needs to be run only once. The PDF and RTF output is saved in the _tmpcat catalog (which causes the creation of a lightweight session). Z Run the report once and then close all the ODS output destinations. [ Generate links for the Replay program to return the PDF or RTF versions of the report. The NO_BOTTOM_MATTER option was used in the ODS HTML statement. The _replay macro variable is used to generate the link, as it includes all the name/value pairs needed to generate a link for the Replay program, including all the fields to direct the request back to the same server. This is necessary since the _tmpcat catalog is available only to the specific server running the current request. The value of _replay includes the value for the _tmpcat catalog; it is necessary only to append the entry name and type. _replay includes the & sign to separate the name/value pairs for the hyperlink and it is already quoted with a single quote (‘) so it can be used directly in a PUT statement.

Upon examining the links (e.g., by selecting view source) that are generated to view the PDF and RTF output, you see that they contain session information (i.e., the URL contains values for _server, _port, and _sessionid). See Figure 8.11. Note that line feeds were added to the HTML source for readability. Writing content to the catalog referenced by the macro variable _tmpcat (referred to as the _tmpcat catalog) creates a lightweight session just as using ODS does. ODS also writes content to the _tmpcat catalog and then uses the replay link to surface that content when generating a page with mixed text and graphics. Selecting either of these links will produce the same output (except for the TITLE statement) shown in Figures 8.7 and 8.8. The difference here is that the program to create the report was only run once.

146 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 8.11 HTML Source Generated Using _replay Showing Session Information

The use of the _tmpcat catalog to create other components of the desired output (e.g., frame-based content, graphics, etc.) is a useful technique when the full overhead of sessions is not needed. Since using the _tmpcat catalog triggers a lightweight session, the Application Server deletes the catalog once the lightweight session expires. There is no need for the application to do this cleanup; unlike the situation if another storage location, e.g. a file system file, is used. Note: The PDF is returned as an attachment since the Replay program generates the attachment header, by default, for PDF output. It is not possible to change or customize this behavior of the Replay program; it was implemented this way by SAS to deal with browser issues.

8.4 Generating Pages with Mixed Content Types: Text and Graphics The most common type of page with mixed content is a page that contains a text report (in HTML) with embedded graphics. This is created in a relatively straightforward way for static pages by using an IMG tag:

When the graph is being generated dynamically, there is no filename to use as the value of the SRC parameter of the IMG tag. Luckily, the SRC parameter can accept a URL if the results returned by the URL are an image with the appropriate content-type header (e.g., image/GIF or image/JPEG). Thus a URL that invokes the Application Dispatcher to generate a graph can be used. For example, here is a link for the Simple Graph example in Section 8.2.1:

The Application Server supports a number of techniques to do this, with the easiest being ODS. To run this example, go to the sample environment and select Chapter 8. Then select Mixed Content Types - Table and Graph via ODS, which runs the program and produces the output shown in Figure 8.12:

Chapter 8: Creating Pages with Mixed and Alternative Content Types 147

Figure 8.12 ODS Output with Mixed Content Types (Text and Graphics)

goptions dev=gif xpixels=800 ypixels=400 transparency; ods html body=_webout (title="Mixed Content Types - Table and Graph via ODS") path=&_tmpcat (url=&_replay) style=sasweb; n proc gchart data = sashelp.shoes; title; hbar3D product/sumvar=sales subgroup=region shape=cylinder nostats discrete; run; quit; proc report data=sashelp.shoes nowd style(summary)=[foreground=green]; columns product region, sales; define product / group ' '; define region / across ' '; define sales / sum ' '; rbreak after / summarize; run; ods html close;

148 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

n When you specify the _tmpcat catalog as the value of the path variable, the two-level name generated for the graph causes it to be written as a .GIF entry in the catalog. The macro variable _replay includes a name/value pair for the entry to be replayed, but includes only the catalog name. When ODS automatically appends the two-level name of the graph entry to &_replay when constructing the URL for the SRC parameter of the IMG tag, the result is the four-level catalog name for the entry to be replayed. The resulting URL will look like this: /scripts/broker.exe?_service=appdisp&_server=localhost &_port=1251&_sessionid=D8QnokXRJ52&_program=replay &_entry=apswork.x0000003,gchart.GIF

As discussed in Section 8.3.4, writing to _tmpcat causes a lightweight session to be created. Although ODS is certainly the easiest way to generate pages with mixed text and graphics, any Application Server program can do this and allow more control over the placement of the images. Consider the following example that displays tables and graphs side by side. To run this example, go to the sample environment and select Chapter 8. Then select Mixed Content Types - Table and Graph - Side by Side, which produces the output seen in Figure 8.13:

Figure 8.13 Custom Generation of Links for Graphic Output: Side by Side Tables and Graphs

Chapter 8: Creating Pages with Mixed and Alternative Content Types 149

goptions gsfname=myGraph gsfmode=replace dev=gif xpixels=500 ypixels=400 transparency; proc gchart data = sashelp.shoes; title; filename myGraph catalog "&_tmpcat..US.gif"; X where region = 'United States'; hbar3D product/sumvar=sales subgroup=subsidiary shape=cylinder nostats discrete nolegend; run; filename myGraph catalog "&_tmpcat..WE.gif"; X where region = 'Western Europe'; hbar3D product/sumvar=sales subgroup=subsidiary shape=cylinder nostats discrete nolegend; run; quit; data _null_; Y file _webout; put '' / '<TITLE>Sample Report with Custom Graphics'/ '' / '

Connect to Created Session'; run;

n The session is created and set to expire in 120 seconds. Whenever the session is reconnected to, the time is extended. In other words this session will expire 120 seconds after the last connection to it. o Create a data set in the SAVE library with session information to demonstrate that the library is still available when reconnecting to the session. p Create macro variables. Only those with a prefix of SAVE in the name are automatically available when reconnecting to the session. q Generate a link to reconnect to the session. The macro variable _thissession contains all the information needed to reconnect to the session. The only information that needs to be added to the link is the name of the program, _debug, and any other needed name/value pairs. %superq

168 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

is used so &_thissession resolves, but with the embedded &s that delimit the name/value pairs in the URL left alone (i.e., they are not interpreted as macro triggers). %programName is used to specify another source entry in the same catalog. Figure 10.2 shows the HTML produced by the DATA _NULL_ step. As discussed in Section 4.5, the presence of the variables _sessionid (and _server and _port) in the request URL causes the request to reconnect to the same Application Server that makes the SAVE library available. The macro variables whose names were prefixed with SAVE_ are also available.

Figure 10.2 HTML Link to the Created Session

The USESESSION program (run when the user selects Connect to Created Session) shown below uses the SQL and PRINT procedures to display the information (the data set and the macro variable whose name was prefixed with SAVE_) that was saved in the previous execution of a program in the session. It also shows when the new session timeout will occur by adding the session timeout value to the current datetime. ods html file=_webout (title='Reconnecting to a Session') style = sasweb; proc sql flow; title 'Available Macro Variables When Reconnecting to a Session'; select name, value from dictionary.macros where scope = 'GLOBAL' and name not like ('SQL%') and /* exclude the names created by this PROC SQL step */ substr(name,1,1) ne '_' /* exclude the appserver and broker created fields */ order name, offset; quit; data _null_; timeout = appsrvgetn('session timeout') + datetime(); call symput("Timeout",put(timeout,datetime.)); run;

n

proc print data=save.sessionInfo split = '_' noobs; title "Data Set from Previous Request, Current Date/Time: %sysfunc(datetime(),datetime.)"; title2 "Due to Reconnect, Session will Now Timeout at &timeout"; run; ods html close;

n Calculate when the session will time out by adding the timeout value to the current datetime. This is not precise since the value returned by the datetime function may be different from the actual reconnect time by a few milliseconds. This difference is noise.

Chapter 10: How to Create and Use Sessions 169

In Sections 8.3.4 and 8.4, lightweight sessions were created simply by writing to the catalog specified by the macro variable _tmpcat. Such sessions, however, had access only to information stored in the _tmpcat catalog. By explicitly creating a session, you can use two other mechanisms to save information for later (i.e., without passing all the information in name/value pairs in the link):

ƒ

Storing the information in the SAVE data library. Data sets as well as catalogs can be saved.

ƒ

Saving macro variables by prefixing their names with SAVE. If the names are not prefixed with SAVE_, they can be saved by including %LET statements in the program, e.g.: %let SAVE_myMacroVar = &myMacroVar;

If the original name is needed, it can be restored at the beginning of later requests with %let myMacroVar = &SAVE_myMacroVar;

Note: The next section presents an alternative technique for saving and restoring macro variables. The application could also be implemented so that any variable to be saved is named with SAVE_ as a prefix. The following example revisits the example from Section 8.4 that generated an image tag to a standalone graph program. Here we will use sessions. The first program saves the subset data in the SAVE library and uses a prefix of SAVE_ for the macro variables. This eliminates the need to pass the parameters as name/value pairs in the URL (and thus also avoids the encoding issues for special characters in the where clause). The code is shown below. To run this example, go to the sample environment and select Chapter 10. Then select Generating an IMG tag to invoke a standalone Graph Program. The results are identical to what was shown in Figure 8.14. The first program, which generates the REPORT procedure output as well as the image tag, is shown here: data _null_; n rc = appsrv_session('create',120); run; ods html file=_webout (title="Generating an IMG tag to invoke a stand-alone Graph Program" no_bottom_matter) style=sasweb; %let save_where = product in ("Boot" "Men's Dress" "Men's Casual"); %let save_data = save.subset; %let save_subgroup = product; data &save_data; p set sashelp.shoes; where &save_where; run; proc report data=&save_data nowd style(summary)=[foreground=green]; columns product region, sales; define product / group ' ';

o

170 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

define region / across ' '; define sales / sum ' '; rbreak after / summarize; run; ods html close; data _null_; q file _webout; put '' ''; put ''; run;

n Create the session. o Create the macro variables with the SAVE_ prefix so they are automatically saved. p Create the appropriate subset of the data in the SAVE library. Note that if you subset the data only once, the programs will run more efficiently (the ability to subset the data once is another advantage of using sessions). q Generate the image tag as in the example above. Note that no other name/value pairs need be included in the URL as they will be available to the next program since the macro variable names had the prefix of SAVE_. The modified program that generates the graph is shown next: %setDefaultValue(save_data,sashelp.shoes); %setDefaultValue(save_var,region); %setDefaultValue(save_subgroup,region); %setDefaultValue(save_sumvar,sales); %setDefaultValue(save_type,hbar3d); %setDefaultValue(save_where,1); %setDefaultValue(save_hsize,600); %setDefaultValue(save_vsize,600);

n

goptions gsfname=_webout gsfmode=replace transparency hsize=&save_hsize vsize=&save_vsize dev=gif; proc gchart data = &save_data; title; &save_type &save_var/sumvar=&save_sumvar subgroup=&save_subgroup; run; quit;

n All the macro variables use a prefix of SAVE_ so the values from requests in the same session are available. The only other change to the program is that there is no need to use a WHERE clause as the data was subset and saved in the SAVE library.

Chapter 10: How to Create and Use Sessions 171

10.3 Saving or Restoring All Macro Variables Saving macro variables from one execution of a program to a later execution of a program (whether it is another instance of the same program or another program) using sessions provides many benefits. This technique is superior to including all the macro variables as name/value pairs in forms or links. You may prefer to use a technique other than prefixing the name with SAVE_. One possible approach is to explicitly save and restore all macro variables except those variables that are created by the Application Server or Application Broker (e.g., all except those whose names begin with an underscore (_)). The following macros, saveMvars and restoreMvars, provide a template for this technique. Here is the saveMvars macro: %macro saveMvars (lib=save, data=savedMacroVars, saveFlag=, includeAuto= ); %if %sysfunc(libref(&lib)) = 0 and n %length(&saveFlag) ne 0 %then %do; /* save is available only for sessions that are not lightweight sessions */ data &lib..&data; set sashelp.vmacro(keep=scope name value offset); o where scope = 'GLOBAL' and offset=0 %if %length(&includeAuto) = 0 %then and substr(name,1,1) ne '_'; and name ne: ‘SYS’; drop scope offset; run; %end; /* save is available only for sessions that are not lightweight sessions */ %mend saveMvars;

n The libref SAVE (the default value for the LIB parameter) exists only when a full (as opposed to a lightweight) session exists. The macro variable values are saved only when the specified library exists. o This sample macro does not handle macro variables whose values length exceeds what can be accessed in the sashelp.macro (e.g., offset is not 0). Here are the parameters for the saveMvars macro:

ƒ

Lib The SAS data library where the macro variables are to be saved. The default value is SAVE.

172 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

ƒ

Data The name of the data set to save the macro variable values in. The default value is savedMacroVars.

ƒ

saveFlag A non-blank value specifies that the values are to be saved. This parameter facilitates calling the macro in, for example, the TERM program. A macro variable can be set to blank or non-blank in the called program, and then that value can be used as the value of saveFlag to indicate whether the values should be saved. The default value is blank.

ƒ

includeAuto A non-blank value specifies that macro variables whose names are prefixed with an _ (e.g., the macro variables defined or created by the Application Broker and Application Server) are also to be saved. The default value is blank.

Here is the restoreMvars macro: %macro restoreMvars (lib=save, data=savedMacroVars ); %if %sysfunc(exist(&lib..&data)) gt 0 %then %do; /* restore only if data set exists */

n

data _null_; set &lib..&data; /* must be added to the global environment for the request executive */ call execute('%global '||trim(name)||';'); o /* only provide value from saved session if not already defined */ if symget(name) = ' ' then call symput(name,trim(value)); p run; %end; /* restore only if data set exists */ %mend restoreMvars;

n The macro checks to make sure the data set exists before restoring it. This allows programs to call the macro unconditionally. o The CALL EXECUTE statement ensures that the macro variable names exist in the global environment (i.e., the same environment as all the name/value pairs passed in to the ® Application Server program) for the request executive. In SAS 9 this can be done more easily by using the SYMPUTX function which can assign the scope of the macro variable to be global. p The macro variable is assigned the saved value only if the variable does not already have a value. Here are the parameters for the restoreMvars macro:

ƒ

Lib The SAS data library where the data set with the saved macro variables is saved. The default name is SAVE, but other libraries can be used.

ƒ

Data The name of the data set containing the saved macro variable values. The default name is savedMacroVars.

Chapter 10: How to Create and Use Sessions 173

The following sample program demonstrates the use of these two macros to save and restore macro variable values without having to include them in any generated links or forms. Note that this program is called recursively by selecting Reconnect to Session. (This is not a requirement to use the macros.) %restoreMvars()n data _null_; if libref('SAVE') then o do; /* create session since it does not exist */ rc = appsrv_session('create'); call symput('sessionCounter','0'); p call symput('mVarNotRestored', q 'saved-but-not-restored'); end; /* create session since it does not exist */ run; %let sessionCounter = %eval(&sessionCounter + 1); r %let MacroVars&sessionCounter = s Session Connection Counter: #&sessionCounter at %sysfunc(datetime(),datetime.);; ods html file=_webout (title='Creating a Session' no_bottom_matter) style = sasweb; proc sql flow; title "Macro Variables from the Current Session &_sessionid"; select name, value t from dictionary.macros where scope = 'GLOBAL' and name not like ('SQL%') and /* exclude the names created by this PROC SQL step */ substr(name,1,1) ne '_' /* exclude the appserver and broker created fields */ order name, offset; quit; ods html close; data _null_; u file _webout; put '

Reconnect to Session'; v run; %saveMvars(saveFlag = Non blank says to save values)

n Invoke the restore macro. Note that the macro includes logic so that it runs only if the data set containing the saved values exists. o If the session does not exist, create it. The existence of the SAVE libref can be used to check if a session exists. p Initialize a session counter macro variable. q Create a macro variable whose value will not be propagated. r Increment the session counter. For now this is an informational field only. The use of this field will be expanded upon in Section 10.4.

174 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

s Create one macro variable per connection to a session (an artifact to create additional macro variables as the session is reconnected to) to simulate later programs creating additional, application specific macro variables. t Print the current values of all the available macro variables. u Generate a link to run the same program again. Another execution of this program that connects to the session will not create a new session (reconnects do extend the session expiration time). mVarNotRestored is included in the link to demonstrate that even though the macro variable mVarNotRestored value was saved, it is not restored. Here is the reason: since the value is defined in the link, the value is passed in and won’t be reset by restoreMvars. v Since there are cases where you may not want to save the macro variable values, use a flag to indicate that they are to be saved. To run an example that uses these macros, go to the sample environment and select Chapter 10. Then select Save/Restore Macro Variables (see Figure 10.3). Once the initial page is displayed, Reconnect to Session (see Figure 10.4) reruns the program. Note how each execution of the program creates a new macro variable and that each execution has all the previous macro variables available (thanks to the save or restore macros) without their having been included in the generated link.

Figure 10.3 Session Created

Chapter 10: How to Create and Use Sessions 175

Figure 10.4 First Reconnect to a Session

You can call the saveMvars and restoreMvars macros by specific programs (as in this example), or you can include them in the INIT and TERM programs so the functionality is available automatically to any program that uses sessions. The trade-off is the (minimal) overhead of invoking these macros when sessions do not apply or when the save facility is not needed. In general it is better to call the macros in each program because that gives more control over how and when to save the macro variables. For example, an application could have a metadata approach that specifies which specific variables are to be saved (e.g., by using a data set that lists the specific macro variable names as opposed to the use of sashelp.vmacro). Note: The SESSION INIT and TERM programs cannot be used since those are invoked only when a session is created or ends. They are not invoked in the process of reconnecting to a session.

10.4 Reconnecting to a Previous State of a Session A common problem with saving the state of a session on the server is handling scenarios where users navigate away from the current page and then return to another page that corresponds to a previous (now potentially invalid) state of the session. This problem exists for any Web-based application that maintains state on the server; it is not specific to the SAS/IntrNet Application Server. The problem can be seen by running the sample from the previous section and selecting Reconnect to Session four times (see Figure 10.5). Figure 10.6 shows what the user will see after pressing the Back button twice, that is, reconnecting to a previous state of a session. Figure 10.7 shows what the user will see upon selecting Reconnect to Session.

176 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 10.5 Multiple Reconnects to a Session

Figure 10.6 Browser Back Button Pressed Twice by the User

Chapter 10: How to Create and Use Sessions 177

Figure 10.7 Reconnecting after Using the Back Button

The user would expect a display that shows Step 4 (i.e., a sessionCounter value of 4). Figure 10.7 shows that the user is at Step 6 (the value of mvarNotRestored shows that the user clicked the link created when sessionCounter had a value of 3). The reason the display shows Step 6 is that the saved session has Step 5 as the last step. The saved session is not aware that the user pressed the Back button twice. In a session application, such as a survey or questionnaire with skip patterns, this presents problems. If all the parameters were included in the link, there would be no problem, but this is not a viable option since links and forms cannot handle large volumes of data (e.g., compared with what can be stored in a SAS data set). In addition, if all the data is embedded in a link, sessions would add little or no value. Note: This navigation problem applies even if the SAVE convention is used to save macro variable values. This example presents the issue from the context of the saved macro variables. However, the same conflict exists for any saved SAS data sets (as demonstrated by the fact that the macro variables were saved in a SAS data set). Fortunately there is a framework for a solution to this problem: include in any link that reconnects to the session an indicator or flag as to the current state of the application. For example, include the value of the sessionCounter variable in any link and use that value to determine what data to restore. To see an example of this, select Reconnecting to a Previous State of a Session. If the steps above are repeated using this link instead of the one for the previous section, the results show that whenever a link is selected the state is recovered to its status at the time that particular

178 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

page was generated. Figure 10.8 shows the output produced when the user clicks Reconnect to Session four times, presses the Back button twice, and then clicks Reconnect to Session again.

Figure 10.8 Reconnecting after Clicking the Back Button Using Session Tracking Framework

The following program demonstrates the framework for this approach. The program is substantially the same as the one in the previous section, and so only the differences are included below: %global previousSession; %restoreMvars(data=savemvars&previousSession) . . . data _null_; file _webout; put '

Reconnect to Session'; run;

Y

n

Chapter 10: How to Create and Use Sessions 179

%saveMvars (data=savemvars&sessionCounter, saveFlag = Non blank says to save values - note this is saved as well )

n previousSession is passed in via the link that reconnects to this session. Since it won’t exist when the session is created, it is defined in a %GLOBAL statement and its value is used in the name of the data set that contains the values stored corresponding to the previous execution. If there is no previous execution the macro will not restore any macro variables since the data set does not exist. Y The unique indicator variable, sessionCounter, that identifies the current connection to the session is included in the link as previousSession (see above). sessionCounter is then used in the name of the data set that stores the macro variables. A separate data set for each connection to the session is maintained. When the user clicks the Back button and then clicks a link or a form to rerun the program, the appropriate data sets are overwritten and used. By creating a sessionCounter Best Practice: For applications or programs that create or use macro variable and using its sessions, create a sessionCounter variable and use its value in all data value in the name of the data set set names to be saved. You can also optionally use options to save the macro variable values work=save; to instruct SAS to save all WORK data sets to the SAVE library, making them transparently available throughout the as well as in any other data set session. saved to the SAVE library, you can simplify the logic to handle such navigation problems (e.g., handling skip patterns in a survey or questionnaire).

10.5 Generating Friendlier Messages for Expired Sessions The default message that is shown below (Figure 10.9) is generated when a user clicks a link to connect to a session that does not exist (e.g., it has expired). The message is cryptic and does not provide any instructions about what the user should do.

Figure 10.9 Default Session Expired Output

180 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

There are a number of reasons why a user might get such a message:

ƒ ƒ

The session simply expired because there was no activity for the specified timeout period.

ƒ

The user saved a URL for a session as a Favorite and attempted to use the Favorite at a later point in time.

ƒ

The Application Server was stopped and restarted while a session was active.

The user completed the process that used sessions, the application deleted the session and then the user pressed the Back button (or the History list), which caused the browser to attempt to reconnect to the expired session.

The INVSESS option of the APPSRV procedure’s SESSION statement provides a facility to generate a friendlier message than the one above. For example, the sample environment uses the following statement to specify an entry for a more descriptive message. session invsess=saspress.appserver_admin.expired_session.source;

Note: If the INVSESS option is specified, the Application Server will not generate any message about session unavailability. The specified INVSESS program must generate the message. If this option is specified, the Application Server runs this program (since the session has expired this program won’t be able to recover any information in the now-deleted SAVE library) instead of the originally requested program in order to generate a custom message stating that the session has expired. The value for the name of the program that the request specified is available as _userprogram, and the value of _program is the name specified in the INVNESS option above. Ideally, the INVSESS option produces a meaningful message for the user regarding the expiration of a session. The program can also provide a link that the user can click if he or she wants to restart the application that used the session. Since the session is gone, there is no way to recover the data from the session. Since the INVSESS option gives access to all the parameters (i.e., the name/value pairs) for the request, including the requested program, the program should be able to provide some sort of meaningful message. Note: Since the name/value pairs from the URL are available, the links could include some sort of acronym or message that could be used by the INVSESS option to provide a better message as well as a link to restart the session. The INVSESS option could also be used to automatically invoke the program that created the session. For example, just the name of the program might be sufficient to produce such a message. Using the program name in conjunction with a metadata approach is one way to produce a more meaningful message. The INVSESS program provided with the sample environment illustrates such an approach. It creates a SAS data set that has two variables:

ƒ ƒ

a value to be compared to the name of the requested program the name of an HTML template that contains the message

This data set is subset by comparing the first variable with the program name. The sample uses simple matching logic (for example, it begins with using the =: operator). More complex patternmatching functions can be used as dictated by your application requirements. As soon as a match is found, CALL EXECUTE is used to invoke the externalHMTL macro on the specified entry. The sample INVSESS program is listed below. The data set is created in the WORK library for the purposes of this example. In a real application, the data set would likely be a saved SAS data set.

Chapter 10: How to Create and Use Sessions 181

data thisShouldBeStoredMetadata; length program message_template $83; input program $ / message_template $; datalines; SASPRESS.CHAPTER10.USESESSION.SOURCE n SASPRESS.TEMPLATE10.RESTARTCREATESESSION.SOURCE SASPRESS.CHAPTER10.REFRESHSESSION.SOURCE SASPRESS.TEMPLATE10.REFRESHFAILED.SOURCE SASPRESS.CHAPTER10 SASPRESS.TEMPLATE10.CHAPTER10EXPIREDSESSION.SOURCE SASPRESS.CHAPTER20 SASPRESS.TEMPLATE20.LOGON.SOURCE DEFAULT SASPRESS.TEMPLATE10.EXPIREDSESSION.SOURCE; data _null_; set thisShouldBeStoredMetadata; where program = 'DEFAULT' or o trim(program) =: "%upcase(&_userprogram)"; call execute('%externalHTML(type=CATALOG,source='||trim(message_template)||')'); stop; run;

n Based on the length of the values for program and the order of the data, the most specific match is always found first. o DEFAULT is included as the last row in the data set to ensure that a match is always found. The five templates provide a different message based on the program being run:

ƒ

For the example in Section 10.2, Create a Session, the generated message states what the session was and provides a link to restart that example (Figure 10.10).

ƒ

The second template is for the example in the next section and states that the request to refresh the session failed.

ƒ

For any other example in the Chapter10 catalog, the template used states that this was a session example and suggests that the user restart (see Figure 10.11).

ƒ

The fourth listed template is discussed in Section 15.7.3.4. In that example, the user can be automatically redirected to the point where the session was initially created.

ƒ

For all other programs, the template that is specified replicates the default message produced by the Application Server when the INVSESS option is not specified (the same output as shown in Figure 10.9).

182 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 10.10 Customized Session Expired Output Including a Link to Restart the Session

Figure 10.11 Customized Session Expired Output Including a Link to Restart the Session

This metadata approach, combined with the use of the externalHTML macro tool, offers great flexibility in customizing session expired messages. The messages generated for invalid sessions can be expanded and customized by adding a new HTML template along with the appropriate row in the metadata table.

10.6 Extending Sessions A session is automatically extended whenever it is reconnected to. It is not uncommon for a period of time to pass before the user clicks a link that exceeds the session time (e.g., the phone rings and the user is examining the output in detail). A desirable feature is the ability to display a pop-up window when the session is about to expire (just as many commercial banking Web sites do). Go to the sample environment and select Chapter 10. Then select Refreshing a Session to see an example where a pop-up window is presented to the user after a specified timeout value is reached. In this example, the user is asked after 60 seconds if he or she would like to refresh the session. See Figure 10.12. If the user clicks OK, a simple request is made using the session, which then causes it to be refreshed.

Chapter 10: How to Create and Use Sessions 183

Figure 10.12 Pop-Up Asking If User Wants to Refresh the Session

The example uses two common JavaScript functions and the externalHTML macro to provide this functionality. The first step in the example is to create a session and include in the generated output the JavaScript function calls that generate the pop-up window. Note: Understanding this example does require significant knowledge of JavaScript. However, the example can be used as-is. The following program demonstrates how to generate such a pop-up. It is the same program described in Section 10.2 with these exceptions:

ƒ ƒ

No macro variables are created or printed. The externalHTML macro is called to include the JavaScript code.

data _null_; rc = appsrv_session('create',120); run; data save.sessionInfo; Session = "&_sessionid"; Session_Created_At = datetime(); Session_Ends_At = datetime() + appsrvgetn('session timeout'); format Session_Ends_At Session_Created_At datetime.; Application_Server_Work_lib = pathname('APSWORK'); Save_Lib_Path = pathname('SAVE'); run; ods html file=_webout (title='Creating a Session' no_bottom_matter); proc print data=save.sessionInfo split = '_' noobs; title "Created Session Info, Current Date/Time: %sysfunc(datetime(),datetime.)"; run; ods html close; %externalHTML n (type=catalog, source=saspress.template10.refreshSession.source)

n The externalHTML macro adds additional HTML to the end of the page and includes the JavaScript code that produces the pop-up that asks the user if he or she wants to refresh the session. This technique can be used with any HTML-based report.

184 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

The refreshSession template below creates macro variables and then uses those values to customize the arguments in the JavaScript function calls. The setTimeout built-in JavaScript function is used to specify a period of time to wait before calling the defined refreshSession function. The refreshSession function uses the JavaScript built-in confirm window to ask users if they want to refresh the session, and if they respond yes, the built-in Open function is used to:

ƒ ƒ

produce a pop-up that connects to the session in order to refresh it specify that the refreshSession function should be called again after the specified timeout period

%let msg = Refresh Session &_sessionid?; n %let sessionTime = %sysfunc(appsrvgetn(session timeout)); %let refreshTime = %sysfunc(max(60000,1000*&sessionTime-60000)); <SCRIPT LANGUAGE="JavaScript"> function refreshSession() {if (confirm("&msg?")) {window.open("%superq(_thissession)%nrstr(&_debug)=&_debug" + o "%nrstr(&_program)=saspress.chapter10.refreshSession.source", "RefreshSession", "toolbar=no,menubar=no,width=400,height=200, resizable=yes,top=200"); setTimeout('refreshSession()',&refreshTime) } } setTimeout('refreshSession()',&refreshTime)

n Create macro variables for the values to use for the message text and the timeout period. The timeout period is set to be the longer of one minute or one minute less than the length of the session. The SAS session time is specified in seconds, while the value for the JavaScript setTimeout must be specified in milliseconds. o _thissession is used to create the URL that connects to the session. %superq is used so _thissession resolves, but without the ampersands (&) it contains causing an attempt to resolve macro variable references. The refreshSession program uses the externalHTML macro to run a program that displays a message that the refresh was successful. Note that this program is run only if the session is still active. Since the program contains only macro statements and then calls the externalHTML macro, it could have been packaged as a SAS Server Page, but then there would not have been a specific program to trigger the correct template in the INVSESS program (without augmenting the selection logic used there to use either a program name or a template name).

Chapter 10: How to Create and Use Sessions 185

Here is the program: %let %let %let %let

msg = Refresh Session &_sessionid?; n sessionTime = %sysfunc(appsrvgetn(session timeout)); now = %sysfunc(datetime()); refreshUntil = %sysfunc(sum(&now,&sessionTime),datetime.);

%externalHTML(type=catalog,source=saspress.template10.refreshSuccess.source)

n Create macro variables that are referenced in the template. One variable (msg) is the message that the session was successfully refreshed, and the other (refreshUntil) is a formatted datetime value corresponding to the new session expiration time. The refreshSuccess template is straightforward. See Figure 10.13 for the output produced when the user clicks the OK button (Figure 10.12) to refresh the session. Here is the refreshSuccess template: <TITLE>Session Refreshed Session, &_sessionID, successfully refreshed.

Will expire at &refreshUntil..

Figure 10.13 Session Refresh Successful

If the session has expired, the Application Server runs the program specified in the INVSESS parameter (as discussed in Section 10.5) instead of the requested program. The second observation in the metadata table shown in the example in Section 10.5 causes the template refreshFailed to be sent to the user’s browser whenever the refreshSession program is not run because the session has expired. See Figure 10.14.

186 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Here is the refreshFailed template: <TITLE>Session Refresh Failed Session, &_sessionID, could not be refreshed.

Please restart the application.

Figure 10.14 Session Refresh Failed

By combining the use of the following resources, it is possible to create a simple, straightforward and customizable framework for informing users before their sessions expire:

ƒ ƒ ƒ ƒ ƒ

scripting languages, as discussed in Chapter 1 the INVSESS option, as discussed in Section 10.5 the refreshSession program, as discussed in this section the externalHTML macro, as discussed in Section 7.5 HTML templates such as refreshSession, refreshSuccess, and refreshFailed

10.7 Session INIT and TERM Programs The INIT and TERM arguments also exist for sessions, just as they do for requests. The INIT program runs when a session is first created and the TERM program runs when the session is destroyed or expired. These arguments can provide key functionality in situations such as these:

ƒ ƒ

logging session start and end times to a data set committing incomplete data to a suspense file when a session expires

Such uses are typically application specific. In general, a program that explicitly creates a session can typically invoke any necessary INIT logic at the same time. Likewise, if a session is actively destroyed, using the appsrv_session(‘delete’) function, that program can invoke the TERM logic at the same time. And since the TERM logic is run as part of the Application Server clean-up process, the program specified in the TERM section must run without any user input or intervention, thus limiting its utility.

Chapter 10: How to Create and Use Sessions 187

As an example of what can be done with a session INIT program, consider that all the examples in this chapter that have provided information about the session have used the value of the sessionid variable in the message. The value for the sessionid variable is not meaningful to the user. Ideally, a more meaningful description should be provided. The SESSION INIT program can provide such a mechanism. To run an example that provides a session description, go to the sample environment and select Chapter 10. Then select Provide a Session Description (see Figure 10.15).

Figure 10.15 Using a Session Description

Providing this more meaningful message was accomplished by:

ƒ ƒ

ƒ

creating a data set to store information about the session. assigning a value to a macro variable, sessionDescription, that contains a text description of the session. Note: You must do this before creating the session (e.g., before executing the appsrv_session(‘create’) function). adding the following code to the SESSION INIT program: %global session Description; proc sql noprint; insert into sampdata.internalSessions(cntllev=record) n set server = "&_server", port = "&_port", sessionID = "&_sessionid", Description = symget('sessionDescription'), start = datetime() ; delete from sampdata.internalSessions(cntllev=record) o where datetime() gt start + 86400 or Description = ' '; quit;

n Insert a record into the data set for the session. The SYMGET function is used instead of a macro variable reference for sessionDescription because using SYMGET will cause a blank value to be inserted if the macro variable has not been defined.

188 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

o Since the description will typically be needed even after the session has expired (e.g., to produce the message seen in Figure 10.15), the record cannot be deleted by the session TERM program. Instead, the INIT program deletes records for sessions that are older than 24 hours (86400 seconds). It also deletes records that have no value for the description.

ƒ

adding the following code to the INVSESS program to enable the description to be used in place of the session ID: proc sql noprint; select Description into: _sessionID p from sampdata.internalSessions(cntllev=record) where server="&_server" and port="&_port" and sessionid = "&_sessionID"; quit; %let _sessionID= &_sessionID; /*trim trailing blanks*/

p If there is a row in the data set for this session, overwrite the value of session ID with the description. If there is no row, the original value of session ID is left unchanged. The output shown in Figure 10.15 was produced using a program that is a copy of the program shown in Section 10.2 that created a session. The only change to that program is that the macro variable sessionDescription is created and assigned a value before the session is created. The approach illustrated here describes a framework for how to provide users with more meaningful messages about sessions.

P a r t

4

Addressing Common Application Requirements Chapter 11

Tools and Techniques for Debugging 191

Chapter 12

Tips for Safeguarding Security 205

Chapter 13

Integrating Application Dispatcher Applications with Other Applications, Products, and Environments 225

Chapter 14

Maintaining an Applications Environment

239

Part 4 provides selected examples that show how the techniques and features of the Application Dispatcher presented in Parts 1 through 3 can be used to address approaches to common application requirements. It contains a number of short chapters that focus on how to use the ideas discussed earlier. Chapter 11 discusses the practice of testing Application Server programs. The facilities that are built-in to the Application Server are described from the context of how they should be used. The use and customization of standard testing techniques is presented. Finally, an approach to enable testing Application Server programs in a stand-alone SAS environment is also described. Chapter 12 discusses security, specifically facilities and techniques that can be used to ensure that only authorized users have access to programs and data.

190 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Chapter 13 describes how systems built with the Application Dispatcher can be integrated with external applications and products. Chapter 14 formalizes many of the techniques presented earlier as a set of Best Practices that can facilitate supporting multiple environments (e.g., Dev/Test/Prod) as well as minimizing maintenance requirements.

C h a p t e r

11

Tools and Techniques for Debugging 11.1 Introduction 191 11.2 Using the _debug Parameter 192 11.3 The PROC APPSRV LOG Statement 196 11.4 Conditionally Generating Debugging Output 197 11.5 Running Application Dispatcher Programs Using SAS Display Manager 200 11.5.1 Special Handling for SCL Programs 201 11.6 Dedicating an Application Server for Debugging 202

11.1 Introduction Debugging is often a complex and frustrating activity. Debugging SAS/IntrNet Application Dispatcher programs can be challenging for a SAS programmer who is accustomed to using a dedicated SAS session (either interactive or batch) for development. The challenge is due to the fact that the SAS programs are being executed by a SAS server that is by-and-large invisible to the programmer. Fortunately the Application Dispatcher provides a variety of the tools and techniques to facilitate debugging. These techniques allow the programmer to address both kinds of errors typically encountered in developing programs: the wrong output is produced or no output is produced.

192 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

11.2 Using the _debug Parameter The _debug parameter is one of the best and easiest tools to debug programs being run by the SAS/IntrNet Application Dispatcher. As discussed in Section 5.2.3, there are three values of particular note:

ƒ

If you specify a value of 1, then name/value pairs passed from the Application Broker to the Application Server are displayed in the user’s browser. The user is typically the programmer during debugging.

ƒ

If you specify a value of 16, the returned content is displayed in the user’s browser in hexadecimal format.

ƒ

If you specify a value of 128, the SAS log for the request is returned to the user’s browser at the end of the output.

Best Practice: The use of &_debug in generating links was discussed earlier as a Best Practice. The use of this practice is of significant value while debugging in that the value can be set once and then propagated to all later requests that result from links. This can make debugging much easier. If the value is not propagated, the only alternative is to edit the URL for each request.

The complete list of values for _debug is included in the SAS/IntrNet documentation. When you invoke the Application Broker with no name/value pairs as shown in Figure 11.1, the result is a link to the SAS/IntrNet documentation on the Web.

Figure 11.1 Application Broker Link to SAS/IntrNet Documentation

Figure 11.2 shows what the user would see when a program has an error. Using a value of 129 for _debug will allow you (the programmer) to see and fix the values passed to the program as well as to the SAS log.

Chapter 11: Tools and Techniques for Debugging 193

Figure 11.2 Output Produced When a Program Has an Error

The results of using a value of 129 for _debug can be seen in Figures 11.3 and 11.4.

Figure 11.3 SAS Log Output Produced by _debug=128 (Actual Value Used = 129)

194 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 11.4 List of Name/Value Pairs Produced by _debug=1 (Actual Value Used = 129)

Figure 11.3 shows two errors in the SAS log:

ƒ ƒ

The NOTOC option is generating an error for HTML output. The data set to be printed does not exist.

Default values for the type of output and the data set name are set using the setDefaultValue macro (discussed in Section 5.3.3). The fact that no values were provided for outputType and data can be seen in Figure 11.4. This debugging example used the most common value, 129, which includes both the name/value pairs and the SAS log. Quite often, this provides sufficient diagnostic output to determine the problem as it includes in a single place: the input to the program, the output from the program, and the SAS log that resulted from running the program. Even when the program itself produces no output (e.g., due to a syntax error, no data being selected due to an invalid WHERE clause, etc.), a value of 128 (or 129) for _debug produces the detail needed to diagnose the problem. Note: As discussed in Section 5.2.3, a value of 129 for _debug can also be specified as _debug=FIELDS,LOG. A value of 16 for _debug is useful in diagnosing problems encountered when the program generates alternative content types and specifically for issues related to HTTP headers. Consider the example from Section 8.3.4 that uses the Replay facility to return PDF or RTF (or both) content to the user’s browser. The example presented here was slightly modified so the links for the Replay facility include _debug=16. When the Printable (PDF) link was selected in Section 8.3.4, it was returned as an attachment, due to the attachment header.

Chapter 11: Tools and Techniques for Debugging 195

To run the PDF example with _debug=16, go to the sample environment and select Chapter 11, select RTF and PDF, and then select Printable PDF.

Figure 11.5 Hex Dump (_debug=16) of PDF Output

The human readable version is listed in the right-hand column where it is clear that the correct content-type header for a PDF file is generated, followed by the content-disposition header with an attachment to be named temp.pdf. That is then followed by the blank line and then by %PDF, which is the beginning of the PDF file. When you select the Editable (RTF) link, the output shown in Figure 11.6 is returned.

Figure 11.6 Hex Dump (_debug=16) of RTF Output

Microsoft Word should be used to view the generated content. Running the example to generate a GIF image (using the stand-alone graph program from Section 8.4) with a value of 16 for _debug produces the output shown in Figure 11.7. The figure shows that a content-type header for GIF files was generated. To run this example, go to the sample environment and select Chapter 11. Then select GIF Image.

196 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 11.7 Hex Dump (_debug=16) of GIF Output

In general, using a value of 16 for _debug can be a significant tool in diagnosing problems related to HTTP headers.

11.3 The PROC APPSRV LOG Statement The LOG statement of the APPSRV procedure specifies where the Application Server writes its log file. It also includes options that provide comparable output to what _debug=1 and 128 return to the user’s browser (and this output is included in the log regardless of the value of _debug). The DISPLAY option controls whether the SAS log for each request is written to the log file and contains output similar to _debug=128. The SYMBOLS option controls whether the name/value pairs (similar to _debug=1) are written to the log. Both have the following options:

ƒ ƒ ƒ

NONE – don’t write the output for any request. ERRORS – write them only for requests that completed with a SAS error message. ALL – always write them.

You can find the location of the log files by examining the appstart.sas file for the Application Server. The location changed after SAS 8 and is also dependent on the operating system. The location is specified in the ALLOCATE FILE statement that defines the fileref LOGFILE. The default value for these parameters is ERRORS. Thus for any request that contained a SAS error, the log includes the same output as could be obtained using a value of _debug= 129. The SAS log corresponding to the error shown in Figure 11.3 can also be seen in the log file as shown in Figure 11.8. Note that the log filename is specific to the day of the week and the port number. The parameters that define the name used for the log file can be specified in the ALLOCATE FILE statement that defines the LOGFILE fileref.

Chapter 11: Tools and Techniques for Debugging 197

Figure 11.8 Application Server Log File with DISPLAY=ERROR

Assuming that you have access to the log file (which on most operating systems can be viewed even while the Application Server is still running), the LOG statement can be an invaluable debugging tool as it contains the output typically needed to diagnose the problem for programs where a SAS error was generated. This is especially true for programs that produce non-HTML content where the use of a value of either 1 or 128 in _debug can corrupt the output or make it non-readable in the browser (as mentioned earlier in Section 5.2.3). The APPSRV LOG statement is also useful in cases where you need to look at an error that has been reported to you after the fact. If the program runs without errors, but the results are wrong, the DISPLAY and SYMBOLS options produce their output only if ALL was selected on the PROC APPSRV statement. This behavior cannot be controlled on a request-by-request basis. Since the ALL output can be voluminous the ALL option should be used with great care. Note: In Section 11.6, the use of a dedicated Application Server for testing will be discussed. This can facilitate the use of the ALL option.

11.4 Conditionally Generating Debugging Output A common technique during development and testing of a program is conditionally producing extra output (e.g., running the PRINT procedure on intermediate data sets) throughout the program. Such techniques can be implemented in Application Server programs by writing and using a simple macro, testPrint, which runs the PRINT procedure on a specified data set, but only if a flag (the macro variable debugFlag is used here) has been set. The following very simple macro illustrates this: %macro testPrint(data=_last_); %global debugFlag; n %if %length(&debugFlag) ne 0 %then %do; /* flag set - produce debugging output */ proc print data=&data; title "Debug Output: &data"; o run;

198 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

%end; /* flag set - produce debugging output */ %mend testPrint;

n The GLOBAL macro statement ensures that the parameter exists, in case it has not been set. o The output is produced only if the _debug parameter values have been set and will be returned to the user’s browser if it is within the ODS block for _WEBOUT. Macro calls such as %testPrint(data=work.intermediateResults) can be included throughout the program. The output is only produced if the macro variable used to specify debugging is set to a non-blank value. The macro calls are always in the program and the output is turned on only when needed. To run this example, go to the sample environment and select Chapter 11. Then select No Debugging Output (Figure 11.9) and Debugging Output--Explicit debugFlag Value (Figure 11.10). The only difference between the two links is that the latter one includes a non-blank value for debugFlag in the URL.

Figure 11.9 No Debugging Output

Chapter 11: Tools and Techniques for Debugging 199

Figure 11.10 Debugging Output—Explicit debugFlag Value

If you have downloaded the sample environment, you will find the program for this example in the Chapter11 catalog, in the testprint.source entry. The program includes the following macro call: %testPrint(data=sashelp.shoes(obs=2))

The testPrint macro conditionally generates the PROC PRINT output only when debugFlag is set to a non-blank value. The testPrint macro does not use, by default, _debug. This is true for a variety of reasons. For example, there may be occasions where such debugging output is appropriate and neither _debug=1 or 128 is desired. You may also want to set the value via some other technique (e.g., as a SET parameter in the Application Broker configuration file, or explicitly including it in a URL). If you want to ensure that debugFlag is set whenever _debug contains a value of 128, that can be easily accomplished by adding code like the following to the program specified for REQUEST INIT: data _null_; if &_debug = '1.......'b then call symput('debugFlag','Yes'); run;

Note: Bit constants are used to facilitate checking that the value contains 128 (i.e., bit 8, counting from the left, is set to ON). When this simple DATA step is run in the INIT program, it updates the value of debugFlag based on the value of _debug. The example below, which produces output similar to that shown in Figure 11.10, demonstrates the technique. Other logic using any of the information available to the INIT program (e.g., all the parameters passed to the Application Server by the Application Broker) can also be used to set or reset its value. Note that the program does not have an ELSE condition because it presumes that the existing value should be unchanged. Since the test Print macro has a %GLOBAL statement, if debugFlag has not been defined or set, it is created by the first execution of the testPrint macro and set to null.

200 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

To run this example, go to the sample environment and select Chapter 11. Then select Debugging Output--debugFlag Set using _DEBUG.

11.5 Running Application Dispatcher Programs Using SAS Display Manager Most SAS programmers are used to using an interactive SAS session for development and testing. An interactive SAS session provides a much richer environment for testing and debugging than the Application Server. For example:

ƒ

A program can be run in pieces with any created data sets examined by the Viewtable window.

ƒ ƒ

The data can be adjusted part-way through to test for other conditions. The debugging options of the DATA step (or SCL for SCL programs) can be used to step through the logic.

Note: If multiple steps write to _WEBOUT, the MOD option will be needed on the FILENAME statement for _WEBOUT during debugging so the output is appended instead of overwritten by each step. The MOD option is not allowed when the program is run by the Application Server because _WEBOUT uses the socket access method. The behavior of the MOD option is built in to the socket access method. Including the MOD option will produce a syntax error. With a few set up steps, it is possible to run programs designed for an Application Server environment in a stand-alone SAS session (either interactive or batch). Here are the steps:

ƒ

Ensure that a fileref for _WEBOUT is defined, e.g.: filename _webout ‘\debuggingOutput.html’;

ƒ

Assign values to all the macro variables for the request. This can be done using a series of %LET statements. Alternatively, a call to the %saveMvars macro (Section 10.3) can be added to the top of the program to be debugged, e.g.: %saveMvars(lib=sampdata,data=chapter11DebugData,saveFlag=Y,includeAutos=Y)

The macro variables can then be made available in an independent SAS session by invoking the %restoreMvars macro (Section 10.3), e.g.: %restoreMvars(lib=sampdata,data=chapter11DebugData)

ƒ

If sessions are involved, define a libref for SAVE. If a program for sessions is to be debugged, it can be run with a long timeout in order to allow you to start an independent SAS session that can define the SAVE libref and then use PROC COPY to save the contents of the SAVE library elsewhere for your testing.

Chapter 11: Tools and Techniques for Debugging 201

ƒ

Ensure that all the set-up options from the INIT program are in place (e.g. the SASAUTOS option, etc.). The easiest way to do this is to run that program using the SAS Display Manager.

ƒ

Then for any program except SCL entries, run the program from the program editor window.

Note: For compiled macros, include the macro source followed by a call to the macro. SCL programs can be run with the DISPLAY procedure. The data set sampdata.chapter11DebugData is available in the sample environment and was created by (temporarily) including the above %saveMvars macro call in the SAS Server Pages example of Section 7.6. If you have downloaded the sample environment, you are encouraged to try these actions:

ƒ ƒ ƒ ƒ ƒ

Start an interactive SAS session. Define librefs for SAMPDATA and SASPRESS. Define _webout. Run the %restoreMvars macro as listed above to load the macro variables. Copy saspress.chapter7.runTemplate_Proc_Print to the program editor and run it in pieces. The MLOGIC option can be used to see the setDefaultValue macro calls at the top of the program. The _debug parameter can also be added to the data _null_ step if desired.

Note: Since the %externalHTML macro writes to _webout without the MOD option, the ODS PROC PRINT output will be overwritten.

11.5.1 Special Handling for SCL Programs Running SCL programs in a SAS Display Manager session requires special handling if the programs use the SCL list to get the name/value pairs. If the SCL program is executed as a standalone program with PROC DISPLAY, there is no input SCL list and the program fails if it attempts to query the list for values. One way to handle this is to run the program with the SCL debugger turned on and step through the statements one at a time, skipping those that query the list. The values would need to be explicitly assigned in the debugger. Alternatively, a driver program can be written that creates an SCL list from a saved SAS data set and then calls the program. A sample program to do this is included in the sample environment (saspress.chapter11.runSCLStandAlone.scl): Note: The SCL code assumes that the name of the data set with the name/value pairs has been assigned to the macro variable listData. rc = rc; /* suppress compile time message */ init: list = makelist(); dsid = open("&listData"); nameVnum = varnum(dsid,'NAME'); valueVnum = varnum(dsid,'VALUE'); do while(fetch(dsid) = 0); n

202 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

name = getvarc(dsid,nameVnum); value = getvarc(dsid,valueVnum); if upcase(name) = '_PROGRAM' then program = value; rc = setnitemc(list,value,name); end; call display(program,list); o dsid = close(dsid); list = dellist(list); return;

n Loop through the data set and add the items to an SCL list. Assign the name of the program to an SCL variable so it can be used in the call display. o Run the program using the SCL variable created above. The program may need to be recompiled to turn the debug option on (or off). The data set sampdata.chapter11SCLDebugData is also included in the sample environment. It contains the name/value pairs that are input to the SCL Paging SCL Example (Section 7.4). You are encouraged to run this SCL program as a standalone program by including the following statements in the SAS program editor and submitting them (along with the other set-up steps described above). The program must be compiled with the DEBUG parameter. You can either recompile this entry after turning the SCL debugger on, or you can copy the SCL entry to another entry and compile it, with the SCL debugger turned on. %let listData = sampdata.chapter11SCLDebugData; proc display c = saspress.chapter11.runsclstandalone.scl; run;

Assuming that the same set-up steps (e.g., defining _WEBOUT, etc.) as described earlier have been done, this program can be run (in debug mode) to facilitate the debugging process. When SCL programs are run in debug mode, no SAS code is submitted. For this reason debug mode should be used only to diagnose problems in the SCL logic.

11.6 Dedicating an Application Server for Debugging Dedicating an Application Server for debugging can greatly facilitate testing and debugging Application Server programs. The dedicated server allows the environment to be customized in order to facilitate the testing process. The steps to do this are straightforward:

ƒ

Define an Application Server using the SAS/IntrNet Service Configuration Utility. For development purposes it may be desirable always to select a Socket service since Socket services offer some additional flexibility in testing.

ƒ

Define the testing Application Server to the Application Broker configuration file. If the same Application Broker directory is used for both the production and debugging Application Server, it may be desirable to adopt a convention in the service names to distinguish them (e.g., a suffix of _test). An alternative is to create another copy of the

Chapter 11: Tools and Techniques for Debugging 203

broker directory for a test version of the Application Broker. In this case, the same service name can be used. The Application Server defined in the configuration file can be running on the programmer’s local PC, even if the Application Broker is running on a centralized Web server.

ƒ

Set the DISPLAY and SYMBOLS options to ALL in the PROC APPSRV LOG statement.

ƒ

Assign debugging options in the INIT program. Such options might include these: … mprint (or mlogic or both) … a value that is assigned to debugFlag as discussed in Section 11.4

ƒ

Edit the Application Broker configuration file to set a default value for _debug of 128 (or some other value that includes 128, such as 129). This can be overridden by supplying a value in the URL via a link or a form.

ƒ

Use the Application Broker Set or ServiceSet directives to specify any other desired values for testing (e.g., debugFlag discussed above can be set in the Application Broker configuration file or in the Application Server INIT program).

ƒ

Optionally the STATISTICS option of PROC APPSRV can be used to populate a data set with key values from each request. If your programs have a common set of programspecific name/value pairs, those names can be included in the template statistics data set. That data set can then be used to test programs in a stand-alone SAS session as discussed in the previous section.

Note: These techniques assume that the Best Practice of using _URL, _SERVICE, _debug has been consistently followed in programs that generate links. If the values are hard-coded, programs run by clicking links or submitting forms are not submitted to the correct Application Server. If the debugging Application Server is running on a server where the programmer can run SAS interactively, a socket service can be run in an interactive SAS session by including in the program editor the appstart.sas file used to start the server before submitting the program. This requires that the default &sysparm reference in the PROC APPSRV statement be replaced by port=[Socket-Service-Port-Number]. If the Application Server is run this way, then for any program which uses the _debug option in a DATA step, the debugger window is activated in the Application Server SAS session. Unfortunately this does not work for SCL programs compiled with the debug option. Since using the debugger can be time consuming, quite often the Application Broker generates a timeout message, thus preventing the output from being visible in the browser. When you are doing this level of debugging, however, this action might not be a problem. Note that a longer timeout value can be defined in the Application Broker configuration file.

204 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

C h a p t e r

12

Tips for Safeguarding Security 12.1 Introduction 205 12.2 The Application Server Environment 206 12.2.1 Limiting Which Application Brokers Can Access an Application Server 206 12.2.2 Hiding Passwords 208 12.2.3 Best Practices for a Secure Application Server Environment 211 12.3 Controlling Access to Data and Reports 212 12.3.1 Customizing Menu Choices 219 12.3.2 Using AUTH=HOST 223

12.1 Introduction A number of facilities and techniques are available that can be used by the Application Server and the programs that are run by the Application Server to ensure that only authorized users have access to programs and data. This chapter covers two basic approaches to safeguarding security.

206 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

12.2 The Application Server Environment To ensure a secure environment for the Application Server, at a minimum you must take these two steps:

ƒ

enabling http authentication by the Web server (as discussed in Section 5.3.3) to ensure that users can be uniquely and unambiguously identified

ƒ

limiting access to debugging facilities

All the techniques presented in this chapter depend upon these two facilities. Enabling http authentication at the Web server validates the user by prompting for a user ID and a password. This facility ensures the identity of the user who is using operating system facilities on the Web server. Many organizations use http authentication for this reason. With http authentication, the entered user ID can be made available to any Application Server program (as discussed in Section 5.3.2) by having the Application Broker export the Web server environment variable REMOTE_USER. The default name is _RMTUSER. A great deal of information regarding the Best Practice: For production application servers, a DebugMask value of 34 provides the most protection. Application Dispatcher environment is This value allows values for _debug of 0 only (no available via the debugging facilities debugging output), 2 (Broker Version, Time, and the provided by _debug. Limiting access to this SAS Powered Logo), or 32 (the SAS Powered Logo information is critical to ensure that the only). All other values could enable users to access Application Dispatcher environment is information they should not have. In particular, values of secure. As mentioned in Section 5.2.3, the 1 and 4 should be disabled. Application Broker DebugMask or ServiceDebugMask directives should be used to limit what types of debugging output are available.

12.2.1 Limiting Which Application Brokers Can Access an Application Server One of the strengths of the Application Dispatcher is that any Application Broker can access any SAS Application Server as long as the TCP/IP host (name or number) and port number are known. This also means that it is possible to submit requests to an Application Server from any Web server, including a user’s local Web server. If a hostile or curious user were to do this he would be able to circumvent any security put in place through the use of _rmtuser or DebugMask. Such an Application Broker could then be used to connect to the Application Server with http authentication disabled. This action would allow the user to set any value he wanted for _rmtuser either in the URL or via a Set or ServiceSet directive in the local Application Broker configuration file. Likewise, DebugMask could be set to allow all debug values. In order to prevent such a security exposure, the Application Dispatcher environment should ensure that only the expected Application Broker can send requests to an Application Server. This exposure can be limited by restricting the Application Brokers that can make requests to an Application Server using the FROMADR argument of the REQUEST statement in PROC APPSRV. For example, if the IP address for the Web server where the Application Broker is running is 1.2.3.4, the following REQUEST statement ensures that only Application Broker requests from that Web server are allowed: proc appsrv . . . . . .; request fromadr=("1.2.3.4"); run;

Chapter 12: Tips for Safeguarding Security 207

A request from any other IP fails and sends a message back to the user as shown in Figure 12.1. Warning: Unfortunately, it is relatively easy to get the server IP address and port number by examining the HMTL from any request that uses sessions, including lightweight sessions where ODS generated a page with embedded text and graphics. While there are techniques that can often prevent a user from viewing the HTML source, they are typically not robust and are not covered here.

Figure 12.1 IP for the Application Broker Not Authorized

The FROMADR argument does allow multiple Application Brokers (from a single Web server) to submit requests to an Application Server. If additional security is needed to limit this access, that can be done by using the Set or ServiceSet directives in the Application Broker configuration file to provide a variable name and value that can be checked in the INIT program of the Application Server. For example, suppose you include the following in the Application Broker configuration file: ServiceSet myBroker "a secret value"

You could then add the following logic in the INIT program: options nosource; data _null_; if “&myBroker” ne "a secret value" then do; /* Generate HTML to say this is not an authorized broker using, for example, the externalHMTL macro */ call execute('ENDSAS;’); end; run;

This combination of actions ensures that only requests from the Application Broker with this special name/value pair defined in the configuration file are allowed.

Best Practice: The NOSOURCE option is included so that the password value is not visible. This is primarily a concern if DebugMask has not been set to limit access to the SAS log (e.g., _debug values that include 128). Section 12.2.2 discusses additional techniques to secure password values.

Note: See the SAS/IntrNet documentation for additional tips and techniques that protect the broker configuration file.

208 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

In order for this technique to provide the desired level of protection, take the following steps:

ƒ

DebugMask must be set to disable a value of 1 (which causes the Application Broker to echo all the name/value pairs). Note that myBroker is not visible in the URL or in the Web server log files.

ƒ

All the Application Server programs need to be reviewed to ensure that none of them include output that displays the name/value pairs passed to the Application Server (e.g., they don't enable SASHELP.VMACRO to be printed by, for example, the data set paging example; that if a debug value of 128 is allowed, that the programs do not include a %put _all_, etc.).

ƒ

The Application Broker configuration file must be secured so that unauthorized users are not allowed to read its contents.

12.2.2 Hiding Passwords Securing the values of passwords is always a concern. In the example provided in the previous section the program contained the password as open text. Additional protection can be realized by packaging that functionality as an SCL program. An SCL program (e.g., checkpw.scl) can be compiled and then a nosource copy of it can be created for use by the Application Server: init: if symget('MYBROKER') ne 'a secret value' then n do; /* not the correct broker */ submit terminate; endsas; endsubmit; end; /* not the correct broker */ return;

n The value for myBroker is not retrieved from the SCL list since this program is not executed directly by the Application Server. Thus it has no access to the list. The SYMGET function is used to get the value of the macro variable. This program can be run in the INIT program as follows: proc display c = libref.catalog-name.checkpw.scl; run;

This program terminates any request that does not have the value for MYBROKER set in the Application Broker configuration file. However, it does not provide any message or information to that effect. In addition, the program still contains the password as a hard-coded string. Both of these deficiencies can be addressed using techniques presented in Section 6.3. References to macro variables as SCL code resolve at compile time. Thus, replacing the IF statement with the following code eliminates the password value from the SCL source code: if symget('MYBROKER') ne “&myBrokerPW” then

The compiled code still contains the correct value to be compared to. The second deficiency can be addressed by including a call to the externalHTML macro (Section 7.5.1) to display a customizable message to the user. Note how the Application Broker fields _ADMIN and _ADMAIL (see Section 5.3.1) are used in this example to provide contact information.

Chapter 12: Tips for Safeguarding Security 209

<TITLE>Request Submitted from an Invalid Broker This request submitted from an invalid Application Broker Contact &_ADMIN if you believe this error to be incorrect.

Note: Instead of using an HTML template, the SCL program could redirect the request using the location http header (see Section 8.2.1.1) to redirect the user to define a static HTML page. Here is the complete SCL program that checks the password value and terminates the request if the password check fails: init: if symget('MYBROKER') ne "&myBrokerPW" then n do; /* not the correct broker */ submit terminate; %externalHTML(type=catalog, source=saspress.template12.invalidBroker.source ) endsas; endsubmit; end; /* not the correct broker */ return;

n The APPSRV_UNSAFE function can be used instead of the SYMGET function if protected special characters are included in the password value. To run this example, go to the sample environment and select Chapter 12. Then select Password not set, e.g. an Invalid Application Broker (Figure 12.2) or Valid Password (Figure 12.3). The first link simulates the results obtained when an invalid Application Broker is used (i.e., the check fails); the second link simulates the results when a valid Application Broker is used. The following sample program demonstrates this functionality. When a valid password is provided, the output shown in Figure 12.3 is produced. proc display c = &_pgmlib..&_pgmcat..checkpw.scl; run; %externalHTML(type=catalog, n source=saspress.template12.validBroker.source )

n The EXTERNALHTML macro will display only the validBroker.source template if the password is valid. If the password is not valid, the SCL program will display the invalidBroker.source template.

210 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Note: The sample environment does not include the password check in the INIT program as that would have caused all the samples to fail because of an invalid password. The value for MYBROKER is passed in via the URL instead of via specification in the Application Broker configuration file. If you decide to use this technique, the SCL program should be called in the INIT program and MYBROKER should be set in the Application Broker config file.

Figure 12.2 Application Broker Password Not Valid

Figure 12.3 Valid Application Broker Password

This example demonstrates that the functionality to protect passwords can be used in multiple ways such as these:

ƒ ƒ

in the INIT program to check that the request was submitted from the expected broker in any application (by including the appropriate PROC DISPLAY call) that needs to check passwords

Best Practice: Choose a password value that is hard to guess, including mixed case and special characters. The name of the password field can also be any valid SAS name.

Chapter 12: Tips for Safeguarding Security 211

12.2.3 Best Practices for a Secure Application Server Environment There are a number of additional best practices that can maximize the security of the Application Server environment:

ƒ

In order to protect any program code from being visible, options such as NOMPRINT, NOMLOGIC, NOSOURCE, and NOSOURCE2 should be included at the top of the program specified in REQUEST INIT. The use of these options prevents any of the SAS source code from being included in the SAS log. They can be used in combination with the DebugMask directive to limit access to the SAS log.

ƒ

Use compiled macro code or SCL to minimize the likelihood of the source code being viewable by a user.

ƒ

Use the ADMINLIBS statement to specify program libraries that can be restricted to Administrator access. The _ADMINPW option should also be specified in the PROC APPSRV statement.

ƒ

Use the VERIFY option of the SESSIONS statement to ensure that only the original user can reconnect to a session. The VERIFY option is a space-delimited list of variable names that the Application Server can check when reconnecting to session. It checks that the names have the same value as the original request that created the session. Fields that should be considered for inclusion in the list are _RMTUSER and _RMTADDR (the TCP/IP address where the user’s browser is running) or _RMTHOST (the DNS name corresponding to _RMTADDR). The use of VERIFY makes it difficult for a user to acquire another user’s URL and access that person’s session information.

ƒ

Store data and programs in separate SAS libraries and, if the application does not require Write access, use the operating system to make the libraries Read-only. Alternatively, use the READONLY option.

ƒ

The Xplore sample application shipped with SAS/IntrNet allows a user to browse data in any library defined to an Application Server. If such access exposes security issues, the Xplore application can be disabled by removing (or commenting out) the ALLOCATE LIBRARY statement for the SAMPLIB libref (or simply by removing it from the PROGLIBS statement). Alternatively, the techniques described in the next section can be used to ensure that users have access only to the data or reports that they are authorized to see. Note: The SASHELP library is, by default, excluded from the list of libraries displayed by Xplore. SASHELP should not be displayed as this enables a user to browse data sets that contain information that could expose security risks (e.g., pathnames for libraries).

ƒ

If SAS programs are stored in SAS catalog entries, do not specify just the libref in the PROGLIBS statement. The catalog names should be specified in the PROGLIBS statements. That is, do not enable any entry in an entire library to be specified as the program to run (e.g., the value of _PROGRAM). Specifying both the library and the catalog allows other catalogs to contain code or (HTML templates) without allowing them to be run or viewed directly by a user. The appstart.sas file provided with the sample environment specifies the allowed catalog names in the PROGLIBS statement.

212 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

ƒ

Specify an administrative password using the ADMINPW option when starting the Application Server. This prevents users from running administrative programs such as STOP (e.g., a Denial of Service attack) without supplying the password.

ƒ

Limit access to the Application Broker configuration file so that only authorized staff can update (or read) it. Protecting this file increases the likelihood that the security put in place through the use of DebugMask and _RMTUSER is effective.

ƒ

Since the Application Broker configuration file is stored in the same directory as the Application Broker executable, some Web servers allow it to be downloaded just like an HTML file. This possibility can be tested by trying to access it via a URL (e.g., http://yourserver/scripts/broker.cfg). If this URL allows the Application Broker configuration file to be downloaded, the Web server configuration should be modified to prevent this. For example, in IIS (Internet Information Service), you can enable Execute access but turn off Read access (for the scripts or for the cgi-bin virtual directory).

12.3 Controlling Access to Data and Reports There are a number of approaches that can be used to ensure that users are allowed access only to certain data or reports. Assuming the measures described previously have been implemented, the use of _RMTUSER can ensure that users see only the data and reports which they are authorized to see using a simple metadata approach. The metadata defines rules for which reports any user is allowed to access or run. A sample of one such metadata structure is included in the examples for this chapter. To see this metadata, go to the sample environment and select Chapter 12. Then select Sample User Access Data. Note: The sample environment does not use _RMTUSER because that would require you to define such users in your environment. Thus, these examples use a field (user ID) whose value is passed in as a name/value pair. Before you use the provided samples, change the examples to use the value of _RMTUSER.

ƒ

The first table (see Figure 12.4) maps users to groups of users who have common privileges. This eliminates the need to define privileges for each user; the privileges need only to be defined for each group. In this example, three users are defined with each user included in one or more groups.

Chapter 12: Tips for Safeguarding Security 213

Figure 12.4 Data Set That Defines Groups for Each User

ƒ

The second table (see Figure 12.5) defines the data libraries each group is allowed to access. Note that the paths are set assuming a Windows installation. It is also assumed that the paths enable different users to have access to different components of the SASHELP library (e.g., superusers have access to the views that correspond to dictionary tables). The use of this table is conceptually the same as the idea presented in Section 9.3.1 where the available librefs were defined in the INIT program. The key difference here is that _rmtuser is used to determine which libraries to assign.

Figure 12.5 Data Libraries to Define Based on Group

214 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

ƒ

The third table (see Figure 12.6) defines the programs (and thus, what reports) users in each group are allowed to run. The table includes a prefix value to be compared to the value of _program. If the prefix value matches the value of _PROGRAM (i.e., the SAS =: operator), then users in the group are allowed to run that program. This sample data imposes the following restrictions: …

Browsers are allowed to run only the programs in the Chapter12 catalog whose names begin with RPTS.

…

Administrators are allowed to run any program in the Chapter12 catalog.

…

Superusers are allowed to run any program in the SASPRESS library that is in a catalog whose name begins with CHAP (subject, of course, to it being defined in a PROGLIBS statement).

Figure 12.6 Allowed Program Mask Based on Group

A simple, but effective, security scheme can be implemented by combining the use of a metadata structure similar to the above with the technique presented in Section 9.3.4 to terminate a request by an unauthorized user. The following sample macro, defineAccess, implements this scheme of defining what data libraries each user is allowed to access. It also generates a message (to the user’s browser) if the user is not authorized to access any data libraries. Note: You can adapt and customize the following sample macro as needed to use other metadata data sets or structures as well as different templates. %macro defineAccess (users = sampdata.chapter12Users, datalibs = sampdata.chapter12Libraries, programs = sampdata.chapter12Programs, notAuthorizedTemplate = saspress.template12.notAuthorized.source ); %local groups authorized; %let _rmtuser = &user;

n

Chapter 12: Tips for Safeguarding Security 215

proc sql noprint; /* determine the groups for this user */ select distinct(quote(upcase(trim(group)))) into: groups separated by ' ' Y from sampdata.chapter12users where upcase(userid) = "%upcase(&_rmtuser)"; quit; data _null_; /* assign the libname for the authorized library */ set &datalibs; where upcase(group) in (&groups); Z rc = libname(libname,path); run; %let authorized = 0; data _null_; /* check the prefix on the program name to see if user is authorized */ set &programs; where upcase(group) in (&groups) and q "%upcase(&_program)" =: upcase(trim(program)); /* if at least one row passed user is authorized */ call symput('AUTHORIZED','1'); stop; run; %if not &authorized %then r %do; /* terminate the request */ %externalHTML(type=catalog, source=¬AuthorizedTemplate ) endsas; %end; /* terminate the request */ %mend defineAccess;

n For purposes of demonstration, _RMTUSER is assigned from a value defined in the calling demo HTML page. In a real application, _RMTUSER itself would be compared with the metadata. You should remove the %LET statement to use the http-authenticated value of _rmtuser. Y Create a macro variable which contains a list of the quoted values for the groups this user belongs to. Z Assign all the librefs for data sets that the groups this user belongs to are allowed to access. q Check to see if any of the groups the user belongs to are allowed to access this program. The macro variable is reset if the user belongs to at least one group with access. r If the user is not authorized, return a message to that effect using the externalHTML macro (Section 7.5.1) and then terminate the request using an ENDSAS statement as discussed in Section 9.3.4. To run the examples demonstrating this, go to the sample environment and select Chapter 12. Then select one or more of the choices under Limiting Access to Reports. The results can be seen in Figures 12.7 through 12.15.

216 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 12.7 Reader1 Allowed to Run Programs in Chapter12 Catalog Whose Names Begin with RPTS Using COREDATA

Figure 12.8 Reader2 Allowed to Run Programs in Chapter12 Catalog Whose Names Begin with RPTS Using COREDATA and WEBDATA

Figure 12.9 Author Allowed to Run Programs in Chapter12 Catalog Whose Names Begin with PTS Using COREDATA, VIEWS, and WEBDATA

Chapter 12: Tips for Safeguarding Security 217

Figure 12.10 Reader1 Not Allowed to Run Other Programs in Chapter12 Catalog

Figure 12.11 Reader2 Allowed to Run Other Pprograms in Chapter12 Catalog Using COREDATA and WEBDATA

Figure 12.12 Author Allowed to Run Other Programs in Chapter12 Catalog Using COREDATA, VIEWS, and WEBDATA

218 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 12.13 Reader1 Not Allowed to Run Programs in Other Catalogs Whose Names Begin with CHAP

Figure 12.14 Reader2 Not Allowed to Run Programs in Other Catalogs Whose Names Begin with CHAP

Figure 12.15 Author Allowed to Run Programs in Other Catalogs Whose Names Begin with CHAP Using COREDATA, VIEWS, and WEBDATA

Chapter 12: Tips for Safeguarding Security 219

The same SAS code (with the exception of the FOOTNOTE statement) is used in each of the three programs. Note that the code displays a list of the librefs defined in the metadata shown above that each user is authorized to access. You can compare the metadata with the results to validate that the %defineAccess macro limits both a user’s access to certain programs as well as to certain data libraries. Note that in the sample environment, the defineAccess macro is invoked in the individual programs instead of the INIT program. If the %defineAccess macro was included in the INIT program for the sample environment, none of them would have been runnable without the dummy user field being provided with a value of SuperUser. In an application environment it is usually best to run defineAccess in the INIT program. However, if only certain sets of programs need to be restricted, defineAccess can be used in just those programs, just as it is called in the sample environment. The metadata approach described above can easily be extended to provide additional security options, e.g.,

ƒ ƒ

limiting access to specific data sets

ƒ

menu options

applying WHERE clauses to data sets based on who the user is

Best Practice: Consider the use of data set passwords to provide security for the metadata tables themselves.

Adding metadata tables or modifying the tables used in the example above should enable a variety of security schemes to be implemented in an Application Dispatcher environment.

12.3.1 Customizing Menu Choices A common application requirement is to limit menu choices based on who the user is. You can do that using techniques similar to those described in Section 12.3. This technique is also commonly used for security (e.g., showing users only the options they are authorized to use). Note: Limiting menu choices, while commonly used for security reasons, is not a robust security implementation. If a user received a link (e.g., via e-mail) to a report program, she would still be able to access it. Thus, limiting menu choices should be combined with the techniques discussed in Section 12.3 (assuming the choices were implemented using _RMTUSER). Generating user-specific menus can be easily done using a metadata approach. Such a data set should contain the appropriate menu choices for each group (as defined in Section 12.3) of users, along with (at a minimum) the following information:

ƒ ƒ

the group

ƒ

the label or description for the menu item

the information needed to generate the link (e.g., the name of the program to run along with any name/value pairs needed by the program)

The following program demonstrates how to implement a simple metadata-driven menu system. The SAS Server Pages program that enabled a user to select a library, a data set, and the variables described in Section 7.6, is the example program used for this example. Depending on the group, the user is allowed to do the following things:

ƒ

Select variables and view the Menu Choices data set (if Group = Browser). See Figure 12.16.

ƒ

Select any data set and then its variables from the SAMPDATA library (if Group = Admin). See Figure 12.17.

ƒ

Select any library, any data set and then its variables (if Group = SuperUser). See Figure 12.18.

220 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

To run this example, go to the sample environment and select Chapter 12. Then select one or more of the choices for Customizing Menu Choices.

Figure 12.16 Generated Menu Choices for the Browser Group

Figure 12.17 Generated Menu Choices for the Admin Group

Chapter 12: Tips for Safeguarding Security 221

Figure 12.18 Generated Menu Choices for the SuperUser Group

Figure 12.19 No Menu Choices Generated for an Unknown User

Figure 12.19 shows the results for a user not authorized for any of the menu items defined in the metadata. %setDefaultValue(user,Not Defined)

n

%externalHTML (type=catalog, source=saspress.template12.menuHeader.source ) %let _rmtuser = &user;

p

%let groups = "-NONE-"; proc sql noprint; /* determine the groups for this user */ q select distinct(quote(upcase(trim(group)))) into: groups separated by ' '

o

222 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

from sampdata.chapter12users where upcase(userid) = "%upcase(&_rmtuser)"; quit; %let trailerTemplate = saspress.template12.menuTrailer.source; r data _null_; file _webout; if _n_ = 1 and lr then call symput('trailerTemplate', s 'saspress.template12.nochoices.source'); set sampdata.chapter12MenuChoices end=lr; where upcase(group) in (&groups); put '

This hsql file allows the user to select which library contains the data to be paged through. After clicking Get List of Data Sets, the user is given a choice of data sets in the selected library. {query server="localhost:5011"} {sql} select _url, _service, saspressRoot from sampdata.htmSQLParameters {/sql} {/query}

o

Select the Library: {query server="localhost:5011"} {sql} q select distinct libname from dictionary.tables {/sql} <select name="libname"> {eachrow} {&libname} r

Z

232 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

{/eachrow} {/query}

n This file is very similar to the liblist template discussed in Section 7.6.2. Instead of macros to generate the data-driven content, htmSQL directives are used. o The hsql statements to create name/value pairs for the parameters are included in the file. They are then available as {&name} references in the rest of the hsql file. Z The htmSQL automatic variable sys.url is used for the name of the htmSQL executable. saspressRoot (from the metadata table) is used to define the directory path for the hsql files. q Get the list of available libraries. r Generate a select tag that passes the selected value to the next hsql file (that generates the list of data sets in the library). The results of running the liblist.hsql file can be seen in Figure 13.3.

Figure 13.3 List of Libraries Produced by htmSQL

When you click Get List of Data Sets, the memlist.hsql file is then processed: <TITLE>htmSQL - Generate a list of Libraries n

This hsql file allows the user to select the data set from a previously selected library. When the user clicks Select Variables, the Application Dispatcher is invoked to enable the user to select the variables to display, along with the number of observations to display at a time.

Chapter 13: Integrating Application Dispatcher Applications 233

{query server="localhost:5011"} {sql} select _url, _service, saspressRoot from sampdata.htmSQLParameters {/sql} {/query}

o

p Select the Data Set from {&libname}: {query server="localhost:5011"} {sql} select distinct memname r from dictionary.tables where libname = "{&libname}" {/sql} <select name="data"> {eachrow} ] {&memname} {/eachrow} {/query}

q

n This hsql file is very similar to the memlist template discussed in Section 7.6.4 The program uses htmSQL directives instead of macros to generate the data-driven content. o The hsql statements to create name/value pairs for the parameters are included in the file. They are then available as {&name} references in the rest of the hsql file. p {&_url} and {&_service} are used to provide the location of the Application Broker and which set of Application Servers the request should be sent to. q The {&libname} r eferences resolve since libname was one of the name/value pairs from the form submitted by liblist.hsql. r Get the list of available data sets. ] Generate a select tag that passes the selected value to the Application Dispatcher. The results of processing the memlist.hsql file can be seen in Figure 13.4.

234 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 13.4 List of Data Sets in Selected Library Produced by htmSQL

Click Select Variables to invoke the same SAS Server Page macro and template as seen in Figures 7.11 and then 7.12. Those figures are included here as Figures 13.5 and 13.6.

Figure 13.5 htmSQL Invoking the Application Dispatcher (sasServerPage Macro)

Chapter 13: Integrating Application Dispatcher Applications 235

Figure 13.6 PROC PRINT Output

13.3 Single Sign-On Environments Many organizations have (or will) implement a single sign-on environment where the user enters a user ID and a password as soon as she connects to the network (or the intranet). In such environments, in-house applications (e.g., like those developed with the Application Dispatcher) are not supposed to have any logon function; instead they need to use the ID from the user’s initial logon. Making applications developed with Application Dispatcher compliant with such environments often involves one or more of the following requirements:

ƒ ƒ

using the single sign-on ID to uniquely identify the user to the application

ƒ

using the single sign-on ID, instead of another ID, in any metadata tables created by the application

using any metadata from the single sign-on product in order to define the user’s privileges

Meeting each of these requirements can be straightforward with an Application Dispatcher application:

ƒ

When the user connects to the intranet (needed before he can connect to any Web-based application), the user ID is validated by the single sign-on product. Such products typically have an environment variable that the Application Broker can access. The variable may be Remote User (which is exported as _rmtuser) or some other applicationspecific environment variable (e.g., for RSA ClearTrust, the environment variable is

236 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

HTTP_CT_REMOTE_USER) which can then be exported (using the Application Broker Export directive) and used by the Application Dispatcher application.

ƒ

If necessary, the extensive data access facilities of SAS can be used to query the appropriate metadata tables (e.g., in an external data base, XML, LDAP, etc.)

ƒ

Export the ID as _rmtuser and use it. Alternatively, as discussed in Section 12.2, export the value for the single sign-on user ID to some other name and use it instead of _rmtuser.

13.4 External Session Facilities In Chapter 10 the use of sessions created and maintained by the Application Server was discussed. There may be occasions where an Application Dispatcher application is to be integrated with an externally maintained session environment. This section describes an example of how the Application Dispatcher might be integrated with a session environment maintained on the Web server via a JSP (or ASP) application. The typical requirements for such integrations are these:

ƒ

The user signs-in to the application via a JSP page that validates the user (e.g., they have an active session and they are allowed to access the requested report/URL).

ƒ

A JSP (or ASP) object exists that examines each request (e.g., the URL including all the name/value pairs) before allowing the user to access the URL.

This requirement can be addressed by ensuring that any Application Dispatcher request, including links generated by an Application Dispatcher program, are funneled through the relevant JSP object and are processed by the JSP object before invoking the Application Broker. Assuming that the Best Practice of using &_url (Section 5.3.1) has been used when generating links or forms, routing requests through such a JSP object is straightforward. For example, assuming the path to the JSP page that does the validation is /path/validate.jsp, the Application Broker SelfURL directive can be used to redefine the value for _url, e.g., SelfURL “/path/validate.jsp”

Note: If _url cannot be globally redefined (i.e., other programs run by the Application Server use the default value), another field can be defined in the Application Broker using the Set directive or using a %LET statement in the Application Server INIT program. Alternatively, a ServiceSet directive can be used if the change applies to all requests for a specific service. This results in multiple values (see Section 5.2.4.1) for a _url with the first being the value from the ServiceSet directive and the second being the original value of _url. This causes any HTML forms or links that are generated by Application Dispatcher to use /path/validate.jsp as the location of the Application Broker. Any name/value pairs defined in the form or the link are defined just as they would be if the form or link directly invoked the Application Broker. 1

A sample /path/validate.jsp page that you can modify to meet your needs follows. The sample does not include an actual authentication mechanism since that is specific to the external application. Note: The following example uses JSP. You could do a similar implementation using ASP if desired.

1

The author wishes to thank Scott Wood of Zencos Corporation for contributing the sample.

Chapter 13: Integrating Application Dispatcher Applications 237



n Check to determine if the user has access and what his access level is. o A null value for the user object means there is no active session; a zero value for getAccessLevel() means the user does not have access; any other value is the user’s access level. p If the users are authorized for the request, they are redirected to a URL that invokes the Application Broker along with any name/value pairs from the original request, augmented by a name/value pair for getAccessLevel(). q Otherwise, they are redirected to the appropriate JSP or HTML page (depending on the reason for the failure).

238 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

C h a p t e r

14

Maintaining an Applications Environment 14.1 Introduction 239 14.2 Supporting Development, Test, and Production Environments and Applications 239 14.2.1 Using a Developer’s Workstation 240 14.2.2 Distinct Services 240 14.2.3 Distinct Brokers 241 14.2.4 Customized INIT Program 242 14.3 Metadata Approaches to Minimize Code Changes 244 14.3.1 The getTextString Macro 249

14.1 Introduction An important component of any application is the environment for its development, testing, and maintenance. This chapter presents a number of Best Practices for Application Dispatcher applications, including supporting multiple applications.

14.2 Supporting Development, Test, and Production Environments and Applications Ideally, separate physical servers are available to keep development and production (and optionally, test) environments completely independent from one another. These servers include

240

Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

both Web servers and servers to host the SAS/IntrNet Application Server. While this type of separation may be desirable, it is not required, and you can choose from a number of techniques that can be employed regardless of how many physical servers are available. The effectiveness of these techniques depends upon all programs using _url, _service, etc., instead of hard-coding these values as was discussed as a Best Practice in Section 11.6.

14.2.1 Using a Developer’s Workstation Using a developer’s workstation (i.e., a PC) to host both the development Application Server and the Web Server is one strategy to consider for applications that are supported by a single developer. If the developer’s workstation is a PC, the workstation may not require an additional license since SAS may allow SAS/IntrNet to be installed on a PC for development purposes when SAS/IntrNet is licensed on a server. Note: Using a developer’s workstation does not preclude other users from accessing the development environment. Such users can access the developer’s Web Server via the corporate intranet. Alternatively, since the Application Broker configuration file can point to any Application Server via TCP/IP (see Section 2.2), the broker configuration file on a centralized Web Server could include a service that points to the developer’s Application Server.

14.2.2 Distinct Services Separate services should be defined for each environment (e.g., development, test, and production. Using the techniques discussed in Section 9.3.1, the Application Server or servers for a service can support multiple applications Best Practice: Use an acronym for the application (or set of while keeping the data independent (e.g., applications) combined with the environment for the by defining the data libraries in the service name: e.g., appname_dev, appname_test, program specified in the INIT parameter appname_prod. of the SESSION statement instead of in the ALLOCATE and DATALIBS statements in the PROC APPSRV statement). Deciding whether a service should support a single or multiple applications can depend on a number of criteria. The decision as to which option to choose should be made on a case-by-case basis. Consider the following criteria when making that determination:

ƒ

High-volume critical applications should likely have a dedicated service, and thus a pool of Application Servers to support them.

ƒ

Applications that have different periods of high demand (e.g., a timesheet application which is expected to have higher demand at the end of the day or week or a reporting application that is expected to have higher demand first thing in the morning) are good candidates to support with a single service (i.e., a single pool of Application Servers). For example, if the two applications each need a maximum of four Application Servers (determined using the Queuing Model presented in Section 2.3.4), it may be possible to support both with four or five Application Servers instead of four Application Servers each.

ƒ

Applications with differing levels of security requirements should probably not be supported via a single service. For example, consider an application where the primary security concern is what data is available. Such applications can be candidates to share a single service (assuming the techniques presented in Section 9.3.1 are used to define the available data libraries).

Caution: If the Load Manager is used, separate services should not point to the same server and port (e.g., for socket services) as the Load Manager associates a server/port combination with a single service definition.

Chapter 14: Maintaining an Applications Environment 241

The Application Broker directives DebugMask or ServiceDebugMask should be used to limit what values for _debug are allowed in each environment. Here are some details:

ƒ

For the production service, a DebugMask value of 34 that allows only the following values for _Debug: 0 (no debugging output), 2 (Broker Version, Time, and the SAS Powered Logo), or 32 (only the SAS Powered Logo), should be considered.

ƒ

For the test service, values of 1 (echo the name/value pairs passed from the Application Broker to the Application Server) and 128 (show the SAS log) may be appropriate. Allowing 1 and 128 in addition to 0, 2, and 32 would imply a DebugMask value of 163.

ƒ

For the development service, all values should be enabled.

As discussed in Sections 11.2 and 11.6, it may also be desirable to use the Debug or ServiceDebug directive to set the default value for _debug specific to the environment, e.g.,

ƒ ƒ ƒ

0 (or 2 or 32) for production 1 (or 3 or 33) for test 129 (or 131 or 161) for development

These default values can be overridden by providing a value for _debug in the URL subject to the restrictions imposed by the DebugMask or ServiceDebugMask values.

14.2.3 Distinct Brokers Separate Application Brokers (and their associated configuration files) can be used for each of the development, test, and production environments. Likewise, separate Application Brokers can be used for each distinct application (or set of applications). Separate versions of the Application Broker can be supported in several ways. One strategy is to copy the Application Broker executable and configuration file to separate cgi-bin (or script) directories on the Web Server. Alternatively, multiple copies can be created in the same directory by copying them to files under new names in the same directory. For example, on PC platforms:

ƒ

Use broker.exe and broker.cfg for production, including only the definition of the production service.

ƒ

Copy broker.exe to broker_test.exe and create its associated file, broker_test.cfg, defining only the test service.

ƒ

Copy broker.exe to broker_dev.exe and create its associated file, broker_dev.cfg, defining only the development service.

Caution: Multiple brokers that share a common Load Manager should not define services with the same names. The Load Manager is not able to distinguish between them. Note: As discussed in Section 3.5, the Application Broker looks for a CFG file in the same directory as the Application Broker. The CFG filename is the same as that of the Application Broker (with the exception of the .cfg extension). These separate Application Brokers (see Figure 14.1), whether they are in the different directories or the same directory with different names, can be restricted to authorized users of each environment by enabling http authentication (on the Web Server) and using the operating system security on the Web Server to limit access to the test and development Application Brokers to only testers and developers. For example, under Windows, right-click on the Application Broker executable in Windows Explorer, select Properties, and then select the Security tab. Then specify which users and groups should be able to access the Application Broker.

242

Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 14.1 Separate Application Brokers for Development, Test, and Production

14.2.4 Customized INIT Program Chapter 9 discussed the use of the INIT program as a Best Practice to perform a range of set-up activities such as defining the data libraries to be made available to programs and checking access. However, an Application Server can have only one INIT program, which is defined in the PROC APPSRV REQUEST statement. This can be a problem if some of the logic to be run in the INIT program is dependent on the application or service or on the environment. While it may be desirable (or preferable) to customize the INIT program so it is specific to a particular application or service or environment, another possible strategy is to use a standard INIT program that performs the basic set-up functions that are required regardless of the environment or application (if the Application Server supports multiple applications). Such an INIT program can include or call another program to define any environment- or application-specific parameters. Assuming the Best Practice in Section 14.2.2 has been used to have application- or environment-specific service names, the following macro (provided with the sample environment) can be called in the INIT program to facilitate customizing the logic based on either environment or application. %macro customInit(entry=); %local initpgm node1 node2 node3 node4 init_type; %let %let %let %let %let

initpgm node1 = node2 = node3 = node4 =

= %sysfunc(appsrvgetc(request init)); %scan(&initpgm,1,.); %scan(&initpgm,2,.); %scan(&initpgm,3,.); %scan(&initpgm,4,.);

n

%if %length(&entry) = 0 %then %let entry = &_service;

o

%if &node4 = %then /* init program is a .sas file */ %let initpgm = %sysfunc(pathname(&node1))/&entry..&node3; p %else %do; /* init program is a SAS catalog entry */ %let initpgm = &node1..&node2..&entry..&node4; q %let init_type = catalog; %end; /* init program is a SAS catalog entry */

q

Chapter 14: Maintaining an Applications Environment 243 filename _init &init_type "&initpgm";r %if %sysfunc(fexist(_init)) %then %str(%inc _init;); %mend customInit;

n customInit assumes the code to be included is another entry of the same type in the same location as the current INIT program. The APPSRVGETC function is used to get its name. The name is parsed into its components. o If no value is provided for the entry to use, the value defaults to the service (e.g., the value of the macro variable reference &_service). p The / separator works under both Windows and UNIX. q Build the filename (the path to the .sas external file or catalog) and then associate a SAS fileref with it. r Include the entry or file only if it exists. This check allows the macro to be called unconditionally even if there is no entry because there are no requirements specific to the application or environment. The use of this macro is illustrated by the following scenarios:

ƒ

The Application Server supports only one application, with separate development and production environments where the value of _service has _dev and _prod as suffixes. The INIT program specified in the PROC APPSRV REQUEST statement can do the set-up functions that are not specific to development vs. production (e.g., checking _rmtuser to determine what librefs to assign). Including the following macro call causes the logic that is specific to the environment to be invoked: %customInit( entry = %scan(&_service,2,_) )

The macro causes catalog entries (or .sas files) called dev or prod to be included (if they exist) and run before each request. For example, code similar to what was used in the defineAccess macro (Section 12.3) could be included in the dev program to terminate the request if the value of _rmtuser is not one of the developers or authorized testers, e.g.,

Best Practice: Even if distinct brokers as discussed in Section 14.2.3 are used (with http authentication) to limit which users can access the development environment, it may be a good idea to add this extra check in the Application Server. For example, other users may be granted http access for other reasons, but are not authorized to access the application.

%if not &authorized %then %do; /* terminate the request */ %externalHTML(type=catalog, source=¬AuthorizedTemplate ) endsas; %end; /* terminate the request */

The code that was used in Section 11.4 to set the debugFlag could also be included in the dev entry: data _null_; if &_debug = '1.......'b then call symput('debugFlag','Yes'); run;

244

Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

ƒ

The Application Server supports multiple applications and environments with different data libraries to be defined for each application. The macro can be called twice. First, it can be called with the application name or acronym from the value of _service used to include or execute an entry to define the librefs for each application, e.g., %customInit( entry = %scan(&_service,1,_) )

Second, it can be called to do any special setup for the specific environment (e.g., development versus production as discussed above): %customInit( entry = %scan(&_service,2,_) )

ƒ

The Application Server supports multiple applications and environments and each combination has a unique set of set-up tasks. The macro can be invoked once and includes the appropriate code for each relevant combination, e.g., %customInit()

which will include a file whose name is the same as the value of the service. Having a program that can be called by the INIT program that is specific to the environment enables the setting of values and parameters specific to that environment. For example, in a production environment, the following OPTIONS statement may be appropriate: Options nomprint nosource nosource2 nosymbolgen nomlogic;

By comparison, in the development and/or test environments the following OPTIONS statements may be appropriate: options mprint source source2; /* logic to check a name/value pair to turn on symbolgen and/or mlogic */ %global symbolgen mlogic; n %iif(%length(&symbolgen) ne 0, options symbolgen;); %iif(%length(&mlogic) ne 0, options mlogic;); o /* See the debugFlag discussion in Section 11.4 */ %let debugFlag = Y;

n %global is used to ensure the macro variables exist. o The iif macro (Section 7.3.1) is used to generate options. The customInit macro, like all of the other macros and code included in the sample environment, is not intended to be a robust implementation. It can, however, provide a foundation that you can enhance to meet your application needs.

14.3 Metadata Approaches to Minimize Code Changes Metadata techniques (sometimes referred to as data-driven) to generate application code are well known and widely used. Updating metadata is easier than updating code (e.g., it can be done by a non-programmer). This is also true for applications generated using the SAS/IntrNet Application

Chapter 14: Maintaining an Applications Environment 245

Dispatcher. For example, HTML generated by the use of the externalHTML macro via template HTML files (Section 7.5) can be more easily updated and maintained by changing the template as opposed to having to deal with PUT statements and the associated quoting requirements. Such HTML templates represent one type of metadata. The metadata approach can also include the use of SAS data sets that contains values that meet any of the following specifications:

ƒ

to be included in the output, e.g., a default title or footnote or both to be used for all output

ƒ ƒ

messages

ƒ

the names of HTML templates to be used for certain common functions

parameter values for the SAS code, e.g., the ODS style to be used for all ODS output

Best Practice: Use a metadata approach for any value that is used in many programs, e.g., define the ODS style using such an approach. Should a change to a new style be required, it is easier to edit the value once in a metadata table instead of reviewing and updating every program in an application.

This approach also facilitates changes required to support, for example, multiple languages or locations. It allows the values to be customized or changed based on language or location (e.g., the name or e-mail address of the contact person to be included in any output is different for different locations or countries). Updating or adding such data once is easier and more maintainable than reviewing and updating every program. The text values defined in the metadata could include macro functions, macro calls, and macro variable references that are resolved by the SAS word-scanner when the value is inserted into the SAS program. To run the examples in this section, go to the sample environment and select Chapter 14. Then select Message Text Metadata as Macro Variables or Message Text Metadata using getTextString Macro. These Best Practice: Loading all the values into macro variables is examples provide two preferred for values used many times in many programs, while the alterative implementations of macro approach is preferred for less frequently used values. An a metadata approach and application can use both techniques by having two data sets (or one produce the output shown in data set with another variable that designates the technique): one that is loaded into macro variables and one that uses macro calls to insert Figure 14.2. The only the values. difference between them is how the values from the metadata are referenced. The first link uses a program that assumes that all the values have been loaded into SAS macro variables. The desired text is inserted into the program by using a macro variable reference for the key or mnemonic value. The second link uses a program that calls a macro to query the data set for the value for a particular key or mnemonic. The macro inserts the returned text into the SAS program.

246

Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 14.2 Using Metadata to Customize or Set Parameter Values

Both examples show a sample metadata data set with two columns: a key or mnemonic value (which serves as the name of the macro variable) and the appropriate text that contains a select set of values such as these:

ƒ

appname, apptitle, appfoot, and copyright contain text that is to be used in any or

all generated output.

ƒ

dsnf, notauth, and notauth_rmtuser define the message text for particular situations. spt_app_name and spt_app_email can provide contact information for the

support person responsible for solving application-specific problems.

ƒ

odsStyle defines the value to use for the style attribute for all ODS output. images and projectRoot define paths that might need to be referenced in generated programs. For example, projectRoot can be used in place of the field saspressRoot used in Section 13.2.1. stylesheet defines the location for the standard stylesheet that should be used.

ƒ

refreshSession, notauth_template, and trailer provide the name of the HTML

templates to use for specific scenarios (the user is not authorized for the request, a standard trailer block of HTML is to be included at the bottom of any generated HTML page, etc.).

Chapter 14: Maintaining an Applications Environment 247

The following program is run when the first link is selected and uses the technique of loading all the values into macro variables: %restoreMvars(lib=sampdata,data=messageMetaData)

n

ods listing close; ods html file = _webout (no_bottom_matter title = "&appname")o style = &odsStyle; proc print data = sampdata.messageMetaData noobs label style(data)=[protectspecialchars=yes]; p title "&apptitle"; o footnote "&appfoot"; run; ods html close; %externalHTML(source=&trailer,type=catalog)

Best Practice: Call restoreMvars to load the values of the macro variables in the INIT program instead of in each individual program (as is done in this sample program).

q

n The restoreMvars macro (Section 10.3) is used to load the metadata values into SAS macro variables. o The values are referenced as macro variables. p protectspecialchars=yes is used so that any HTML metadata values are shown as is. q The name of the template for the standard trailer block is referenced as a macro variable. If the location of the trailer HTML is changed, only the metadata needs to be updated. A virtually identical program is used for the second technique. It uses a macro (discussed in Section 14.3.1 below) to get the desired value and insert it into the program. The restoreMvars macro is not called to create the macro variables; instead the getTextString macro is used at each point in the program where a value is to be inserted. The macro also queries the metadata to get the value to be inserted into the program: ods listing close; ods html file = _webout (no_bottom_matter title = "%getTextString(keyvalue=appname)") style = %getTextString(keyvalue=odsStyle); n proc print data = sampdata.messageMetaData noobs label style(data)=[protectspecialchars=yes]; o title "%getTextString(keyvalue=apptitle)"; p footnote "%getTextString(keyvalue=appfoot)"; p run; ods html close; %externalHTML(source=%getTextString(keyvalue=trailer), type=catalog)

q

n The getTextString macro provides the value for the ODS style to use. o protectspecialchars=yes is used so that any HTML metadata values are shown as is. p The getTextString macro also provides the value for the default title and footnote. q The getTextString macro provides the value for the name of the HTML template that contains the standard trailer text to be included at the bottom of each page.

248

Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

The HTML template referenced by the externalHTML macro illustrates some techniques of interest. The output produced by the externalHTML macro call using the template listed below is shown in Figure 14.3 (and is the rest of the output corresponding to Figure 14.2). standard HTML text deleted The values are loaded from a SAS data set and two ways of using this metadata are illustrated

• all the values are loaded into macro variables which can then be referenced in the code
• a macro is used to query the data set for the required value

standard HTML text deleted Applications Development Using the SAS/IntrNet Applications Dispatcher%getTextString(keyvalue=copyright) o standard HTML text deleted

n The iif macro (Section 7.3.1) customizes the message in this template to reference which approach (macros variables vs. macro calls) was invoked. Figure 14.3 was generated using the getTextString macro. o The getTextString macro is used since it cannot be assumed that every reference to this template will have the macro variable Copyright defined. Calling getTextString should always work, while macro variable references will work only if the values have been loaded into macro variables from the metadata.

Chapter 14: Maintaining an Applications Environment 249

Figure 14.3 Metadata Values Used in HTML Processed by the externalHTML Macro

14.3.1 The getTextString Macro Here is a list of the macro parameters.

ƒ

msgdata provides the name of the metadata data set that contains the message text. In the sample environment this parameter defaults to sampdata.messageMetadata. You can customize the default value to point to your metadata table.

ƒ

keyname the name of the variable that contains the unique identifier. The default value is Name.

ƒ

msgtext the name of the variable that contains the text to be returned. The default value is Value.

ƒ

keyvalue the value that identifies which text string value is to be included.

ƒ

default a text value to be used if there is no row in the data set corresponding to the key value. The default value is %nrstr(&keyvalue) Not Found. The use of %nrstr(&keyvalue) allows the default value to include the value passed in for the keyvalue parameter while preventing SAS from attempting to resolve the value at macro compile time.

250

Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

The parameter names may need to be changed if they conflict with macro variable references in a text string defined in the metadata. For example if there is a text value that references &msdata or &msgtext, the macro will resolve it to the value passed in for this parameter instead of the expected macro variable. Note: Name and Value were specified as the default for keyname and msgtext so the restoreMvars macro (Section 10.3) could be used to load the values. If other names are desired, the restoreMvars macro could be changed so the names it uses are parameters (instead of assuming they will always be Name and Value). The macro source follows. Note that it is conceptually similar to the generateOptionTag (Section 7.6.3) and getVarsAsTextBoxes (Section 7.6.6). SCL functions that can access values in a SAS data set are invoked using the %sysfunc macro. %macro getTextString (msgdata=sampdata.messageMetadata, keyname=name, msgtext=value, keyvalue=, default= %nrstr(&keyvalue) Not Found ); %local _rc _dsid _varnum _value;

n

%let _dsid = %sysfunc(open(&msgdata(where=(&keyname="&keyvalue"))));o %let _varnum = %sysfunc(varnum(&_dsid,&msgtext)); %let _rc = %sysfunc(fetch(&_dsid)); %if &_rc = 0 %then %let _value = %sysfunc(getvarc(&_dsid,&_varnum)); p %else %let _value = &default; q %let _dsid = %sysfunc(close(&_dsid)); %unquote(&_value) r %mend getTextString;

n The _ prefix for the local macro variables is used to provide protection against those values 1blocking access to global macro variables that may be referenced in the returned message text. o Open the data set using a WHERE clause to subset the data to the one observation for the desired key value. p If the value is found, use it. q Otherwise use the value for the default parameter. r %unquote is used to ensure that macro references or calls are resolved. The getTextString macro, as for all the other macros and code included in the sample environment, is not intended to be a robust implementation. It can provide the foundation that you can enhance to meet your application needs.

P a r t

5

Selected Examples Chapter 15

Generating Static Versions of Dynamic Reports 253

Chapter 16

Simulating a Pause and Resume Capability for the Application Server 259

Chapter 17

Techniques for Handling Long-Running Processes 267

Chapter 18

Using Scheduled Execution to Handle Long-Running Processes 275

Chapter 19

Handling On-Demand Long-Running Requests 281

Chapter 20

Using Metadata-Driven Reporting to Construct Reports 307

Chapter 21

Packaging the Application Dispatcher as a Web Service 327

Part 5 provides a number of examples that use the techniques, samples, and approaches described in previous chapters. Part 5 also illustrates how these techniques, samples, and approaches can be integrated to address commonly encountered requirements. Each example describes a scenario or requirement along with a suggested approach for implementing it using the SAS/IntrNet Application Dispatcher. The following examples are included: Chapter 15 provides an example of generating static versions of dynamic reports (e.g., run by the Application Dispatcher). Chapter 16 demonstrates building a simple facility to simulate a pause and resume capability for the Application Server.

252 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Chapters 17, 18, and 19 discuss a variety of techniques for long-running processes or programs:

ƒ

Chapter 17 demonstrates two techniques that display a “Please Wait” message in the user’s browser while the program is running.

ƒ

Chapter 18 shows how the parameters for a user’s request can be saved and processed in a separate SAS session (e.g., a scheduled batch SAS process).

ƒ

Chapter 19 presents a reusable framework that enables the spawning of an independent SAS session to handle long-running requests on demand.

Chapter 20 illustrates how to build a metadata-driven reporting application. Chapter 21 shows Application Dispatcher packaged so its services are available as a Web service. The examples are not intended to be robust implementations of the functionality described. Instead, they are intended to provide insight about how the tools and techniques presented in this book can be used to address some typical application requirements. The examples can be the foundation for building robust applications. The examples presented in Part 5, as well as the techniques presented earlier in the book, can be combined in a number of ways to meet your needs.

C h a p t e r

15

Generating Static Versions of Dynamic Reports 15.1 Introduction 253 15.2 Sample Program 254 15.3 Ensuring That Generated Links Function Correctly 256 15.4 E-mailing Static Copies of Dynamic Reports 256

15.1 Introduction Suppose an organization has a nightly process that extracts new data and stores it in a data warehouse. In addition, a summary table is created that is used to provide drill-down functionality. Everyone in the organization can access these reports, but a large number of users in the sales organization access the report as soon as they log on to the corporate intranet and the sales portal. This has caused a performance bottleneck since the demand is orders-of-magnitude higher at the beginning of the day. Adding additional capacity (e.g., more SAS/IntrNet Application Servers) to address this once-a-day bottleneck is not an option. Here is a solution to this dilemma. Since the data is typically updated nightly, and everyone starts with the same high-level summary, there is no need to generate that high-level summary dynamically for each user as he logs on to the portal. Instead the decision is made to create a static version of the top-level page at the end of the nightly process. Because the program has been set up to run via the SAS/IntrNet Application Server, and because some users will still need to run the report request dynamically (e.g., they do not have access to the sales portal), there is no need to create another program to produce the same report. Instead a simple program is run that uses the URL access method to generate a static copy of the report each night after the data is updated. The URL access method can access the specified URL, which calls the desired program via the Application Dispatcher and can save the results in an HTML file accessible from the sales portal. The technique uses the URL access method of the

254 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

FILENAME statement (shown in an earlier example in Section 13.2.1). The example presented here demonstrates that the URL access method has broad applicability; it can be used to access any dynamic report in order to generate a static copy of a dynamically generated report.

15.2 Sample Program The template code to generate a static copy of a dynamically generated report is shown below. The template code is stored in staticReport.source in the Chapter 15 catalog of the sample environment. To run the code, download it to an interactive SAS session and fill in the appropriate values. %let lrecl = 512; n filename static url o 'http://[SERVERNAME]:80/[BROKERLOCATION]?_service=appdisp&_program=sam plib.websamp.drill.macro&dataset=sampdata.shoeSummary&classlst=Region+ Product&vars=Sales+Returns' lrecl=&lrecl; filename out '[SPECIFY OUTPUT LOCATION]' lrecl=&lrecl; data _null_; infile static; input; file out; put _infile_; run;

The sample runs the Xplore drill-down macro against a summary data set that is provided in the sample environment. It assumes that the samplib is specified in a PROGLIB statement (it is included in the default appstart.sas file). Otherwise, the program SAMPLIB.WEBSAMP.DRILL.MACRO is not found. Note: If the Xplore sample is not available, the URL can be replaced by any URL that generates an HTML-based report. Before submitting the code for execution, you should make the following changes to it. n The value specified for LRECL in the %LET statement may need to be updated if the generated HTML contains lines that are longer than the provided value of 512.

o The following placeholder values should be replaced with appropriate values for your site: …

[SERVERNAME] – The Web server name.

…

[BROKERLOCATION] – The location of the Application Broker, e.g., /scripts/broker.exe or /cgi-bin/broker, etc.

…

[SPECIFY OUTPUT LOCATION] – The location to write the static copy to.

Chapter 15: Generating Static Versions of Dynamic Reports 255

Note: The FTP access method of the FILENAME statement can be used to write the static version of the report to the Web server if the server where this program is run does not have file system access to the Web server directory tree. See Figure 15.1 to see the SAS log for the template code. The code has been modified to use the FTP access method of the FILENAME statement.

Figure 15.1 SAS Log Showing the Use of the URL and FTP Access Methods to Create a Static Copy of Output

256 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

15.3 Ensuring That Generated Links Function Correctly If the static copy is not written to a location on the Web server where the Application Broker is available, in all likelihood the links will not work since they won’t include the server name. If the Best Practice of using &_url to generate links has been followed, the links will include the complete path. The completeBrokerName macro (Section 5.3.2) can be used to replace the value of _url with a value that includes the complete path. For example, %let _url = %completeBrokerName;

This can be done using either of the following techniques:

ƒ

using the complete broker name by executing the above %LET statement unconditionally at the beginning of the program

ƒ

using a value (e.g., completeBrokerName) having a non-blank value passed in on the URL, e.g.: %global completeBrokerName; %iif((%length(&completeBrokerName) gt 0),%nrstr(%let _url = %completeBrokerName;))

n

n The iif macro (Section 7.3.1) is used to set the value based on the parameter. %nrstr is used to prevent the %LET statement from being executed when the macro parameters are being scanned. This code can be included in either of the following locations: …

the specific program(s) that may need this option

…

the INIT program

Best Practice: If only one (or a few) programs need this functionality, include this code in those programs. Otherwise, include this code in the INIT program.

Note: It is assumed that such reports contain links as otherwise there may be little or no reason to make the reports available dynamically.

15.4 E-mailing Static Copies of Dynamic Reports The EMAIL option of the FILENAME statement can be used with an e-mail address (or distribution list) as the value for [SPECIFY OUTPUT LOCATION] (see Section 15.2 above) if a static version of reports is to be distributed via e-mail instead of via the company’s intranet (e.g., the sales portal for the scenario described above). If the static version is to be e-mailed, any generated links must include the full path as discussed above in Section 15.3. The SAS log that shows the use of the EMAIL option of the FILENAME statement is shown in Figure 15.2.

Chapter 15: Generating Static Versions of Dynamic Reports 257

Figure 15.2 SAS Log Showing the Use of the URL and EMAIL Access Methods to E-mail a Static Copy of Output

258 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

C h a p t e r

16

Simulating a Pause and Resume Capability for the Application Server 16.1 Introduction 259 16.2 Sample Implementation 260 16.2.1 The Metadata Control Table 262 16.2.2 The Toggle Program 263 16.2.3 Macro to Check Status 264 16.2.4 The HTML Templates 265 16.3 Doing More with the Sample 266

16.1 Introduction Most if not all production applications have scheduled downtimes that allow updates or promotions to be done on the application code. In an ideal world all updates could be applied during those scheduled downtimes. Occasionally, however, a situation arises when a quick update (i.e., something that can be done and tested in a few minutes) needs to be made to an application before the next regularly scheduled downtime. If an update is being made to an Application Server program while the Application Server is processing a request, a user could get a message similar to the message that is shown in Figure 16.1. And if the user does not get such a message, he might get results from a program (or set of programs) for which the updates have not yet been completed. Since the Application Server does not include a built-in facility to handle temporarily not running (i.e., pausing) requests, the only way to make such changes without allowing any requests is to shut down the Application Servers, apply updates, and restart the Application Servers.

260 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 16.1 Error Seen by a User If a Program Is Being Edited

Such an approach may not be viable if there are active sessions since users can lose their sessions (and thus their current work) if the Application Servers are shut down and restarted. An alternative is needed where requests can be intercepted before the programs are run by the Application Server. A metadata-based approach that can intercept requests in the INIT program is described in this chapter.

16.2 Sample Implementation As discussed in Section 9.1, the INIT program is run before any requested program is run (the use of an INIT program was suggested as a Best Practice). A simple approach is to use a metadata control table to filter requests. Filtering prevents the requests from being run during the few minutes that it takes to make an update. Here is a way to implement such functionality:

ƒ ƒ

Use a metadata control table to indicate that requests should not be accepted. Add logic (e.g., a macro call) to the program specified in the INIT parameter of the REQUEST statement to determine if requests are to be allowed.

ƒ

Use an administrative program, i.e., one that requires the _ADMINPW password (discussed in Section 4.4.2.4), that toggles the status of the Application Server.

ƒ

Use HTML templates to provide the user with the current status of the Application Server.

To run the examples in this section, download and use a local copy of the sample environment. Then select Chapter 16 and select the appropriate links for the task you want to perform.

ƒ

Select the Toggle Pause/Resume Status button to update the metadata so requests are not run (see Figure 16.2).

ƒ

Select any other of the example links (e.g., the link for Section 7.1) to see that the request has been intercepted (Figure 16.3).

ƒ

Select the Toggle Pause/Resume Status button again to allow requests to again be processed (Figure 16.4).

ƒ

Confirm that requests are now allowed by selecting, for example, the link for Section 14.3 again (Figure 16.5). Note that if the user leaves the browser window open as shown in Figure 16.3, it displays her requested output (e.g., the output shown in Figure 16.5) once the Application Server is available to process requests. The reason for this is the automatic refresh (discussed in Section 16.2.4.2).

Chapter 16: Simulating a Pause and Resume Capability for the Application Server 261

Note: The sample environment on the Web does not support this example because it requires knowledge of the Application Server administrative password. If you want to run this example, you must download and use a local copy of the sample environment.

Figure 16.2 Application Server Is Paused

Figure 16.3 Message Seen by a User When an Application Server Is Paused

Figure 16.4 Application Server Status Reset to Resume

262 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 16.5 User Output Automatically Displayed

16.2.1 The Metadata Control Table To see the table saspress.pauseResume, go to the sample environment and select Chapter 7. Select SAS Server Pages, and then select a library and data set (Figure 16.6). The data set contains one observation and five variables:

ƒ

pauseResume a non-blank value indicates that requests should not be accepted. Since the value shown in Figure 16.6 is blank, requests are accepted.

Best Practice: Consider storing applicationspecific metadata such as the pauseResume metadata in a specific library. That library can be the same one that the programs for an application are stored in. The libref is defined in the Request Executive (Section 4.2) whenever a program entry is used as the value of _program. As discussed in Section 4.4.2.3, the library is defined because of its being referenced in a PROGLIBS statement. However it is not available for programs in other libraries.

ƒ

templateON the name of the HTML template that displays a message to the user that the application is currently being updated.

ƒ

templateToggle the name of the HTML template that displays the current value of the pauseResume variable after it has been updated.

ƒ

timeChanged the datetime when the value was last toggled.

ƒ

available if the Application Server is in Pause mode, contains the estimated datetime when the application will be available. In Figure 16.6 the value is blank because the Application Server in not in Pause mode.

Best Practice: It may be desirable to include the _service value in the data set name. This would allow the same program to control Application Servers for different services.

Note: The code, chapter16PauseResume.source, that creates the sample metadata control table is located in the setup catalog, which included with the sample environment.

Chapter 16: Simulating a Pause and Resume Capability for the Application Server 263

Figure 16.6 Pause/Resume Metadata Control Table

This data set is checked during the INIT program to determine if the request should be allowed.

16.2.2 The Toggle Program The sample toggle program provided is stored Best Practice: Store code that runs updates in a similar in the same catalog as the INIT program since it way to this toggle program in a location defined by the ADMINLIBS (Section 4.4.2.4) statement, e.g., the is an administrative program and access to the same location where the INIT program is located. ability to run the program can be restricted by defining the location in an ADMINLIBS statement. The toggle program checks the current value and toggles the value (blank to non-blank and vice-versa). The program also calculates when the Application Dispatcher is expected to be available again by adding the estimated length of time during which the Application Server is expected to be in Pause mode (i.e., the value of the backOn macro variable) to the current datetime. %setDefaultValue(data,saspress.pauseResume) %setDefaultValue(backOn,300)

n

data &data; set &data; timeChanged = datetime();o call symput(‘timeChanged’, trim(left(put(timeChanged,datetime.)))); p if pauseResume = 'x' then do; /* on now, turn it off */q pauseResume = ' '; available = .; call symput('available',' '); call symput('pauseResumeMessage','Pause/Resume turned off.'); end; /* on now, turn it off */ else do; /* off now, turn it on */ pauseResume = 'x'; available = timeChanged + &backOn; r call symput('available', trim(left(put(available,datetime.)))); call symput('pauseResumeMessage','Pause/Resume turned on.'); end; /* off now, turn it on */ call execute('%externalHTML(type=catalog,source=' || trim(templateToggle) || ')'); run;

264 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

n Use the setDefaultValue macro (Section 5.3.3) to define the values. They can be overridden by providing values in the request if necessary. o Set the value for when the value was toggled. p In SAS 9, the STRIP(string) can be used instead of TRIM(LEFT(string)). ®

q Toggle the values and set a message to be used by the template. r Create a macro variable with the name of the template defined in the metadata and call the externalHTML macro (Section 7.5.1) to display the template to the (administrative) user.

16.2.3 Macro to Check Status The following macro can be called in the INIT program to determine the current status and take the appropriate action: %pauseResume(data=saspress.pauseResume)

The macro logic checks to see if the Application Server is in pause mode and either allows the request, or display a message that requests are not currently allowed. The macro source code follows: %macro pauseResume(data=); %if %sysfunc(exist(&data)) %then n %do; /* pause/resume data set exists */ data _null_; set &data; where pauseResume ne ' ' and o /* allow specific programs */ "%upcase(&_pgmlib..&_pgmcat)" ne: upcase(appsrvgetc ('request init'));p /* can only get here if the flag is set */ call symput('refresh','120'); call symput('available', q trim(left(put(available,best12.)))); call execute('%externalHTML(type=catalog,source=' || trim(templateOn) || ')');r call execute('endsas;'); s stop; run; end; /* pause/resume data set exists */ %mend pauseResume;

n Verify the metadata control data set exists and do nothing if it does not. o If the toggle is set and the program is not in an allowed catalog, the WHERE clause allows the observation to be read. This causes the DATA step statements to be executed. p Programs in the same catalog as the INIT program are allowed to run. Other allowed values can be added. q Set values for macro variables used in the template.

Chapter 16: Simulating a Pause and Resume Capability for the Application Server 265

r Display the template specified in the metadata. s Issue an ENDSAS statement to end the request executive (and thus the request).

16.2.4 The HTML Templates The sample Pause/Resume facility uses two templates. One is used by the toggle program to display the current status. The other is used by the macro to inform the user that the Application Server is in Pause mode. Using templates enables you to easily update and change the HTML to be generated.

16.2.4.1 The pauseResumeToggle Template This template displays the current status. It is invoked by the toggle program that sets the value for the macro variables referenced in the template. <TITLE>Toggle Pause Resume Status Toggle Pause Resume Status &pauseResumeMessage n

Status toggled at: &timeChanged..

%iif(&available ne %str( ),Estimated time to be available: &available.)

o

n The template uses the macro variables created in the toggle program so the users know what the current status is. o When Pause mode is enabled, the iff macro (Section 7.3.1) is used to conditionally generate the estimated availability time.

16.2.4.2 The pauseResumeMessage Template This template displays a message whenever the Application Server is in Pause mode and the submitted program is not an allowed program. The template includes macro %LET statements in order to perform selected calculations. <TITLE>Please Wait . . . <META http-equiv="refresh" content="&refresh">n Application Being Updated - Please Wait The application is being updated and %let now = %sysfunc(datetime()); %let back = %sysfunc(ceil((&available-&now)/60)); o %iif(%eval(&back > 0), should be back online in &back minutes.,p

266 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

estimated availability is TBD.)

This request page will be refreshed every &refresh seconds. As soon as the maintenance is completed, your request will be processed with the next refresh.

Current Datetime: %sysfunc(putn(&now,datetime.)) %global _sessionid; /* make sure it exists */

%iif(%length(&_sessionid) ne 0,Your session is extended each time this page is refreshed.) q

n The META tag causes the requested URL to be refreshed using the value defined in the toggle program. This allows the original request to be automatically submitted when the Application Server is no longer in Pause mode. o Determine how many more minutes Pause mode is expected to be enabled. p The iif macro is used to generate a customized message to tell the user how much longer before the Application Server is expected to be available to process a request. If the estimated end time has passed, the message indicates the wait time is TBD. q If the request uses sessions, the iif macro informs the user that refreshing this page keeps the session alive until Pause mode is ended. This assumes that the refresh time is shorter than the session timeout.

16.3 Doing More with the Sample With minor changes to the metadata control table, the pauseResume macro, and the templates, a number of enhancements could be made to this facility, including:

ƒ

The toggle program could be enhanced to allow for a parameter to update the expected time when the Application Server will no longer be in Pause mode.

ƒ ƒ ƒ ƒ

Enabling Pause mode to be set specific to particular applications. Generalizing the logic for what programs can be run while in Pause mode. Providing contact information so users know who to contact. Sending an e-mail to interested parties when Pause mode is started and/or ended.

You can adapt or enhance this facility to meet your particular application requirements.

C h a p t e r

17

Techniques for Handling Long-Running Processes 17.1 Introduction 267 17.2 Using the Cascading Style Sheets Display Attribute 268 17.3 Using the JavaScript location.replace Function 271

17.1 Introduction Users of Web applications expect results of their requests to be returned in a matter of seconds. For this reason, a Web-based application often uses a two-step approach to providing responses to users of a long-running process:

ƒ ƒ

First, provide an immediate response that says “Please Wait.” Then replace the “Please Wait” message with the output from the process once it has been completed.

Such functionality is straightforward to implement using the Application Dispatcher.

268 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

However, keep these caveats in mind. The first technique is simple to implement and uses industry standard Cascading Style Sheets. But, it produces HTML that may be considered invalid. The second technique produces valid HTML, but must generate the output to a temporary location (the &_tmpcat catalog), which is then replayed to the user’s browser once the request is complete. This result may be an issue for voluminous output. You can choose which technique to use based on your environment and user expectations.

17.2 Using the Cascading Style Sheets Display Attribute Cascading Style Sheets (CSS) have a number of attributes that can be used when producing HTML output. One of them is the DISPLAY attribute, which allows parts of the HTML to be dynamically displayed or hidden. When combined with JavaScript, the display of specified parts of HTML can be toggled on or off. The following example demonstrates this technique using a program similar to the PROC PRINT examples discussed in Chapter 8. To run this example, go to the sample environment and select Chapter 17. Then select Please Wait Using CSS.

Figure 17.1 “Please Wait” Message Using Cascading Style Sheets

Once the program has completed, the output shown in Figure 17.2 is displayed.

Chapter 17: Techniques for Handling Long-Running Processes 269

Figure 17.2 Output Replaces “Please Wait” Message

An HTML template (as discussed in Section 7.5) is used to display the “Please Wait” message so the message can be used easily by multiple programs. Using HTML templates eliminates complicated quoting issues and makes it easy to generate and update HTML with an HTML editor. The HTML must be saved in a location known by the Application Server. n




Please Wait o

p

n Use a DIV tag to wrap the text to associate a unique identifier (pleaseWait) with the text. As a result, the DISPLAY attribute can be changed using JavaScript. o The &images macro variable was created in the INIT program (as discussed in Section 14.3) and is the location of the application images directory. This avoids having to hardcode the location.

270 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

p A number of blank lines may be needed so the “Please Wait” message is seen by the user’s browser. The number of blank lines needed may be site dependent. The template in the sample environment has 25 blank lines. You may need to adjust the number of blank lines via trial and error. The following sample program demonstrates how to generate a “Please Wait” message using this template: %setDefaultValue(obs,5); %setDefaultValue(startAt,1); %setDefaultValue(data,sashelp.shoes); %externalHTMLn (type=catalog, source=saspress.template17.pleasewait.source ) data _null_; /* simulate a longer process */ x = sleep(15); o run; %generateOdsStmtp (type=html, htmlOptions=(title = "Please Wait Example") style=&OdsStyle ); proc print data = &data(firstobs=&startAt obs=&obs); title "Please Wait Example"; footnote '<script>pleaseWait.style.display = "none"'; run;

q

ods html close;

n Use the externalHTML macro (Section 7.5.1) to display the template asking the user to wait. o The Sleep function is used to simulate a longer running process (so the “Please Wait” message can be displayed before the output is returned). p The generateODSStmt macro (Section 8.3.3) is used to generate the ODS HTML statement. q Embed a JavaScript command in the FOOTNOTE statement so that once the output is returned, the display of the “Please Wait” message (as defined by the ID pleaseWait) is turned off.

Chapter 17: Techniques for Handling Long-Running Processes 271

17.3 Using the JavaScript location.replace Function The Display attribute is a flexible technique that can be used in most, if not all, scenarios where a “Please Wait” message is to be displayed. An alternative implementation of the functionality using the JavaScript location.replace function is also straightforward to implement. The program should be structured as follows:

ƒ ƒ ƒ

Generate the “Please Wait” message (just as in the example in Section 17.1).

ƒ

The argument to the location.replace function is the URL that should replace the current content (e.g., the “Please Wait” message). Construct that URL by using &_replay to replay the output written to the &_tmpcat catalog.

Generate the content, writing it to the &_tmpcat catalog instead of the _webout catalog. Send JavaScript that calls the location.replace function back to the user’s browser once the program has been completed.

Note: The location Content-type header (Section 8.2.1.1) cannot be used in this situation since the “Please Wait” message has already been returned to the user’s browser. The following example demonstrates this. It produces the same “Please Wait” message as shown in Figure 17.1. See Figure 17.3 to see the generated output. To run this example, go to the sample environment and select Chapter 17. Then select Please Wait Using a Re-Direct.

Figure 17.3 JavaScript location.replace Function Used to Replace the “Please Wait” Message

272 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

The program, which is shown below, uses ODS to generate a table and a graph (similar to the example in Section 8.4). Both the HTML and the graph are written to the &_tmpcat catalog. The only other content (other than the “Please Wait” message) written directly to the user’s browser (i.e., to _webout) is a location.replace function call with a URL that uses the Replay facility. The Replay facility returns the ODS-generated HTML (from the &_tmpcat catalog) to the user’s browser. That HTML then includes an ODS-generated replay to display the graph. %externalHTML n (type=catalog, source=saspress.template17.pleasewait.source ) data _null_; /* simulate a longer process */ x = sleep(15); run; filename results catalog "&_tmpcat..results.html";

o

goptions dev=gif xpixels=800 ypixels=400 transparency; %generateOdsStmtp (type=html, file=results, htmlOptions=(title = "Please Wait Example") path=&_tmpcat (url=&_replay) style = &OdsStyle ); proc gchart data = sashelp.shoes; title; hbar3D product/sumvar=salesq subgroup=region shape=cylinder nostats discrete; run; quit; proc report data=sashelp.shoes nowd style(summary)=[foreground=green]; columns product region, sales; define product / group ' '; define region / across ' '; define sales / sum ' '; rbreak after / summarize; run; ods html close; data _null_; file _webout; url = &_replay || 'results.html'; put '<SCRIPT>' / 'location.replace("' url +(-1) '");' /r '' ; run;

Chapter 17: Techniques for Handling Long-Running Processes 273

n As in the above example:

ƒ ƒ

Use the externalHTML macro to display the “Please Wait” message. Use the Sleep function to simulate a longer process.

o Generate a FILENAME statement for the generated output that points to the &_tmpcat catalog. p Use the generateODSStmt macro (Section 8.3.3) to generate the ODS HTML statement. q As discussed in Section 8.4, the graph will be written to the &_tmpcat catalog. Since the ODS statement points the fileref results, the HTML output will also be written to the catalog. r Generate HTML that includes a call to the JavaScript location.replace function with a URL as its argument that replays the generated HTML to the user’s browser. While only the JavaScript example includes a graph (using the ODS-generated Replay facility), both techniques presented in this chapter support pages produced by ODS that have mixed text and graphics.

274 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

C h a p t e r

18

Using Scheduled Execution to Handle LongRunning Processes 18.1 Introduction 275 18.2 Sample Implementation 276 18.3 Doing More with Scheduled Execution 279

18.1 Introduction This example demonstrates the use of the Application Dispatcher to handle a long-running program or process. This example provides the first of two alternative approaches to the “Please Wait” example presented in Chapter 17. This approach allows the user to enter parameter values via a Web browser. It is appropriate for long-running requests that will take a substantial amount of time (for example, submitting a request for a daily/weekly/monthly batch process on a mainframe). It is typically more convenient for the user to do this than to log on remotely to that machine and then edit or enter the parameter values. This scenario involves using a separate SAS session (not using the SAS/IntrNet Application Dispatcher) that can be run on a scheduled basis (e.g., nightly or hourly) to process the request. If necessary, the results can be sent to the user via e-mail (e.g., using the filename e-mail access method).

276 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

The result can take either of two forms:

ƒ ƒ

include the full report provide a link to a Web site that includes the complete report

Best Practice: Sending the full report is usually the best approach when the report is not too voluminous and when the report is intended for only the requesting user. When reports are large, or when others may access the report, the SAS process should write the report to a Web server (using the FTP access method if necessary) and should include a link to the report in the e-mail.

18.2 Sample Implementation To run this example, go to the sample environment and select Chapter 18. Then enter values for the form fields and click the Run button.

Figure 18.1 HMTL Input Form

The sample code that does this is straightforward (the runLater source entry in the Chapter 18 catalog of the sample environment). %savemMVars n (lib=work, data=mvars, saveflag=y ) data runLater/view=runLater; o format email $64. datetime datetime.; retain datetime %sysfunc(datetime()); set work.mvars;

Chapter 18: Using Scheduled Execution to Handle Long-Running Processes 277

label email = "Email Results To" datetime = "Submitted At" name = "Parameter Name" value = "Parameter Value" ; email = symget("email"); run; proc append base = sampdata.runLater data=runLater; run;

Z

%externalHTML q (type=catalog, source=saspress.template18.runLater.source )

n The saveMVars macro (Section 10.3) is used to save all the name/value pairs from the request in a data set in the SAS WORK library. Excluding the includeAuto parameter causes the parameters whose names begin with an underscore (_) to not be saved. This is the default behavior of the macro. o In order for the request to be processed later, it is necessary to uniquely identify each request. The requesting e-mail and the datetime values of the request are assumed in this example to provide unique keys. A view is used to eliminate extra passes of the data. Z The data (i.e., the name/value pairs) is appended to a cumulative data set so the name/value pairs are available to the stand-alone SAS session to be run later. For convenience of the sample environment, the library used here is the sample data library for the sample environment. As a Best Practice, data should be stored in some other data library (e.g., one that is not available to other Application Server requests). q The externalHTML macro (Section 7.5.1) is used to display a message to the user. This template reports that the request data has been saved for later processing. Submitting this request will cause the results shown in Figure 18.2 to be sent to the user’s browser. The captured parameter values are shown in Figure 18.3.

Figure 18.2 Confirmation Message Following Request

278 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 18.3 SAS Data Set Containing the Parameter Values for the Request

The data shown in Figure 18.3 includes all the macro parameters (excluding those prefixed with an _). The values to be saved could be further subset by the program if desired. To see the table saspress.runLater, go to the sample environment and select Chapter 7. Select SAS Server Pages, and then select the library and the data set (Figure 18.3). The only other required component is another SAS program that:

ƒ ƒ

runs on a scheduled basis

ƒ

processes each request and, optionally, e-mails the results (or a link to the results) to the e-mail address provided by the requesting user

uses the restoreMvars macro to make the name/value pair available as macro variables to the program to be run (which is itself defined as the value of program2Run)

A program that does this is not included in the sample environment. It is a relatively straightforward SAS program that you can develop to meet your exact requirements.

Chapter 18: Using Scheduled Execution to Handle Long-Running Processes 279

18.3 Doing More with Scheduled Execution The example presented is the second of three techniques to handle long-running processes. It can be used as-is to implement a facility to capture parameters for reports and requests to be processed later. It used the externalHTML macro (Section 7.5) as well as the saveMvars (Section 10.3) macro. There are a number of enhancements that you may wish to consider before implementing this facility in your environment.

ƒ ƒ

Define a specific library where the requests to be processed are stored.

ƒ

Create a more robust set of keys (vs. e-mail and datetime) for the request. The ® UUIDGEN function can be used to do this in SAS 9.

ƒ

Include a parameter in the request to provide a description for the request (e.g., to be used in the e-mail sent to the requestor).

ƒ

Include an opportunity to specify that a request should be grouped with other requests by the same user into a single e-mail vs. a separate e-mail for each request.

ƒ

Include an opportunity to specify that a link to the output location should be e-mailed (instead of e-mailing the actual output). Optionally, the report location can be defined as a report parameter. This could be used by an administrator to run reports and have them saved on the Web server. The e-mail notification the administrator receives could then be forwarded to any interested parties.

Ensure that the data set name where the requests are saved is specific to the request date (e.g., libref.runLater_DDMMMYY) or the hour (e.g., libref.runLater_DDMMMYY_HH). Using the date or time can allow for: … a daily request to be run shortly after midnight to process all the requests from the previous day … an hourly request to be run, for example, five minutes after the top of the hour to run all the requests from the previous hour.

280 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

C h a p t e r

19

Handling On-Demand Long-Running Requests 19.1 Introduction 281 19.2 E-mailing Results from an On-Demand Long-Running Process 282 19.1.1 Notifying the User 284 19.2 Updating Process Status by Refreshing the User’s Browser 285 19.2.1 Notifying the User 287 19.3 The Sample Framework—Spawning a Separate SAS Session 290 19.3.1 Sample Program to Submit a Long-Running Program— spawnSAS.source 295 19.3.2 Sample spawnSAS Macro 298 19.3.3 Sample Long-Running Program 300 19.4 Doing More with Independent Sessions 305

19.1 Introduction Ideally, requests submitted to the SAS/IntrNet Application Dispatcher are programs that run relatively quickly. When this is not the case, consider using the Application Dispatcher to spawn an independent SAS session to run a long-running program or process. An independent session is an alternative to the scheduled execution approach discussed in Chapter 18 and the “Please Wait” message approach discussed in Chapter 17. Why is it not a good idea to allow on-demand long-running programs to be directly processed by the Application Dispatcher?

282 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

ƒ ƒ

Users don’t expect to submit a request and then wait a long time for the results.

ƒ

Long-running programs can tie up the Application Server for an extended period, making it unavailable for other requests.

The Application Dispatcher times out after a specified time period. While this timeout can be overridden, it is not always reliable: … Long timeouts disable protection against run-away processes. … Browsers have a built-in timeout.

Instead of allowing on-demand long-running requests to be run directly by the Application Server, a better approach is to have the Application Server spawn a separate SAS session to do this processing. Once the Application Server has submitted the code to this separate SAS session, the current request can be ended, thus freeing the Application Server so that it is available for other requests. This chapter presents a sample implementation of a framework to spawn asynchronous separate SAS sessions to handle long-running requests. In addition to the two examples that use this framework to spawn a separate SAS session, this chapter also provides an overview of how the sample framework enables the generated results to be returned to the requesting user:

ƒ ƒ

by sending the user an email by providing updates via the user’s browser on the status of the request, with the final output available once the separate SAS session has completed its processing

The sample framework (which is included in the sample environment) is described next.

19.2 E-mailing Results from an On-Demand Long-Running Process To run the example in this section, go to the sample environment and select Chapter 19. Then select Long-Running Request: E-mail the Results (see Figure 19.1) for a demonstration of spawning a separate SAS session to process a request. Here are the results:

ƒ

A message is returned to the browser almost immediately, informing the user that the request has been submitted (see Figure 19.2).

ƒ

The request to the Application Server is completed, and it is immediately available to respond to other requests.

ƒ

The separate SAS session produces the desired output and e-mails it to the address provided by the user (see Figure 19.3).

Chapter 19: Handling On-Demand Long-Running Requests 283

Figure 19.1 HTML Input Form—E-mailing Results On-Demand

Figure 19.2 User Notification

Figure 19.3 E-mailed Results from a Request for an On-Demand Process

284 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

The output shown in Figure 19.3 is produced by the following program. This program looks like any other program that can be run via the Application Dispatcher; i.e., nothing special needs to be added to the program to allow it to be run by a separate SAS process. Running this program via the sample framework (discussed in detail in Section 19.3), instead of directly, is what enables this program to have its results e-mailed to the requesting user. %generateOdsStmt (type=html, htmlOptions=(title = "Email Results") style = &OdsStyle ); proc report data=sashelp.shoes nowd style(summary)=[foreground=green]; title 'Sample E-mailed Output'; footnote "Completed at %sysfunc(datetime(),datetime.)"; columns product region, sales; define product / group ' '; define region / across ' '; define sales / sum ' '; rbreak after / summarize; run; ods html close;

Note: Programs that e-mail their results to the user cannot use the SAS Output Delivery System (ODS) to generate graphs. As discussed in Section 4.3.1, lightweight sessions are used when ODS generates an HTML page that has an embedded graph. In most cases, the lightweight session will have expired before the user opens the e-mail message containing the reference to the graph. For results with mixed text and graphics, a stand-alone program, as illustrated in Section 8.4, is suggested for pages with embedded graphs.

19.1.1 Notifying the User The sample framework notifies the requesting user that the request has been submitted with the results e-mailed to the address that was specified. The externalHTML macro (Section 7.5.1) produces the output (see Figure 19.2) in the user’s browser using the following template. The details of how the program’s output is delivered via e-mail will be discussed in Section 19.3. <TITLE>Results Will be Emailed Request Submitted Your request to run &program2Run has been submitted n and will be emailed to &email when it is completed.

Request Sumbitted at: %sysfunc(datetime(),datetime.)

n The template references the macro variable program2Run. As discussed in Section 19.3, the sample framework uses this parameter to specify the name of the long-running program that is to be run on demand.

Chapter 19: Handling On-Demand Long-Running Requests 285

19.2 Updating Process Status by Refreshing the User’s Browser E-mailing the results of a long-running process may not be an acceptable solution in some cases. For example, consider the following scenario:

ƒ ƒ

Large data sets are subset in the process.

ƒ

The resulting custom summary data set or cube is then made available for drill-down analysis.

The user specifies the class and analysis variables to be used to summarize the data (e.g., by using the SUMMARY procedure or by creating an OLAP cube).

This scenario is demonstrated later in Section 19.3.3. A simpler example is presented here. To run this example, go to the sample environment and select Chapter 19. Then select LongRunning Request: Browser Refresh. Upon running the example, the user sees the display in Figure 19.4. This page will be automatically refreshed, thus keeping the user informed about the status of his request (e.g., the output shown in Figure 19.5). Finally, when the program has finished running, the output shown in Figure 19.6 is displayed.

Figure 19.4 Browser Refresh Notification—Session Spawned

Figure 19.5 Updated Status—Requested Program Has Started

286 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 19.6 Updated Status—Results Returned

This example uses a program similar to the one used in Section 19.2, except a graph is included in the output. Other than the calls to the updateStatus macro (discussed in Section 19.2.1), this program also looks like any other Application Server program. %updateStatus n (statusDataSet = &statusDataSet, msg = Request Beginning Execution ) data _null_; x = sleep(&refresh); run;

o

goptions dev=gif xpixels=600 ypixels=300 transparency; %generateOdsStmt (type=html, htmlOptions=(title = "Browser Refresh") path=&_tmpcat (url=&_replay) style = &OdsStyle ); proc gchart data = sashelp.shoes; title; hbar3D product/sumvar=sales subgroup=region shape=cylinder nostats discrete; run; quit;

Chapter 19: Handling On-Demand Long-Running Requests 287

proc report data=sashelp.shoes nowd style(summary)=[foreground=green]; columns product region, sales; define product / group ' '; define region / across ' '; define sales / sum ' '; rbreak after / summarize; run; ods html close; %updateStatus (statusDataSet = &statusDataSet, msg = Report Generated, done = Y )

p

n The updateStatus macro adds an observation to a SAS data set containing an update on the program’s status. The name of the data set is made available as a macro variable. The macro should be called, with an appropriate value for the Msg parameter, at key checkpoints in the program. This call to the macro generates the observation in the status data set shown in Figures 19.4 and 19.5 (the first row is inserted by the sample framework that spawns the independent SAS session). o Use the Sleep function to simulate a long-running process. p When the Done parameter is set to a non-blank value, the STATUS data set has an observation that indicates that the request has been completed. The sample framework interprets this as a trigger to display the output of the program instead of redisplaying the STATUS data set (e.g., the output seen in Figure 19.6). The details of how this works are discussed in Section 19.3.

19.2.1 Notifying the User As in the e-mail example, the sample framework takes care of notifying the user about the status of her request. The example uses two components that are specific to this case, where the user is notified by forcing a refresh of a browser page and uses sessions so the SAVE library is available. The first component is the updateStatus macro, which is called to add a row to the STATUS data set at key points during the execution of the long-running program. The updateStatus macro is used in the sample code listed above. The second component is a program which displays the STATUS data set. The program also includes HTML META tags that force an automatic refresh to show the current status of the request. The data set that is displayed is the one that is updated by the calls to the updateStatus macro in the long-running program that is being processed by the separate SAS session. Note: The sample framework uses sessions, and the STATUS data set is stored in the SAVE library.

288 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

The refresh forced by the HTML META tag causes the program to be rerun, and thus causes the current STATUS data set to be redisplayed. This use of the META tag performs two important functions:

ƒ

It keeps the user updated about the status of his request, as long as he does not navigate away from this page.

ƒ

It causes the end time of the session to be extended, as long as the refresh time is shorter than the session time. In the sample spawnSAS driver program discussed in Section 19.3.1, the session time is set to be 10 times longer than the refresh interval.

Although running this program repeatedly places additional demands on the Application Server, the program runs very quickly. Thus, this approach enables the Application Server to accept other requests between the refresh intervals while the separate SAS session is executing the longrunning request. The impact on the Application Server of repeatedly running this short program is significantly less than the impact of tying up the Application Server to run the long-running request. Here is the program (part of the sample framework) that displays the STATUS data set: data _null_; set &statusDataSet; where done ne ' '; n /* do a location replace */ file _webout; rc = appsrv_header('Location', "http://&_srvname/" || &_replay || 'results.html'); put; call execute('endsas;'); run; %generateOdsStmt o (type=html, htmlOptions=(title = "Job status as of &sysdate:&systime") style = &OdsStyle metatext="http-equiv=""refresh"" content=""&refresh""" );

p

proc print data = &statusDataSet(drop=done) label noobs; q title "Job status as of &sysdate:&systime"; footnote "If you leave this page, the output may not be displayed.”;r run; ods html close;

n If the status data set contains an observation with the Done flag set to a non-blank value, the additional SAS process has finished running and has written its output to the &_tmpcat catalog (details discussed below in Section 19.3). In this case, this DATA step redirects the browser to the generated output using a location header (Section 8.2.1.1) using the Replay facility. Since no more content should be returned to the browser, the Request Executive for the current request is terminated using an ENDSAS statement. o The statements starting with the generateOdsStmt (Section 8.3.3) are run only if the longrunning request has not yet completed.

Chapter 19: Handling On-Demand Long-Running Requests 289

p The refresh rate is specified by the macro variable &refresh. q The PROC PRINT output (with the META REFRESH tag) is returned to the user’s browser. The PROC PRINT will be refreshed as long as the additional SAS session is still processing the long-running request. r If the user navigates away from this page she may lose the link that enables the output to be delivered to her browser. As seen in the above example, the updateStatus macro is used to add an observation to a SAS data set. This is the data set that provides the status information that is displayed by the program discussed above. Here are the macro parameters:

ƒ

Msg the text of the message for the new observation to be added.

ƒ

statusDataSet the name of the STATUS data set. When you specify a value in the SAVE library, the value is available until the session ends, and is cleared by the Application Server when the session ends (as discussed in Section 10.2). The STATUS data set contains three variables: … the datetime the observation was added (obtained using the datetime DATA step function) … the message text (the value of this parameter) … a flag indicating the request (i.e., the spawned SAS session) has finished running.

ƒ

Done a non-blank value for this parameter specifies that the processing has finished running.

The macro source follows. As with all the macros included in the sample environment, this macro is not intended to be a robust implementation. Rather, it provides core functionality that you can update. %macro updateStatus (msg=, done=, statusDataSet= ); %if %length(&email) ne 0 %then /* do nothing as results being emailed */; n %else %if not %sysfunc(exist(&statusDataSet)) %then %do; /* status data set does not exist - create it */ data &statusDataSet; o format AsOf datetime. Status $256. Done $1.; Done = symget('done'); AsOf = datetime(); Status = symget('msg'); run; %end; /* status data set does not exist - create it */ %else %do; /* status data exists - add a new row */ data; /* use DATAn convention to generate name */ if 0 then set &statusDataSet; AsOf = datetime();

290 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Status = symget('msg'); Done = symget('done'); output; stop; run; proc append base = &statusDataSet data = _last_ force; run;

p

%end; /* status data exists - add a new row */ %mend updateStatus;

n Do nothing if there is a value for e-mail as that indicates that the user is to receive her results via e-mail. Embedding this logic here allows the long-running program to always call the macro regardless of whether the output it returned via e-mail or the browser refresh method. This is desirable, as it allows the user to control how she is to receive the output, while allowing the long-running program to handle either scenario transparently. o If the data set does not exist, create it with one observation. p Append the observation containing the updated status information to the STATUS data set.

19.3 The Sample Framework—Spawning a Separate SAS Session The examples presented in Sections 19.1 and 19.2 used the sample framework to spawn a separate SAS process for the long-running request. Unlike the technique presented in Chapter 18, a separate SAS session is asynchronously spawned by the Application Server to process the request. That separate SAS session executes independently of the Application Server Request Executive that spawned this SAS session. Thus the Application Server is immediately available and can accept new requests. The sample framework provides two different methods to spawn this separate SAS session:

ƒ

the SYSTASK statement, which issues an operating system command. The advantage of the SYSTASK command is that it is simple and requires no additional products. However, it may not scale well as too many SAS sessions can degrade overall performance, and it is not available on all SAS platforms, e.g., Z/OS. MP CONNECT requires that an additional product be licensed (SAS/CONNECT), but MP CONNECT works on all platforms and can take advantage of any additional processors on the server.

ƒ

MP CONNECT, which spawns a separate SAS session on the same SAS server that the Application Server is running on. Note: The X command cannot be used to start another SAS session since the Request Executive environment that is used by the APPSRV procedure does not support X commands. The sample framework for long-running programs contains four reusable components that you can use and modify to meet your requirements:

ƒ ƒ

The checkStatus source entry (discussed in Section 19.2.1) The updateStatus macro (discussed in Section 19.2.1)

Chapter 19: Handling On-Demand Long-Running Requests 291

ƒ

A source entry (spawnSAS.source) that sets up the environment for the separate SAS process. Figure 19.7 shows the logical flow illustrating how it works. Figure 19.8 provides a more detailed description for the process to create the actual program that will be executed by the separate SAS session.

ƒ

A macro (also called spawnSAS) is called by the spawnSAS.source entry. Its process flow is shown in Figure 19.9. The spawnSAS macro issues the operating system command to start the separate SAS session.

Figure 19.7 Process Flow—Set Up the Environment: spawnSAS.source Entry

292 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 19.8 Detailed Process Flow to Create the .sas File

Figure 19.9 Process Flow for the spawnSAS Macro

As seen in the examples presented in Sections 19.1 and 19.2, the program that was run using this approach looks like a typical Application Server program. There are only three requirements that the proposed framework imposes on the programs:

ƒ

The generated output should be written to the fileref _webout (the default behavior for any Application Server program).

Chapter 19: Handling On-Demand Long-Running Requests 293

ƒ

As illustrated in the example shown in Section 19.2, the updateStatus macro should be used to add an observation to the SAS data set that contains the current status information.

ƒ

Upon completion, the updateStatus macro should be called with a non-blank value for the Done flag.

Another example (shown in Figures 19.10 through 19.13) runs a program similar to the one run in Section 19.1 (invocations of the updateStatus macro have been added). This example allows the user to select whether he wants the results delivered by e-mail or by a browser refresh (if no email address is provided) as well as whether the separate SAS session is spawned with the SYSTASK command or MP CONNECT. To run the example in this section, go to the sample environment and select Chapter 19. Then select Spawn a new SAS Session.

Figure 19.10 Query User for Parameters for How to Run the Long-Running Program

294 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 19.11 Initial Display Informing User That a Session Was Spawned

Figure 19.12 Updated Display Informing User That the Requested Program Has Started

Chapter 19: Handling On-Demand Long-Running Requests 295

Figure 19.13 Results Displayed in User’s Browser Due to Automatic Refresh

19.3.1 Sample Program to Submit a Long-Running Program— spawnSAS.source The process flow for the spawnSAS.source program in the sample environment was shown in Figures 19.7 and 19.8 above. The spawnSAS.source program does the following things:

ƒ

sets up the environment to allow the requested program to be run by a separate SAS process

ƒ

invokes the spawnSAS macro (described below in Section 19.3.2) to start the separate SAS process

ƒ

depending on whether the user has chosen to be notified by e-mail or by having the browser display the current status, the spawnSAS.source program will take one of the following actions: … inform the user that the request has been submitted and that the results will be e-mailed … enable the display of the STATUS data set (using the checkStatus program discussed in Section 19.2.1)

296 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

This Driver program handles all four scenarios (e-mail vs. refresh and SYSTASK vs. MP CONNECT). The following logic is used to determine which scenario to use:

ƒ

If a value for e-mail is passed in from the request, it is assumed that the results are to be e-mailed. Otherwise, the user is kept up-to-date on the status by a refresh of the browser.

ƒ

If a non-blank value for MP CONNECT is passed in from the request, MP CONNECT is used to spawn the separate SAS process. Otherwise SYSTASK is used.

Note: The framework presented here can be extended to use different control logic. For example, the requestor may wish to be notified both by e-mail and a browser refresh. This would require a separate parameter that specifies notification by e-mail, refresh, or both. The spawnSAS.source code follows: %setDefaultValue(refresh,30) %global email MPConnect;

n

data _null_; rc = appsrv_session('create',&refresh*10); run;

o

%spawnedSASSessionBegin()p %let statusDataSet = save.jobStatus;

q

%updateStatus (statusDataSet=&statusDataSet, msg=Session Spawned r ) %saveMvars (data=nameValuePairs, saveFlag=Y, includeAuto=Y )

s

filename code2run "%sysfunc(pathname(save)).sas"; filename source catalog "&program2Run";

t

data _null_; infile source end=lr; file code2run; u if lr then put '%spawnedSASSessionEnd()' / 'endsas;'; if _n_ = 1 then do; /* generate setup statements */

v

put 'libname save "' "%sysfunc(pathname(save))" '";' / w "options sasautos=%sysfunc(getoption(sasautos));" / 11 '%restoreMvars(data=nameValuePairs)'; 12 if %length(&email) = 0 then 13 put 'filename _webout catalog "' "&_tmpcat" '.results.html";'; else put 'filename _webout email "' "&email" '" Subject="Emailed Results" CT="text/html";' / '%let _url = %completeBrokerName();';

Chapter 19: Handling On-Demand Long-Running Requests 297

end; /* generate setup statements */ input; put _infile_; 14 run; %spawnSAS 15 (program=%sysfunc(pathname(code2Run)), MPConnect=&MPConnect ) data _null_; 16 file _webout; if "&email" = " " then do; url = 'http://' || "&_srvname" || "%superq(_thissession)" || '&_debug=' || "&_debug" || '&_program=' || "%programName(pgm=checkStatus)" || 17 '&statusDataset=' || "&statusDataset" || '&refresh=' || "&refresh"; rc = appsrv_header('Location',url); put; /* blank line needed to force header to be generated */ end; else call execute ( '%externalHTML(type=catalog,source=saspress.template19.emailResults.source)' ); run; 18

n A default refresh value is specified using the setDefaultValue macro (Section 5.3.3). For requests where the results are not e-mailed, this parameter controls how often the page informing the user of status is updated. The %GLOBAL statement is used to make sure the control parameters exist with null values. o Create a session so that the SAVE library is available to store the STATUS data set as well as a data set to contain the name/value pairs from the request. p Call a user-exit macro so any needed set-up processing can be easily integrated by adding the needed logic to the spawnedSASSessionBegin macro. q A macro variable is used to specify the name of the STATUS data set. r Add a row to the STATUS data set stating that the session will be spawned. s Save all the name/value pairs from the request, including those set previously in the program, using the saveMvars macro (Section 10.3). The includeAuto option is set to non-blank to indicate that the automatic variables (i.e., those beginning with an _) are to be saved. The macro variable statusDataset is also saved. t Set up filenames for the requested program (only source entries are supported in this example) as well as a .sas file (stored in the SAVE directory) to contain the statements to be processed by the spawned SAS session. u Generate the .sas file containing the code to run. The name of the .sas file is the session name. The file is saved in the parent directory of the SAVE library.

298 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

v Call a user-exit macro to perform so any needed clean-up processing. Since additional requests are not handled by this process, generate an ENDSAS statement. w Prefix that code with the location of the SAVE library. 11

SET the sasautos options and the location of the macro auto call library.

12

Include a call to the restoreMvars macro (Section 10.3). The %restoreMvars macro call makes all the parameters available to the program that is run in the generated SAS session.

13

Prefix the code to be run with a FILENAME statement for _webout that, depending on how the output is to be returned, uses the e-mail access method to e-mail the results or uses the catalog access method to write the results to the &_tmpcat catalog in the SAVE library.

14

Copy the code from the specified source entry (&nextProgram).

15

The spawnSAS macro (discussed in Section 19.3.2 below) starts the separate SAS session. The location of the program to run and the method to use to initiate the separate SAS session are passed in as parameters.

16

The spawnSAS macro started the separate session asynchronously, so this DATA step executes immediately and either uses the location header (Section 8.2.1.1) to redirect the user’s browser to a program that updates him on the status of the program, or uses the externalHTML macro (Section 7.5.1) to inform him that the request has been submitted.

17

The programName macro (Section 5.4) is used to provide the value for _program (instead of hard-coding the library and catalog) that points to another entry, checkStatus, in the same catalog as the spawnSAS.source entry.

18

The current request finishes running, while the separate SAS session is processing the user’s request. The Application Server is thus available for other requests.

19.3.2 Sample spawnSAS Macro The spawnSAS macro starts the separate SAS session that runs the desired code. As with all the macros included in the sample environment, this macro is not intended to be a robust implementation. It provides the core functionality needed and you can update it as needed. In particular, this macro is specific to the Windows environment. When the starting of the separate SAS session is encapsulated into a macro (stored in a SAS autocall library) changing the macro so it is specific to the operating system is straightforward. Here are the macro parameters:

ƒ

Program the path to where the program is stored.

ƒ

Log used only by the SYSTASK option. This parameter supplies the path to where the SAS log should be written. If no value is specified, no log is written.

ƒ

MPConnect non-blank values indicate that the separate SAS session is to be an MP CONNECT session. The default is to use the SYSTASK option instead of MP CONNECT.

Chapter 19: Handling On-Demand Long-Running Requests 299

Note: The spawnSAS macro has been tested only on Windows systems using localhost. Before using the macro to start a SAS session on another host, your SAS license should be checked to see if that is allowed by the site’s SAS license agreement. %macro spawnSAS (program=, log=, MPConnect= ); %local sasexe; %let sasexe = %sysget(sasroot)\sas.exe;

n

options noxwait noxsync; %if %length(&MPConnect) = 0 %then Y %do; /* use systask to start a new SAS session */ %if %length(&log) = 0 %then %let log = -nolog; %else %let log = -altlog ""&log""; systask command """&sasexe"" ""&program"" -rsasuser -noterminal &log"; %end; /* use systask to start a new SAS session */ Z %else %do; /* use MP Connect to start a new SAS session */ options autosignon = yes; filename rsubcode catalog "&_tmpcat..mpconnect.source"; filename code2Run "&program"; data _null_; infile code2Run truncover end=lr; file rsubcode; if _n_ = 1 then put 'rsubmit '\ "%scan(%sysfunc(pathname(save)),-1,/\)" ' sascmd = "' %if %substr(&sysver,1,1) = 8 %then '""'; "&sasexe" %if %substr(&sysver,1,1) = 8 %then '""'; '" log = purge output = purge wait = no;'; input; put _infile_; s if lr then put 'endrsubmit;'; run; %include rsubcode;

t

u

%end; /* use MP Connect to start a new SAS session */ %mend spawnSAS;

q

300 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

n Assign a macro variable to be the command needed to start another SAS session. This will need to be adjusted based on the operating system and may need a custom SAS configuration file (e.g., if the default config file is used, there may be security issues with the location of the SASUSER library if the SYSTEM started the Application Server because the spawned SAS session will inherit those privileges. Y SYSTASK is used to start the additional SAS session using the .sas program file generated by the spawnSAS.source entry. Z If MP CONNECT is used the code to be run must have an RSUBMIT command at the beginning and an ENDRSUBMIT command at the end. The RSUBMIT command includes options that enable the additional SAS session to be run asynchronously. Note that if the UPLOAD procedure or the %sysput macro were used to provide the macro variable values, the spawned SAS session could not be run asynchronously. q Define a FILENAME statement so the code, including the SUBMIT and ENDRSUBMIT statements, will be written to an entry in the &_tmpcat catalog. \ Generate the RSUBMIT command. The last node of the SAVE library name is used to provide a unique value for the remote session ID. In SAS 8, the SAS command needs to be ® embedded in triple double quotes, while in SAS 9 only one set of double quotes is needed. s Copy the original program entry. t Generate the ENDRSUBMIT command. u Execute the generated code which has been wrapped with the RSUBMIT and ENDRSUBMIT commands to start the SAS session using MP CONNECT.

19.3.3 Sample Long-Running Program To run the example for the scenario described in Section 19.2, go to the sample environment and select Chapter 19. Then under Long-Running Request: Drill-Down Analysis, select Using SYSTASK (see Figures 19.14 through 19.17). The sample framework uses sessions (and the SAVE library) to pass information to the separate SAS session that creates the summary table. It then generates a link to the drill-down functionality available in the Xplore sample application (see Section 1.2.3). Xplore should be available as long as the Application Server has defined the location (i.e., the SAMPLIB proglib) of the Xplore sample application in a PROGLIBS statement.

Chapter 19: Handling On-Demand Long-Running Requests 301

Figure 19.14 Initial Display for Long-Running Request: Drill-Down Analysis

Figure 19.15 Updated Display—Program Is Running

302 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 19.16 Updated Display—Summary Process Completed

Figure 19.17 Drill-Down Using the Xplore Sample Program

Chapter 19: Handling On-Demand Long-Running Requests 303

The following sample program (which is run by the separate SAS process when Using SYSTASK is selected) runs the SUMMARY procedure and creates an output data set that can be passed to the drill-down facility in the Xplore sample application. A common application requirement is to provide functionality where a large data set is selected, perhaps with a WHERE clause applied, different statistics calculated in the summary process which is then used in drilldown analysis. Note that the initial step, creating the summary table, can be time-consuming. %updateStatus (statusDataSet = &statusDataSet, msg = Program &program2Run Beginning Execution ) data _null_; x = sleep(&refresh); run;

n

proc summary data=sashelp.shoes; o class Region Product Subsidiary; var Stores Sales Inventory Returns; output out=save.shoeSummary p (drop=_freq_ label='Shoe Sales') sum=; run; %updateStatus q (statusDataSet = &statusDataSet, msg = Summary Step Completed ) data _null_; x = sleep(&refresh); run;

n

%updateStatus (statusDataSet = &statusDataSet, msg = Processing Completed - Report Being Generated )

304 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher data _null_; r url = "&_url" || "?_service=&_service" || '&_server=' || "&_server" || '&_port=' || "&_port" || '&_sessionid=' || "&_sessionid" || '&_debug=' || "&_debug" || '&_program=samplib.websamp.mkdrlhtm.source' || '&dataset=save.shoeSummary'; file _webout lrecl=512; put '<SCRIPT>' / 'location.replace("' url +(-1) '");' / s '' ; run; %updateStatus t (statusDataSet = &statusDataSet, msg = Results from spawned SAS Session, done = Y )

n Use the Sleep function to simulate a long-running process. o Run PROC SUMMARY to create the summary table. In a real application the name of the data set, the classification variables, the analysis variables, and the summary statistic to calculate would likely be passed in as parameters. p The output data set is stored in the SAVE library so it is available for further analysis. q The updateStatus macro is used to update the STATUS data set so the user is told about the status of his request. r Generate a URL to reconnect to the session, passing the name of the summary data set to the Xplore drill-down programs. s The JavaScript location.replace function is used to redirect the browser to the Xplore drilldown program on the summary data set in the SAVE library. The SAVE library is available since the URL includes the session ID. The location header cannot be used since the browser refresh facility is being used to deliver the results to the user’s browser. t The updateStatus macro is called one last time to set the Done flag so the checkStatus program will display the generated output.

Chapter 19: Handling On-Demand Long-Running Requests 305

19.4 Doing More with Independent Sessions The framework described in this chapter can be used as-is to implement a facility for long-running requests. However, there are a number of enhancements that you may wish to consider before implementing the framework in your environment.

ƒ

Allow for the program (e.g., &program2Run) to be something other than a catalog source entry.

ƒ

Instead of assuming that the absence of an e-mail address implies that the user wants to be notified via a browser refresh, use an explicit parameter to control this behavior.

ƒ ƒ ƒ ƒ

Update the spawnSAS macro for other operating systems.

ƒ

Provide a location for the generated output so it can be access later via a URL (that can be e-mailed to the requesting user).

Allow the session time to be passed in as a parameter value. Enable the user to enter a description for the subject line for the generated e-mail. Provide a mechanism that keeps track of the number of currently running asynchronous SAS sessions. If the maximum number is currently running, the user can be informed (via a template) to try again later.

Check the sample environment for updates on supporting long-running programs via the Application Dispatcher. The techniques described in this chapter may meet your requirements for applications with ondemand long-running requests. However, for the most current techniques and Application Dispatcher features that address these requests, see the sample environment for examples. Spawning separate SAS sessions to handle long-running processes should be done with care. Too many such requests may seriously degrade the performance of all the applications, including the Application Server or servers, running on the server.

306 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

C h a p t e r

20

Using Metadata-Driven Reporting to Construct Reports 20.1 Introduction 307 20.2 Sample Implementation 309 20.2.1 The Logon Template 311 20.2.2 The Logon Program 312 20.2.3 Selecting the Case or Individual to Examine 315 20.2.4 Report Components 319 20.2.5 The assembleReport Macro 323

20.1 Introduction This chapter examines a sample application that provides a data review facility to enable various users to see relevant data and reports. While the example provided here is specific to patient reporting, the approach is broadly applicable. This example demonstrates the use of a sample framework that uses metadata to define and construct reports. This sample framework is not robust (e.g., it does very little error handling) and demonstrates the techniques presented earlier to facilitate the development of such applications. One of the keys to this is the use of small components, each of which performs a simple function.

308 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Here are some selected reporting requirements where the use of a framework like the one presented here might be useful:

ƒ

A clinical trials reporting environment, where the user may need to see patient demographics, visit history, treatment history, adverse events history, etc.

ƒ

A CRM environment where a call center representative might need to see the customer’s profile, current services, offer history, payment history, etc.

ƒ

A manufacturing environment where a quality control analyst might need to see the product history, information about the supplier of the raw materials, or details about the production line.

ƒ

A financial services environment, where a compliance officer might need to see summary and detailed information on transactions for a particular client or with a particular broker.

The reports are to be built from individual components, and those components can be combined depending on the user’s access level (i.e., what they are allowed to see). Certain report components are included in multiple reports. For example, the example presented here includes the patient’s demographics on every report. The reports are conceptually similar to a portal in that a single page is produced containing a variety of information about the selected entity (in this case, a patient). To run this example, go to the sample environment and select Chapter 20 and then select Metadata-Driven Reporting. See Figure 20.1 for an example report constructed using this framework.

Figure 20.1 Sample Metadata-Driven Report

Chapter 20: Using Metadata-Driven Reporting to Construct Reports 309

20.2 Sample Implementation The framework and example reports that are provided with the sample environment are built using the following components:

ƒ

Metadata that defines each report by listing the individual report components that it contains, as well as information about what groups of users are allowed to see each component of the report.

ƒ

The security model discussed in Section 12.3. There are any number of approaches to implemented security that can be used. You can replace the provided one with an alternative that better meets your requirements.

ƒ

A logon facility that captures the user ID and creates a session for the user’s reporting requests.

ƒ

The extending sessions feature discussed in Section 10.6, including a template that will automatically direct the user to the logon page if a session has timed-out because of no activity.

ƒ

A sample macro, assembleReport, which uses the metadata to build the report by calling all the component programs.

ƒ

A variety of sample reporting programs that perform specific functions.

The list of users and their assigned groups for the available reports in the sample environment are shown in Figure 20.2.

Figure 20.2 Users Mapped to One or More Groups

310 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Note: As discussed in Section 12.2, _rmtuser should be used if possible to identify the user. This example illustrates the alternative use of a logon page for these reasons:

ƒ ƒ

to demonstrate how it can be done using the SAS Server Pages facility (Section 7.6) since the sample environment cannot assume HTTP authentication is available and, therefore, _rmtuser cannot be used

The process flow for the framework is shown in Figure 20.3 and described below.

Figure 20.3 Metadata-Driven Reporting Framework Process Flow

1. The SASServerPage macro is used to generate a logon page. 2. A logon program checks the ID and password and if either is invalid, the logon page is redisplayed. 3. Otherwise, the following actions occur: 3.1 A session is created. 3.2 The metadata is subset to include only those report components or reports the user is authorized to see. This subset of the data is saved in the SAVE library created for the session. 3.3 The user is redirected to a page where she can select the individual or entity to be reviewed. 4. The report is assembled and displayed for the selected individual or entity. The generated report includes forms to allow the user to select a different report (if he is authorized for multiple reports) or a different individual or entity to report on.

Chapter 20: Using Metadata-Driven Reporting to Construct Reports 311

20.2.1 The Logon Template The first step in the process is to log on. The logon page is generated using the SAS Server Page macro discussed in Section 7.6 using the following template. Any number of logon pages (e.g., the structure and format) can be supported by adding new templates and making the appropriate changes. <TITLE>Logon - Metadata Driven Reporting Logon - Metadata Driven Reporting %global failed; n &failed o

Current Datetime: %sysfunc(datetime(),datetime.)

n The template may be called recursively and can include a message (the macro variable reference &failed) if the calling program sets it. The %global statement ensures the macro variable exists. o &_pgmlib is used instead of hard-coding the library for the program. This facilitates maintenance and re-use of the logon template. In a real application, the catalog would have a more descriptive name than chapter20. It can also be stored as a file in the file system. Z For your convenience only, the password is pre-populated into the template so that you do not need to know/remember the password to run the example. To run this example, go to the sample environment and select Chapter 20, which shows the Metadata Driven Reporting example. As seen in Figure 20.4, entering receptionist, nurse, or physician for the user ID and then clicking the Logon button causes the program to run.

312 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 20.4 Logon Screen Using Customizable Template HTML Page

20.2.2 The Logon Program As mentioned in the previous section, this step in the process accomplishes several things.

ƒ

Checks the user ID and password to make sure they are valid. Note that the sample code uses an IF statement to check the ID/password combination. In a real application, a more robust scheme should be used. The SCL approach discussed in Section 12.2.2 allows for flexibility and security in checking passwords. The user ID/password combinations can be stored in a password-protected SAS data set. The password for that data set can be provided by a macro variable reference whose value is provided when the SCL is compiled (also discussed in Section 12.2.2).

ƒ

If the user ID or password is not valid, the user is returned to the logon page so he can reenter his user ID and password (see Figure 20.5).

Figure 20.5 Invalid User ID/Password Combination Entered

Chapter 20: Using Metadata-Driven Reporting to Construct Reports 313

ƒ

Otherwise, the following actions occur: …

A session is created so the SAVE library is available.

…

The SAVE library is used for the user-specific subset of the metadata that defines the reports (and their components) that the user is authorized for.

…

The request is redirected to a page where the user can begin the process to select the data and the report she wants to review.

The logon program follows. %global userID Password;

n data _null_; if lowcase(symget('userID')) not in ('receptionist' 'nurse' 'physician') or symget('Password') ne 'paSSword' then do; /* invalid login */ call symput('failed','Invalid UserID/Password Combination'); call execute('%externalHTML(type=catalog,source=’ o|| ”&_pgmlib”||’.template20.logon.source)'); call execute('endsas;'); p stop; end; /* invalid login */ rc = appsrv_session('create'); q run; %let groups = "-NONE-"; proc sql noprint; /* determine the groups for this user */ r select distinct(quote(upcase(trim(group)))) into: groups separated by ' ' from sampdata.chapter20users where upcase(userid) = "%upcase(&userID)"; s quit; proc sql; rt create table save.layouts as select components.Type, components.Entry, reports.Layout, reports.Order, reports.newRow, reports.columns from sampdata.chapter20ReportComponents components, sampdata.chapter20ReportLayouts reports where upcase(components.group) in (&groups 'ALL') and components.componentKey = reports.componentKey order reports.Layout, reports.Order; proc sql; create table save.reportList as select * from u

314 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

sampdata.chapter20reportList where layout in (select distinct layout from save.layouts); quit; data _null_; file _webout; v url = 'http://' || "&_srvname" || "%superq(_thissession)" || '&_debug=' || "&_debug" || '&_program=' || "&_pgmlib..chapter20.assembleReport.macro"; rc = appsrv_header('Location',url); put; /* blank line needed to force header to be generated */ run;

n For simplicity, an IF statement is used to check the ID/password combination. A more robust scheme to validate such values is mentioned above. o If the entered combination is not valid, the externalHTML macro is used to display the logon template (originally displayed by the SASServerPage macro), with a custom message provided by the value of the macro variable (failed). p An ENDSAS statement is used to terminate the current request so the rest of the code to subset the reporting metadata for this user is not run. q A session is created so the SAVE library is available. r The logic for the example in Section 12.3 (customizing menu choices based on who the user is), with the data shown above in Figure 20.2, is used to subset the report metadata to include only the report components the specific user is allowed to see. s _rmtuser could be used instead of userID if there is no logon page. t This SQL step creates the report layout data needed by the assembleReport macro and stores it in the SAVE library for the session so that it is available to later requests. See Figure 20.6 to see this data for a user ID of nurse. The source data used here is discussed in Section 20.2.4 below. To learn more about PROC SQL, see the SAS documentation. u The list of reports is subset to include only those reports for which the current user is authorized to see at least one of the report components. It is also saved in the SAVE library for the session. See Figure 20.7. v The user is redirected to a page generated by the assembleReport macro (Section 20.2.5). The location header (Section 8.2.1.1) is used to do the redirect. The data sets created by the SQL step (corresponding to a user ID of nurse are shown in Figures 20.6 and 20.7. Note that the select layout is not included in Save.ReportList as, by design, it is not in the sampdata.chapter20ReportList data set. It is a default used by the assembleReport macro when no layout is specified (e.g., upon initial entry).

Chapter 20: Using Metadata-Driven Reporting to Construct Reports 315

Figure 20.6 Report Layouts for the Current User (nurse)

Figure 20.7 Available Reports for the Current User (nurse)

20.2.3 Selecting the Case or Individual to Examine The assembleReport macro is used with the select layout seen in Figure 20.6 as the default report (i.e., when the user first enters the reporting application). The select layout includes two customizable templates that can be displayed by the externalHMTL macro (see Section 7.5). The

316 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

selectKey.source entry contains the HTML form that allows the user to select the individual or entity as well as the report he wants to see. The overview.source entry includes a description of the reporting facility (e.g., it could serve as a Help page). This use demonstrates how the assembleReport macro can be used to combine components to assemble the page to be seen by the user, including components that are not reports generated from the data using ODS.

The sasServerPage macro could be used instead if only a single HTML template (e.g., the selectKey.source template) is to be displayed. The selectKey template is shown below. It contains the HTML that allows the user to select the key value for the individual to be examined. Consolidated Data Review as of %sysfunc(datetime(),datetime13.) for: %global Name_Key Layout; %generateOptionTag n o (data=sampdata.chapter20Demographics, var=Name_Key, label=Name, selected=&Name_Key) %generateOptionTag (data=save.ReportList, var=Layout, label=Description, selected=&Layout)

n For readability and formatting purposes, the calls to the generateOptionTag macro have been split across multiple lines. In the actual template, the complete macro call must be specified on a single line. o The generateOptionTag macro (Section 7.6.3) is used to generate the option tags that allow the user to select the key for the case or individual, as well as the report layout. The SELECTED argument shows the current value (if the template is called recursively). The reportList data set is the subset version in the SAVE library that includes only reports and report components the user is authorized to see. The second template, overview.source, contains a text description of the reporting framework that is to be included when the user enters the reporting application. Figure 20.8 shows the output produced when the assembleReport macro is called with this default report layout. When the user selects Lab History and then clicks the Review button, the output shown in Figure 20.9 is displayed.

Chapter 20: Using Metadata-Driven Reporting to Construct Reports 317

Figure 20.8 Initial Display—Select Patient with Overview or Help Text

The sample environment will be expanded to include reports other than the one shown here (see Figure 20.8) that can be produced from this facility. Download and install the sample environment (and check http://hcsbi.com/IntrNetAppDev regularly) to see these additional examples. Check the sample environment on the Web for updates.

318 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 20.9 Partial Output—Lab History Report

Chapter 20: Using Metadata-Driven Reporting to Construct Reports 319

20.2.4 Report Components Three metadata data sets that define the reports that are used to create the SAVE.Layouts and SAVE.reportList data sets are displayed in Figures 20.6 and 20.7. They can be seen using the data set paging facility discussed in Section 7.6. To run the example in this section, go to the sample environment and select Chapter 7. Select SAS Server Pages, and then select the SAMPDATA library. The results are shown in Figure 20.10.

ƒ

Chapter20ReportComponents is the list of available report components (see Figure 20.10).

Figure 20.10 Report Definition Metadata—Report Components

ƒ

Chapter20ReportLayouts is the data set that defines which components are included in each report and how they are laid out (see Figure 20.11).

320 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

Figure 20.11 Report Definition Metadata—Report Layouts

ƒ

Chapter20ReportList is the list of layouts that the user can select, depending on his level of access (see Figure 20.12).

Figure 20.12 Report Definition Metadata—Available Reports

Chapter 20: Using Metadata-Driven Reporting to Construct Reports 321

The example reports can be constructed by combining any of the eight listed report components seen in Figure 20.10. Two of the components are HTML templates which are processed by the externalHTML macro (corresponding to a value for Type of T) and the rest are programs (Type values of P) that generate HTML using ODS. The variable Group defines the security group the user must be part of in order to see the individual component. Figure 20.11 shows the report layouts data set that defines the reports that can be generated by the assembleReport macro. It has variables that define the following:

ƒ

which report layout it is and the component identifier (componentKey), which provides a link to the component as seen in Figure 20.10.

ƒ ƒ

the order in which the component is included in the report. two columns (newRow and Columns) that are used by the assembleReport macro to specify that the report component does not take up the full width of the page (i.e., if Columns has a value). For example, components 4 (printMeds) and 5 (printDiagnoses) are displayed in side-by-side panels. The field newRow is used to force the display of the component below the previous component (e.g., it forces a new report component row if the previous row contained multiple components).

The select layout, as discussed above, includes the component (componentKey=1, selectKey), which is the HTML template that allows the user to select which individual and which report is to be generated. It also includes another HTML template (componentKey=2, overview) which is a description of this metadata reporting framework. This is the default layout used by the assembleReport macro when the user first logs in. The selectKey entry is included in every report so the user can change the case or individual being examined, as well as the report contents, while reviewing any of the defined reports. Figure 20.12 lists reports that can be selected by the user as long as she is authorized for at least one of the components of a report. The function of this data set is to provide a more meaningful description to present to the user than the value of the layout variables. The logic used in the logon program (Section 20.2.2) results in including only report1 and report2 in this data set. The select component is not included in the pull-down list the user is allowed to select from. As discussed above, the select component is used as a default entry point for the assembleReport macro. The sample report shown earlier in Figure 20.1 (report1, which is Current Status) contains five components.

ƒ

The selectKey template (discussed above in Section 20.2.3) allows the user to select the individual as well the report to be displayed.

ƒ

The Demographics program (Section 20.2.4.1) is used to display the data for the selected case or individual and is discussed below.

ƒ

The following three simple programs (source available in the Chapter 20 catalog of the sample environment) that use a WHERE clause to subset the appropriate data sets to the selected case or individual are included next. Each program includes the ODS statements needed to produce the desired output. All three use the NO_TOP_MATTER and NO_BOTTOM_MATTER options in the ODS statement. …

printMeds

…

printDiagnoses whose output is displayed next to, rather than below, the output from printMeds

…

printCurrentLabs

322 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

The sample report shown above in Figure 20.9 (report2, which is Lab History) contains four components. The first two are the same components included in report1. The other two are (like the programs in report1) simple programs that use a WHERE clause to subset the appropriate data sets to the selected case or individual and use ODS to produce the desired output. Both use the NO_TOP_MATTER and NO_BOTTOM_MATTER options in the ODS statement

20.2.4.1 The dataReviewDemographics Program This entry is used to display the data for the selected case or individual. The program subsets the data and then loads all the values into macro variables. This allows a template to be used (with the externalHTML macro) to display the data. The use of macro variables embedded in a template HTML file gives great flexibility in formatting with none of the awkward quoting issues that would be encountered using PUT statements. The program follows. data _null_; n set sampdata.chapter20Demographics; where name_key = &name_key; array _n _numeric_; array _c _character_; do i = 1 to dim(_n); fmt = vformat(_n(i)); if fmt = ' ' then fmt = 'best12.'; call symput(vname(_n(i)),trim(left(putn(_n(i),fmt)))); o end; do i = 1 to dim(_c); fmt = vformat(_c(i)); if fmt ne ' ' then call symput(vname(_c(i)),trim(left(putc(_c(i),fmt)))); else call symput(vname(_c(i)),trim(left(_c(i)))); o end; run; %externalHTML (type=catalog, p source=saspress.template20.Demographics.source )

n A generalized DATA step that creates macro variables corresponding to each variable in the data set for the selected individual and should work for virtually any data set. o If a variable has a format associated with it, the format is used to create the value of the macro variables. These macro variables are referenced in the template discussed below. p Display the data using a template specific to the data set. Note: If you are familiar with the FSLETTER procedure, you may see similarities (i.e., the use of & references) between FSLETTER letters (which get their values directly from a data set) and the use of macro variables in this template.

Chapter 20: Using Metadata-Driven Reporting to Construct Reports 323

The template used by the externalHTML macro follows and is specific to the data set being displayed, chapter20Demographics. The data set can be viewed using the data set paging facility discussed in Section 7.6: &Name(&Name_Key) %iif((%length(&Sex)>0), | Sex:&Sex) %iif((%length(&Height)>0), | n Height:%sysfunc(int(&height/12))%str(%')%sysfunc(mod(&height,12))%str( %"))o %iif((%length(&Weight)>0), | Weight:&Weight.lbs) %iif((%length(&Height)>0 and %length(&Weight)>0), | BMI: %sysfunc(putn(703*&Weight/&Height/&Height,4.1))) o %iif((%length(&Birth_Date)>0), | Date-of-Birth:&Birth_Date) %iif((%length(&Last_Visit)>0), | Last Office Visit:&Last_Visit) %iif((%length(&Phone)>0), | Phone:&Phone) %iif((%length(&Insurance)>0), | Insurance:&Insurance, | Insurance:No Insurance on File)

n The iif macro (Section 7.3.1) conditionally generates labels for columns and values that may not have values. o %sysfunc is used to enable calculations within the template to generate values for display (i.e., BMI is calculated from Height and Weight; Height in inches is displayed in feet and inches).

20.2.5 The assembleReport Macro The last component of the sample framework is the assembleReport macro that uses the metadata data sets to define what individual report components are to be included in a specific report. It assembles the report by invoking each component in the appropriate order. If the report component does not take up the full width of the display (as defined in the metadata), HTML tables are used to display components side-by-side. The macro is provided in the sample environment and, as for all the other provided macros, is meant to provide you with sample code that you can use as the foundation of a more robust reporting tool. It includes a very simple (with limited functionality) ability to lay out report components and is not intended to be a robust report generation facility. Depending on your release of SAS there are a variety of options, e.g., the ODS document object, that you may wish to consider. %macro assembleReport; %local entries closeTable; %setDefaultValue(layouts,save.Layouts) %setDefaultValue(layout,report1)

n

proc sort data=&layouts out=_report; o where "%upcase(&layout)" = upcase(layout); by order; run;

p

ods html file = _webout(no_bottom_matter title=”Consolidated Data Review) style = &OdsStyle; ods html close; %let entries = 0; %let closeTable =0;

324 Building Web Applications with SAS/IntrNet: A Guide to the Application Dispatcher

data _null_; length putText $256; retain cnum '0 ' lastColumns; if lr then call symput('entries',cnum); set _report end=lr; type cnum call call

= upcase(type); = left(put(_n_,3.)); symput('type'||cnum,trim(upcase(type))); symput('entry'||cnum,trim(entry));

[

if lastColumns and (not Columns or newRow) then putText = ''; \a if (Columns and not lastColumns) or newRow then putText = trim(putText) || '