Creating Your Own Configuration File

To help you create your own configuration file, we have provided a configuration file template. You must modify the template file to create your configuration file. The template includes comments about each of the directives.

The instructions provided here and the comments provided in the template guide you through the creation process.

Guidelines for Creating a Configuration File

• Comments start with # as the first nonblank character.
• Because the Broker ignores leading spaces, you can include them to make the file easier for you to read.
• Line continuation is not supported. Each line of the configuration file must not extend beyond the first 256 columns.
• Quotation marks are required for values that contain blanks. You can use single or double quotation marks. Values that might require quotation marks are filenames and descriptions.
• If a configuration file entry accepts multiple values, delimit the values with spaces only.
• To specify a single quotation mark in a value, use \'.
• To specify a double quotation marks in a value, use \".
• To specify a single backslash in a value, use \\.

Hints for working with the template

• If an entry in the configuration file begins with #, activate that entry by removing the #.

• To complete an entry, delete or modify the text provided in the sample file, especially variables shown in uppercase. Replace this text with information that is valid for your site and installation.

Creating a Configuration File

Before you can use the Application Dispatcher, you must copy and modify the template configuration file to create your own configuration. The configuration file is part of the Broker; therefore, it is located in the same directory where you installed the Broker, which is the directory on your Web server for CGI programs. This directory is usually created during the installation of the Web server and is often called cgi-bin or scripts. (For documentation purposes, these instructions refer to your CGI directory as cgi-bin.)

To create your configuration file:

1. Copy the broker.cfg template that is provided in the package you downloaded.

2. Specify the global administrator information.

3. Complete one or both of the following two items:
   • Define at least one service. We recommend that you define a service named default. You can define as many other services as you need. After reading this basic information, you may want to review Enhancing Performance.

   • Define a launch service. Do this if you plan to send Broker requests that start a new SAS session, process the data, return results, and then exit that SAS session.

4. Optionally, specify the HTTP methods that you want to allow.

5. Optionally, set the default value for the _DEBUG option.

6. Optionally, restrict the flags allowed in the _DEBUG option using the DebugMask option.

7. Optionally, pass environment variables to Dispatcher applications using the Export directive.

Specifying the Self-Referencing URL

The self-referencing URL identifies the Broker program URL. Most of the time you will not need to set this value. The URL is passed to the SAS program in a macro variable called _URL. The Web server uses the SCRIPT-NAME environment variable to change the value of _URL.

You may need to change the self-referencing URL in the following situations:

• if your Web server does not set the SCRIPT-NAME environment variable or sets it incorrectly.

• if your site uses load balancing with its Web servers. For example, a site may have a Web server WWW.COMPANY.COM that dynamically refers all browser requests to WWW1.COMPANY.COM-WWW5.COMPANY.COM. In this situation, the self-referencing URL might direct the request to WWW2.COMPANY.COM/CGI-BIN/BROKER rather than to the original, load-balanced Web server. If all the company's Web servers used the Dispatcher, you could set the self-referencing URL to point to WWW.COMPANY.COM/CGI-BIN/BROKER, which would direct all requests to the load-balanced service to maintain the use of Web server load balancing with each page of the Dispatcher application.

Specifying Global Administrator

The global administrator is the designated contact for service definition requests and general Broker problems. You can specify a single person or a group of people. At least one administrator must have write access to the configuration file and understand the information required to define a service.

To specify information about the global administrator,

1. Locate the following two lines that appear near the top of the file:

   Administrator "Your Name"
   AdministratorMail "yourname@yoursite"

2. Replace Your Name with the administrator's name. This value can include spaces.

3. Replace yourname@yoursite with the fully qualified e-mail address for the administrator.

These two values become the macro variables _ADMIN and _ADMAIL in your Dispatcher program.

Defining a Service

The configuration file defines the services that are available for Dispatcher applications to use. A service definition identifies an installed Application Server and, if using the socket service, the TCP/IP port number that the Broker should use to send requests to that server. When you create the HTML portion for your Dispatcher applications, you specify the service name in the HTML to ensure that the Broker sends the processing request to the proper location.

Your configuration file can contain as many services as you need. You might include multiple services because you have:

• applications using the launch protocol and others using the socket protocol
• applications that access Application Servers running on different machines
• some applications that require that SAS software be invoked with different options or different autoexec files.

We recommend that you create a service named default. The service definition that we supply in the configuration file template defines a default service. The example Dispatcher applications included in the software packages use the default service.

You may have more than one of these sections, each defining a different service. You can create additional service definitions by copying and then modifying this default service definition.

Example SocketService definition:

SocketService default "Reuse existing session"
ServiceDescription "Pages reference this generic server when they don't care which service is used."
   ServiceAdmin "YOUR NAME"
   ServiceAdminMail "YOURNAME@YOURSITE"
   Server APPSRV.YOURCOMP.COM
   Port 5001
   ServiceTimeout 90

See the Configuration File Directives page for a description of all directives.

