Configuration File Directives

The required directives are listed below. For usage tips, see Using the Broker Configuration File.

Administrator Directives

Administrator name ServiceAdmin name: specifies the name of the person who is the administrator of the entire system or service. The name is passed to the Dispatcher program in the _ADMIN variable and is used in error messages.
AdministratorMail e-mail ServiceAdminMail e-mail: specifies the fully qualified e-mail address of the system or service administrator. The e-mail value is passed to the Dispatcher program in the _ADMAIL variable and is used in error messages.
BrokerPassword string: specifies a password to protect the administration interface. If the BrokerPassword directive is specified, you must supply the password to access the Broker Admin page (debug=4).

Debugging Directives

Debug flags ServiceDebug flags: specifies flags for debugging and output management. This directive can be overridden with the _DEBUG field. The default is 2 (indicates to display the status line and the Powered by SAS logo). See also List of Valid Debug Values.
DebugMask flags ServiceDebugMask flags: specifies the debug values that users are allowed to set. The default value for the DebugMask is 32767, which indicates that all debug values are allowed. If any debug values represent a security risk, you can selectively disable them by specifying a different DebugMask value, and then allow them only on certain services or for troubleshooting. See also List of Valid Debug Values.

File and Variable Manipulation Directives

Allow method-1 ...: lists the allowable values for the request method. This directive does not actually set the method. The method names are GET and POST. See also HTML Syntax Reference.
AppendFile filepath ServiceAppendFile filepath: specifies a file that is added to the bottom of every HTML page that is generated by your application. It can also be added to requests that generate errors in the Application Server. Note that this is a host pathname, not a URL. If you use this feature, your applications might not output the </BODY> and </HTML> tags, but most browsers allow this.
Export env-var sas-var ServiceExport env-var sas-var: specifies environment variables to be made available to Dispatcher programs. The sas-var is optional; if omitted, the SAS variable name is the same as the environment variable name (as long as it is a valid SAS name). Variables that do not begin with an underscore are subject to long-value splitting according to the field width. See also Exporting Environment Variables.
Language code: specifies the language used for error messages. The code is a two-letter language code. Currently only EN and FR are valid. The default is English.
PrependFile filepath ServicePrependFile filepath: specifies a file that is added at the top of every HTML page that is generated by your application. It can also be added to requests that generate errors in the Application Server. Note that this is a host pathname, not a URL. If you use this feature, your applications might not output the </BODY> and </HTML> tags, but most browsers allow this.
Set variable value ServiceSet variable value: specifies a variable to define on every request. This is similar to Export, but no environment variable is needed. This enables you to avoid hard-coding values such as the location of htmSQL in your applications. Values that do not begin with an underscore are subject to long-value splitting according to the field width.

General Service Directives

DefaultService: specifies the default service to use when no service name is supplied. DefaultService is the default.
Encrypt algorithm lib-path ServiceEncrypt algorithm lib-path: specifies the configuration file line that enables encryption. When this line is included for a service and the SAS/SECURE product has been installed, all data sent between the Broker and the Application Server will be encrypted by using the specified algorithm.
algorithm: is one of the values SASPROPRIETARY, RC4, RC2, DES, or TRIPLEDES. A special keyword NONE may be entered to disable encryption for a particular service.
lib-path: is the path to where the SAS libraries TCPDENCR.DLL, TCPDEAM.DLL, and TCPDCAPI.DLL (Windows) and TCPENCR and TCPDRSA/TCPDRSAI (all other platforms) reside, for example,
"C:\\Program Files\\SAS Institute\\Shared Files\\Secure".

Platform Notes

OS/390

lib-path is not used, but the path must be specified in an environment variable named STEPLIB.

Windows

You must install Microsoft Enhanced Cryptographic Provider Version 1.0 or later in order to use DES or TRIPLEDES.
The lib-path value is optional if SAS/SECURE is installed. The software automatically obtains the library location from the registry value:
HKEY_LOCAL_MACHINE\SOFTWARE\SAS Institute Inc.\Common Data\Shared Files.

