Administering the Application Server

• Server Invocation Parameters
• Supplying a Password When Starting the Server
• Using Server Administration programs
• Program Libraries
• Server Control Files
• Server Logging
• Creating an Icon to Run the Server (Windows only)
• Using a Script to Start the Server
• Multiple Application Servers Using the Same File System
• Development vs. Production Environments
• Using SAS/SHARE Software
• Launch vs. Socket
• Notes for Using the Application Server for MVS

Server Invocation Parameters

The Application Server is invoked by issuing an AF command within a SAS session. This can be done through the -initcmd option when invoking SAS or by submitting a dm statement as a SAS program. The syntax of the AF command is

af c=sashelp.web.appstart.scl port=port 
   srvroot='path-to-server-root-directory'
   <logwind> <debug=yes> <passwd=password>
   <resident=0>

The port= and srvroot= parameters are required. Both of these should have been determined during the installation of this software. The port is the TCP/IP port number on which the Application Server listens for requests, and the server root directory is where the server looks for the server control files.

The logwind parameter produces verbose output to the SAS log. Use this option when you are debugging Dispatcher programs. Turn off this option when you are not debugging to keep the SAS log from filling up with text. The debug=yes parameter should be supplied when debugging SCL programs. The passwd= parameter is described in the next subsection.

The resident=0 parameter turns off caching of SCL programs. This should be used when you are actively modifying SCL Dispatcher programs. Supplying this parameter will cause a decrease in server performance, but by loading the SCL program every time it is called, you will be able to view any program modifications. Without the resident=0 option, the default SAS behavior is to load each SCL entry from disk only the first time it is called. Better performance will result by omitting this option, however, the server will have to be restarted to view any modifications to the SCL programs.

Supplying a Password When Starting the Server

By default, any user with a Web browser can send a request to an Application Server and cause it to execute one of the administrative programs. Most of the time these special programs should only be executed by the Application Server administrator. If you wish to block users from running administrator programs, then you must supply a password when you start the Application Server. Then the administrator is required to supply this password in the _PASSWD variable each time he/she wants to run an administrative program. The value of the password cannot begin with a number. If it contains embedded spaces, then you must enclose it in quotation marks within the SAS/AF command. For example,

af c=sashelp.web.appstart.scl port=5001 passwd=foobar

af c=sashelp.web.appstart.scl port=5001 passwd="two words"

Using Server Administration Programs

The Application Server has a few built-in programs that instruct the server to perform special administrative tasks. Here is a table detailing the administration programs:

Command	Description
AUTOEXEC	Reruns the server autoexec file (srvauto.sas).
BREAK	If you started SAS software from DMS mode, this command interrupts the server and returns the SAS session to DMS mode. Otherwise, this interrupts and terminates the Application Server, similar to using ENDSAS.
ENDSAS	Interrupts and terminates the Application Server.
PERMDATA	Reruns the server permdata file (permdata.sas). Defines libnames that should not be cleared. These libnames should not be cleared because every program should have access to them.
PING	Executes a simple program that verifies that the Application Server is working properly.
RESET	Reruns the server reset file (reset.sas).

You can execute a Server Administration Program by supplying the name of the program in a Dispatcher request:

   http://myserver/cgi-bin/broker?_SERVICE=default&_PROGRAM=ping

If you started the Application Server with a password, you must supply the password to execute these programs. For example,

   http://myserver/cgi-bin/broker?_SERVICE=default&_PROGRAM=break&_PASSWD=foobar

Remember: If you do not start the Application Server with a password, any client can run the ENDSAS program and shut down your server.

Program Libraries

Program libraries are directories, partitioned data sets, or SAS libraries that contain Dispatcher programs. Each Dispatcher program must be placed in a program library before the Application Server can run it. One Application Server can access many program libraries. They are defined in the special server autoexec file, srvauto.sas.

Libname or filename statements can be used to allocate a program library. If a program library contains both .sas programs in external files and SAS catalogs, you do not need to issue both a filename and a libname to the same location. The Application Server automatically figures out during each request whether a libname or filename is needed and issues the appropriate statement.

