Stand Alone Compare/Merge Tool User Guide. Contents 1 Overview 2 System Requirements 3 Set Up 3.1 Unix 3.2 Windows NT 3.3 Memory Setting/Limitation 4 Compare/Merge of Oracle Forms 4.1 Format of Forms Path 5 Compare (Diff) Usage 6 Description Of Compare (Diff) Functionality 6.1 Diff Window 7 Merge Usage 8 Description of Merge Functionality 8.1 Automatic vs Manual (Prompt) 8.2 Merge Window 8.3 Difference blocks 1 Overview The Standalone Compare/Merge tool can be used to compare and merge text and Oracle Forms files on the Windows NT and Unix platforms. The tool is essentially a subset of the full compare and merge functionality found in the Oracle Repository 6i. 2 System Requirements Operating System: Unix, Windows NT. A Java 1.1 Runtime Environment. Oracle Forms 6i. In order to be able to do Forms compare and merge operations the tool needs to call out to the Oracle Forms API. The following files are required in order to be able to run the Standalone Compare/Merge tool: ORACLE_HOME/Repadm61/Java/jfapi.jar ORACLE_HOME/Repadm61/Java/jr_cws.jar ORACLE_HOME/Repadm61/Java/jr_diff.jar ORACLE_HOME/Repadm61/lib/ewtcompat-dbg-3_2_6.zip ORACLE_HOME/Repadm61/lib/ewt-dbg-3_2_6.zip ORACLE_HOME/Repadm61/lib/share-dbg-1_0_7.zip Windows NT only ORACLE_HOME/BIN/JNIFormsLib.dll Unix Only ORACLE_HOME/lib/libJNIFormsLib.so (ewtcompat-dbg-3_2_6.zip, ewt-dbg-3_2_6.zip & share-dbg-1_0_7.zip are also obtainable from the Bali web site at: http://bali.us.oracle.com/bali/ewt/balirelease.html) 3 Set Up 3.1 Unix: The following files need to be included in the CLASSPATH environment variable: jfapi.jar jr_cws.jar jr_diff.jar ewtcompat-dbg-3_2_6.zip ewt-dbg-3_2_6.zip share-dbg-1_0_7.zip The location of the following file needs to be included in the LD_LIBRARY_PATH environment variable: libJNIFormsLib.so The following file is used on the Windows NT platform only and so can be ignored: JNIFormsLib.dll 3.2 Windows NT: The following files need to be included in the CLASSPATH environment variable: jfapi.jar jr_cws.jar jr_diff.jar ewtcompat-dbg-3_2_6.zip ewt-dbg-3_2_6.zip share-dbg-1_0_7.zip The following file needs to be included in the PATH environment variable: JNIFormsLib.dll The following file is used on the Unix platform only and so can be ignored: libJNIFormsLib.so 3.3 Memory Setting/Limitation The size of objects that can be compared or merged are subject to limitations imposed by the memory usage of the tool. With default heap size settings an "Out Of Memory" error will be thrown and the operation aborted with file sizes in excess of approximatly 1 MB. To increase the size of objects that can be compared/merged the heap size of the Java interpreter can be increased above the default value. 4 Compare/Merge of Oracle Forms The Compare/Merge tool uses the Oracle Forms API to load the following types of Forms: Oracle Developer Form modules: file extension .fmb Oracle Developer Menu modules: file extension .mmb Oracle Developer Object Library modules: file extension .olb These Forms modules can reference Forms libraries and subclass components from those Forms libraries. When a Form object does subclass from a library then in order for the Forms API to be able to load the Form it must be provided with a path where it can find the library. The Compare/Merge tool provides two methods by which this path information can be supplied by the user. i) As a parameter, described under the usage notes given below. ii) Via the Forms path dialog box which will be displayed in some instances when the tool detects that the compare/merge operation is being carried out on a Forms object. The Forms path dialog box may still be displayed in some instances when the Forms objects do not subclass from a library. In these cases it is OK to close the dialog without entering any path information. 4.1 Format of Forms Path: On Unix the Forms path directory separator character should be "/". On windows NT the Forms path directory separator character should be "\". It is not necessary to provide a trailing directory separator at the end of the path string. The path can be given in full or as a relative path. 5 Compare (Diff) Usage usage: oracle.repos.tools.file.Diff [flags] -fp1 : optional path for Forms subclassing -fp2 : optional path for Forms subclassing -x : text only mode (no GUI) When you are comparing or merging Oracle Forms objects which have subclassed objects you must provide the path for those subclassed objects. If an Oracle Forms object does not subclass then the Path for that object may be left blank. 6 Description Of Compare (Diff) Functionality A comparision of two files located on the file system can be displayed in one of two ways. i) Using the normal compare window. An explanation of this window is given below. ii) By specifying the text only mode, [ -x ], the difference information is output to the command line of the operating system instead and the compare window is not shown. 6.1 Diff Window The Compare window displays the results of a compare operation. A compare operation involves a base object version and a contributor object version. The base object version is the version with which the contributor object version is compared. The compare display consists of two panes separated by a resizing splitter. The left pane displays the contents of the base object version; the right pane displays the contents of the contributor object version. Expanding or collapsing branches on the right pane will cause the corresponding branch on the left to expand or collapse. You can scroll the screen vertically and horizontally using the scroll bars. Horizontal scrolling is synchronized so that corresponding items can be examined side by side. The compare display provides three ways in which differences between object versions can be identified: Different text colors to represent additions, deletions and modifications. Vertical bars to the left of each section of the object version to highlight what is being compared. The color of the block marker corresponds with the text color. Icons to indicate the nature of the difference that exists between object versions: Icons Added - An item has been added to the contributor version but not to the base version with which it is being compared. Deleted - An item has been deleted from the contributor version but not from the base version with which it is being compared. Update - An item is included in both the contributor and the base versions but the item is different in each version. 7 Merge Usage usage: oracle.repos.tools.file.Merge [flags] -c : common ancestor version -r : result file -fp1 : optional path for Forms subclassing -fp2 : optional path for Forms subclassing -fpc : optional path for Forms subclassing -a : automatic mode. This is the default mode. -p : prompt (manual) mode -b : batch mode The common ancestor file is that file which is the ancestor common to the two files to be merged in a version tree. If the common ancestor is not provided then the merge tool will be unable to carry out an automatic merge and will switch to manual mode. When you are comparing or merging Oracle Forms objects which have subclassed objects you must provide the path for those subclassed objects. If an Oracle Forms object does not subclass then the Path for that object may be left blank. Automatic Mode. Default. If no conflicts are detected the merge result will be saved into the file specified (-r). If a conflict is detected then the merge UI will be displayed to allow the user to resolve any conflict points. Prompt (Manual) mode: No automatic merge will be attempted and the UI will always be displayed. Batch mode: Automatic merge will be attempted. If no conflicts are detected the merge result will be saved into the file specified (-r). If -r is not specified in Batch mode then the operation will terminate with a non zero exit status. If a conflict is detected no UI will be shown and the tool will exit with a non zero exit status. 8 Description of Merge Functionality 8.1 Automatic vs Manual (Prompt) An automatic merge operation uses the merge algorithm; a set of rules for comparing two object versions with respect to a common object version and determining which differences should be implemented in a new composite object version. The merge algorithm works with units of comparison found in the versions involved in the merge operation. The nature of a unit of comparison depends on the object type: for example, when handling text files, the merge algorithm selects clusters of new, changed, or deleted lines. A difference is a change in either of the objects to be merged when compared to the common ancestor. A difference can be an addition, a subtraction, or a modification. Usually, the algorithm can make a correct selection (resolution) that will go forward into the new version. Resolution of a difference occurs when two of the versions agree over a given unit of comparison. However, it is not the majority use of the unit that is selected by the algorithm, but the one that represents a change, as illustrated in the following table. If all three of the units are the same, no resolution is required. A conflict arises when the differences are such that they cannot be resolved by the algorithm. If no common ancestor is specified then automatic resolution of the merge will not be possible, the tool will switch to manual (prompt) mode and the merge window as described below will be displayed. 8.2 Merge Window The merge window displays the results of a merge operation, showing the differences and conflicts encountered by the merge algorithm. It also shows selections made by the algorithm, and lets you override those selections before the result is produced. The Merge window appears in the following circumstances: You attempt to do an automatic mode merge [-a (defualt) ], and the merge algorithm encounters conflicts. You explicitly ask for the Merge window to be displayed by using the prompt (manual) mode [ -p ]. 8.3 Difference blocks The Merge window displays any differences in a series of difference blocks. A difference block shows the form that an item of data has in the contributor versions and the common ancestor version. The difference might be: A simple difference: a difference that the algorithm has been able to resolve using its own rules. In this case, the version containing the form of the item that the merge has selected to go forward to the result has its box selected. You can override the selection made by the algorithm by choosing an alternative form. A conflict: a difference that the algorithm has been unable to resolve using its own rules. In this case, no contributor has its box selected. You must resolve the conflict by choosing a form, otherwise an empty item goes forward to the result in that position.