Hitachi

uCosminexus Service Platform Setup and Operation Guide

G.3 Migration procedure for an update installation

Note: Update installation can be used only when the version to be updated is 07-50 or later. To update a version earlier than 07-50, install version 11-00 as a new installation.

Update Service Platform from the old version (07-50 or later) to the new version (11-00), following the steps in the below figure ((1) Export the repository (operating environment) to (10) Update the execution environment (operating environment).

Figure G‒2: Migration procedure for an update installation

[Figure]

The steps in Figure G-2 ((1) Export the repository (operating environment) to (10) Update the execution environment (operating environment)) are described below.

For details about the commands used in these steps, see Chapter 5. Commands (Operating and Execution Environments) in the uCosminexus Service Platform Reference Guide. For details about the tasks performed in the development environment, see the manual Service Platform Basic Development Guide.

Important note

  • From version 07-60, the development environment and operating environment cannot share the same repository. If the repository is shared by the development and operating environments in the old version, prepare separate repositories in these environments before starting migration. For details about the migration procedure, see A.3 Migrating procedure when a repository is shared between development environment and operating environment in earlier version in the Service Platform Basic Development Guide.

  • If you stop the HCSC server and update the version of the execution environment while HCSC components are running, the HCSC components will stop when you restart the HCSC server. Therefore, after you restart the HCSC server, you must also restart the HCSC components.

  • Check whether the Service Coordinator administrator has been changed from root in a UNIX environment. If so, change the owner of the files in the following directory to the Service Coordinator administrator, and the owner group of those files to the group that the Service Coordinator administrator belongs to:

    /opt/Cosminexus/CSC

Organization of this subsection

(1) Export the repository (operating environment)

Before you update the version, in the operating environment, export the repository as a backup. If there are multiple repositories, export all necessary repositories as backups.

In the operating environment, execute the cscrepctl command (with the -export option) to export the repository (or repositories).

For details about how to export a repository, see 4.2 Exporting Repository Information.

To Page Top

(2) Perform update installation in each environment

Update the version of Service Platform by installing Service Platform 11-00 as an update installation in the development, operating, and execution environments. For a test environment in which Service Platform was set up by using HCSC Easy Setup, use HCSC Easy Setup to perform unsetup before you perform update installation, and perform setup again after update installation.

The following shows the prerequisites for update installation in each environment.

Prerequisites:

  • The HCSC server has been set up.

  • Service Platform and Reliable Messaging are not running.

  • The embedded database (if used) is not running.

  • The HCSC server, J2EE server, and HCSC components are not running.

Notes
Notes on update installation:

  • Before you start update installation, terminate all components, such as the J2EE server, Management Server, and PRF, in the execution environment.

  • If an embedded database is used, terminate it before you start update installation.

Notes on updating the version in the development environment:

  • In the development environment, delete the HCSCTE project before updating the version, and then re-create the project after updating the version.

  • To perform migration from a version earlier than 11-00, if necessary, back up the information in the following directory, and then perform update installation:

    service-platform-installation-directory\CSCTE\Samples

Note that update installation overwrites all files other than the files listed below:

To Page Top

(3) Change the class path of the J2EE server

If the version to be updated is earlier than 09-00 and the option definition file for the J2EE server (usrconf.cfg) contains the entries listed below, delete all of them. When you change the definition, we recommend that you use Smart Composer functionality or management portal.

To Page Top

(4) Perform migration of old option adapter definition files

Migration of the option adapters that were used in a version earlier than 09-00 requires the tasks described below.

(a) Migration of the TP1 adapter definition files

Copy the TP1 adapter execution-environment property files. The files to be copied and the copy destination directory are as follows:

Files to be copied: TP1-adapter-installation-directory\config\*.properties

Copy destination: Service-Platform-installation-directory\CSC\custom-adapter\TP1\config\

(b) Migration of the file adapter definition files

Copy the file adapter execution-environment property files. The files to be copied and the copy destination directory are as follows:

Files to be copied: file-adapter-installation-directory\config\*.properties

Copy destination: Service-Platform-installation-directory\CSC\custom-adapter\File\config\

(c) Migration of the Object Access adapter definition files

Copy the Object Access adapter execution-environment property files. The files to be copied and the copy destination directory are as follows:

Files to be copied: Object-Access-adapter-installation-directory\config\*.properties

Copy destination: Service-Platform-installation-directory\CSC\custom-adapter\OA\config\

(d) Migration of the Message Queue adapter definition files

Copy the Message Queue adapter execution-environment property files. The files to be copied and the copy destination directory are as follows:

Files to be copied: Message-Queue-adapter-installation-directory\config\*.properties

Copy destination: Service-Platform-installation-directory\CSC\custom-adapter\MQ\config\

(e) Migration of the FTP adapter definition files

Copy the FTP adapter command definition files and FTP adapter execution-environment property files. The files to be copied and the copy destination directory are as follows:

Files to be copied: FTP-adapter-installation-directory\config\*.properties

Copy destination: Service-Platform-installation-directory\CSC\custom-adapter\FTP\config\

To Page Top

(5) Uninstall products

The products listed below come with Service Platform 09-00 or later. If you update Service Platform from a version earlier than 09-00 and any of these products have already been installed, we recommend that you uninstall them.

To Page Top

(6) Import the repository (development environment)

In (1) Export the repository (operating environment) above, you exported the repository. Here, import the exported repository in the development environment. When you import the repository that was used in the old version, packaging and deployment definition are automatically performed, and the new version inherits the repository information. Note that packaging and deployment definition are automatically performed for only the service adapters, business processes, and user-defined receptions for which packaging and deployment definition were performed in the old version.

(a) Note applying to update from version 07-60 or later

If the version that you want to update is 07-60 or later, the service adapters and user-defined receptions to be deployed in the execution environment must be imported to the development environment and must be packaged again. If you do not repackage service adapters, the KDEC03007-E message might not be output. If you do not repackage user-defined receptions, incorrect characters might be output to the KDEC00001-E message. For details about how to perform packaging, see 7.2 Packaging in the Service Platform Basic Development Guide.

(b) Note applying to update from a version earlier than 08-10

If the elements (compositors) listed below are defined under the sequence or choice element in the data transformation definition and the number of occurrences is fixed to 1 for those elements, the node display is changed. As a result, an error message appears, indicating that the XML schema used in the mapping definition file has been changed.

  • sequence

  • choice

If this error message appears, restart mapping definition, and then apply the change.

(c) Notes applying to update from a version earlier than 09-50

  • If the data transformation definition includes the schema definitions shown below, the namespace is changed. As a result, an error message appears, indicating that the XML schema used in the mapping definition file has been changed.

    1. The schema that defines the target namespace (targetNamespace) at the import destination is specified on the transformation source node.

    2. The namespace in 1 is not defined in all namespace declarations (xmlns[:prefix]) including the import or include destination.

    If this error message appears, restart mapping definition, and then apply the change.

  • Default values are used for the minimum and maximum numbers of pooled instances. Therefore, if the property xml-pooled-instance-minimum or xml-pooled-instance-maximum is specified in the HCSC server runtime definition file, performance might be affected because of the specifications of these properties. To prevent performance from being affected, make sure that the same values are specified for these properties and the corresponding properties in the usrconf.properties file (user property file for the J2EE server), as shown below.

    Item

    Properties in the HCSC server runtime definition file#1

    Properties in the usrconf.properties file (user property file for the J2EE server)#2

    Min.

    xml-pooled-instance-minimum

    csc.dt.pool.DocumentBuilder.initialSize

    Max.

    xml-pooled-instance-maximum

    csc.dt.pool.DocumentBuilder.maxSize
    #1

    For details about the HCSC server runtime definition file, see 6.5.6 HCSC server runtime definition file in the uCosminexus Service Platform Reference Guide.

    #2

    For details about how to specify these properties, see 2.3.9(5) Using XML parser pool functionality option.

(d) Note applying to migration from a version earlier than 09-70

If the following schema is included in the data transformation definition, the namespace will be changed. Therefore, an error message stating that the XML Schema used in the mapping definition file has been changed will be displayed.

  • A namespace URI for which multiple different namespace prefixes are specified

If this error message is displayed, restart the mapping definition editor to apply the change.

(e) Note on memory

Import of the repository used in the old version requires a lot of memory. Therefore, use the procedure below to check whether the amount of installed memory is sufficient. If the amount of installed memory is insufficient, increase memory, and then import the repository.

  1. From the Eclipse menu, select Window, and then Preferences.

  2. In the tree view at the left of the dialog box that opens, select General.

  3. Select the Show heap status check box at the right of the dialog box.

  4. Select the trash can icon in the bottom right of the Eclipse window to run the garbage collector.

  5. Check the heap size displayed to the left of the trash can icon.

  6. If unused heap space is insufficient, edit the eclipse.ini file to increase the memory size (the value of -Xmx). For details about how to edit the eclipse.ini file, see 2.4.3 Setting up the Eclipse environment in the uCosminexus Application Server Application Development Guide.

To Page Top

(7) Export the repository (development environment)

Export the repository that was imported in (6) Import the repository (development environment).

To Page Top

(8) Import the repository (operating environment)

Import the repository that was exported in (7) Export the repository (development environment). Note that you cannot import the repository that was used in the old version.

Execute the cscrepctl command (with the -import option) in the operating environment.

For details about how to import the repository, see 4.3 Importing a repository.

To Page Top

(9) Update Service Platform and Reliable Messaging (execution environment)

Update Service Platform and Reliable Messaging by using the following procedure, which is also required when the version to be updated is earlier than 09-00:

To Page Top

(10) Update the execution environment (operating environment)

Update the version of the execution environment from the operating environment.

(a) Prerequisites

The execution environment can be updated when all of the following conditions are satisfied:

  • Management Server is running.

  • If a database is used (db-use=ON is specified in the HCSC server setup definition file), the database is started.

  • The versions of the repository and installation are the same.

    If the repository version and installation version do not match, update the development environment, and then execute cscrepctl -import repository-ZIP-file to update the repository.

  • (If the FTP inbound adapter is to be used) The resource adapter has already been updated by using the cjrarupdate command#.

    #

    For the cjrarupdate command, specify the following options and values:

    -type option: rar

    -f option: Service-Platform-installation-directory\CSC\inbound-adapter\ftp\rar\ftp_inbound_adapter.rar

    For details about the cjrarupdate command, see cjrarupdate (update resource adapter version) in the uCosminexus Application Server Command Reference Guide.

    Note that if you update the FTP inbound adapter from a version earlier than 09-50, the default terminator used for FTP response changes from the OS-dependent line break code to CR-LF. If you do not want to change the terminator, use the cjgetrarprop command to obtain the attribute file from the FTP inbound adapter's RAR files, change the definition, and then use the cjsetrarprop command to set the attribute file. For details about how to set the attribute file, see 3.2.3(3) Setting up the FTP inbound adapter.

If the prerequisites listed above are not satisfied, satisfy them in the order in which they are listed.

(b) How to update the version

Execute the cscenvupdate command to update the version of the repository and HCSC server. 

cscenvupdate -csc name-of-the-HCSC-server-to-be-updated

If you choose to convert the existing repository information before or after version update in the development environment, and to use the converted repository information with the new version, see Appendix A. Migrating from old version in the Service Platform Basic Development Guide.

Important note

If HTTP reception is used in the old version and the HITACHI Application Integrated Property File has been edited except the following elements, the changes are not applied to the new HITACHI Application Integrated Property File:

  • //hitachi-application-all-property/ejb-jar/hitachi-ejb-jar-property/display-name[.='cscmsg_urecp_custom']/../../hitachi-session-bean-property/display-name[.='CSCMsgCustomServiceDelivery']/../session-runtime/stateless/pooled-instance/minimum

  • //hitachi-application-all-property/ejb-jar/hitachi-ejb-jar-property/display-name[.='cscmsg_urecp_custom']/../../hitachi-session-bean-property/display-name[.='CSCMsgCustomServiceDelivery']/../session-runtime/stateless/pooled-instance/maximum

  • //hitachi-application-all-property/ejb-jar/hitachi-ejb-jar-property/display-name[.='cscmsg_urecp_custom']/../../hitachi-session-bean-property/display-name[.='CSCMsgCustomServiceDelivery']/../ejb-transaction-timeout/method/method-name[.='*']/../../transaction-timeout

Therefore, if necessary, use the csccompoconfig command to obtain the HITACHI Application Integrated Property File, edit the contents, and then apply the changes.

For details about how to use the csccompoconfig command, see A.6 csccompoconfig (Defining HCSC components) in the uCosminexus Service Platform Reception and Adapter Definition Guide.

(c) Note applying to migration from a version earlier than 09-71

If the version is updated to 11-00, because the initial values of the following properties in the HCSC runtime definition file will be changed, memory usage might increase. For details about the HCSC runtime definition file, see 6.5.6 HCSC server runtime definition file in the Service Platform Reference Guide.

  • formatdef-maxcache-num

  • transformdef-maxcache-num

(d) Note applying to migration from a version earlier than 11-00

To update the version to 11-00, the application server compatibility mode must be used. Therefore, only the functions that support the application server compatibility mode can be used.

To Page Top

Trademarks

All Rights Reserved. Copyright (C) 2022, Hitachi, Ltd.