cjrarupdate (update resource adapter version)

Format

For updating the resource adapter version

cjrarupdate -type {dbconnector|rar} [-force] [-f file-path ...]
      [-backupto backup-storage-destination-directory]

For restoring the work directory environment

cjrarupdate -recoverfrom backup-RAR-directory

To Page Top

Function

For updating the resource adapter version

This command updates the version of resource adapter imported or deployed on Cosminexus Component Container.

The conversion of resource adapter requires unused space that is at least twice^# the disk usage space required for the work directory. Moreover, during upgrade installation, before you execute this command, you must use the conversion command cjenvupdate for checking that the conversion processing was completed without any problems.

The work-directory is the directory specified by the ejb.public.directory key in usrconf.cfg (option definition file for J2EE server).

#

The amount of required unused disk space depends on the number of resource adapters to be converted and the number of executions of the command. For the disk space required for conversion, you confirm the Application Server migration procedure. For the Application Server migration, see 10. Migrating from Application Server of Earlier Versions (In the J2EE Server Mode) in the uCosminexus Application Server Maintenance and Migration Guide.

For recovering the work directory environment

If an attempt to update the version of resource adapter imported or deployed on Cosminexus Component Container fails, this command recovers the work directory environment.

To Page Top

Arguments

-type {dbconnector|rar}

Specifies the type of resource adapter to be upgraded:

• dbconnector

  DB Connector.

• rar

  Resource adapter that is supported by Cosminexus Component Container; however, is not the DB Connector.

-force

Forcibly upgrades the version. When this argument is specified, the version of the resource adapter is upgraded regardless of the current version of the resource adapter.

-f file-path

• When a resource adapter other than the DB Connector is specified as the conversion target (when -type rar is specified)

  Specifies the file path of the resource adapter that replaces the existing old version resource adapter. Although multiple file paths can be specified, the -f option cannot be specified more than once.

  If a resource adapter conforming to the Connector 1.5 specifications other than TP1 inbound adapter or FTP inbound adapter is specified in the -f option, the message KDJE42356-E is displayed.

• When a DB Connector is specified as the conversion target (when -type dbconnector is specified)

  This argument is ignored.

-backupto backup-storage-destination-directory

Specifies the storage destination of the work directory backup. If this option is omitted, the backup directory is created in work-directory.

You specify this option when the disk containing the work directory does not have enough unused space or when the backup cannot be created because of a path length limitation associated with the file system. When you use this option to specify the backup storage destination directory, you should note the following items:

• To execute the cjrarupdate command multiple times, you specify the same directory.

• Backup creation might fail if a long path name is specified. If this happens, delete the failed backup and re-execute the command with a shorter path name specified.

• Specify a directory that does not include the installation directory of Cosminexus Component Container.

-recoverfrom backup-RAR-directory

Specifies the backup RAR directory for the work directory that becomes the recovery source.

To Page Top

Post-conversion operations

Once conversion has been completed, a backup work directory is created directly under the work directory of each J2EE server or the directory specified by the -backupto option. The work directory stores the post-conversion information (files), and the backup work directory stores the pre-conversion information (files). If the name of the work directory is ...\directory-name\ or .../directory-name/, the name of the backup work directory becomes ...\directory-name\rarupdate_bk\ or .../directory-name/rarupdate_bk/.^# After conversion, you should perform a startup check of the resource adapter, a termination check of the resource adapter, and a check of the resource adapter's connection with the database. After the checks have been completed, you can delete the backup work directory if the pre-conversion work directory information (files) is no longer required. However, it is recommended that you save the backup work directory to another location.

#

The backup target directory is related to the resource adapter.

