Contents SAS/IntrNet 9.1: Application Dispatcher Previous Next

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 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 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 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. 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 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 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\\SAS 9.1\\core\\sasexe".

Platform Notes

z/OS

Windows

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.

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 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 may 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 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 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 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
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. On UNIX systems, it is recommended that you use the -LOG /DEV/NULL option.

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 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 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 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 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 Application 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). 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.

Contents SAS/IntrNet 9.1: Application Dispatcher Previous Next