![]() |
Working with Cloudscape Properties
|
Reference Manual |
Ways of Setting Cloudscape PropertiesThis section covers the different ways of setting properties.
System-Wide PropertiesYou can set system-wide properties programmatically (as a command-line option to the JVM when starting the application or within application code) or in the text file cloudscape.properties. ProgrammaticallyYou can set properties programmatically--either in application code before booting the Cloudscape driver or as a command-line option to the JVM when booting the application that starts up Cloudscape. When you set properties programmatically, these properties persist only for the duration of the application. Properties set programmatically are not written to the cloudscape.properties file or made persistent in any other way by Cloudscape. NOTE: Setting properties programmatically works only for the application that starts up Cloudscape--for example, for an application in an embedded environment or for the application server that starts up a server product. It does not work for client applications connecting to a running server. As a Parameter to the JVM Command LineYou can set system-wide properties as parameters to the JVM command line when starting up the application or framework in which Cloudscape is embedded.
java -Dcloudscape.system.home=C:\home\jbms\
jview /d:cloudscape.system.home=C:\home\jbms\ JDBCTest For other JVMs, see the JVM-specific documentation on setting system properties. Using a Properties Object Within an Application or StatementIn embedded mode, your application runs in the same JVM as Cloudscape, so you can also set system properties within an application using a Properties object before loading the Cloudscape JDBC driver. The following example sets cloudscape.system.home on Windows: Properties p = System.getProperties(); p.put("cloudscape.system.home", "C:\databases\tours"); In client/server mode, you can accomplish the same thing within an SQL-J statement (this works in embedded mode, too):
CALL (CLASS java.lang.System).getProperties().put( NOTE: You cannot set any static system-wide properties (which require you to reboot Cloudscape) in an SQL-J statement. cloudscape.system.home is one of those properties. NOTE: If you pass in a Properties object as an argument to the DriverManager.getConnection call when connecting to a database, those properties are used as database connection URL attributes, not as properties of the type discussed in this book. In the cloudscape.properties FileYou can set persistent system-wide properties in a text file called cloudscape.properties, which lives in the directory specified by the cloudscape.system.home property. There should be one cloudscape.properties file per system, not per database. The file lives in the system directory. In a client/server environment, that directory is on the server. (For more information about a Cloudscape system and the system directory, see Cloudscape System in the Cloudscape Developer's Guide.)
Instead, you must create, write, and edit this file yourself. The file should be in the format created by the java.tools.Properties.save method. A sample cloudscape.properties files is provided in /demo/programs/tours/scripts. The following is the text of a sample properties file: cloudscape.infolog.append=true cloudscape.storage.pageSize=8192 cloudscape.storage.pageReservedSpace=60 Properties set this way are persistent for the system until changed, until the file is removed from the system, or until the system is booted in some other directory (in which case Cloudscape would be looking for cloudscape.properties in that new directory). If a database is removed from a system, system-wide properties do not "travel" with the database unless explicitly set again. Verifying System PropertiesYou can find out the value of a system property if you set it programmatically. You cannot find out the value of a system property if you set it in the cloudscape.properties file. For example, if you set the value of the system-wide property in an SQL-J statement, in a program, or on the command line, the following SQL-J statement returns its value:
VALUES (CLASS java.lang.System).getProperty( Database-Wide PropertiesDatabase-wide properties, which affect a single database, are stored within the database itself. This allows different databases within a single Cloudscape system to have different properties and ensures that the properties are correctly set when a database is moved away from its original system or copied. NOTE: Cloudscape recommends that you use database-wide properties wherever possible for ease of deployment. You set and verify database-wide properties using methods of the COM.cloudscape.database.PropertyInfo interface (aliased as PropertyInfo) within SQL-J statements. Use this interface only within the context of SQL-J statements. Cloudscape provides a class alias for this class, PropertyInfo. To set a property, connect to the database, create a statement, and then use the setDatabaseProperty method, passing in the name and value of the property. To check the current value of a property, connect to the database, create a statement, and then use the getDatabaseProperty method, passing in the name of the property. To check the current values of all database-wide properties, use the getProperties() method.
-- set the statement cache size to 40
-- set the default page size for all new tables in the database -- find out the current database-wide properties If you specify an invalid value, Cloudscape uses the default value for the property. Since you set database-wide properties within SQL-J statements, you can set these properties in embedded or client/server mode. In addition, in a Cloudscape synchronization system, you set properties for target databases by publishing database-level properties. (You cannot publish system-level properties, but you can set system-level properties individually on targets.) For more information, see the Cloudscape Synchronization Guide. See the javadoc for COM.cloudscape.database.PropertyInfo for complete information on the static methods. Shortcut for Setting Database PropertiesYou can create a method alias for setDatabaseProperty. Cloudscape provides a script in /demo/util/methodalias that creates method aliases for the methods in the COM.cloudscape.database.PropertyInfo class. For more information, see /demo/util/methodalias/readme.html. After you run the script, you will be able to set the property like this:
CALL SETDATABASEPROPERTY( Conglomerate-Specific PropertiesYou can apply some storage-related properties to specific conglomerates (tables or indexes) within a database. These properties, which you set as part of the CREATE TABLE or CREATE INDEX statement at table or index creation time, define the way rows are stored only for the specific table or index, including backing indexes for constraints; the rest of the database uses the database or system defaults. Overriding the default with conglomerate-specific properties is useful when you have one table or index with storage needs different from those of the rest of the tables or indexes in a database. For more information, see PROPERTIES clause in the Cloudscape Reference Manual. For indexes, you can set only cloudscape.storage.pageSize and cloudscape.storage.initialPages. For tables, you can set cloudscape.storage.initialPages, cloudscape.storage.minimumRecordSize, cloudscape.storage.pageSize, or cloudscape.storage.pageReservedSpace. For example, the following SQL-J statement creates a table with a page size of 2048:
CREATE TABLE NewTable (a INT, b VARCHAR(50)) NOTE: If you specify an invalid property name or an invalid value, Cloudscape uses the default value. Verifying Conglomerate-Specific PropertiesTo verify which properties were used for a specific table or index, use the static methods of COM.cloudscape.database.PropertyInfo. The static methods getTableProperties and getIndexProperties return a Properties object equal to the properties used when creating that conglomerate. The methods take the name of the index or table as a string parameter. Unnamed constraints use system-generated names. To find out the system-generated name of an index that backs a constraint, query the system tables. The following example shows how to find out the name of the backing index for the primary key constraint on the table Flights.
SELECT constraintname You have a lot of flexibility in the way you find out the information. For example, you can use the toString method to see the properties listed as text strings. In ij, you could find out the values of the properties used for creating a table like this:
VALUES PropertyInfo.getTableProperties( NOTE: The table name string is case-sensitive. Tables and indexes created as non-delimited identifiers must be specified in all caps. Or you could find out the values for a particular property like this:
VALUES PropertyInfo. See the javadoc for COM.cloudscape.database.PropertyInfo for complete information on the static methods. You can also use Cloudview to see database property values. In a Client/Server EnvironmentIn a client/server environment, you must set the system properties for the server's system. That means when you are using the cloudscape.properties file, the file exists in the server's cloudscape.system.home directory. Client applications can set database-wide and conglomerate-specific properties, since they are set via SQL-J statements. Client applications can set dynamic system-wide properties in an SQL-J statement, as shown in the example in Using a Properties Object Within an Application or Statement. For more information, see the Cloudscape Server and Administration Guide. Dynamic or Static Changes to PropertiesNOTE: Properties set in the cloudscape.properties file and on the command line of the application that boots Cloudscape are always static, because Cloudscape reads this file and those parameters only at startup. Conglomerate-specific properties, on the other hand, are always dynamic. Only properties set in the following ways have the potential to be dynamic:
See Chapter 5, "Cloudscape Properties", for information about specific properties. |
|
![]() Cloudscape Version 3.6 For information about Cloudscape technical support, go to: www.cloudscape.com/support/.Copyright © 1998, 1999, 2000 Informix Software, Inc. All rights reserved. |