Contents SAS/IntrNet 9.1: Application Dispatcher Previous Next

PROC APPSRV Statement

PROC APPSRV PORT=n <options>;
Option Definition
ADMINPW='password' The optional server administration password. This option does not have a default setting.
AFPARMS='string' An optional quoted string of parameters that are passed when invoking SAS/AF to run SCL programs. Users will pass AFPARMS='debug=yes' to invoke the SCL debugger.
AUTH=scheme The authentication scheme. The values that can be used with this option are HOST (denotes a secure Application Server), META (denotes a metadata server), or NONE. The default is NONE.
CHARSET=character-set-name appends the specified character set name to the HTTP content-type header for any text output.
ENCODING=encoding-name The default character-set encoding for all data sent to and received from the Application Broker.
GUESTP2='password' An optional second password to use for guest access.
GUESTPASS='password' The password to use for guest access.
GUESTUSER='username' The username to use for guest access.
LOCALIP=IP-address A manual override for GETSOCKNAME.
LRECL=n The logical record length for _WEBOUT and _GRPHOUT filerefs.
NETBUFFK=n The buffer size (in kilobytes) for _WEBOUT and _GRPHOUT output buffering.
NOCHARSET Disables any special content-type processing and reverts to existing SBCS behavior.
NOSHAREPOLL Disables polling of the SAS/SHARE server librefs.
PORT=n The only required option. The port number or name. Zero is used for dynamic ports. PORT=n does not have a default setting.
PROGRAMS=n The maximum number of requests that can run concurrently. The default setting is 1.
SHAREPOLL=n controls the period of SAS/SHARE server libref polling. The period is equal to n, which is a positive integer representing seconds. The default setting is 300 seconds (5 minutes).
UNSAFE='string' An optional list of characters that when used, enhances security by compressing name/value pairs.


PROC APPSRV Arguments

ADMINPW=password
allows the user to restrict access to specific administrator programs. The server has several built-in programs, such as STATUS and STOP. If ADMINPW is specified, the user must supply the password in the request (using the _ADMINPW variable) in order to run the STOP program. When the request is received, the server performs the following tasks:
  • verifies that the request is one of the administrator programs
  • searches the request data for the variable _ADMINPW
  • determines if the variable value matches the ADMINPW password that is specified in the PROC APPSRV statement
  • if it is a match, the request is returned; if it is not a match, the request is rejected.

In addition to built-in programs, the ADMINLIBS statement can be used to declare various librefs and filerefs as containing administrator-only programs. Programs in these libraries are not executed unless _ADMINPW is passed and is verified.

Note: If a libref or fileref has been defined in both a PROGLIBS statement and an ADMINLIBS statement, then the ADMINPW is not required for programs in that libref or fileref. General users will have access to programs that might have been intended only for administrators.

AFPARMS='string'
is a quoted string that is appended to the SAS/AF command when users invoke user programs that are written in SCL. It can be used to pass a variety of parameters to the SAS/AF environment, but the primary use in the Application Server is to enable the SCL debugger. To invoke the SCL debugger, compile your SCL program with debug on and then start the server with 
   AFPARMS='debug=yes'

AUTH=scheme
specifies the authentication scheme. The default scheme (AUTH=NONE without GUESTUSER being specified) causes all requests to be run with the credentials of the username under which PROC APPSRV was started. Specifying GUESTUSER (and the corresponding GUESTPASS) with the default AUTH=NONE scheme causes all requests to be run with the credentials of the GUESTUSER username. All access to catalogs, datasets, and external files are checked against this username. Note that the AUTH=HOST special requirements listed below also apply to AUTH=NONE when GUESTUSER and GUESTPASS are specified.

The AUTH=HOST scheme requires a username and password with each request, which will run using the credentials of the authenticated username. All access to catalogs, datasets, and external files are checked against this username. The username and password can be specified with the reserved variables _USERNAME and _PASSWORD (and optionally _PASSWORD2). The GUESTUSER and GUESTPASS (and optionally GUESTP2) options can be used to specify default values if they are not specified with the request. If the username is not specified by either the _USERNAME variable or by the GUESTUSER option, the request is rejected (unless the LOGIN option is used.) Usernames and passwords are saved with sessions, so requests that connect to an existing session do not need to and cannot specify a new username and password.

The AUTH=META option enables the PROC APPSRV statement to use a metadata server. The credentials passed in _USERNAME and _PASSWORD are validated against the metadata server instead of the host operating environment. META* SAS options must be set to valid values for AUTH=META to function. The GUESTUSER and GUESTPASS options are supported for AUTH=META.

The AUTH schemes do not apply to administration programs. Unprotected administration programs such as PING and STATUS can be run by any client without specifying a username or password. Protected administration programs such as STOP require only the _ADMINPW parameter (for more details, see the ADMINPW option). ADMINPW is required if AUTH=HOST is specified.

See the Special Requirements section for more information about the AUTH=HOST option.

CHARSET=character-set-name
appends the specified character set name to the HTTP content-type header for any text output unless the content-type was explicitly set by APPSRV_HEADER() or explicitly written to _WEBOUT by the SAS program. If CHARSET= is not specified, then the content-type header character set name will be determined from the _WEBOUT output encoding.

ENCODING=encoding-name
specifies the default character-set encoding for all data sent to and received from the Application Broker. This option is not normally required unless the Web server uses a different encoding from the one used by the Application Server. PROC APPSRV ENCODING defaults to the appropriate Windows encoding regardless of the platform. The default output encoding is automatically set based on the SAS session encoding. The SAS session encoding is normally determined by the locale setting of your SAS installation, but may be set directly using the SAS ENCODING option.

The following are the default Windows SAS encodings based on the Application Server's locale.

