Chapter 3 Creating and Configuring Servers

Configuring a server

To configure or modify the properties of an individual server:

From within Jaguar Manager, display the list of installed servers by double-clicking the Servers folder.
Highlight the server you want to configure.
Select File | Server Properties. You see the Server Properties window, which contains these tabs:
- General - define general individual server properties.
- HTTP Config - determine browser accessibility.
- Transactions - determine the transaction coordinator for components that participate in EAServer transactions.
- Security - see "Administration password and OS authentication" for security options accessible from this tab.
- Resources - define the maximum number of client connections.
- Log/Trace - set logging and trace options.
- Handlers - define individual server event handlers.
- Naming Service - set the server's naming service options. See Chapter 5, "Naming Services" for additional information.
- Servlets - disable servlet execution in EAServer and configure additional properties to control the execution of servlets.
- PowerDynamo - enable hosting of PowerDynamo Web sites in EAServer.
- Hot standby - Enable hot standby and define the master and backup servers.
- JAXP Support - configure Java API for XML Parsing support.
- Java Classes - specify classes to include in the server's run-time JAR file.
- JPDA - specify the port number for remote debugger connections.
- Static Page Caching - enable caching for static pages.
- HTTP Custom Headers - define custom headers for HTTP responses.
- All Properties - edit server property settings in their raw format, that is, as they are stored in the configuration repository.

If you modify any property, click OK in the Server Properties sheet to save your changes, or click Cancel to disregard the changes.

When you modify server properties, you must refresh the server for the changes to take effect. To refresh the server, highlight the server icon and select File | Refresh.

General

Table 3-3 describes the general properties that you can configure for individual servers.

Table 3-3: Server general properties
Property	Description	Comments
Description	Enter a description of the server, up to 255 characters in length.
Codeset	Specify the character set used by the server.	By default, the server uses iso_1.
Classpath	Displays the contents of the CLASSPATH environment variable for the server that you are connected to. This setting specifies the directories from which Java class files can be loaded. It is defined by the start-up script when you start the server. CLASSPATH does not display for servers that you are not connected to.	This setting is read-only and helpful for debugging various errors. To change the value, you must reset the environment variable and restart the server.

HTTP Config

Clients can access EAServer and retrieve HTML pages using a Web browser. You can customize certain aspects of your server's HTTP behavior by modifying the HTTP configuration properties listed in Table 3-4.

Table 3-4: HTTP properties
Property	Description	Default value	Comments/example
Domain Name	Domain name in .company.xxx format.	N/A	.sybase.com
Document Root	The path to the directory where documents are served.	$JAGUAR/html (UNIX) %JAGUAR%\html (Windows)	/work/WWW/ C:\work\WWW\
Default Web Application	The default Web Application.	None.	The Web application must be installed in the server. When specified, clients requests are redirected to the Web application context. For example, if the default Web application is MyWebApp, requests for `http://myhost:8080` are redirected to `http://myhost/MyWebApp` , and the welcome file is used.
Web Application Partial URL	Identifies the resource to load for the default Web application.	None.	If the partial URL is myServlet and the default Web application is MyWebApp, requests for `http://myhost:8080` are redirected to `http://myhost:8080/MyWebApp/myServlet`
Maximum Threads	The maximum number of threads allocated for HTTP requests. WARNING! If you increase this value, you must also increase the maximum number of threads on the Resources tab. See "Resources" for more information.	25	The maximum thread setting allows you to balance memory resources. A maximum value set too high needlessly uses memory resources. Monitor the total number of hits listed in the httpstat.dat file for indications of a heavily loaded server. Adjust the maximum thread setting as necessary.
Keep Statistics	Select to log statistics.	Disabled.
Statistics File Name	If you select to keep statistics, specify the log file name.	Jaguarhttpstat.dat	/work/logs/Jaguarhttpstat.dat (UNIX) C:\work\logs\Jaguarhttpstat.dat (Windows)
Frequency (Seconds)	If you select to keep statistics, specify how often to log them.	36000 seconds (10 hours)
Log Type	You can select All Logs or one of these log types: Request log Servlet log Error log	All Logs	If you select All Logs, the directory, file size, and truncate options apply to all the log files.
Enable Logging	Select to enable logging.	By default, logging is enabled.
Log Directory	The directory where the log files are stored.		See "HTTP logging and statistics" for information about the log files.
Log File Size	The size, in bytes, to which the log file grows before it is truncated.	Unlimited. If you do not enter a value, log size is unlimited.
Truncate Log on Startup	When this flag is set, the log truncates every time the server is restarted.	The default is to not truncate on start-up.	Keep in mind that if the server crashes and this flag is set, you will lose the log file and the information it contains.
Extended Log File Format	If enabled, EAServer writes to the Reguest log using the extended log file format, instead of the common log format.	Disabled. By default, common log format is used for the request log.	If enabled, the com.sybase.jaguar.server.http.elffitems property determines what is listed in the request log file--see com.sybase.jaguar.server.http.elffitems.