When creating SocketService definitions, the minimum information needed is

SocketService default "Reuse existing session"
   Server APPSRV.YOURCOMP.COM
   Port 5001

Although this example is sufficient, adding the remaining service directives makes the definition more understandable.

LaunchService newsas "Start a new 6.12 SAS session"
   ServiceDescription "Applications should use this service to start 
                 a new SAS session (release 6.12) on the Web server."
   ServiceAdmin "YOUR NAME"
   ServiceAdminMail "YOURNAME@YOURSITE"
   SasBin /pathname/sas
   SasOpts "-dmsbatch"
   TmpDir /tmp/
   InitCmd "af c=sashelp.web.appstart.scl srvroot='/pathname/IntrNet/inetsrv'"
   ServiceTimeout 60

Note: For Windows systems, include the .exe extension on the SAS executable and specify pathnames using the double backslashes as shown in the Windows configuration file template.

Optional Configuration Settings

You can control the following additional settings in the configuration file:

• HTTP methods
• Debug settings
• DebugMask settings
• Environment variables

Specifying HTTP Methods

The HTTP methods specified in the ALLOW directive are the two methods used by the HTTP server to pass information to the CGI program (Application Broker). The ALLOW directive merely lists the allowable values for the request method; this line does not actually set the method. The method names are GET and POST.

• GET tells the server to process the entire form as one long concatenated string of values appended to the URL. Using GET allows users to bookmark the resulting dynamic pages. However, the resulting page's URL can become very long and display variable information that you might prefer not to display.

• POST sends the form data in a long, input stream, which is not visible to users. Using POST is helpful when processing a large amount of data. However, users cannot bookmark the resulting pages.

To specify which HTTP methods the Broker should allow, locate the following line in the configuration file: Allow get post. If you want to allow both methods, leave the line as it is. If you want to allow only one method, delete the method that you do not want to allow. By default both methods are allowed so commenting or omitting the directive allows both GET and POST.

As stated, the ALLOW directive does not set the HTTP method. That is done in each HTML page that references the Broker. The author of the HTML portion of a Dispatcher application specifies either the GET or POST method in the HTML FORM tag, for example:
<FORM ACTION=<location of Broker> METHOD=POST|GET>.
For more information about designing the HTML input portion of a Dispatcher application, see Creating Dispatcher Applications.

Setting the Default Value of _DEBUG

If you are writing your own Dispatcher applications or are having problems with some of the samples we provide, you may want to specify a different default _DEBUG value. We set the default to 2, which will display the elapsed processing time, the Powered by SAS logo, and the Broker build number at the bottom of the Web page. However, you can set a different default value that will take effect if the _DEBUG field is not included in the HTML page. The config file directives Debug and ServiceDebug set the default values for the _DEBUG field on a global and by-service basis. To set them just follow the directive with the value you want as the default.

See the List of Valid Values for a current list of debug values.

Remember that you can set more than one debug option. Simply add the option values together. For example, to set both the 256 and 4 options, enter 260 as the value for Debug, DebugService, or _DEBUG as appropriate.

Restricting Value Allowed in _DEBUG with the DebugMask and ServiceDebugMask Directives

You can also specify the debug values that users are not allowed to set. The DebugMask and ServiceDebugMask directives are global and by-service directives that control this. Simply add together the debug values you want to allow and use that number in the directive.

The default value for the DebugMask is 32767, which is fine for most sites. The value 32767 indicates that all debug values are allowed. If you comment out the DebugMask option by maintaining the # sign in front of DebugMask, you are also allowing all debug values. Some debug values may represent a security risk, so you may want to selectively disable them here by specifying a different DebugMask value. Setting a different DebugMask value dictates the allowable values for the _DEBUG field in the HTML form or link.

For a chart showing another way of looking at the debug flags, see Disabling Debug Flags in the Reference section.

Exporting Environment Variables to Dispatcher Applications

The Web server makes essential information available to CGI programs as environment variables. You can pass some or all of this information on to your Dispatcher programs by using the Export directive. The syntax is

The Export directive instructs the Broker to retrieve the contents of the specified environment variable and make it available to Dispatcher programs in the specified SAS macro variable or SCL list item.

The sample configuration file includes several Export directives; activate a directive by changing the information to match your site and removing the # that appears at the left of the export line. Some Export directives, for example, Export REMOTE_HOST _RMTHOST, are activated by default, as they are not preceded by a # in the default configuration file.

If you omit the SAS name, the name of the environment variable will be used as the SAS macro name. Be sure to name the variable using eight characters or fewer or the Broker will return an error message.

If the value of the environment variable is greater than your field width (as set in _FLDWDTH), then the variable splits up like any field into multiple variables. You can avoid this by beginning SAS variable names with an underscore. Dispatcher variables that begin with an underscore are not split according to _FLDWDTH. These variables are truncated at 200 characters. Remember, the default _FLDWDTH is 80.

For ideas about what environment variables you might find useful in your Dispatcher applications, see the list of Common Environment Variables.