Dispatcher Program Details

• Types of programs
• Program libraries
• Data libraries
• Accessing name/value pair data
• Producing output
• Debugging

Types of Programs

There are four types of Dispatcher programs. They are

• a SAS program
• a source entry
• a compiled SCL entry
• a stored compiled macro.

Each of the programs must be stored in a Dispatcher program library.

SAS programs are stored in external files and must have a .sas filename extension. They can contain DATA step, procedures, and macro code. This is the only program type not stored in a SAS catalog, and the program name is case sensitive if the Application Server host is case sensitive. The proper query string syntax for specifying a SAS program is

_program=library.program.sas

Source programs are stored in SAS catalog entries ending in .source. They can contain the same code as .sas programs. The program names for source programs are not case sensitive. The proper query string syntax for specifying a program of this type is

_program=library.catalog.program.source

SCL programs are stored in SAS catalog entries ending in .scl. They contain Screen Control Language (SCL) code that must be compiled. If this program type is not compiled, it could halt the Application Server. The program names for SCL programs are not case sensitive. The proper query string syntax for specifying an SCL program is

_program=library.catalog.program.scl

Macro programs are stored in SAS catalog entries ending in .macro. They consist of compiled SAS macro language statements. These programs can be created with the store option in the %macro statement along with the SAS option sasmstore= to indicate a library. Names for macro programs are not case sensitive. The proper query string syntax for specifying a macro program is

_program=library.catalog.program.macro

SAS software automatically creates stored compiled macros in a catalog named SASMACR. The Dispatcher allows you to copy these macro entries to any catalog name and run them. They do not have to be in a catalog named SASMACR for the Dispatcher to access them.

Program Libraries

Program libraries are segregated areas where Dispatcher programs are stored. They are special because they are the only locations from which the Dispatcher is allowed to execute programs. The Application Server control file srvauto.sas defines the program libraries at the server startup. SAS libnames or filename statements issued in this server autoexec file allocate the program libraries.

In preproduction releases of the Application Dispatcher, it was possible to submit a libname statement in open SAS code before invoking the server and it would define a program library. This feature has been disabled. Now all program libraries must be defined in the server autoexec file (srvauto.sas).

Dispatcher programs stored in .sas files and those stored in SAS catalogs can be accessed via libname or filename allocations. This may seem strange because SAS software only allows catalog access through libnames and file access through filenames. However, the Application Server is sensitive to the type of program requested by the Web browser, and it will automatically issue the proper filename or libname to access the program. This means if you have some SAS programs stored in files in the same program library with some SAS catalogs, you simply issue one libname or filename statement to that path. After executing the server autoexec file, the server clears all libnames and filenames. Only when a request is made does the server reassign a handle for the library. At that time the proper libname or filename statement is used. For more information, see Administering the Application Server.

Data Libraries

Data created or used by Dispatcher programs should not be stored in program libraries. It is a security risk to store programs in the same location as their data. The suggested method for access data from a Dispatcher program is to issue a libname or filename statement in the Dispatcher program code. After the program has completed, the Application Server will clear any libnames or filenames that the program has left assigned.

Sometimes there may be the need to have certain libnames or filenames permanently assigned for the duration of the server session. Perhaps a library that contains employee data is accessed by many separate applications. It would be convenient if each application did not have to issue the libname statement. This is the purpose of the permdata.sas file. This server control file contains libname and filename statements that will not be cleared after each program is executed. Thus, each Dispatcher program can assume these librefs and filerefs are always available automatically. For more information, see Administering the Application Server.

Accessing Name/Value Pair Data

The name/value pair data provided by the HTML form are sent to the Dispatcher program and made available as macro variables. The Dispatcher creates these variables, assigns their values, and clears their values after the program has completed. The name/value pair data are also supplied in an SCL list to SCL Dispatcher programs.

Application developers must write their Dispatcher program to accept the proper macro variable names. The macro variable values can be obtained by direct reference (for example, &var) or by using one of the following:

• the SYMGET function of the DATA step
• the SYMGET, SYMGETC, and SYMGETN functions in SCL.

For example, if the HTML name/value pair for a text entry field is color/blue, all of the following store the value blue in the DATA step variable color:

color="&color";
or
color=%superq(color);
or
color=symget('color');

We recommend that you do not use the first method because it is a security risk. The second method is slightly more secure but also a potential problem. If you intend to use the values in a DATA step, the SYMGET technique is the safest because any special characters contained in the value will not be "seen" by the SAS syntax scanner. Using a reference like &var should be avoided! For additional information about security issues, see Security.

Because all macro variables are a character data type, some extra processing is required in DATA step code if the value will be stored in a numeric variable:

age=input (symget('age'),12.);

If the Dispatcher program is written in SCL, you have another option for accepting the variable values. An SCL list is passed to each Dispatcher program written in SCL. Therefore, each SCL program must contain the following code statement or it will fail when the Application Server invokes it:

     entry inputlist 8;