HTTP logging and statistics

EAServer maintains three HTTP log files and a statistics data file that allow you to monitor HTTP events. The file names are prepended with the server name. For example, if you create a server named Test_server, error messages for that server are directed to the Test_serverhttperror.log file. By default, the log files are located in the EAServer bin subdirectory (or devbin if you are running the debug server version).

<server_name>httprequest.log - records HTTP request log information about each HTTP request.
<server_name>httperror.log - logs HTTP errors, such as a request for an HTML file that does not exist.
<server_name>httpservlet.log - logs HTTP servlet requests.
<server_name>httpstat.dat - records HTTP statistics.

For information on viewing these files, see "Using the File Viewer".

Transactions

This section describes the transaction coordinator models that are available. All components installed in one instance of EAServer share the same transaction coordinator.

EAServer transaction coordinator models are:

Shared connection - for Windows or UNIX users this option, which is the default, is a "pseudo-coordinator" that is built into EAServer. All components participating in a transaction share a single connection. To use this model, all your application data must reside on one data server, and all components that participate in a transaction must use a connection with the same user name and password.
Microsoft Distributed Transaction Coordinator (DTC) - for Windows users only, DTC uses two-phase commit to coordinate transactions among multiple databases. DTC is available on Windows NT as part of Microsoft SQL Server 6.5.
Object Transaction Service X/Open Architecture (OTS/XA) Transactions - for Windows or UNIX users, this option is the Transarc Encina transaction coordinator that is built into EAServer. The Encina transaction coordinator uses two-phase commit to coordinate transactions among multiple databases.

AIX and HP-UX users must install the Distributed Computing Environment (DCE) package, which is provided on the operating system CDs. For information about how to install the DCE package, see your operating system documentation. AIX users must also set Async I/O to Available. See your AIX documentation for details.
To enable the OTS/XA transaction coordinator, you must create the transaction coordinator log file as follows:
- For Solaris and HP-UX, execute:
```
echo x | dd seek=8k of=JagOTSLog.dev
```
- For Windows, execute:
```
Filevol JagOTSLog.dev 4000K
```
- For AIX, go to the /dev directory and execute:
```
echo x | dd seek=8k of=rJagOTSLog.dev
```
If you do not create a log file, the server will not start up.
Java Transaction Service/Java Transaction API (JTS/JTA) Transactions - the JTS/JTA transaction coordinator functions similarly to the OTS/XA coordinator. They differ only in the way they handle JDBC XA connection caches. JTS/JTA dynamically registers a cache into a transaction when it is requested. OTS/XA registers all XA connection caches when a new transaction is started.

To set the transaction coordinator for your server, select the transaction model from the server's Transactions tab in the Server Properties window.

For detailed information about components and transactions, see Chapter 2, "Understanding Transactions and Component Lifecycles," in the EAServer Programmer's Guide.

Resources

The Resources tab allows you to limit the number of concurrent client sessions and contains configurable properties used by Open Server applications. Table 3-5 describes the server resource properties.

