SAS/IntrNet 9.2: Application Dispatcher

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.
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.
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). 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 will also be added to requests that generate errors in the Application Server, but will not be 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 will also be added to requests that generate errors in the Application Server, but will not be 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 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 Application 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 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.2\\core\\sasexe".

Platform Notes

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 will be 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

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 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 timeout is specified, then the timeout default is 60 seconds.

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

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 Application Broker and the server, are created in TmpDir. The directory value is passed to the Application 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 Application 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 Application Broker from the HTML information in the Web browser.

Port port1 port1-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 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 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.

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.

Top of Page