Step 8: Resolve exceptions

Exceptions are logged if the Upgrade Utility cannot add or update an object. After running an upgrade, you can identify exceptions by viewing error messages in the except.log or sm.log file. These exceptions are reported in the Upgrade Results list as "Error."

Data type mismatches

If the data type of a field in your dbdict does not match the data type of the like-named field defined in the dbdict provided by the upgrade package, the Upgrade Utility cannot merge these dbdicts. For example, if an existing dbdict has a scalar field and the Upgrade Utility attempts to add a structure field with the same name, this discrepancy prevents the dbdict from being updated.

To fix this issue, you can change the data type and the SQL type of the field, and use Complex Update to migrate existing data on that field to the target data type. Follow these steps to modify field data type by using the Dbdict Utility:

1. Navigate to System Navigator > Tailoring > Database Dictionary.
2. Type the dbdict name in the File Name field, and then click Search.
3. Double-click the field you want to change the data type, and then make updates as expected.
4. Save your changes.

The following is an example that shows the process of fixing a typical data type mismatch.

The following table displays a list of data type mismatches that may appear in the except.log file for an Oracle database. Only some examples are listed for each category of data type mismatch. If you are using an MSSQL database, the actual error message may vary slightly. For example, the following list highlights the different errors in the different databases:

• Oracle Error : dbdict:ApprovalDef, field:appr.condition, SQL type is CHAR(1) -- expected to be:RAW(255)
• MSSQL Error: dbdict:ApprovalDef, field:appr.condition, SQL type is CHAR(1) -- expected to be:VARBINARY(255)

dbdict:computer, field:video, SQL type is EMPTY -- expected to be:BLOB
dbdict:computer, field:vid.card.id, SQL type is VARCHAR2(30) -- expected to be:EMPTY
dbdict:computer, field:vid.card.bios, SQL type is VARCHAR2(30) -- expected to be:EMPTY
dbdict:computer, field:vid.manufacturer, SQL type is VARCHAR2(30) -- expected to be:EMPTY
dbdict:computer, field:vid.model, SQL type is VARCHAR2(30) -- expected to be:EMPTY
dbdict:computer, field:vid.chip.type, SQL type is VARCHAR2(30) -- expected to be:EMPTY
dbdict:computer, field:vid.memory, SQL type is NUMBER -- expected to be:EMPTY
dbdict:computer, field:vid.resolution, SQL type is VARCHAR2(30) -- expected to be:EMPTY
dbdict:computer, field:vid.resolution.x, SQL type is VARCHAR2(30) -- expected to be:EMPTY
dbdict:computer, field:vid.resolution.y, SQL type is VARCHAR2(30) -- expected to be:EMPTY

Fixing the FolderRights delete field

Example: The dbdict for the FolderRights table has a delete field with the "logical" data type. The Upgrade Utility tries to update the delete field with the "character" data type, which has possible values of "always," "never," "workgroup," and "assigned."

1. In the dbdict for the FolderRights table, add a field named delete.tmp with a data type of character, and update the dbdict.
2. Log out of the system and log back in.

3. Make sure that the Complex Update feature is enabled for the FolderRights table.

   Note To enable the Complex Update feature, open the FolderRights Format Control record, go to Privileges and open the Advanced tab, and then update the values in the Simple Mass Update field and in the Complex Mass Update field to true.

4. In the Database Manager, search for all records in the FolderRights table.
5. From the More Actions menu, click Mass Update.
6. When you are asked whether you want to update all records, click Yes.
7. Click Complex Update on the toolbar.

8. In the statements area under Instructions for action on EACH RECORD, add statements using standard RAD expressions to migrate data from the delete field to the delete.tmp field.

   Example:

   if delete in $file=true then delete.tmp in $file="always" else delete.tmp in $file="never"

9. In the dbdict for the FolderRights table, edit the delete field and add the Type (character) and SQL Type (same as the SQL Type automatically assigned for delete.tmp).
10. Log out of the system and log back in.
11. In the Database Manager, search for all records in the FolderRights table.
12. From the More Actions menu, click Mass Update.
13. Click Complex Update on the toolbar.