Table 3-5: Server resource properties
Property	Description	Default
Maximum Number Client Sessions	The maximum number of concurrent client sessions supported by EAServer. This does not include HTTP sessions, which are controlled by the maximum thread property described in "HTTP Config". Modify this variable as needed to balance system resources versus session availability. WARNING! If you increase this value, you must also increase the maximum number of threads.	30
Thread Stack Size (Available on UNIX platforms only)	The stack size for server threads, specified in bytes as a decimal number.	See Configuring server stack size for information on setting this property.
Message Pool Size The Open Server property SRV_S_MSGPOOL	The number of messages available to an Open Server application at runtime.	These properties are for Open Server applications. See your Open Server documentation for additional information.
Message Queue Size The Open Server property SRV_S_NUMMSGQUEUES	The number of message queues available to an Open Server application.
Network Buffer Size The Open Server property SRV_S_NETBUFSIZE	The maximum size of the network I/O buffer to be used for TDS and Open Server listeners.
Maximum Number Threads	The maximum number of connection threads, including HTTP and IIOP connections and message service threads. Set this value equal to, or greater than, the sum of the maximum number of HTTP connections, the maximum number of client sessions, and the number of threads in the message service thread pools. See "HTTP Config" for information on the HTTP connections value. See "Thread pools" for information on configuring message service thread pools.	50

Log/Trace

Tracing provides information about activities carried out by your application. Trace output is sent to the server's log file. To establish the level of detail for logging and tracing, select the Log/Trace tab. Table 3-6 describes the logging and trace properties.

For information on viewing the log file, see "Using the File Viewer".

Table 3-6: Debug/Trace properties
Property	Description
Log File Name	The name of the server's log file. This file defaults to server.log in the EAServer bin subdirectory, where server is the name of your server. The server.log file logs a wide range of information and is helpful in isolating problems. You can create the log file in an alternate directory by prefixing a full path to the file name you enter. If you do not enter a full path, the file is created in the EAServer bin subdirectory. You cannot use environment variables when specifying a full path.
Log File Size (Bytes)	The size, in bytes, to which the log file grows before it is truncated.
Truncate Log on Startup	When this flag is set, the log truncates every time the server is restarted. Keep in mind that if the server crashes and this flag is set, you will lose the log file and the information it contains.
Trace Attentions	If set, traces attentions received or acknowledged by EAServer.
Trace Network Driver APIs	If set, traces Net-Lib driver requests.
Trace Network Driver Requests	If set, traces network layer protocol requests.
Trace Protocol Data	If set, traces TDS packet content (the actual TDS traffic between a client and EAServer) in hexadecimal and ASCII format.
Protocol Headers	If set, traces TDS protocol packet header information, such as packet type and length.
Trace Servlets	If set, traces the execution of EAServer's servlet execution engine.

Handlers

EAServer supports event-based programming in addition to component-based programming. In the event-based programming model, the application programmer creates custom event handlers that extend the way EAServer responds to a variety of events. Some of these events are triggered by client requests, while others originate in EAServer.

For example, if you have coded a connect event handler, here is what happens:

The client sends a request to connect to EAServer.
EAServer receives the request, which generates a connect event.
EAServer executes the connect event handler code.

Specifying an event handler

Select the Handlers tab.

Enter the DLL or shared library name and the function name of the specific event handler being called, separated by a colon.

The following example illustrates an entry for a connect event handler:

Platform	Entry
Solaris, AIX, Digital UNIX, and LINUX	libsamp.so:debug_connect
HP-UX	libsamp.sl:debug_connect
Windows	libsamp.dll:debug_connect

where libsamp is the DLL or shared library name and debug_connect is the function called whenever a connect event handler is called.

Table 3-7 summarizes the types of event handlers that you can install. For information on coding event handlers, see the EAServer Programmer's Guide.

Table 3-7: Individual server event handlers
Event handler	Called
Connect	Each time a client connects to EAServer.
Disconnect	When the client disconnects from EAServer.
Error	When a server processing error occurs.
Initialization	Before starting a server.
Start	When a request to start the server is made.
Stop	When a request to stop the server is made.
Language	When a client sends a language request, such as a SQL statement.
RPC	When a client issues a remote procedure call.
Attention	When an attention has been received. An attention is an immediate event; EAServer services the attention as soon as it occurs, rather than adding it to the client's event queue.
Cursor	When a client sends a cursor request.
Dynamic	When a client sends a dynamic SQL request.
Message	When the client sends a message.
Option	When a client sends an option command.
Bulk	When a client issues a bulk copy request.