LoadManager host:port ServiceLoadManager host:port: defines the host and port number for the Application Load Manager. The Broker attempts to connect to this host and port to request an available Application Server from the Load Manager. You can supply the DNS name (for example, APPSRV.YOURCOMP.COM) or IP address (for example, 127.0.0.1) of the machine for host. You can supply a numeric port value or a symbolic name that is defined in the system services file for port.
LocalAddress address: overrides the automatic determination of the local host IP address. Only specify this directive in special cases where the Application Server cannot connect back to the Broker host.
ServiceCompatibility version: specifies the Application Server version number, if not the current version. This directive is useful for transitioning between incompatible releases. It is not needed if Broker and the server releases match. For Version 6 and Version 7 of SAS software, set this value to 1.0.
ServiceDescription description: provides a long description for the service.
Set variable value ServiceSet variable value: specifies a variable to define on every request. This is similar to Export, but no environment variable is needed. This enables you to avoid hard-coding values such as the location of htmSQL in your applications. Values that do not begin with an underscore are subject to long-value splitting according to the field width.
Timeout seconds ServiceTimeout seconds: specifies the number of seconds that the Broker waits for a response from the Application Server. When the specified time elapses, the Broker returns an error message to the browser. If no global timeout is specified, then the timeout default is 60 seconds.

For OS/390 Only

ServerEncoding encoding ServiceServerEncoding encoding

defines the encoding used for data sent from the Broker to the Application Server and returned from the Application Server to the Broker. Use one of the following values for encoding:

ISO-8859-1 (Latin1): This encoding is recommended in all cases except those listed below. This value is the default.
ISO-8859-2 (Eastern Europe): This encoding is recommended only if your Web server and SAS system are using IBM-870 encoding.
ISO-8859-5 (Cyrillic): This encoding is recommended only if your Web server and SAS system are using IBM-1025 encoding.

Note that the body of the response from the Application Server (whether in HTML or another text format) defaults to the specified encoding but might be changed by the request program. For example, your request program might choose to generate a ISO-8859-1 response even if the ServerEncoding directive specifies a different value.

Service-Specific Directives

LaunchService

LaunchService name desc

begins a service definition and accepts two values: a name and an optional short description for the service. The name is used as the value for the _SERVICE field that is passed to the Broker from the HTML information in the browser. The name value is required.

Note: A launch on Windows NT systems does not work if you do not have the TEMP system variable set or if you do not specify -work on the SAS command line. Within the SAS configuration file, WORK is defined as

   /* Setup the default SAS System user the work folder */ 
   -WORK "!TEMP\SAS Temporary Files"

Because the Web server uses only system variables, if TEMP is not defined as a system variable, then WORK is not found and SAS does not start.

SasCommand command

specifies the SAS command and arguments that are necessary to invoke a new SAS session. It is usually the fully qualified path to your SAS executable file or a shell script. The argument SYSPARM must be included with the command. It must be specified at the end of the command as shown in the template configuration file delivered with SAS/IntrNet software. When you specify SasCommand on a Windows system, you must include the .exe extension for the SAS executable file.

LaunchService Directives for Previous Version Servers

InitCmd (Version 6 servers only): specifies the SAS statement necessary to invoke the Application Server. Do not include the PORT= argument, which is valid only with the SocketService.
InitStmt (Version 7 servers only): specifies the SAS statement necessary to invoke the Application Server. Do not include the PORT= argument, which is valid only with the SocketService.
SasBin command (Version 7 and Version 6 servers only): specifies the SAS command necessary to invoke a new SAS session. It is usually the fully qualified path to your SAS executable file. When you specify SasBin on a Windows system, you must include the .exe extension for the SAS executable file.
SasOpts options (Version 7 and Version 6 servers only): specifies the SAS command line options that are used to invoke a SAS session. You must include a -SYSIN file as one of your SAS options or the server will not start. This file must exist, but it is empty because the real input to the server session is supplied by the InitStmt directive.
TmpDir directory (in Version 7 and Version 6 LaunchServices only): specifies a directory (that must end with a slash) on the Web server machine (with read and write permissions allowed) where the application writes temporary files. All temporary files and directories, including the SASUSER and WORK libraries, log files, and other files used by the Broker and the server, are created in TmpDir. The directory value is passed to the Dispatcher application in the _TMPDIR variable.

PoolService

Note: You must specify a Load Manager before you use PoolService. Also, if the specified server is not on the same machine as the Load Manager, you must specify a spawner port to use.

FullDuplex True

indicates that the Broker and Application Server use only one socket for communication. Use this only with servers Release 8.1 or later because it will cause previous releases to hang.

IdleTimeout minutes

specifies the optional pool server timeout (in minutes). The default is 60 minutes. A value of 0 indicates immediate shutdown after processing the job. A server does not shut down until all sessions have expired.

MinRun value

specifies the minimum number of servers to keep running. This directive is optional.

Password string

specifies the optional password used with the Username directive to start a new server. If _PASSWORD is specified, the password is taken from the client _PASSWORD field. A password that starts with an exclamation point (!) character is assumed to be encrypted. This directive is valid only if you have specified a spawner port.

PoolService name desc