The input list contains named character items that correspond to the macro variables created. If your program is written in SCL, you can use either the input list or macro variables. To access the same name/value pair as above, a statement like this can be used:

  color=getnitemc(inputlist,'COLOR',1,1,'');

As with the macro variables, this SCL list is cleaned up by the Application Server when the Dispatcher program completes.

The Dispatcher automatically creates several variables based on the program request and various information in the Broker configuration file. These automatic variables are available to your program as macro variables and SCL list items. For a complete list of these automatic variables, see the sections Common Environment Variables and Special Dispatcher Fields under Dispatcher Reference.

Producing Output

All output created by Dispatcher programs must contain an abbreviated HTTP header. This header is everything from the beginning of the output up to the first null line. Here is some example output, including the header:

Content-type: text/html
Pragma: no-cache

<HTML>
<HEAD><TITLE>Application Server Administrative Program</TITLE></HEAD>
<BODY>
<H1>Administrative Program</H1>
<P>The application server has been shutdown.</P>
<HR>
</BODY>
</HTML>

In this example, the HTTP header contains two lines. The minimal requirements for Dispatcher output are that the header contain Content-type: or Location:. The null line that terminates the HTTP header is important. It can be created with a statement like this:

put ;

This, however, is incorrect

put " ";

because it produces a line containing one blank followed by carriage control. A line with one blank is not a null line and will not be recognized as terminating the header.

The output that follows the HTTP header depends upon the content type. If Location: is used, then no output follows the header because this header will trigger the browser to redirect to another page. The most common type of output is, of course, HTML. The HTML source for the Web page follows the header when the content type is text/html.

No matter whether the program output is plain text, binary graphics, HTML code, or any other content type, all output intended for the Web browser should be sent to the fileref _WEBOUT. This special fileref is actually a TCP/IP socket connection to the Broker. Sending output to this socket will stream it back to the browser. Think of the socket like a pipe through which data flows. Because it behaves in this way, the fileref _WEBOUT is in a permanent append mode. There is no concept of writing something to _WEBOUT and then reopening the fileref and overwriting the previous output. It all gets appended. Therefore, the mod parameter should not be used (and is actually not allowed) in any file _webout statements.

The HTML Formatting Tools will likely be used for the bulk of any Dispatcher program output. There are some important guidelines to follow when using the Formatting Tools in a Dispatcher program.

• The Output Formatter and Tabulate Formatter operate by a capture on/capture off mechanism. Do not forget to turn capturing off before the program completes. Each capture=on needs to have a corresponding capture=off. The Application Server is not guaranteed to turn these tools off for you.

• Use runmode=s with each of the tools. This runmode value designates that the tools are running in server mode. If openmode=replace is used along with this run mode, then the tools will generate a Content-type: text/html header automatically.

• Use openmode=replace if this call to one of the tools will be creating the first output from this program. This open mode will cause the formatting tools to generate the header (if runmode=s), the HTML head section of the document, and body tags.

• Use openmode=append if this call to one of the tools will not be creating the first output from this program. If the program has already produced some output then it has already supplied the content type header and most likely the HTML head section, as well.

The Application Dispatcher is a very flexible programming environment because it provides procedures and tools that automatically generate output, but it also allows exact control of the output. Many SAS programmers have encountered the situation where they want to generate completely custom output. This is often done by using the DATA step and PUT statements. The Dispatcher technology supports PUT statement reporting and allows you to supplement such reports with powerful procedures and Formatting Tools.

Debugging

There are three techniques for debugging Dispatcher programs:

• returning the log to the browser
• DATA step debugger
• SCL debugger.

Returning the log to the browser

Passing a name/value pair of _debug=128 to the Dispatcher will cause the SAS log to be returned to the Web browser. This is very useful because most errors will show up in the log. The Dispatcher will highlight them in red. If the code that you are debugging contains macro statements, it will help to turn on various options such as mprint, symbolgen, and/or mlogic. Sometimes the Dispatcher will return an error message that suggests to send a debug value of 131. This is the values 1, 2, and 128 combined. See the Debug Flags section for a complete list of debug values.

DATA step debugger

To use the DATA step debugger, you must start the Application Server in full-screen mode, and you must be working on the computer where SAS software will display the debugger windows. At the server startup, the logwind parameter must be added to the AF command. To debug a DATA step, simply add /debug to the DATA statement, like this:

data mylib.mydata/debug;

When the server executes the program, the DATA step debugger windows will pop up and pause, waiting for you to step through the code.

SCL debugger

To use the SCL debugger, you must start the Application Server with the logwind and debug=yes parameters. The SCL program that you wish to debug must be compiled with the debug option. The Application Server must be run in full-screen mode, and you must be working on the computer where SAS software will display the debugger windows. When the server executes the SCL program, the debugger windows will appear and allow you to step through the code.

For more information on Application Server invocation options, see Server Invocation Parameters.