Naming Service

Select the Naming Service tab on the Server Properties window to set the server's naming service options. You can use this property sheet to configure a server to be a name server, or to point to another server as its name server.

You can also set the bindpassword server property to enable password protection for name binding on a name server. For more information, see "Name binding password security".

For general information about naming services, see Chapter 5, "Naming Services"

Initial Context - enter the server's default name context. The name server binds any object implementations on the server to the server's initial name context.

If you use an EAServer as a name server, the name context can be a compound name with each organization level separated with a forward slash ("/"); for example, /us/sybase/finance.

If you use an external LDAP server to provide persistent storage, the initial context must match the schema used by the LDAP server. For example, c=us,o=sybase,ou=finance.

Naming server options

Use these options to specify whether the EAServer instance is also a name server, or whether it uses another EAServer instance as its name server.

Click Enable as a Name Server to configure the server as a name server. If you select this option, you can then also set the Name Server Strategy options described below.
If EAServer uses another EAServer instance as its name server, unselect Enable as a Name Server. Enter the URL for the EAServer instance acting as the name server; for example, iiop://myhost:9000 .

Naming server strategy

If you enabled the EAServer instance to be a name server, indicate whether the server provides transient or persistent object name storage. By itself, an EAServer name server provides transient storage. However, you can add persistent storage capabilities to EAServer by using an external naming service, such as an LDAP name server.

If you enable persistent storage, enter the following information:

The URL of the LDAP name server
A manager DN (distinguished name) for the LDAP server
The manager DN password

The manager DN provides exclusive access to all objects in the LDAP server database in order to bind and update the objects on the name server. The manager DN and its password are part of the LDAP server configuration properties, set by the server administrator. See your LDAP server documentation for complete information.

Servlets

On the Servlet tab in the Server Properties window, you can disable servlet execution in EAServer and configure additional properties to control the execution of servlets.

See Chapter 20, "Creating Java Servlets," in the EAServer Programmer's Guide for complete information about developing and configuring servlets.

PowerDynamo

This section discusses how to configure EAServer to host your PowerDynamo Web sites and provide access to those sites from a browser. Access to PowerDynamo Web sites is disabled by default.

Hosting PowerDynamo Web sites in EAServer

Install PowerDynamo version 3.6 or greater and EAServer 3.6 or greater on your Windows or UNIX machine.
Update your EAServer's environment to include PowerDynamo DLL and class files. Depending on your platform, perform the following:

On Windows, depending on the virtual machine you are using, modify the %JAGUAR%\bin\serverstart.bat file (JDK 1.1.x VM), %JAGUAR%\bin\serverstart_jdk12.bat file (JDK 1.2), or %JAGUAR%\bin\serverstart_msvm.bat file (Microsoft SDK 3.2):
- Add %PDYNAMO%\win32 to your PATH.
- Add %PDYNAMO%\class03 to your CLASSPATH, where %PDYNAMO% is the root of your PowerDynamo installation. You do not need to define a %PDYNAMO% environment variable.
On UNIX, modify your $JAGUAR/bin/setenv.sh file:
- Define a PDYNAMO environment variable and set it to the root of your PowerDynamo installation. This environment variable is required on UNIX machines.
- Define a JAGUARCLASSES environment variable and set it to your client zip file, $JAGUAR/client/jagclient.zip.
- Add $PDYNAMO/lib to your LD_LIBRARY_PATH.
- Add $PDYNAMO/class03 to your CLASSPATH.
  
  Source these files.