SAS Locale Default PROC APPSRV ENCODING
Western Europe and the Americas wlatin1
Eastern Europe wlatin2
Cyrillic wcyrillic
Japanese ms-932

Encodings whose names include a dash (-) must be enclosed in quotation marks (').

GUESTP2='password'
See AUTH. This option is used only in OpenVMS environments because OpenVMS can accept two passwords.

GUESTPASS='password'
See AUTH.

GUESTUSER='username'
See AUTH.

LOCALIP=IP-address
allows you to manually override the local IP address used by the Application Server. In rare cases, the local IP address returned by the operating environment is not usable, and a manual override is necessary.

LRECL=n
is the logical record length for _WEBOUT and _GRPHOUT filerefs. The default is 65535.

NETBUFFK=n
is the buffer size in kilobytes (KB) for _WEBOUT and _GRPHOUT output buffering. The buffer size must be a value between 4 and 128. Output buffering is disabled by default. Use of this option is not recommended without consulting SAS Technical Support.

NOCHARSET
disables any special content-type processing and reverts to existing SBCS behavior. This option cannot be used at the same time as the CHARSET= option.

NOSHAREPOLL
disables polling of the SAS/SHARE server librefs. This option cannot be used at the same time as the SHAREPOLL= option.

PORT=n
specifies the request socket for the Application Server.
  • If a numeric value other than zero is supplied, the value is used as the TCP/IP port number on which the server listens for requests.
  • If an alphanumeric value is supplied, it is assumed to be a network service name. The name is searched in the system services file (for example, /etc/services) and translated to a port number.
  • If zero is supplied, PROC APPSRV chooses an available port. This feature is used only for launch or pool services.

PROGRAMS=n
specifies the maximum number of requests that can execute concurrently. The default setting is 1.

Note: This option should not be used if PROC APPSRV is run in the SAS windowing environment.

SHAREPOLL=n
controls the period of SAS/SHARE server libref polling. The period is equal to n, which is a positive integer representing seconds. The default setting is 300 seconds (5 minutes). The SHAREPOLL setting should be interpreted as the minimum amount of time between polls of the SAS/SHARE server. SHARE polling has a lower priority than the servicing of client requests so in periods of high client activity the SHARE polling will be delayed beyond the period specified by n. The SHAREPOLL= option cannot be used at the same time as the NOSHAREPOLL option.

UNSAFE='string'
specifies a quoted string listing characters that should be stripped from values in the request data (the name/value pairs). This option is normally used to strip characters from input values that could cause unwanted SAS macro language processing.

The characters that users most often want to mark as unsafe are the following:

  • single quotation mark
  • double quotation mark
  • ampersand
  • percent
  • semicolon.

Because this list is enclosed by single quotation marks, you can represent a single quotation mark by placing two single quotation marks within the quoted string in the following manner:

   UNSAFE='&"%;'''

There are times, such as processing free-format text input, when you might want to use the original, complete value for an input name/value pair. The APPSRV_UNSAFE function can be used for this purpose. For example, the complete text of an input variable named MYTEXT can be accessed in a DATA step or SCL program with APPSRV_UNSAFE, as in the following:

   fulltext = appsrv_unsafe('MYTEXT');

The APPSRV_UNSAFE function can be called from macro with the %sysfunc function:

   %let fulltext = %sysfunc(appsrv_unsafe(MYTEXT));

Note: If you are using programs developed before Version 8 of SAS, you may need to omit the UNSAFE option for proper operation of your application. If the UNSAFE option is not specified, no unsafe processing is performed and all name/value pairs are passed unmodified to the request program.

Special Requirements for AUTH=HOST

Using AUTH=HOST on OpenVMS systems

The AUTH=HOST option requires that the account that is running PROC APPSRV must have SYSPRV privilege enabled to allow the server to verify login information. Note that all client requests will be rejected as invalid if the server account does not have this privilege.

Using AUTH=HOST on z/OS systems

The AUTH=HOST option requires that the SAS SVC routine be installed on z/OS systems. The SAS SVC control program routine is an interface between the z/OS operating environment and a specific request, such as third-party checking. This facility provides verification in the form of calls for authentication of both the user ID and password and of library authority. Perform the following steps before using the AUTH=HOST option.

  1. Install the SAS SVC routine, if necessary.

    • If you have already installed the SAS SVC routine for SAS 9.1, do not repeat the step here. If you need to perform the installation, see the installation instructions for SAS under z/OS for details.

    • Because SAS SVC 9.1 is backward compatible, it replaces the SAS SVC routines from previous releases. You can continue using previous releases of Base SAS and SAS/IntrNet or SAS/SHARE with SAS SVC 9.1.

  2. Verify the SAS options for the SVC routine.

    • You must verify that the SAS options for the SVC routine accurately reflect the way that the SAS SVC is installed. The SAS option SVC0SVC should be set to the number at which the SAS SVC is installed (for example, 251 or 109). If the SAS SVC is installed at 109 as an ESR SVC, set the SAS option SVC0R15 to the ESR code (for example, 4).

  3. Verify installation on all CPUs, as needed.

    • If you have more than one CPU, verify that the SAS SVC routine is installed on the systems that will be running the Application Server at your site.

Using AUTH=HOST on UNIX systems

The AUTH=HOST option requires that the SAS User Authorization utilities (sasauth and sasperm) be configured properly. See the section on configuring user authorization in the SAS 9.1 post-installation instructions for UNIX for more information on these utilities.

Using AUTH=HOST on Windows systems

The AUTH=HOST option requires special user rights on Windows systems. Review the following requirements carefully before enabling the AUTH=HOST option.


Contents SAS/IntrNet 9.1: Application Dispatcher Previous Next