X-Cart:Applying Upgrade Packs and Database Upgrade Scripts

Applying upgrade packs

To apply an upgrade pack to your X-Cart installation:

1. Place the files of your upgrade pack in the X-Cart root directory on your server or hosting account.
   • If you use a Windows-based server, or a UNIX-based server without terminal access:
     Decompress the upgrade pack archive to a directory on your system using your favorite compression program (WinZIP or any other archiver with support for TAR files).
     Use an FTP client to upload all the files of the decompressed archive (retaining the directory structure) to the X-Cart root directory on your server or your hosting account.
   • If you use a UNIX-based server with terminal access:
     Use an FTP client to upload the upgrade pack archive to the X-Cart root directory on your server or your hosting account.
     Decompress the archive using the following command:
     

     tar -xzvf <archive_filename>

2. Make sure that the files that will be patched during the upgrade have world writable permissions. Names of the files to be patched are listed in the file <xcart_dir>/upgrade/[source-version]-[target-version]/file.lst.
   If you use a UNIX-based server, to set world writable permissions to the required files you can run the following shell command:
   

   for i in `sed -e 's/,.*$//g' < upgrade/[source-version]-[target-version]/file.lst`; do chmod 666 $i ; done

   replacing the [source-version] and [target-version] parts with the source and target versions of the X-Cart installation that you upgrade.
   Important! The command must be run from the X-Cart root directory.
3. Log in to the X-Cart Admin area.
4. Go to the 'Patch/Upgrade Center' page (Tools menu -> Patch/Upgrade. Before X-Cart 4.4.x: Administration menu -> Patch/Upgrade).
5. In the 'Upgrade' section of the 'Patch/Upgrade Center' page, use the 'Target version' drop-down box to select the version to which you are going to upgrade your store (This corresponds to the upgrade pack you have uploaded). Also, in the 'I confirm that:' list, select all the checkboxes that apply. Click the Apply button.
   X-Cart will test whether the files that need to be patched by the upgrade pack can be patched successfully and will list the respective files showing their status. The file status definitions are as follows:
   
   • OK - File can be patched successfully.
   • Checksum error - Patch is corrupted. Try to download the patch again.
   • Non-writable - File does not have write permissions. Set write permissions on the file.
   • Not a file - Target is not a file. The original X-Cart structure has been modified and you need to apply the patch manually.
   • Not exists - File is missing. The original X-Cart structure has been modified and you need to apply the patch manually.
   • Could not patch - Patch cannot be applied to the file automatically, as the original X-Cart structure has been modified, and you need to apply the patch manually.
   • Already patched - File has been patched already.
     If your Patch/Upgrade center detects any problems (errors - marked in red), you will not be able to proceed with upgrading your X-Cart based store until these problems are resolved. You will have to go back, make the necessary corrections and run the upgrade pack applicability test once again.
     As soon as the applicability test has been passed successfully, you can continue with the upgrade pack application.
6. Click the Apply patch button at the bottom of the page.
   X-Cart will start patching the files. After the upgrade pack has been applied, X-Cart will display the list of patched files and a detailed report about the changes that have been made.
7. Click the Finish button at the bottom of the page to complete the upgrade pack application.

Applying database upgrade scripts

To apply a database upgrade script:

1. Place the database upgrade script in the X-Cart root directory on your server or hosting account.
   
   • If you use a Windows-based server, or a UNIX-based server without terminal access:
     Decompress the database upgrade archive to a directory on your system using your favorite compression program (WinZIP or any other archiver with support for TAR files).
     Use an FTP client to upload all the files from the decompressed archive (retaining the directory structure) to the X-Cart root directory on your server or your hosting account.
   • If you use a UNIX-based server with terminal access:
     Use an FTP client to upload the database upgrade archive to the X-Cart root directory on your server or your hosting account.
     Decompress the archive using the following command:
     

     tar -xzvf <archive_filename>

2. In a web browser, run the upgrade script <xcart_dir>/upgrade_sql.php replacing the <xcart_dir> part with the actual URL of your X-Cart installation. For example, http://www.example.com/xcart/upgrade_sql.php.
   
3. Read the X-Cart License Agreement and click the Proceed with Upgrade button.
   The script will display the progress of the upgrade procedure and finally report the results.

Troubleshooting

Checksum errors during upgrade

Checksum errors during upgrade are typically the result of corruption of the upgrade pack files either by the archiver program that was used to extract the upgrade archive or by the FTP client that was used to upload the upgrade pack files to the server.

If the upgrade pack files were extracted from the archive using WinZip, and now you are getting checksum errors, check your WinZip configuration to see if it is causing the problem: click Options, then Configuration, then select the Miscellaneous tab. The option 'TAR file smart CR/LF conversion' must be turned off. If it is not, clear this option and extract the files from the archive once again.

Also, ensure that your FTP client is set to transfer data in 'Binary' mode. If, instead of the 'Binary' mode, your FTP client is using the 'ASCII'/'Text' mode, the files of your upgrade pack may end up being corrupted due to the incorrect translation of line break character codes between Windows and Unix systems. Although the changes are not visible, the test performed by X-Cart returns checksum values that do not match the checksums of the original files; thus, you get checksum errors. To resolve this problem, you should set your FTP client to the 'Binary' mode and upload the upgrade pack files to the server again.