Start EAServer and connect to it from Jaguar Manager. To enable PowerDynamo support:
1. From Jaguar Manager, open the Servers folder.
2. Highlight the server you want to configure.
3. Select File | Server Properties.
4. Select the Dynamo tab.
5. Click Enable Dynamo Execution.
6. If you have both a Dynamo mapping and a servlet alias with the same URL, select Dynamo or Servlets from the Priority of EAServer HTTP Services list. This determines whether the Dynamo Web site or servlet is served to the client.
7. Click OK.
Configure your machine so that your Web sites can connect to and retrieve information from databases that they use. For example, on Windows, if you load a Web site that accesses data from a SQL Anywhere database, you must include the SQL Anywhere DLLs in your PATH and set up the ODBC data source properly. See your database software instructions and the PowerDynamo User's Guide for detailed information.

WARNING!

If you have a Netscape Web server installed on your machine, PowerDynamo loads a Netscape version of ns-httpd30.dll instead of an EAServer version of the same DLL. Rename (but do not delete) Netscape's version of this DLL so that PowerDynamo loads the EAServer version instead.

You can now access a PowerDynamo Web site by entering into your browser, the EAServer HTTP address followed by a PowerDynamo Web site. For example:

http://EAServer_server_host:8080/mapped_url_name/file_name

This example connects your browser to:

EAServer's HTTP port 8080 on the host machine identified by EAServer_server_host.
The mapped_url_name is the mapping you supply for a PowerDynamo Web site in the PowerDynamo | Utilities | Configuration | Mappings folder.
file_name is the file you are accessing from the mapped PowerDynamo Web site.

Hot standby

If you have two EAServer installations, you can enable hot standby which allows you to designate one of the servers as a backup server that accepts client connection requests in case the master server fails. The master server processes client requests. The backup server starts in "Admin" mode and does not accept client requests. If the master server fails or is unreachable, the backup server sets itself to "Ready" mode and accepts client requests. Once the master server is up and accepting requests, the backup server enters "Admin" mode, refusing connections from clients.

See Chapter 7, "Load Balancing, Failover, and Component Availability" for information about component failover.

Enabling hot standby in EAServer

You must first enable the two hot standby servers as name servers. Select the Naming Service tab and click Enable as a Name Server to configure EAServer as a name server.
Select the Hot Standby tab and click the Enable Hot Standby check box.
Enter the Master Server URL using the format iiop://hostname:port . For example, iiop://EAServer_master:9095 .
Enter the Backup Server URL using the format iiop://hostname:port . For example, iiop://EAServer_backup:10000 .

The master and backup servers must be valid IIOP or IIOPS URLs. You can have only one master and one backup server defined and one of them, but not both, must be defined on the local server.
Synchronize the servers using the master as the primary server--see "Synchronization".

You can verify the settings of hot standby by checking these properties on the All Properties tab:

com.sybase.jaguar.server.CosNaming.nameserver must be set to true for both the master and backup servers.
com.sybase.jaguar.server.hotstandby is set to true if hot standby is enabled.
com.sybase.jaguar.server.hotstandby.master is the URL of the hot standby master server.
com.sybase.jaguar.server.hotstandby.backup is the URL of the hot standby backup server.

Licensing requirements Hot standby requires two server deployment licenses, or a separately priced hot-standby license. Contact your Sybase sales representative for hot-standby licensing and pricing details.

JAXP Support

The JAXP Support tab allows you to configure the default Java XML parsers for components and Web applications running on the server. See Chapter 27, "Configuring Java XML Parser Support," in the EAServer Programmer's Guide for more information.

Java Classes

The Java Classes tab allows you to configure the set of classes to be custom loaded at the server level.

Configuring the custom class list

Edit the class list as follows:
- To add a class, click Add and edit the name of the class, package, or JAR file following the value syntax rules described below.
- To rearrange the order of listed items, highlight the item to be moved in the list and click Move Up or Move Down.
- To remove an item, click Remove.

Value syntax for Java class lists

Enter a comma-separated list of Java classes, packages, and JAR files. You can specify all classes in a package using wildcards, as in this example:

com.xyz.MyPackage.*

You can specify all classes in a JAR file by specifying the JAR file name, as in this example:

MyEntityBean.jar

JAR files must be deployed in the EAServer java/classes subdirectory.

For more information, see Chapter 28, "Configuring Custom Java Class Lists," in the EAServer Programmer's Guide.

JPDA

