Using repos_copy

Repos_copy is a command line interface for working with integration components and InterChange Server repositories. It allows you to deploy a package--a collection of integration components--to a server repository, or to export components from the repository to a package.

Repos_copy is also used to migrate components from earlier versions to the current release. If you are working with old-format components, first migrate your components. Refer to the WebSphere Business Integration Server Express installation guide for Windows, for Linux, or for OS/400 for more information. Repos_copy does not support "-ar, -arp, -vr, -vp -xCompilePackage", and has limitations for "-o", and all the -xCompile options when working with old-format components.

To run repos_copy, enter the command in an MS-DOS command prompt window (Windows) or at a shell prompt (Linux). For OS/400, From the command line, type the QSH command, and from QSHELL run the repos_copy.sh script. The ProductDir/bin directory, where the utility resides, should be in your path as a result of installation. For OS/400, the script resides in /QIBM/ProdData/WBIServer43/bin directory by default.

Note:
The repos_copy output file contains encrypted passwords for relationships and connector applications. If you try to edit the output file and change these passwords, repos_copy does not work.
Important:
When repos_copy deploys components to the repository, it deploys them to the repository only. It does not deploy them to any in-memory tables of business object definitions. For example, connectors load business object definitions from the repository into their memory space when they start. If you deploy a business object definition to the repository to update it, you must restart the connector agent so that it loads the modified business object definition into memory. You must stop and restart InterChange Server Express and components that load definitions into memory for them to load recently deployed components.

This chapter has the following sections:

For more information about backing up the system, see the System Administration Guide.

Repos_copy syntax

Table 13 describes the options of repos_copy and their arguments, and shows the correct case usage for the options and the lack of spacing between the option and its argument. The syntax shows that the options between curly braces ({}) represent a set of options, at least one of which is required. If you do not specify the -u, -p, -i, -o, or -s options at the command line, then repos_copy prompts you for them. If you do not specify them when prompted, repos_copy does not execute. Options enclosed in brackets ([]) are optional.