It is an important security measure to segregate Dispatcher programs from their data. Dispatcher programs should not be placed in libraries along with the data they read and update. If your operating system allows you to set read and write permissions on specific directories, then it is recommended that the Application Server have only read access to all program libraries. Furthermore, it is best to allocate program libraries using the access=readonly option. If any programs need to create or update data sets or files, then read and write access must be allowed to those data libraries. Though the Dispatcher will function properly without these security measures, we advise you to follow these guidelines.

During startup the Application Server clears all previous allocated files and libraries. This means that any libname or filename statements in your SAS autoexec file will be cleared. Next, the server submits the code in the server autoexec file (srvauto.sas), which will assign the libnames and filenames to your program libraries. It records the paths to each of these libraries and clears them. When a request is made, the Application Server reassigns the reference to the particular program library needed. After the program has finished executing, the reference to its program library is cleared.

Server Control Files

The Application Server looks for the following server control files in the server root directory:

File	Description
srvauto.sas	This file contains SAS code that runs once at server start-up. Any libnames or filenames issued in this code are assumed to be libraries containing programs for execution. You should issue these libname or filename statements as read only and place the appropriate protection on these directories using the file system security available to you. You can run any application placed in one of these directories. The sample srvauto.sas program provided in the Application Server package contains a libname statement for the sample library. You may need to update the pathname for your installation.
permdata.sas	This file contains SAS code that issues libnames or filenames to data libraries, files, directories, or partitioned data sets that should be available to all applications. Normally, all libnames and filenames are cleared between server requests because an application may leave them assigned. The libnames and filenames issued in this file remain assigned for the duration of the server process.
reset.sas	This file contains SAS code that issues options, title and footnote statements, and other SAS statements that are executed between server requests. If you find that certain applications are leaving the SAS session in a state disagreeable to other applications, you can insert SAS code in this file to correct the problem.

To identify the server root directory, invoke the Application Server using the srvroot= parameter, as shown in the following examples:

• Starting the server in a running SAS session on UNIX:

      dm "af c=sashelp.web.appstart.scl port=5001 
          srvroot='/usr/local/lib/IntrNet/inetsrv'";
  

• Starting the server at a Windows command prompt or in a shortcut:

      D:\sas\sas.exe -config D:\sas\config.sas -dmsbatch
                     -initcmd "af c=sashelp.web.appstart.scl port=5001
                               srvroot='D:\sas\IntrNet'"
  

Make sure to enclose the path in quotation marks so it is interpreted as a single parameter, and be careful to use single quotation marks inside of the double quotation marks if you use a dm statement or -initcmd option.

The permdata.sas file is a convenient tool for the server administrator. By adding a libname or filename to it, you can be assured that all programs have access to that data. You may be tempted to put any and all libname and filename statements in this file because it is convenient. There are two pitfalls to this approach. It is a known problem of the Application Dispatcher that server libnames should not be issued in this file. See Using SAS/SHARE Software for details. Secondly, putting too many libnames and filenames in this file can slow the Application Server down. After running each Dispatcher program, the server must look through the list of allocated libraries and files and clear those that are not permanent. The more permanent libraries there are, the longer this lookup will take. This is most likely a minor concern if you keep the number of permanent data libraries under fifty. Ultimately, the amount of performance decrease is dependent upon your particular hardware, operating system, and the number of permanent data libraries.

Server Logging

If you want to log Application Server events, you need to include the -altlog SAS option when you invoke the Application Server. SAS software will create the log file or replace it each time the Application Server is started with this option.

The logwind parameter may be added to the command that starts the server to produce verbose messages in the SAS log window. Once you are sure that your installation works properly, you should remove the logwind parameter so that the SAS log window does not fill up.

A server command using the -altlog option and logwind parameter might look like the following:

   /usr/local/sas -dmsbatch -fsd ascii.vt100                  \
   -initcmd "af c=sashelp.web.appstart.scl port=5001 logwind  \
             srvroot='/usr/local/lib/IntrNet/inetsrv'"        \
   -altlog /usr/local/lib/IntrNet/inetsrv/appsrv.log

Note: Don't forget to use different names or directories for log files when starting more than one Application Server.