begins a service definition and accepts two values: a name and an optional short description for the service. The name specified for the service is used as the value for the _SERVICE field that is passed to the Broker from the HTML information in the browser.

Port port1 port1-port3

specifies the TCP/IP port number(s) or network service name(s) used by the Broker to send requests to the Application Servers. You can define multiple ports by separating their values with spaces or by issuing the Port directive multiple times. Numeric port ranges and symbolic names that are defined in the system services file are supported. A number less than 256 indicates a count of the maximum number of servers to start.

SasCommand command

Server host-1 host-2 ...

specifies the names of the physical machines on which the Application Servers are installed. You can supply the DNS name (for example, APPSRV.YOURCOMP.COM) or IP address (for example, 127.0.0.1) of the machine. This directive is required with the pool service. You can supply a value of LOCALHOST instead of a fully qualified DNS name if the Application Server is running on the same machine as the Web server.

SpawnerPort port

specifies the port on which the SAS Spawner is listening. The SAS Spawner is used to start new Application servers for this service. This directive is optional.

Note: Some of the SAS Spawner features cannot be used with pool services. For example, because the Load Manager does not support data encryption, the SAS Spawner cannot be started with -netencrypt or -netencralg.

StartAhead value

indicates how many SAS servers to start ahead of time when all current servers are busy. The default is 0. This directive is optional.

Username string

specifies an optional username used with the Password directive to start a new server. If _USERNAME is specified, the username is taken from the client _USERNAME field. A username starting with a ! character is assumed to be encrypted. This option is valid only if you have specified a spawner port.

SocketService

FullDuplex True

indicates that the Broker and Application Server use only one socket for communication. Use this only with servers Release 8.1 or later because it will cause previous releases to hang.

Port port1 port1-port3 ...

specifies the TCP/IP port number(s) or network service name(s) used by the Application Servers for this service. You can define multiple ports by separating their values with spaces or by issuing the Port directive multiple times. Numeric port ranges and symbolic names defined in the system services file are supported.

Note: For Pool Services, a number less than 256 indicates a count of the maximum number of servers to start.

Server host-1 host-2 ...

specifies the names of the physical machines on which the Application Servers are installed. You can supply the DNS name (for example, APPSRV.YOURCOMP.COM) or IP address (for example, 127.0.0.1) of the machine. This directive is required with the socket service. You can supply a value of LOCALHOST instead of a fully qualified DNS name if the Application Server is running on the same machine as the Web server. See also Enhancing Performance.

SocketService name desc

Begins a service definition and accepts two values: a name and an optional short description for the service. The name specified for the service is used as the value for the _SERVICE field passed to the Broker from the HTML information in the browser. The name value is required.

URL Directives

SASPoweredAlt text ServiceSASPoweredAlt text

specifies the alternate text used for the Powered by SAS logo image. This text appears while the image is loading, or if images are disabled or not supported, or in some browsers, when the mouse is held motionless over the image. The default is "SAS Institute Inc."

SASPoweredHref URL Service SASPoweredHref URL

specifies the destination URL, that is, where you go when you click the image. The default is HTTP://WWW.SAS.COM.

SASPoweredLogo URL ServiceSASPoweredLogo URL

specifies the location of the Powered by SAS logo image file. See also Displaying the Powered by SAS Logo.

SASPoweredTarget frame ServiceSASPoweredTarget frame

specifies the frame that is used for the hypertext link on the Powered by SAS logo. The default is no target. Any browser-supported target might be used, such as _TOP, which indicates to take over the whole browser window, _BLANK, which indicates to open a new window, _PARENT, which indicates to use the parent of the current frame, and _SELF, which indicates to use the current frame.

SelfURL URL

specifies the self-referencing URL that identifies the Broker program. The default value is the SCRIPT_NAME environment variable set by the Web server. The URL is passed to the SAS program in a macro variable named _URL.

Note: Normally you do not need to set SelfURL. SelfURL may be useful in the following situations:

if your Web server does not set the SCRIPT_NAME environment variable or sets it incorrectly.
if your site uses DNS load balancing with its Web servers. SelfURL can be used to specify the load-balanced Web server name instead of the particular Web server executing the Broker. For example, assume your company Web address HTTP://WWW.COMPANY.COM uses DNS to refer browser requests to one of five servers (WWW1.COMPANY.COM through WWW5.COMPANY.COM). A Broker running on WWW2.COMPANY.COM might have a default SCRIPT_NAME value of HTTP://WWW2.COMPANY.COM/SCRIPTS/BROKER.EXE. The SelfURL directive could be used to specify the load-balanced address HTTP://WWW.COMPANY.COM/SCRIPTS/BROKER.EXE instead.