Server Startup Command

An IOM server is a noninteractive SAS session that is run with the OBJECTSERVER system option. Depending on how the server is run, the startup command might be stored in a script, in the Windows registry, or in the SAS Metadata Server. Furthermore, in order to make it easy to specify the command, the server can be started using a simple command with an option to connect back to the metadata server to obtain additional IOM-specific options.

You can specify the server startup command in several different locations:

• on the system command line
• in a script
• in the Command field in the server definition (located on the Options tab of the server definition in SAS Management Console)
• in the Windows registry (for COM connections only)

The general form of the server startup command is:

SAS-exec -objectserver <other-system-options>
   -objectserverparms "object-server-parameters" 

• SAS-exec is the path to the SAS executable. The following table contains example values for SAS-exec:
  
  

  Location	SAS-exec
  system command line, script	Use the complete path to the SAS executable. Windows example: c:\program files\sas\sas 9.1\sas.exe UNIX example: /usr/local/bin/sas
  Command field in the server definition (located on the Options tab of the server definition in SAS Management Console)	Use the name of the SAS executable. The complete path is not needed. Example: sas
  Windows registry	Use the complete path to the SAS executable. You must use "8.3" (short) filenames. Example: c:\progra~1\sas\sas9~1.1\sas.exe

  
  

• -objectserver launches this SAS session as a server.

• other-system-options are other system options. System options that are typically used for servers include LOG, NOTERMINAL, and NOLOGO. For complete information about system options, see the SAS Language Reference: Dictionary.

• object-server-parameters are IOM-specific options that are passed to the server by the OBJECTSERVERPARMS system option. For more information, see Object Server Parameters.

Note: For SAS Workspace Servers that run on UNIX, it is sometimes necessary to call the SAS startup command using a wrapper script. For more information, see Initializing UNIX Environment Variables for Workspace Servers.

The server startup command is obtained as follows:

• When the server is started by a spawner, the startup command is stored in SAS metadata (SAS Workspace and SAS Stored Process Servers with IOM Bridge connection). In the SAS metadata, there is one metadata field for the SAS startup command and system options, and another field for the object server parameters. The object spawner combines these two fields, along with connection information and some spawner internal object server parameters, to create the complete SAS command. The object spawner then passes this command to the operating environment.

• When the server is started by a script or as a Windows service, or is launched by COM (that is, a SAS Workspace Server with a COM connection, any OLAP server, or any SAS Metadata Server), the command that is passed to the operating environment is not determined by SAS metadata. However, SAS Workspace Servers with a COM connection, and any OLAP server can connect back to the SAS Metadata Server in order to obtain additional object server parameters and connection information (such as protocol engine and port number). (Note that some object server parameters cannot be obtained from the metadata).

  When object server parameters are specified in the metadata, if there are any object server parameters that are also specified in the command, then the object server parameters in the command take precedence over those that are stored in the metadata. To enable the ability to connect back to the SAS Metadata Server for additional object server parameters and connection information, you specify the METAAUTOINIT and SERVER= object server parameters in the command. For more information, see Specifying Metadata Connection Information.

Regardless of how the server is started, SAS Workspace Servers (with IOM Bridge or COM connections), SAS Stored Process Servers (IOM Bridge only), and SAS OLAP Servers can also connect back to the SAS Metadata Server in order to obtain configuration information, such as preassigned libraries, that is associated with the SAS Application Server. For example, if the SERVER= and METAAUTOINIT object server parameters are used, then the workspace, stored process, and OLAP servers will preassign libraries that are associated with the SAS Application Server definition. For more information, see Specifying Metadata Connection Information.

The following table summarizes the ways that the SAS command, system options, and object server parameters can be specified for each type of IOM server.

Important Note: When you start the server with a script, some object server parameters cannot be obtained from the metadata. For details, see the "Can Be Fetched at Server Startup" column in the Object Server Parameters section. Do not enter these object server parameters in your metadata.

In the server startup command, you can provide the following information:

• SAS configuration file (required)

• Metadata Connection Information (required when you specify the METAAUTOINIT object server parameter to enable a connection to the SAS Metadata Server)

• SAS Autoexec File (optional)

• Logging Options (optional)

• Encoding and locale information (optional)

For a workspace server with a COM connection, see Customizing the Startup Command for Workspace Servers.

For workspace servers and stored process servers, see Preventing Conflicts over the SASUSER Library.