Creating an Icon to Run the Server (Windows only)

Under Windows, SAS/IntrNet software creates a Start Menu shortcut in The SAS System program group to start a default Application Server. You can copy this shortcut to create additional Start Menu or Desktop shortcuts for Application Servers.The shortcut should include the following information:

• the path to your sas.exe command
• the -config option for your SAS configuration file
• the -dmsbatch option
• an optional -altlog option to specify the log file
• an -initcmd command that runs the af command to start the Application Server:

  -initcmd "af c=sashelp.web.appstart.scl port=5001
            srvroot='C:\Program Files\SAS\IntrNet'"   

The complete command in your shortcut might look like this:

"C:\Program Files\sas\sas.exe" -config "C:Program Files\sas\config.sas" 
               -dmsbatch
               -altlog "C:Program Files\sas\IntrNet\appsrv.log"
               -initcmd "af c=sashelp.web.appstart.scl port=5001
                         srvroot='C:\Program Files\sas\IntrNet'"

You may want to check the box to run the Application Server minimized rather than in a normal window.

Using a Script to Start the Server

You can write a script that automatically starts your Application Server and runs it in the background. The following items should be included in the script:

• Invoke SAS software with the -dmsbatch and -initcmd options, followed by the AF command enclosed in quotation marks.

• If you created a new SAS configuration file during the installation, include a -config option on the command line and specify the full path to your configuration file.

• If your server runs in a UNIX environment, you can suppress any icons or windows by including the option -fsd ascii.vt100 and setting your DISPLAY environment variable to blank.

The following is an example script that you could use to start the Application Server on UNIX:

  
   export DISPLAY= 
   /usr/local/sas -dmsbatch -fsd ascii.vt100            \
   -initcmd "af c=sashelp.web.appstart.scl port=5001    \
             srvroot='/usr/local/lib/IntrNet/inetsrv'"

On Windows, your script would be very similar to the default Start Menu shortcut created at installation. It might contain the following:

  
   C:\Program Files\sas\sas.exe -dmsbatch
       -initcmd "af c=sashelp.web.appstart.scl port=5001   
                 srvroot='C:\Program Files\sas\IntrNet'"

For further information on SAS invocation options, consult the SAS Companion for your operating system.

Multiple Application Servers Using the Same File System

Running multiple Application Servers raises the same issues as running multiple SAS sessions. There is little to be concerned with if you set up each server on a different file system. However, quite often, multiple servers may be set up which access the same file system. This raises the general issue of file contention between the Application Servers.

Here are some guidelines to follow if you set up multiple Application Servers on the same file system:

• Servers can share a server root directory.

• Servers can share a single SAS configuration file, or they can have separate ones.

• Servers can share or have individual server control files (srvauto.sas,permdata.sas, reset.sas).

• Servers can share program libraries. Be sure to use access=readonly when allocating shared program libraries. This prevents an Application Server from opening SAS catalogs in update mode.

• Servers on the same machine must use different port numbers.

• Update access to data sets should be done through the use of SAS/SHARE software. If you do not use SAS/SHARE software and two users attempt to update the same SAS data set at the same time, then a failure will result.

• Because update access to files can fail due to operating system contention, Dispatcher programs should be prepared to handle such failures.

• Each server should write to a different log file.

Development vs. Production Environments

There are several tradeoffs that you will need to assess when administering Application Servers for both development and production levels of service. In general, the choices are between performance and security for production environments and the ease of use and ease of administration for development environments.

You can run Application Servers without passwords for users who are busy developing applications. This enables the users to handle some administrative tasks such as shutting down a server if needed. You may also find it is easier on the system administrator to allow any application developer to administer their own Application Server. This could also free up some of the load on centrally administered servers and improve performance. It is important, though, not to forget to employ the proper security measures for production, and especially for Internet-accessible environments.

Using SAS/SHARE Software