If a backup work directory already exists, ...\directory-name\rarupdate_bk\ or .../directory-name/rarupdate_bk/ is renamed to ...\directory-name\rarupdate_bk_?\ or .../directory-name/rarupdate_bk_?/ (? is the command's execution date/time to the millisecond).

To Page Top

Procedure for comparing the version tags

Conversion processing might not terminate normally because the system is unable to evaluate the version tag for a RAR file to be converted.

To compare version tags:

1. Obtain the version character string from the <version> tag of the ra.xml containing the RAR file or the ra.xml of the resource adapter that was imported or deployed to the J2EE server.

2. If the version character string is specified in the following format, edit it to a format that can be compared:

   sequential-number-1.sequential-number-2character-string-beginning-with-a-non-numeric-character

   Format that can be compared

   V₁V₂-R₁R₂-S₁S₂ (or V₁V₂-R₁R₂)

   V₁, V₂, R₁, R₂: Number from 0 to 9

   S₁: /

   S₂: Upper-case alphabetic character (A to Z)

   The editing procedure is as follows:

   • Add a single-byte hyphen (-) between sequential-number-1 and sequential-number-2.

     sequential-number-1-sequential-number-2character-string-beginning-with-a-non-numeric-character

   • If sequential-number-1 is 9 or less, add a leading 0.

   • If sequential-number-2 is 9 or less, add a trailing 0.

   Editing examples

   1.0 → 01-00

   1.1 → 01-10

   1.12 → 01-12

   2.0 → 02-00

If the version character strings are specified in the format V₁V₂-R₁R₂[-S₁S₂], use the following procedure to compare the versions:

• Compare the V₁V₂-R₁R₂ sections as character strings. The string that is larger based on the Unicode dictionary sequence indicates the newer version. (Example: Between 01-00-/Z and 02-00, the newer one is 02-00.)

• If the V₁V₂-R₁R₂ sections are the same, the string that has a -S₁S₂ section indicates the newer version. (Example: Between 02-00-/A and 02-00, the newer one is 02-00-/A.)

• If the V₁V₂-R₁R₂ sections are the same and both character strings have a -S₁S₂ section, use the following comparison procedure:

  1. Compare the S₂ values as character strings. The string that is larger based on the Unicode dictionary sequence indicates the new version.

  2. Compare the S₁ values as character stings, and use the sequencing / > P > S to determine the new version.

  Examples: Between 02-00-/A and 02-00-/B, the newer one is 02-00-/B.

  Between 02-01-SB and 02-01-/A, the newer one is 02-01-SB.

  Between 02-01-SA and 02-01-PA, the newer one is 02-01-PA.

  Between 02-01-PA and 02-01-/A, the newer one is 02-01-/A.

• If the formats of one or both of the version tags are different from either of the formats discussed above, compare the entire version character strings. The string that is larger based on the Unicode dictionary sequence indicates the newer version.

If the value of the <version> tag of ra.xml is an unsupported character string, the versions cannot be compared correctly, and the following actions become necessary:

• If the replacement RAR file is recognized as the old version even though it is actually the new version, specify the -force option when you execute the command.

• If a resource adapter that was imported or deployed to the J2EE server with a RAR file of the old version is converted by mistake, recover the original environment from the backup work directory. For the backup work directory, see the following locations:

  • Chapter 10 in the uCosminexus Application Server Maintenance and Migration Guide.

To Page Top

Input examples

When multiple file paths are specified in the -f option

cjrarupdate -type rar -f file1 file2 file3

To Page Top

Return values

0:

The command terminated normally.

1:

The command terminated abnormally.

To Page Top

Notes

• To execute the cjrarupdate command in Windows, you must have administrator permission.

• To execute the cjrarupdate command in UNIX, you must have root permission (if Component Container Administrator is not set) or the Component Container Administrator permission (if Component Container Administrator is set).

• You must specify the -type option immediately after the command name and then specify dbconnector or rar. You can specify the -force, -f, and -backupto options in any sequence.

• Do not execute this command more than once concurrently.

• If the J2EE server is running or if a problem occurs during the J2EE server startup check, this command outputs a message and interrupts processing.

• The RAR file version is not upgraded in the following cases:

  • The contents of the RAR file have changed.

  • A file with the same name as a RAR file provided or supported by Cosminexus Component Container is created and imported.

  • A file name is generated by combining the name of a RAR file provided or supported by Cosminexus Component Container with numbers and characters.

  • When the resource adapter conforms to the Connector 1.5 specifications other than TP1

  • inbound adapter or FTP inbound adapter.

• To update the version of the resource adapter conforming to the Connector 1.5 specifications other than TP1 inbound adapter or FTP inbound adapter, import and redefine the resource adapter.

• Check whether the new RAR file is of same version when performing TP1/Message Queue-Access migration. If the new RAR file is of same version then specify the -force option and execute the migration process forcibly.

• If version upgrade is performed on resource adapters (uCosminexus TP1 Connector and TP1/Message Queue-Access) provided by products other than Cosminexus Component Container, you must add the properties as the resource adapters will not operate just by migration of these commands. In such a case, you must set up the resource adapters as instructed in the resource adapter manuals.

• Version upgrade might fail for resource adapters (uCosminexus TP1 Connector and TP1/Message Queue-Access) that are provided by products other than Cosminexus Component Container. If that happens, delete the resource adapter for which version upgrading failed, re-import the resource adapter, and then set the properties. It is advisable to write down the settings before deleting the resource.

• If the substituted RAR file is recognized as the same version or an earlier version, even if this version is a new version, you specify the -force option, and then re-execute the cjrarupdate command.

• Do not modify or delete a RAR file found in Cosminexus-installation-directory\CC\DBConnector\ (in Windows) or /opt/Cosminexus/CC/DBConnector/ (in UNIX), because conversion processing might not operate normally if the RAR file is modified or deleted.

• If an exception occurs during the backup process, the cjrarupdate command continues the process without being terminated after issuing the exception message. The backup directory is not created during this process.

• If a J2EE server does not have any resource adapter, the command continues processing without creating a backup.

• The command does not execute conversion processing if a backup has not been created for the J2EE server.

• When conversion is executed by using this command, for a property that is not defined in the <config-property> tag in the Connector attribute file for DB Connector, the <config-property-value> tag is set with the default value. For the added property, the default value is set. However, if the loginTimeout, PreparedStatementPoolSize, CallableStatementPoolSize, and CancelStatement properties do not exist, they are set with the following values after conversion:

  • loginTimeout: 0

  • PreparedStatementPoolSize: 0

  • CallableStatementPoolSize: 0

  • CancelStatement: false

To Page Top