Specifying a SAS configuration file (required)

To initialize SAS options, you must specify a SAS configuration file using the CONFIG system option in the server command. For example,

SAS-exec -config "C:\Program Files\SAS\SAS 9.1\sasv9.cfg"

The SAS configuration file contains SAS options that are automatically executed when SAS is invoked. The default configuration is located in the SAS installation directory; you can also create your own configuration file.

Specifying a SAS Autoexec File (optional)

SAS-exec -autoexec "C:\Program Files\SAS\SAS 9.1\autoexec.sas"

A SAS autoexec file contains SAS statements that are executed as part of the SAS invocation. SAS autoexec files are particularly useful for pre-assigning librefs, filerefs, and macros. When multiple workspaces are used on the same server, each workspace inherits the server properties that are set by the autoexec file. Individual workspaces can override the properties that are inherited from the server by specifying new LIBNAME, FILENAME, or macro statements; however, these changes only affect the workspace where the new statements are submitted.

Note: Workspaces do not inherit the server WORK library that is used during autoexec processing.

To use a single autoexec file for both SAS sessions and IOM servers, you can set up conditional statements in your autoexec file. For example:

%macro autsetup;
%if %sysfunc(getoption(objectserver))=OBJECTSERVER
 %then
  %do;
      <IOM server autoexec statements>
  %end;
%else
 %do;
     <SAS session autoexec statements>
 %end;
%mend autsetup;
%autsetup;

Important: For some SAS 9.1 hosts, IOM servers process a SAS autoexec file implicitly if the file is stored in the default location. This might cause compatibility issues for existing configurations because IOM servers did not process autoexec files in previous versions of SAS. You can suppress this behavior by specifying the NOAUTOEXEC option in the server command.

For more information about the AUTOEXEC system option, see the SAS documentation for your operating environment.

Specifying Logging Options (optional)

To diagnose server problems, specify the -log and -logparm logging options in the server command. Additional IOM-specific logging is available by specifying certain object server parameters. These object server parameters can be used to control the type and amount of information that is logged. For example, IOMLEVEL=1 can be used to log all of the calls that are processed by the server. For details about object server parameters, see Object Server Parameters.

When you specify the logging options, you can also configure the server to create a different log for each process, or switch logs during execution.

The following command (specified in the Command field of the server definition) creates a unique log file (in the server user's home directory) for each instance of this server definition.

SAS-exec -log "test%v.log" -logparm "rollover=session"

In the preceding example, when the spawner starts the first server, a log named test1.log is created; when the spawner starts the second server, a log named test2.log is created.

For information about system logging options, see SAS Language Reference: Dictionary.

If you are having trouble creating a log, then start the server from the system command line and specify the TERMINAL system option to see if additional messages are shown. Doing so can help diagnose problems such as an invalid log file path or a permission problem that prevents the creation of the log file.

Note: Specifying logging options can cause performance degradation in your server; therefore, you should specify logging options only to diagnose problems with your server connections.

Note: If you specify a log destination in the configuration metadata rather than the startup command, then you might miss some messages that are generated before the log destination is set.

Encoding and Locale Information (Optional)

If your server metadata contains characters other than those typically found in the English language, then you must be careful to start your server with an ENCODING= or LOCALE= system option that accommodates those characters. For example, a SAS server that is started with the default US English locale cannot read metadata that contains Japanese characters. SAS will fail to start and will log a message that indicates a transcoding failure.

In general, different SAS jobs or servers can run with different encodings (such as ASCII/EBCDIC or various Asian DBCS encodings) as long as the encoding that is used by the particular job or server can represent all of the characters for the data that is being processed. In the context of starting a server, this fact requires you to review the characters that are used in the metadata that describes your server (as indicated by the SERVER= objectserverparm) in order to ensure that SAS runs under an encoding that supports those characters.

Preventing Conflicts over the SASUSER Library

When multiple workspace servers or stored process servers are launched for the same user ID, the separate processes share a common SASUSER library. To prevent access conflicts, specify the -RSASUSER system option to make the SASUSER library read-only. You can specify the -RSASUSER option in the server command or in a SAS configuration file.

Note that some client applications might assume that the SASUSER library is writable. For example, Enterprise Guide 2.0 makes this assumption by default. Others clients, such as Web applications that use pooling, can potentially launch many workspace processes that would conflict over SASUSER. In order to support the requirements of both types of client, you might need to define a different workspace server configuration for use with each type.