SAS/AF software has a default feature that causes SCL entries to be cached after the first time they are executed. This feature helps to improve performance. A program that repeatedly issues a statement such as call display('foo.scl'); runs faster because of this caching because SAS software only reads the catalog entry from its catalog the first time. After that, the SCL entry is resident in memory. This is a good feature for production environments because of the performance benefit; however, it is a deficit to development environments because SCL code cannot be updated. If the SCL entry is recompiled, the Application Server must be restarted before the new code will become active. To disable the caching, supply the parameter resident=0 in the command that is used to start the server. If you supply this option, then SAS software will reload each SCL entry from the catalog every time it is called. This will be a slight performance hit, but it will eliminate the need to restart the server when SCL code is modified and recompiled.

Launch vs. Socket

The two Dispatcher service types, launch and socket, provide a choice for processing Dispatcher programs. As you learn more about the software it will become easier to make the decision about which type of service to use. This section assists you in making those choices.

The primary difference between the two services is that a socket service reuses a server session, and a launch service provides a fresh server session that handles only that single request. The primary consideration that stems from this difference is that programs executed with a socket service can impact other applications attempting to use the same service. Many applications can use a single launch service without directly impacting one another because, with each click to submit a Web form, a new process is started to service that user. Because each request to a launch service is a separate process on the server side, they cannot directly impact one another. They can, however, indirectly impact one another through their demands on system resources.

At first it may appear that launch is the better choice because users will be more insulated from one another. However, there is no clear choice. Launch is better for some situations and socket is better for others.

One negative aspect of using launch is that there is currently no way to limit the number of server sessions that can be invoked. If 1000 users go to your Web site and click "submit" on a form using a launch service, your Web server will attempt to run 1000 brokers that will attempt to run 1000 Application Server sessions. This example is probably extreme for most sites and most applications, but it illustrates the effect of attempting to scale an application using a launch service.

A benefit to the socket service is that the server can run on any machine in your network. Launch can only start Application Servers on the Web server machine, the same machine where the Broker runs. Some sites need to restrict the resource usage on their Web server machines and will probably prefer to put the Application Server on a separate machine. Socket services accommodate this need.

Another important difference is that each Application Server is serial, meaning that it only handles one request at a time. If a socket service maps to a single server and that server is currently busy processing a request, each request sent to that server will wait. This essentially forms a queue of requests waiting for the same server port. If the number of requests is large or the length of time to process a request is large, then it is possible that some of the queued requests will time out. One way to handle this is to define a pool of servers as a single socket service and/or to increase the timeout value for the service. Comparatively, you can think of a launch service as a demand-driven pool of servers. The Application Dispatcher will do no queuing under launch (though the Web server might) and each user will be processed in parallel instead of sequentially. No user will timeout because of a long running program that was submitted before their request.

Some Dispatcher programs can take a long time to complete. This can be a problem when processed via a socket service. If a long running job ties up the server, then other users may not get served. It is important to note that the timeout set in the configuration file does not interrupt the Application Server. This timeout simply causes the Broker to exit and return an error message. The Application Server session will continue to process the job until it completes. Meanwhile, users with requests queued up would be receiving timeout messages. For this reason, the launch service is recommended for long-running Dispatcher programs. The socket service is recommended for short programs.

Launch services are much easier for the system administrator to support. Once a launch service is set up, the system administrator's work is complete, unless there is a need for changes in the configuration. Socket services map to Application Servers, which must be started up and left running. The disadvantage for system administrators is that they must make sure the Application Servers are started, and they must respond if they go down. The advantage for users is that they do not pay the cost of starting a SAS session. This is a big benefit to users, especially when the compute task is something that only takes a couple seconds. Each launch request must incur the additional time for starting a SAS session.

Lastly, the issue of development vs. production environments can also be an issue of launch vs. socket. The Dispatcher programs that the developers at your site are creating will be will be unstable and contain errors. Some errors can cause the server to get into an unrecoverable or undesirable state. If the server is a socket service, then multiple developers may be using it at once. One program's error could affect the server in such a way that another developer's program produces unexpected results. Application Server administrators may find themselves restarting the servers often and explaining to one developer how another developer's program was the problem. One solution to this is to have the program developers run their own Application Servers, as explained above, but that too may prove difficult to administer. A second alternative would be to encourage developers to use a launch service when developing Dispatcher applications. No matter how defective the behavior of a single program, it will not affect any other developers if a launch service is used.