14. In the statements area under Instructions for action on EACH RECORD, add statements using standard RAD expressions to migrate data from the delete.tmp field to the delete field and empty the delete.tmp field.

    Example:

    delete in $file=delete.tmp in $file; delete.tmp in $file=NULL

15. In the dbdict for the FolderRights table, follow these steps to remove the delete.tmp field:

    1. In the Database Manager, search for all records in the dbdict table.
    2. Select the dbdict format.
    3. Type FolderRights in the Name field, and then click Search.
    4. Locate the row for the delete.tmp field. Remove the values in the Name, Type, Index, and Level fields respectively.
    5. Click Save and OK.
16. Log out of the system and log back in.
17. Test the change by updating records in the FolderRights table and populating the delete field with "always," "never," "workgroup," or "assigned."

Add new object record failure

All the upgraded objects are saved in the upgradeobjects table, and you need to add some objects from this table to the current upgradeobjects table. If the target table contains more than one unique type key, some errors may occur when adding new objects during the upgrade process. Refer to the following error message as an example.

2014-03-20 14:04:29 file:inbox, updated the field inbox.id value from 10000313 to 14042954310000313

The value of the inbox.id field is 10000313 in this example, which is used in the current upgradeobjects table. If the Upgrade Utility adds an inbox record that contains the same value for this field, the current value of the inbox.id field is automatically prefixed with a timestamp to avoid duplication errors. The timestamp is composed of hour (two bits), minute (two bits), second (two bits) and millisecond (three bits). In this example, the timestamp is 140429543.

After upgrading, you can update the temporary value of the inbox.id field as necessary.

Handle key change failure

If the Upgrade Utility fails to apply certain key changes, error information is logged into the except.log file. Review the log file and make appropriate operations.

Error message 1: Failed to add <key_type> key: <field_name> to table <table_name>. You must add it manually.

Follow these steps to handle this error:

1. Type dbdict in the Service Manager command line, and press Enter.
2. In the File Name field, type the table name indicated by the error message, and click Search.
3. Click the Keys tab.
4. Position the mouse point in the key name part of an empty key structure, and click New Field/Key.
5. Select the appropriate key type from the combo list, and add the appropriate field to the key, as indicated by the error message.
6. Click Add, and click Yes to confirm.
7. Click the Keys tab, and click OK to save the change.
8. Continue to follow steps 1 through step 7 for each key that failed to be added.

Error message 2: Failed to update <key_type> key: <old_field_name> to <new_field_name> in table <table_name>. You must update it manually.

Follow these steps to handle this error:

1. Type dbdict in the Service Manager command line, and press Enter.
2. In the File Name field, type the table name indicated by the error message, and click Search.
3. Click the Keys tab.
4. From the key list, select the key name that is indicated by the error message, and click Edit Field/Key.
5. Update the fields in the key according to the field names indicated by the error message.
6. Click OK, and click Yes to confirm.
7. Click the Keys tab, and click OK to save the change.
8. Continue to follow steps 1 through step 7 for each key that failed to be updated.

Error message 3: Failed to remove <key_type> key: <field_name> from table <table_name>. You must remove it manually.

Follow these steps to handle this error:

1. Type dbdict in the Service Manager command line, and press Enter.
2. In the File Name field, type the table name indicated by the error message, and click Search.
3. Click the Keys tab.
4. From the key list, select the key name that is indicated by the error message, and click Edit Field/Key.
5. Click Delete, and click Yes to confirm.
6. Click the Keys tab, and click OK to save the change.
7. Continue to follow steps 1 through step 6 for each key that failed to be removed.

In addition, you may encounter the following Unique Key errors:

Error:dbdict:Approval, Unique Key is {"unique.key", "file.name", "name"} -- expected to be:{"unique.key", "file.name", "name", "component"}

Error:dbdict:ApprovalLog, Unique Key is {"counter", "file.name", "unique.key"} -- expected to be:{"counter", "file.name", "unique.key", "component"}

Unexpected errors

If the except.log file or the Upgrade Results list reports any errors other than data type mismatches, review the sm.log file for more information, and if needed, contact Customer Support for assistance.