Configuration File Directives

The required directives are listed below. For usage tips, see Using the Application 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 Application Dispatcher program in the _ADMIN variable and is used in error messages. For more information about _ADMIN, see the table in Reserved or Special Variables.

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 Application Dispatcher program in the _ADMAIL variable and is used in error messages. For more information about _ADMAIL, see the table in Reserved or Special Variables.

BrokerPassword string

specifies a password to protect the administration interface. If the BrokerPassword directive is specified, you must supply the password to access the Application Broker Admin page (debug=4).

ConnectionError "string"

ServiceConnectionError "string"

specifies the message to be displayed when there is an Application Server connection error. The directive can be specified in the configuration file on a global or service level. The message is not displayed for connection errors in socket service administration programs such as ping and status.

Debugging Directives

Debug flags

ServiceDebug flags

specifies flags for debugging and output management. This directive can be overridden with the _DEBUG field, which can be specified with a value or a keyword. The default is 2, or TIME (indicates to display the status line and the Powered by SAS logo). For more information about _DEBUG, see the table in Reserved or Special Variables. 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. The file is also added to requests that generate errors in the Application Server, but is not added when errors are generated by the Application Broker. 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 Web browsers allow this.

Export env-var sas-var

ServiceExport env-var sas-var

specifies environment variables to be made available to Application 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. The file is also added to requests that generate errors in the Application Server, but is not added when errors are generated by the Application Broker. 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 Web 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 hardcoding 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 algorithmlib-path

ServiceEncrypt algorithmlib-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 Application Broker and the Application Server is encrypted by using the specified algorithm.

algorithm

is one of the values SASPROPRIETARY, RC4, RC2, DES, or TRIPLEDES. A special keyword NONE can 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\\SASFoundation\\9.3\\core\\sasexe".

Operating System	Note
z/OS	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 has been installed. The library location is automatically obtained from the Windows registry.

LoadManager host:port

ServiceLoadManager host:port

defines the host and port number for the Application Load Manager. The Application 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.

Note: Any fields that are specified with host:port have to be changed to [host]:port if host contains a colon.

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 Application 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 the Application 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

Timeout seconds

ServiceTimeout seconds

specifies the number of seconds that the Application Broker waits for a response from the Application Server. When the specified time elapses, the Application Broker returns an error message to the Web browser. If no global time-out is specified, then the time-out default is 60 seconds.

The following directive applies to z/OS only:

ServerEncoding encoding

ServiceServerEncoding encoding

defines the encoding used for data sent from the Application Broker to the Application Server and returned from the Application Server to the Application Broker. This option is not necessary unless the Web server uses a different encoding from the one used by the Application Server. The default ServerEncoding is automatically set based on the Web server encoding. The server encoding must match the Application Server output encoding. The Application Server output encoding is normally determined by the locale setting of your SAS installation, but can be set directly using the PROC APPSRV ENCODING option. Use one of the following values for encoding:

wlatin1 (Western Europe): This value is the default in all cases except for when the Web server encoding is IBM-870 or IBM-1025.
wlatin2 (Eastern Europe): This is the default encoding when the Web server is using IBM-870 encoding.
wcyrillic (Cyrillic): This is the default encoding when the Web server is using IBM-1025 encoding.
ISO-8859-1 (Latin1)
ISO-8859-2 (Eastern Europe)
ISO-8859-5 (Cyrillic)
ISO-8859-15 (Latin9)

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 wlatin1.

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 Application Broker from the HTML information in the Web 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.

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 Application Broker and Application Server use only one socket for communication. Use this only with servers Release 8.1 or later because it causes previous releases to hang.

IdleTimeout minutes

specifies the optional pool server time-out (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 Application Broker from the HTML information in the Web browser.

Port port1port1-port3

specifies the TCP/IP port number(s) or network service name(s) used by the Application 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 user name used with the Password directive to start a new server. If _USERNAME is specified, the user name is taken from the client _USERNAME field. A user name 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 Application Broker and Application Server use only one socket for communication. Use this only with servers Release 8.1 or later because it causes 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 Application Broker from the HTML information in the Web 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 Web 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 Web browser-supported target might be used, such as _TOP, which indicates to take over the whole Web 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 Application 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. For more information about _URL, see the table in Reserved or Special Variables.

Note: Normally you do not need to set SelfURL. SelfURL might 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 Application Broker. For example, assume your company Web address HTTP://WWW.COMPANY.COM uses DNS to refer Web browser requests to one of five servers (WWW1.COMPANY.COM through WWW5.COMPANY.COM). An Application 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.