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.

Note The error messages in the except.log file identify each data type by an index number:

Index number Data type
1 number
2 character
3 date/time
4 logical
8 array
9 structure
11 expression

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)
Error message in Oracle: Solution:

dbdict:incidents, field:svc.options, SQL type is VARCHAR2(90) -- expected to be:BLOB

dbdict:SMISTaskQueue, field:failedReason, SQL type is VARCHAR2(60) -- expected to be:BLOB

dbdict:Workflow, field:description, SQL type is VARCHAR2(255) -- expected to be:BLOB

To fix these issues, change the SQL type to RAW(255) or BLOB by using the Dbdict utility.

Additionally, you will need to set the “SQL RC” to true to allow the field to store RAD expressions. Note that the stored value of the field in the database is encoded by Service Manager.

dbdict:cm3eventack, field:number, field type is number -- expected to be:character

To fix this issue, change the field type to character by using the Dbdict utility.
dbdict:Rule, field:tablename, SQL type is VARCHAR2(60) -- expected to be:CLOB Ignore the error message. No further action is necessary.
dbdict:svcItemCount, field:access.filter, SQL type is RAW(255) -- expected to be:CLOB To fix these issues, change the SQL type to CLOB by using the Dbdict utility. Additionally, you need to switch the value of “SQL RC” to update the type.

dbdict:eventin, field:evnumber, field type is number -- expected to be:character

dbdict:eventout, field:evnumber, field type is number -- expected to be:character

These fields reside in the descriptor structure field of BLOB SQL type. To fix this issue, change the field type to character by using the Dbdict utility.

dbdict:svcCatLanguage, field:catalogid, field type is character -- expected to be:number

This field resides in the catalog structure field of BLOB SQL type. To fix this issue, change the field type to number by using the Dbdict utility.

dbdict:licenseinfo, field:id, field type is character -- expected to be:number

The licenseinfo table is used to track license information by Service Manager server. This issue should be ignored.

dbdict:svcCatalog, field:id.attach, field type is character -- expected to be:number

This id.attach field is an alias of id field in svcCatalog table. To fix the issue, change the field type to by using the Dbdict utility.

dbdict:FolderRights, field:close, field type is logical -- expected to be:character

The close field is an alias of delete field in FolderRights table. To fix the issue, change the field type to character by using the Dbdict utility.

dbdict:FolderRights, field:delete, field type is logical -- expected to be:character

This issue can be fixed by following the steps in the Fixing the FolderRights delete field section.

dbdict:cm3r, field:assets, SQL type is CLOB -- expected to be: VARCHAR2(200)

dbdict:cm3r, field:assets, field type:character, SQL type is CLOB -- expected to be:VARCHAR2(200), SQL table is m1 -- expected to be:a3

This kind of error message is generated because the Upgrade Utility does not remap the field of array type from the main table to the alias table and the subsequent full-table copy may slow down the upgrade.

Follow these steps to fix the issue:

  1. Double-click the field of array type which contains this field in the related table, and then update the value in “SQL Table” to a<number> which is not used in the alias table. For example, a3.
  2. Double-click the field of character type in the related table. Update the value in “SQL TYPE” to the expected value, and then update the value in “SQL Table” to the same a<number> which is not used in the alias table. For example, a3.

  3. Click OK to save your changes.

Caution If the related table contains more than 100,000 records, fixing the data type mismatches in the field may take more than one hour.

dbdict:inbox, Primary Key is inbox.id -- the primay key can not be added. Since SM doesn't support operation on table with primary key when applications version is older than 9.32, then add inbox.id as unique key. To fix this issue, change the unique key to primary key by using the Dbdict utility.
Update field type for record.number in kmreindex dbdict from number to character -- You need to update the relevant data in dbdict kmreindex manually. The field type is updated from number to character. You need to check whether the data values are updated and then update the data values to the correct ones.
Failed to add Primary key: {"mailno"} to table mail. You must add it manually. Check whether the primary key is added to dbdict mail. If not, please check whether the values of this field are filled for all records in this table. You need to manually fill this field and add the primary key by using the Dbdict utility.

Note Ignore the message if the child fields of an array of structure field have been mapped to the database columns. For example:

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."

Note

The field type of delete field in FolderRights dbdict may be updated to character. There is another information in except.log:

Update field type for delete in FolderRights dbdict from logical to character -- You need to update the relevant data in dbdict FolderRights manually.

The value of the field also need to be updated following the steps manually.

  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.

Important If you are upgrading from applications version earlier than 9.32, we recommend you to enable primary keys after the applications upgrade and the main steps are as follows:

  1. Apply the out-of-box upgrade
  2. Build a custom upgrade
  3. Apply the custom upgrade
  4. Enable primary keys

You can review the except.log file and then refer to Working with primary keys for conversion instructions.

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.