The JPDA (Java Platform Debug Architecture) tab allows you to specify the port number for remote debugger connections. The debugging software must use the JPDA client interface. When the debug server is started, it allows JPDA client connections at this port, using the JPDA dt_socket transport type.

The JPDA software is not included with JDK 1.2.2 on Solaris and Windows platforms. You can download the software from the JPDA Web page .

Static Page Caching

You can configure EAServer to cache HTML and other static pages, which improves the speed at which the page contents are served. When a client requests an HTML page, EAServer checks the cache for a suitable entry. If the cache entry exists, the cached page is sent to the client. If the cache entry is not found, EAServer loads the page from disk, sends it to the client, then saves the page contents in the cache.

To further improve the speed at which static page contents are served, you can disable the HTTP request log--see "HTTP Config" for details.

Table 3-8: Static page caching properties
Property	Description	Default value	Comments/example
Enable Page Caching	Select to enable page caching.	Enabled
Enable Server Log Debug Messages	Select to log cache-related messages in the server log file, server_name.log.	Disabled
Cache Size	The maximum size of the cache, specified in bytes, kilobytes, or megabytes, which you set using an integer plus "B", "K", or "M".	10M	You can specify the size using uppercase or lowercase letters; for example, to set the cache size to 20 megabytes, you can enter either `20M` or `20m` .
Cache Timeout	The maximum number of seconds an entry remains valid in the cache.	600 seconds (10 minutes)	To allow entries to remain valid in the cache for 30 minutes, enter `1800` .
Exclude Web Application Files	A comma-delimited string that specifies the Web application files to exclude from caching. Enter the string in this form; items in brackets are optional: (<WebAppName>[/<dir>], [<file_type>], [<file_type>], ...), (<WebAppName>[/dir>], ...), ...	An empty string	To exclude all the GIF and JPG files in the images directory and all the files in the archives directory for the Web application "Vacation", enter: (Vacation/images, .gif, .jpg), (Vacation/archives, .) To exclude all the files in the Vacation Web application, enter: (Vacation)
Exclude Files	A comma-delimited string that specifies the non-Web application files to exclude from caching. Enter the file definitions in this form, relative to the document root directory: (<dir>, [<file_type>], [<file_type>], ...), (<dir>, [<file_type>], ...), ... By default, the document root directory is $JAGUAR/html. You can change it on the HTTP Config tab--see "HTTP Config".	An empty string	To exclude all the files in the $JAGUAR/html/images directory, enter: (images, .) To exclude all the files in the $JAGUAR/html/images directory and all the files in its subdirectories, enter: (images)
Flush Cache	Select to flush all the entries from the cache.	N/A	You can also flush the cache programmatically by calling the Management interface method flushStaticPageCache, which requires one string parameter. Currently, you must pass an empty string. In the future, multiple caches will require that you specify the cache name.

When you modify static page cache properties, you must refresh the cache for the changes to take effect. To refresh the cache, highlight the server icon and select File | Refresh Static Cache.

HTTP Custom Headers

The HTTP Custom Headers tab allows you to define custom headers for HTTP responses at the server level. You can customize header information such as the server name or the expiration date of the response. A server-level custom header applies to all server resources. You can also define custom headers at the Web application level by installing the default filter com.sybase.jaguar.servlet.AddHeadersFilter in a Web application. Chapter 21, "Using Filters and Event Listeners," in the EAServer Programmer's Guide describes how to do this. When both server and Web application custom headers exist, the Web application custom header takes precedence.

Defining custom headers

Enter the custom header as property name/value pairs.

Click Add to display the New Property dialog box.
Enter a property name, property value, and (optionally) a description.

To edit a header property, highlight the property and click Modify. Edit the property name or value, and click OK.

To delete a header property, highlight the property and click Delete.

For more information

For more information on filters and programming customized responses, see the Java Web page .

All Properties

For advanced users only. Select this tab to edit server property settings in the EAServer configuration repository. Properties are listed in Appendix B, "Repository Properties Reference" You can use this tab to edit any property prefixed with "com.sybase.jaguar.server". Most server properties can be configured on other tabs in the Server Properties dialog box, except the following: