Chapter 8: Utility Commands Reference

preupgrade

Description

Performs tests on an installation or database to determine its readiness for upgrade, and reports found problems. preupgrade is located in $SYBASE/$SYBASE_ASE/upgrade.

Windows The utility is preupgrd.exe, located in %SYBASE%\%SYBASE_ASE%\upgrade.

Syntax

preupgrade [-v] [-h] [-N]
    [-D database_name]
    [-I interfaces_file]
    [-P password]
    [-S server_name]
    [-U user_name]
    [-X option[,option]...]

Parameters

-D database_name: limits checking to the named database and a subset of possible checks. Use this parameter to check newly loaded databases before bringing them online.

-h: prints help text and then exits.

-I interfaces_file: specifies an interfaces file for the server. The default is $SYBASE/interfaces.

-N: specifies preupgrade is to run in noninteractive mode. Thus, if preupgrade determines that any database is too small, the utility exits immediately.

-P password: specifies the password for connecting to the server. Sybase recommends that you do not use this option on the command line as the password is then visible to other users when they view displays of system information. Rather, wait until Adaptive Server prompts for a password, and enter the information then.

-S server_name: specifies the name of the server to which you want to connect. This server must be listed in the interfaces file specified by the -I parameter. The default is $DSQUERY.

-U user_name: specifies the user name to use when connecting to the server. The default is “sa.” user_name must have “sa_role” privileges on the server being checked.

If you use the -D option, which limits checking to a named database, and that database is offline, you must enter “sa” or accept the default as the user name.

-v: prints version information and exits.

-X option[, option...]

specifies a list of checks to be made. The default is all checks, except when using the -D option, which uses only a subset of available checks. If you specify the -X option more than once on the command line, preupgrade performs only those checks in the last entered -X parameter.

When using the -X parameter with an options list, you must either:

List options without a space between the comma and the next option, or
Surround the options list with quotes.

Valid check options are described in Table 8-2. Sybase may occasionally change valid options for the -X parameter; use the -h parameter to view the current set of valid options

**Table 8-2: Check options with the -X parameter**
Check options	Options used with the -D parameter	Description
all		Performs all permitted checks. When used with the -D option, only checks subset of options. Otherwise, all options are checked.
cache		Checks the definition of default cache size. If the definition is DEFAULT, enter its current value in the configuration file as its actual value. This ensures that its size does not change because the new server’s default value is different from the current server’s default value.
config		Checks the server’s configuration parameters to see if they are consistent with new requirements, and reports discrepancies. Discrepancies can cause errors or warnings for certain parameters: Errors – occur when the current value of a parameter is outside the new server’s range, or when its value is too low for upgrade. Warnings – occur when the current value of a parameter is between the maximum and minimum values, but less than the default value
data_mods		Performs updates to system tables, including clearing certain system table columns that are non-zero. Applies primarily to older Adaptive Servers, and will make no changes to newer systems.
datatype	X	Checks the systypes table to make sure that if existing datatypes use a system-defined name, type, or user type, they match what the new server expects. Reports discrepancies and suggests remedies.
db_size		Checks that certain system databases meet the minimum size requirements for installation.
free_space	X	Checks for free space in the named database or in all databases. Makes sure that there is sufficient free data and log space to perform the necessary upgrade steps.
object_id	X	Checks that object IDs of user-defined objects are not reserved for system objects. Adaptive Server 15.0 and later reserves objects IDs 1 – 255. Adaptive Server 12.5.x and earlier reserves object IDs 1 – 99. Does not issue an error. If you receive a warning that a user object ID is reserved, contact Sybase Technical support for directions for changing the user object ID after upgrade.
required_dbs		Checks that required system databases exist. Some versions of Adaptive Server may require specialized databases such as sybsystemdb.
sproc_text	X	Checks for stored procedure text in the named database or in all databases. After upgrade, you must recompile stored procedures from their source text. This check makes sure that all of the source text is both available and valid.
srvclass		Checks for servers classed as “generic” in master.dbo.sysservers. This class is deprecated by Adaptive Server 12.0 and later.
statistics		Checks for duplicate rows in sysstatistics. Duplicate rows may occur when upgrading from Adaptive Server 12.0 to Adaptive Server 15.0 and later due to schema changes in the sysstatistics table.

Examples

Example 1

This example runs preupgrade and specifies checks for the default cache size, minimum database size, and duplicate rows in sysstatistics for the installation.

preupgrade –X cache,db_size,statistics

Example 2

This example runs preupgrade to check a newly loaded, offline database. preupgrade checks datatypes, free space, object IDs, and stored procedure text.

preupgrade –Dmy_db –Usa

Example 3

This example shows how the sqlupgrade utility uses preupgrade. When used in this way, preupgrade checks all databases, runs noninteractively, and exits with a failing status if any database is too small.

preupgrade –N

Usage

When preupgrade finds no errors, it exits with status 0 (zero).
preupgrade is primarily used before upgrading an installation to ensure the procedure will run smoothly. You can also run preupgrade after loading a database created by a previous version of Adaptive Server to check for problems that might prevent that database from upgrading while being brought online.
sqlupgrade calls preupgrade as part of its normal procedure.
Unless the -D parameter is included, preupgrade checks all databases in the system, and runs only on previous server versions.
If the -D parameter is included, preupgrade:
- Checks only the named database.
- Can run be run against server of the same version number as the preupgrade utility.
- Limits checking to a subset of possible checks. See Table 8-2 for a list of checks that are valid when used in conjunction with this parameter.
The -D parameter is used primarily to check newly loaded databases before bringing them online. To do so, preupgrade must force access to offline databases, which requires that preupgrade log in as user “sa” The “sa_role” privilege alone is insufficient. The default is -Usa.

When run as part of a normal upgrade, the -D parameter is optional, and you can choose a System Administrator login other than “sa.”
When running preupgrade after upgrade to check a newly loaded but offline database, you must use the -D parameter and either specify the “sa” login or omit the -U parameter.
When you specify the -D option, or specify a partial list of options with the -X parameter, preupgrade performs the specified checks and, if there are no errors, displays a list of checks performed in the exit message.
You may want to use the -D and the -X parameters as part of the normal upgrade if preupgrade reports warnings or errors for a particular database or area. Using these parameters allows you to focus on problem areas without repeating unnecessary checks.

sqlupgrade always runs the full set of preupgrade checks. You can correct problems and run preupgrade to ensure that the problems are indeed corrected before letting sqlupgrade repeat the full preupgrade procedure.

Permissions

The user login specified by the -U parameter must have System Administrator privileges to run preupgrade on the server specified by the -S parameter.

When using the -D parameter to check an offline database, preupgrade must log in as user “sa.” The “sa_role” privilege is insufficient