This chapter contains procedures for upgrading your GSM Manager system directly from Release 1.0 to Release 2.0. It covers Oracle on both HP-UX and Solaris platforms.
Note:
If the slash character used in this document to separate elements in a path does not work in your operating system, replace that character with the appropriate one. For example, if you use UNIX, replace the backslashes in the following path with forward slashes: Portal_Home\upgrade\gsm\10_20\upgrade.cfg.Note:
You need to upgrade GSM Manager Release 1.0 to Release 2.0 only if you are upgrading from Infranet Release 6.5 to Portal™ 7.3.Install new GSM Manager software.
Update the GSM Manager database. The new GSM Manager release includes an updated database schema with new tables and indexes. You use upgrade scripts to update your GSM Manager database to the new schema.
Note the following important information:
GSM Manager 2.0 runs only on the Oracle 9i or 10g database.
To upgrade any data stored in custom tables, you must create additional SQL scripts. To run these scripts with the default upgrade scripts, add appropriate SQL file entries to the upgrade configuration file, upgrade.cfg. For more information, see "Configuring the Upgrade Parameters".
Portal supports only the UTF8 character set on Oracle. If you haven't already done so, you should move your data to a new UTF8 database before you upgrade. For more information about exporting your existing data to a UTF8 database, see ”Modifying Your Oracle Database Installation” in BRM Installation Guide.
After preparing your environment, prepare your database:
Before running the database upgrade scripts, review the default database schema changes between Release 1.0 and Release 2.0. Knowing the schema changes helps you plan your upgrade. For example, if 2.0 contains many new tables, you might need to increase the disk space for your 2.0 database. If your 1.0 custom applications refer to tables that have been modified or deleted in 2.0, you might need to update the applications for 2.0.
To review database schema changes, temporarily install the Release 2.0 database upgrade files on a supplementary server.
In addition, perform the database-specific tasks described in the section "Preparing an Oracle Database".
If you use an Oracle database, perform the following tasks before upgrading Portal:
Upgrading the Oracle Software and Database
You can use GSM Manager 2.0 only on Oracle 9i or 10g.
Caution:
If you are using an earlier version of Oracle, you must upgrade it before you install GSM Manager 2.0. For information on upgrading Oracle, see your Oracle documentation.Changing the Database Character Set to UTF8
GSM Manager 2.0 supports only the UTF8 character set. If your database character set is not UTF8, re-create your database with the UTF8 database character set.
For information on changing the database character set, see your Oracle documentation.
Configuring Oracle to Run the Upgrade Scripts
To run the database upgrade scripts, you must prepare your Oracle system as follows:
Setting Up Rollback Segments and Temporary Tablespaces
The upgrade scripts modify and sort many Portal tables. Some tables, such as EVENT_T, can contain millions of rows. The recommended rollback segment configuration for normal operation is inadequate for running the upgrade scripts. Therefore, you must adjust the size of the rollback segments to support the upgrade transactions:
Unless your database is very small, create two or three rollback segments that are half the size of your largest table (usually the EVENT_T table).
Take the smaller rollback segments used during normal operation offline while you run the upgrade scripts.
Granting New Privileges to the Oracle Portal User
The upgrade scripts require you to grant CREATE TABLE and CREATE SEQUENCE privileges directly to the Portal user pin.
To grant these privileges, enter these commands:
SQL> connect system/manager@databaseAlias SQL> grant create table to pin; Grant succeeded. SQL> grant create sequence to pin; Grant succeeded. SQL> quit
This section provides a complete list of upgrade tasks. Some tasks are optional or apply only to certain platforms or system configurations. Be sure to check whether a task is required for your system.
To upgrade directly from GSM Manager Release 1.0 to Release 2.0, perform some or all of these tasks, depending on your system:
Creating Required Database Objects and the Upgrade Log Directory
Dropping Obsolete Database Objects from the Database (Optional)
Before removing the old GSM Manager Release 1.0 packages, back up your 1.0 files. In particular, ensure that you back up all customized files, including source code, pin.conf, and pin_setup.values files.
To maintain a controlled environment for pre-upgrade testing, cut off interaction between your Portal system and your customers.
For information on the Portal authentication module, see BRM RADIUS Manager in Oracle Communications Billing and Revenue Management (BRM) Documentation.
Stop all Portal processes.
Only the database instance should be running during the upgrade. For more information, see ”Starting and Stopping the BRM System” in BRM System Administrator's Guide.
Ensure that the Connection Managers (CMs) and Data Managers (DMs) are not running.
Ensure that sure no users are logged on to Portal.
Users include customers, client applications, customer service representatives (CSRs), and so on.
Make a complete offline backup of your Portal database, and ensure that the backup is completely valid and usable. For more information on performing full database backups, see your database software documentation.
In addition to the backup, use the Oracle export utility to export all Portal tables. This helps you restore individual tables if necessary.
Install the Third-Party software by following the instructions given in ”Installing the Third-Party Software” in BRM Installation Guide.
Important:
Before installing GSM Manager and the Wireless Provisioning Data Manager, you should be familiar with the overall wireless integration installation procedure. See the following documents: ”About Integrating Wireless Services” and ”Installing and Configuring GSM Manager and Provisioning Data Manager” in BRM Telco Integration.To install GSM Manager Server Release 2.0:
Install the GSM Manager Server Release 2.0 package for your platform. Follow the instructions in ”Installing and Configuring GSM Manager and Provisioning Data Manager” in BRM Telco Integration.
Caution:
Do not run the pin_setup script before upgrading your database. Running pin_setup before upgrading your database might corrupt your data.Important:
Pay particular attention to entries that specify your installation directory; CM and DM port numbers; and database host name, user name, and password.
Ensure that the $SETUP_INIT_DB entry is set to YES.
Make a backup copy of the release Portal_Home/setup/pin_setup.values file, and save it to another location.
Important:
The upgrade scripts do not modify these files.To install the GSM Manager-Release-1.0-to-Release-2.0 upgrade scripts:
Download the software to a temporary directory (temp_dir).
Important:
If you download to a Windows workstation, use FTP to copy the .bin file to a temporary directory on your UNIX server.
You must increase the heap size used by the Java Virtual Machine (JVM) before running the installation program to avoid ”Out of Memory” error messages in the log file. For information, see ”Increasing heap size to avoid ”Out of Memory” error messages” in BRM Installation Guide.
Go to the directory where you installed the Third-Party package and source the source.me file.
Caution:
You must source the source.me file to proceed with installation, otherwise ”suitable JVM not found” and other error messages appear.Bash shell:
source source.me.sh
C shell:
source source.me.csh
Log in as user integrate, go to the temp_dir directory, and enter this command:
7.3_GSM_10_20_OraUpg_platform_32_opt.bin
Note:
You can use the -console parameter to run the installation in command-line mode. To enable a graphical user interface (GUI) installation, install a GUI application such as X Windows and set the DISPLAY environment variable before you install the software.Follow the instructions displayed during installation.
The upgrade.cfg file contains your upgrade parameters, such as which scripts to execute and whether to upgrade only the most recent data. You should customize these parameters to meet your business requirements.
To edit the upgrade.cfg file:
Log in as user pin, go to Portal_Home/upgrade/gsm/10_20, and open the upgrade.cfg file in a text editor such as vi:
% su - pin % cd Portal_Home/upgrade/gsm/10_20 % vi upgrade.cfg
Configure the file's parameters as necessary. For information on each parameter, see the comments in the upgrade.cfg file. Pay particular attention to the parameters described in Table 26-1:
Table 26-1 upgrade.cfg Parameters of Note
| Parameter | Description |
|---|---|
|
SQLPLUS IMP EXP |
Specify the location of the database utilities and executables. By default, they are set to sqlplus, imp, and exp, respectively. |
|
OWNER |
Specifies the Portal database user name. By default, this is set to pin. |
|
PASSWD |
Specifies the Portal database password. By default, this is set to pin. |
|
DBNAME |
Specifies the name of the Portal database you are upgrading. By default, this is set to pindb. |
|
PIN_CONF_TBLSPACEn PIN_CONF_TBLSPACEXn |
Specify the tablespaces where your new tables and indexes will be created. |
|
PIN_CONF_STORAGE_SMALL PIN_CONF_STORAGE_SMALL_INS PIN_CONF_STORAGE_MED PIN_CONF_STORAGE_MED_INS PIN_CONF_STORAGE_LARGE PIN_CONF_STORAGE_LARGE_INS |
Specify the storage parameters to use when the tables and indexes are created. Information on how your tablespace and storage parameters are configured in Release 1.0 is in your Release 2.0 Portal_Home\setup\scripts\pin_tables.values file. You can use this information to help you configure the parameters in your Release 2.0 upgrade.cfg file. |
|
@ALL_SCRIPTS |
Specifies which upgrade scripts are executed by the upgrade.pl script. By default, all upgrade scripts are executed. |
|
$UPGRADE_LOG_DIR |
Specifies in which directory to create the log and pinlog files generated by the upgrade process. |
|
$UPG_DATA_START_TIME |
Specifies the start date for upgrading only the most recent data. Only objects created during the time period defined by $UPG_DATA_START_TIME and $UPG_DATA_END_TIME are upgraded. An object's created time is used to calculate the age of its data. Note:
|
|
$UPG_DATA_END_TIME |
Specifies the end date for upgrading only the most recent data. Important: You must change the default value of this parameter. Note: If you specify only a date, the default time is 00:00:00 on the specified date. Therefore, the end date is exclusive. For more information, see $UPG_DATA_START_TIME. |
To create the database objects required for the upgrade and the upgrade log directory, run the upg_mgr.pl script with the -o parameter. For more information, see "About the upg_mgr.pl Script".
Run the upg_mgr.pl script with the -s parameter to verify the following:
The indexes required for upgrading have been created.
Portal storable class objects required for upgrading exist.
The following database preparations have been made:
The correct version of Oracle is installed. See "Important Information for System Administrators".
The database character set is correct. See "Oracle Database Character Sets".
The Portal user pin has CREATE TABLE and CREATE SEQUENCE privileges. See "Granting New Privileges to the Oracle Portal User".
The required rollback segments exist. See "Setting Up Rollback Segments and Temporary Tablespaces".
The -s parameter also reports how much disk space is required for event table partitioning.
Results are printed to the Portal_Home/upgrade/gsm/10_20/sqllog/pre_upg_sanity_chk2.sql.log file. For more information, see "About the upg_mgr.pl Script".
Note:
To reduce system downtime, you can perform the sanity checks before stopping Portal (see "Shutting Down Portal").To see what modifications you made to the default Release 1.0 database schema, compare the tables and indexes in your 1.0 database with those in the default 1.0 database. You need this information to interpret error messages that might be generated when you run the upgrade scripts (see "Running the Database Upgrade Scripts") and when you add custom tables and indexes to the upgraded Release 2.0 database.
The schema_tbls.sql script generates a list of your Release 2.0 database table columns and writes it to the table_schema.out file.
Run the schema_tbls.sql script from the UNIX or DOS command prompt:
% cd Portal_Home/upgrade/gsm/10_20 % perl upg_mgr.pl –e schema_tbls.sql
The upgrade.pl script runs a series of scripts that upgrade the Release 1.0 database to Release 2.0. By default, the upgrade.pl script runs all the upgrade scripts.
To run only the offline scripts, you must first edit the upgrade.cfg file. See "Configuring the Upgrade Parameters".
For more information about the upgrade.pl script, see "About the Upgrade.pl Script".
To upgrade your database schema:
Run the upgrade.pl script from the UNIX or DOS command prompt:
% cd Portal_Home/upgrade/gsm/10_20 % perl upgrade.pl
Check each script's log and pinlog file in the directory specified by the UPGRADE_LOG_DIR parameter in your upgrade.cfg file (by default, Portal_Home/upgrade/gsm/10_20/sqllog). These log files show how long each script took to execute and list any errors that occurred.
Important:
If any errors are reported, fix them, and then rerun the upgrade.pl script.You must install Patch 4489. This patch is critical to the proper performance of GSM Manager. For more information, see the patch README file.
The pin_setup script reads the pin_setup.values file and configures Portal by initializing the database, configuring various pin.conf files, and starting various servers, including the dm_oracle server, the Connection Manager (CM), and the Java server.
To run the pin_setup script:
Log in as user pin, go to the Portal_Home/setup directory, and run the pin_setup script:
% su - pin % cd Portal_Home/setup % ./pin_setup
Check the following files for errors:
Portal_Home/setup/pin_setup.log
Portal_Home/sys/cm/CM.log
Portal_Home/var/cm/cm.pinlog
Portal_Home/sys/dm_database/DM.log
Portal_Home/var/dm_database/dm_database.pinlog
See ”Using the Authentication and Authorization Modules” in BRM RADIUS Manager.
Perform it after you verify that the upgrade is successful. Dropping obsolete database objects from the database is optional.
To drop obsolete database tables and columns, run the drop_tables.sql script from the UNIX or DOS command prompt:
% cd Portal_Home/upgrade/gsm/10_20 % perl upgrade.pl drop_tables.sql
The following command-line scripts automate routine upgrade tasks:
Run these scripts from the UNIX or DOS prompt.
This Perl script performs many of the upgrade tasks, such as creating database objects and running sanity checks.
perl upg_mgr.pl -o | -s | -e sql_script_name.sql | -r step_name | -d step_name | -t | -n | -h
Note:
Specify only one parameter at a time.
Run upg_mgr.pl with the -o parameter before you run it with any other parameters.
If you omit sql_script_name after the -e parameter or step_name after the -r or -d parameters, the script does nothing.
The upg_mgr.pl parameters are described in Table 26-2:
Table 26-2 upg_mgr.pl Parameters
| Parameter | Description |
|---|---|
|
-o |
Creates the database objects required for the upgrade. Important: Run upg_mgr.pl with the -o parameter before you run it with any other parameters. This parameter performs these operations:
|
|
-s |
Runs the pre-upgrade sanity check. See "Performing Pre-upgrade Sanity Checks". Note: This requires a database administrator (DBA) user name and password for the Portal database. See the upgrade.cfg file for details. |
|
-e sql_script_name.sql |
Executes the specified SQL script against the Portal schema. It replaces all the Perl variables before running the script. Important: You must include the .sql extension with the script name. |
|
-r step_name |
Prints a report of the status of the specified step and directs the report to the Portal_Home/upgrade/gsm/10_20/sqllog/step_name.sql.pinlog file. Important: Do not include the file extension with the script name. |
|
-d step_name |
Deletes all the information related to an upgrade script from the upgrade log tables. After a script is run, its completion is logged in the upgrade log tables. If a user tries to rerun the script, the upgrade software first checks those tables. When it finds the script has already run, it skips the script. Thus, you must run upg_mgr.pl -d to delete all information about a previously run script from the tables before rerunning the script. Important: Do not include the file extension with the script name. |
|
-t |
Displays the maximum and minimum CREATED_T for the EVENT_T, ITEM_T, and BILL_T tables. |
|
-h |
Displays these parameter descriptions. |
The upgrade.pl Perl script is the main upgrade script. It runs many other SQL scripts in the correct order.
To run all the scripts listed in the upgrade.cfg file's @ALL_SCRIPTS parameter, enter this command at the UNIX or DOS prompt:
% cd Portal_Home/upgrade/gsm/10_20 % perl upgrade.pl
Note:
The scripts are run in the order they are listed in the parameter. For more information, see "Configuring the Upgrade Parameters".To run a single script, enter this command:
% cd Portal_Home/upgrade/gsm/10_20 % perl upgrade.pl script_name
Important:
script_name must include the file extension.This section describes the scripts and files used to upgrade your Portal database.
Table 26-3 lists the offline scripts used to upgrade the Portal database.
Table 26-4 lists the online scripts used to upgrade the Portal database.
The following scripts in Table 26-5 are configuration files executed by offline or online scripts:
Table 26-5 Miscellaneous Scripts and Files
| Script or File | Description |
|---|---|
|
schema_idxs.sql |
SQL script that produces the index schema listings. |
|
schema_tbls.sql |
SQL script that produces the table schema listings. |
|
delete_info.sql |
SQL script that deletes the UPG_LOG_T table entries related to a specific script. |
|
get_created_t.sql |
SQL script that retrieves the max and min CREATED_T from various tables. |
|
pre_upg_sanity_chk1.sql pre_upg_sanity_chk2.sql |
SQL scripts that perform sanity checks. |
|
crt_pinlog.sql |
SQL script that creates the pinlog files. |
|
pin_pre_cmp_tcframework.pl |
Perl script that configures the tcframework component. |
|
pin_pre_cmp_gsm.pl |
Perl script that configures the GSM component. |
|
upgrade.cfg |
Configuration file in which you must enter details about the Oracle Server database configuration before you run the upgrade scripts. All the upgrade Perl scripts parse this file to get the database connection parameters. |
|
upg_oracle_functions.pl |
Perl script that performs many miscellaneous upgrade tasks related to the Oracle database. |
|
upg_mgr.pl |
Perl script that manages many miscellaneous upgrade tasks. |
|
upgrade.pl |
Master Perl script for the upgrade process. This Perl script calls other SQL scripts to perform the upgrade. |
|
crt_upg_indexes.sql |
SQL script that creates a unique index for BILL_T, EVENT_T, and ITEM_T tables. |
|
drop_procedures.sql |
SQL script that drops all the stored procedures from the Portal schema. |