Usage:repos_copy [-sserverName][-uusername][-ppassword] |
[-ifilename [-ai| -ar| -arp] [-k] [-ncENCODING] [-xcompilepackage] [-xdi]
[-xdn][-r[[relationshipName1[:relationshipName2]: ...]|*] ]|
[-oJARfilename [-xnoclasses]] |
[-eentityType:entityname1[+entityType:entityname2]+... [-deep] [-oJARfilename] ]
[-fentityfilename [-deep] [-oJARfilename] ] |
[-xCompileAll [-wi] ] |
[-xCompileAllCollabs [-wi]] |
[-xCompileAllMaps [-wi] ] |
[-xCompileCollab:templateName1[+templateName2]+...[-wi] ] |
[-xCompileMap:mapName1[+mapName2]+... [-wi] ] |
[-mode] |
[-d] |
[-doentityType:entityname1[+entityType:entityname2]+... [-deep] ] |
[-dfoentityType:entityname1[+entityType:entityname2] -deep] |
[-summary [-oXML_filename] ] | 
[-vp [-iJARfilename] ] |
[-vr]


Table 13. Repos_copy command options

Option Description
-ai

Ignore and do not load duplicate objects (business objects, maps, relationships, collaboration templates and objects, and connectors) that are found when deploying a package.

-ar

Replace duplicate objects (business objects, maps, relationships, collaboration templates and objects, and connectors) that are found when deploying a package.

-arp

Replace duplicate components. This is an interactive version of the -ar option. If the components in the package being deployed already exist in the repository, you are prompted to ignore or replace the component.

-d

Delete the components in the repository, except the state data. Use this option to delete all of the components from the repository.

-deep

Use with the -e option to include all the dependent components. If you omit the -deep option, only the component that is specified with the -e option is included.

-dfoEntityType:Entity[+EntityType:Entity2]

Forcefully deletes the component even if the component has referents that depend on it. This option only works with the repository of a server that is running in design mode. A server that is running in production mode does not permit unresolved dependencies and references. See also the -do option.

-doEntityType:Entity[+EntityType:Entity2]

Specify the entities to be deleted from the repository. See Table 14 for the list of entity types and keywords. If the object has no referents--other components that depend on it--then the deletion takes place. If the object has referents, then the deletion fails and a message is displayed. The behavior is the same in both design mode and production mode. For more information about starting the server in design mode or production mode, see the System Implementation Guide.

-eEntityType:Entity1[+EntityType:Entity2...]

Export one or more referenced first-class entities. A first-class entity is a business object, collaboration object, collaboration template, connector, database connection pool, map, or relationship. You identify the entity to load or unload by specifying one of the keywords in Table 14.

Follow the EntityType keyword with a colon (:) and the name of the entity. Use the "+" to specify more than one entity. When combined with the -o option, the -e option unloads the data to an output file.

-fentityFile

Similar to the -e option, but take the names of the entities from the file EntityFile. The file should contain references to the entities, with the following conditions:

  • The entity names must follow after the proper entity type keyword. The entity types and their keywords are listed in Table 14.
  • A colon must separate the entity type from the entity name.
  • There must be a new line separating each entity reference.

When combined with the
-o option, this option exports the components to a package.

-ifilename

Deploy the specified package file to the repository. If you omit the input file name value, the command interactively prompts you to enter the name of the input file. The file can be either a .jar file containing objects in XML format or an .in file containing objects in a text format.

The .jar files created by repos_copy or System Manager have a particular structure which must be maintained for any subsequent imports of such a file to be successful. You should not, therefore, ever modify an input file manually.

-k

Override the default behavior of repos_copy when it finds a Mercator map in the package file it is loading. By default, repos_copy exits if it encounters a Mercator map. If you use the -k option, repos_copy skips over any Mercator maps in the package file and proceeds with the deployment process.

-mode

Return the mode of the server. For more information about InterChange Server Express modes, see the Implementation Guide for WebSphere InterChange Server.

-ncencoding

See the Java documentation about the String class for a list of valid character encodings.

When deploying a repository created with WICS version 4.1.1, specify the character encoding used in the 4.1.1 environment.

-ooutfilename

Export the components in the repository to the specified package file. You must specify the name of the package file. If the file already exists then repos_copy prompts you to overwrite it or not. The output file is in .jar format, and contains the component definitions in XML format, and .java source files for components that have them. This option cannot be combined with the -i or -d options, nor can it export components in text format as it did in previous releases. Repos_copy does not append the .jar extension, so you must specify it when specifying the name of the output file.

-ppassword

Specifies the password for the user name supplied with the -u option. The password case-sensitive. If you do not specify this option then repos_copy prompts you for the password.

-r*

Import relationship definitions and not create the run-time schemas for any of them. See also the -r option.

-rrelationshipName1[:relationshipName2]

Load the named relationship definition(s) into the repository without creating its run-time schema.

-sserverName

Specify the name of the InterChange Server Express instance with which repos_copy should interface. The name is case-sensitive. If the server name is not specified, the tool prompts for a server name.

-summary

List components in the server repository (they are identified as "artifacts" rather than as components in the output). The output is in XML format. You can combine this option with the -o option to print the output to a file rather than the console.

-uusername

Specify the user name to log on to InterChange Server Express. If no user name is specified, repos_copy prompts for a user name.

-v

Print the version number of the program that the repos_copy utility executes.

-vp

Validate a package file. The server validates packages against the repository and makes sure that the dependencies among the components in the package are resolved. If the validation is not successful, repos_copy prints a list of the missing dependencies. This option does not make any changes to the repository; it just validates the package file. When using the -vp option you must also use the -i option to specify the package file to be validated.

-vr

Validate the repository. The output message indicates whether the validation is successful or not. If the validation is not successful, repos_copy prints a list of the missing dependencies.

-wi

Do not display warning messages that occur during the compilation of collaboration templates or maps. Only errors that occur during compilation are displayed. This allows the user to ignore warnings about deprecated methods, for example.

-xCompileAll

Compile all collaboration templates and maps in the repository.

-xCompileAllCollabs

Compile all collaboration templates in the repository.

-xCompileAllMaps

Compile all maps in the repository.

-xCompileCollab:collabTemplateName[+collabTemplateName]

Compile the specified collaboration templates in the repository.

-xCompileMap:nativeMapName[+nativeMapName]

Compile the specified maps in the repository.

-xCompilePackage

Tells the server to compile maps and collaboration template java files. If the package contains pre-compiled class files, don't use this option. In production mode, unless all class files are in the package, this option is selected by default. For a full description of InterChange Server Express modes, see the System Implementation Guide.

-xnoclasses Identifies whether to include class files when exporting components from the server.

Table 14. Keywords for different entity types

Entity type Keyword
Business object BusObj
Collaboration object Collaboration
Collaboration template CollabTemplate
Database connection pool ConnectionPool
Connector Connector
Map Map
Relationship Relationship

Repos_copy usage scenarios

This section describes many of the common situations in which you can use repos_copy. It contains the following sections:

Example of printing the repos_copy command

You can run repos_copy without any arguments to have the command and its arguments printed out. The example below shows repos_copy when run without any arguments, and the resulting output:

No Command line arguments to ReposCopy were specified
Usage:repos_copy [ [-sServerName] [-uUserName] [-pPassword] ] |
[-iFileName [-ai| -ar| -arp] [-k] [-ncEncoding] [-xcompilepackage]
[-xdi] [-xdn] [-r[[RelationshipName1[:RelationshipName2]: ...] |

*] ] |
[-oJARfileName [-xnoclasses]] |
[-eentityType:EntityName1[+entityType:EntityName2]+... [-deep]
[-oJARfileName] ] |
[-fENTITYFILENAME [-deep] [-oJARfileName] ] |
[-xCompileAll [-wi] ] | [-xCompileAllCollabs [-wi]] | [-xCompileAllMaps
[-wi] ] | [-xCompileCollab:TemplateName1[+TemplateName2]+... [-wi] ] |
[-xCompileMap:MapName1[+MapName2]+... [-wi] ] |
[-mode] |
[-d] |
[-doentityType:EntityName1[+entityType:EntityName2]+... [-deep] ] |
[-dfoentityType:EntityName1[+entityType:EntityName2] -deep] |
[-summary [-oXML_FileName] ] |
[-vp [-iJARfileName] ] |
[-vr]

Example of validating a package

You can validate a package of components before deploying the package to a server. This is very useful because if you deploy a package to a production-mode server all the dependencies must be resolved or the deployment fails. You cannot validate a user project or integration component library in System Manager to make sure that the dependencies are satisfied, so the only way to find out if a package is valid when deploying with System Manager is to attempt the deployment and use the error information when it fails to resolve the dependencies. If there are many components in the package, this can be a very time-consuming process.

Although you cannot validate an integration component library, you can export it to a package file and then validate the package file using repos_copy.

To validate a package file using repos_copy, use the -i option to specify the name of the package file to be validated and the -vp argument to validate it rather than deploy it.

For example:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-iWebSphereICS420DEVServer.jar -vp

Repos_copy validates the contents of the package and displays a message to indicate whether or not the dependencies are resolved.

Example of deploying a package to the repository

The -i option allows you to deploy a package of components to the repository. If you do not specify the name of the package file then you are prompted to enter it.

The following example shows a a file named WebSphereICS420DEVServer.jar being deployed to a repository:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-iWebSphereICS420DEVServer.jar

Example of deploying a package with precompiled class files to the repository

Normally if a package contains some collaboration template or map implementation java files, but no related class files, use the -xcompilepackage option when deploying the package to the repository. This is because class files must exist when these maps or templates are running. (Refer to Example of compiling and creating schemas.)

If precompiled class files are also in the package, you can use them directly after deployment without compiling the java files on server. This increases performance (because there is no additional compilation time) but the behavior is the same as common deployment.

The following example shows a file named WebSphereICS420DEVServer.jar with precompiled class files being deployed to a repository:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull
-iWebSphereICS420DEVServer.jar

Example of duplicate components

Commonly there are components with the same name in the package file as there are in the repository. In this case you must decide whether or not you want to replace the components in the repository with those in the package file. The -ai option specifies that duplicate components should not be loaded into the repository:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull
 -iWebSphereICS420DEVServer.jar

If you want to replace all the duplicate components in the repository, use the -ar option as in the following example:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-iCustomerSyncInterface.jar -ar

You can use the -arp option to interactively replace duplicate components in the repository. This lets you decide for each individual duplicate component whether it should be replaced or not.

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-iCustomerSyncInterface.jar -arp

Example of compiling and creating schemas

For maps and collaboration to execute at run time, the maps and collaboration templates defined in the repository must be compiled. For relationships to function properly at run time, their schemas must be created.

When you deploy components to a server running in production mode, all templates are automatically compiled and all relationship schemas are created. For the deployment to succeed, then, the code of the map and collaboration templates must be valid and InterChange Server Express must be able to communicate with the databases specified in the settings of the relationship definitions.

When you deploy components to a server running in design mode, the templates are not automatically compiled; relationship schemas are automatically created. There are options you can use to compile the templates, however, and there are options to not create relationship schemas.

The following example uses the -xCompilePackage option and does not use any form of the -r option. The result is that when the package specified by the -i option is deployed, the maps and collaboration templates are compiled and schemas are created for the relationships:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-iWebSphereICS420DEVServer.jar -xCompilePackage

You may not want relationship schemas created when you do a deployment. For example, if you are deploying a package from one environment to another and did not change the properties of the relationships to use the database resources in the new environment, you want to change the relevant properties before schemas are created. The following example uses the -r* option to not create schemas for all of the relationships in the package being deployed:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-iWebSphereICS420DEVServer.jar -xCompilePackage -r*

Note:
You can use the -r option without the asterisk to specify the names of individual relationships whose schemas should not be created. For example,
-rCustomer:Order would not create schemas for the Customer and Order relationships, but would still create schemas for any other relationships in the package being deployed.
Important:
Although there are options to compile maps and collaboration templates after deployment, there is no way to either through repos_copy or System Manager to create the schema for a relationship other than during deployment. So, if you chose not to create the schema for a relationship during deployment because you needed to change the database settings, then you need to re-deploy the relationship afterwards and allow repos_copy to create the schema for the relationship.

Example of validating the repository

The repository must be valid for the server to process flows successfully. Use the -vr option to validate a server repository, as in the example below:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull -vr

If the server is valid then repos_copy writes the following output to the console:

Validation Succeeded.All Dependencies Resolved.

If the repository is not valid then repos_copy prints a list of the dependencies that must be resolved.

Example of compiling components in the repository

If you deployed maps or collaboration templates to the repository and did not compile them during deployment, you can use repos_copy to compile them afterwards. This can be useful in situations where there are many components to deploy because deployment can take a long time and compiling can make the operation take even longer. Waiting until after the deployment has succeeded to do the compilation task can reduce the risk of spending an even greater amount of time migrating the environment if an error occurs.

The following example shows the use of the -xCompileAll option to compile all maps and collaboration templates in the repository:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-xCompileAll

There are options to compile all of either type of component as well. Use
-xCompileAllCollabs to compile all the collaboration templates, and
-xCompileAllMaps to compile all the maps. The example below shows the use of
-xCompileAllMaps:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-xCompileAllMaps

Just as you can compile all of one type of component, you can also compile an individual component. Use the -xCompileCollab or -xCompileMap option followed by a colon and the name of the collaboration template or map to compile a single component. The example below would compile a collaboration template named CustomerSync:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-xCompileCollab:CustomerSync

Example of deleting components from the repository

There are several options provided by repos_copy for deleting components in the repository. You can delete the entire repository, individual components, and individual components and any components that reference them.

Note:
Components must be inactive for you to delete them. If you delete a single component then you must deactivate it first or the delete operation fails. If you want to delete a component and all the components that reference it, you must deactivate not only the single component, but all those that reference it as well. You can delete the entire repository when the components are in an active state. Use System Monitor or web-based System Monitor to manage the states of components. System Monitor and web-based System Monitor are described in the System Administration Guide.

Example of deleting the entire repository

Use the -d option to delete all of the components in the repository. The following example shows the syntax:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin 
-pnull -d

Repos_copy presents a prompt asking if you want to delete the entire repository or not.

Example of deleting components without referents

If a component does not have any referents--other components that reference it and require it to exist in order to perform their function in the system--then you can delete the individual component.

Use the -do option followed by the entity type, a colon, and the name of the component. The entity types are listed in Table 14. The following example deletes the relationship named Customer:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin 
-pnull -doRelationship:Customer

Examples of deleting components with referents

If a component does have referents--other components that reference it and require it to exist in order to perform their function in the system--then you can only delete the component if the server is running in design-mode, and by using certain options.

Example of forcing a delete in spite of references

If a component has referents, repos_copy does not let you delete it with the -do option. You must use the -dfo option to force deletion of a component with referents. Forcing deletion of a component that has referents leaves the repository in an inconsistent state, and a server running in production mode does not permit that, so this option only works with a design-mode server. The following example shows the use of the -dfo option to delete the Order business object in spite of the fact that other components in the system (such as maps and relationships) have references to it:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-dfoBusObj:Order

Example of deleting the referents as well

Another way you can delete a component that has referents is to use the -deep option to delete the referents as well. This deletes the component and all of the components that have references to it. The following example shows the use of the -deep option when using the -do option to delete the Customer business object:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-doBusObj:Customer -deep

This option, unlike the -dfo option, is supported with servers running in production mode because the deletion of the referents along with the component guarantees that the repository remains valid. Keep in mind, however, that it can result in many components being deleted; you should be aware of the implications of this action prior to taking it.

Example of exporting components to a package

The -o option allows you to export components from the repository to a package. You must specify the name of the package file. When the -o option is used alone the entire repository is exported to a file, as in the following example:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-oWebSphereICS420DEVServer.jar

You can specify individual components to be exported by using the -e option. You must use the -e option with the appropriate EntityType keyword listed in Table 14, and must follow the keyword with the name of the component. You can specify multiple components by concatenating them with the plus (+) sign. In the following example, the Customer business object and CustomerSync collaboration template are exported to a package named CustomerSyncInterface.jar.

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-eBusObj:Customer+CollabTemplate:CustomerSync -oCustomerSyncInterface.jar

Normally the class files of maps and collaboration templates (if they exist) are also exported with their java files into the package file. If you don't need them, using the -xnoclasses option to ignore these class files, for example:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull
-oWebSphereICS420DEVServer.jar -xnoclasses

You can use the -deep option to export the dependencies of a component as well. In the previous example, the Customer business object was exported, but none of its child business objects were. The following example uses the -deep option to export the CustomerSync_ClarifyToSAP collaboration object and all of its dependencies.

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-eCollaboration:CustomerSync_ClarifyToSAP -oCustomerSyncInterface.jar -deep

If you want to export specific components, but do not want to have to enter the entity type keyword and component names, you can store them in a text file and use the -f option. This is very convenient when you want to frequently export the same components. The following example uses the -f option to load the components listed in a text file named Components.txt:

C:\WebSphereICS420DEV>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull 
-fComponents.txt -oCustomerSyncInterface.jar -deep

The contents of the file Components.txt are shown below; a paragraph return follows each entity type keyword and name combination:

BusObj:Customer
Relationship:Customer
CollabTemplate:CustomerSync
Note:
Repos_copy and System Manager are unfortunately inconsistent with respect to what they identify as "dependencies". If you attempt to delete a component using repos_copy but there are components that depend upon it then repos_copy lists those referring components as dependencies. However, if you right-click the component in System Manager and click Show Dependencies, the tool lists the components that the selected component depends on.

Example of printing a list of components in the repository

You can use the -summary argument when executing repos_copy to print a list of the components in the repository. The output is presented in XML format. Although it is not particularly useful to view at the command line, you can combine the -summary argument with the -o argument to redirect the output to a file and then view the file in a browser or XML editor. The command usage in this case would be the following:

C:\>repos_copy -sWebSphereICS420DEVServer -uadmin -pnull -summary -oRepository.xml

Locale for repos_copy files

The repos_copy utility reads metadata from the repository and writes the data out to files in Unicode (UTF-8 format). It also reads such files and loads them into the repository in Unicode (UTF-8 or UCS-2, as the underlying repository database dictates).

Repos_copy files created with InterChange Server Express version levels earlier than 4.1.1 can be loaded into the repository correctly only if the dates and times for the component schedules are in full US format. (This is usually not a problem. Repos_copy saves all schedule dates in full US format only. The incompatibility may arise if the repos_copy files have been manually edited.)

In addition, when deploying 4.1.1 repositories, be sure to specify the character encoding with the '-nc' option.

Copyright IBM Corp. 2004