IBM ERwin MetaData Extract Program
Version 1.0



1. INTRODUCTION

   This document describes how to use the IBM ERwin MetaData Extract
   Program to extract the metadata from an ERwin ER1 file to generate a
   Visual Warehouse tag file.


2. SOFTWARE REQUIREMENTS

   Following are the software requirement in order to run the extract program:
   
      - Windows NT 3.5 or higher
      - ERwin 3.5.2
   
   Following are the software requirement in order to import the tag file:

      - Visual Warehouse Version 5.2 CSD 2


3. INSTALLATION
   
   The IBM ERwin MetaData Extract Program defaults to install under the 
   Visual Warehouse directory unless specified otherwise.  The extract program
   folder will also be added the the current Visual Warehouse folder.  If you 
   don't have Visual Warehouse installed, the folder is added to the Programs 
   menu.  The program requires less than 2M of disk space and after setup is 
   completed, you will find the following files in your directory:
   
      File name          Description
      ---------          -----------
      erw_ext.exe        Main migration program.
      vwexport.dll       Tag file generator dll.
      cdmerwsn.dll       ERwin API wrapper class dll.

   To run the extract program you have to register the ERwin API on your system.
   This enables the program to use the ERwin API without further manual 
   interaction.  If you are not sure if the ERwin API is registered on your 
   machine, you can just re-register the API, and the existing one will be 
   overwritten.
   
   Follow these steps to register the ERwin API:
   
      - In a MS DOS command prompt, go to the directory where your ERwin program
        files are installed. E.g. 'C:\Program Files\PLATINUM\ERwin ERX 3.5.2'
      - Execute the following command:
        regsvr32 er2api32.dll
      - A message box then comes up with the following information message:
        DllRegisterServer in er2api32.dll succeeded.
        Press OK.

   You can either invoke the extract program by using the short cut provided
   in the IBM ERwin MetaData Extract Program folder, a submenu of the Visual 
   Warehouse folder, or by executing the erw_ext command from a MS DOS 
   command shell.  

   
4. FUNCTIONALITY  
   
   The IBM ERwin MetaData Extract Program extracts all database, table and
   column objects stored in the input ERwin ER1 file.  It also creates
   relationship tags between databases and tables and between tables and 
   columns.  For tables without a database, a default database named DATABASE is 
   created and attached.  For tables without a schema, it uses a default schema
   of USERID.  To read more details regarding the mapping of ER1 attributes to 
   Visual Warehouse tags, please refer to Appendix B below.
   
   The current release of this program supports ERwin ER1 models with target 
   servers of:
   
      - DB2 for MVS/ESA Version 3
      - DB2 for MVS/ESA Version 4
      - DB2 for S/390 Version 5
      - DB2 for Common Servers Version 2
      - DB2 Universal Database Version 5
   
   The current release of this program supports ERwin ER1 models with source
   servers of:
   
      - Oracle Database Version 7.3
   
   If you received a error regarding an unsupported version of server, you 
   need to change the target server from ERwin and try again. See Appendix A
   on how to do this and for more information on error messages.
   

5. USAGE

   To generate a VW tag file, simply execute erw_ext.exe and provide two 
   parameters.  The first parameter should be the ERwin ER1 file to be extracted
   and the second parameter should be the name of the output tag file.  You need
   to make sure that the input ER1 file is in a writeable state. ERwin saves the
   ER1 file in a readonly state if it's being used in a current ERwin session or 
   if some error condition was detected.  You might receive an 'abnormal program
   termination' error message if the ER1 file is in a readonly state.  Below is 
   the syntax for using the extract program:
     
      erw_ext inputFile.er1 outputFile.tag
   
   The extract program writes out the table name that it is currently working on
   and when it finishes, you should see the message 'Extract program completed 
   successfully'.


6. IMPORT TAG FILE INTO VISUAL WAREHOUSE

   To import the resulting tag file into Visual Warehouse, follow these steps:
   
      - Invoke the 'Visual Warehouse Desktop' in the Visual Warehouse folder
      - Click on 'File->Import from Tag File', this will open the 
        'Import Warehouse' dialog.
      - Click on 'Find...' to search for the tag file, then click on 'Import'
      - After the import is completed, you can click on 'View->Refresh' to view 
        the new business view or search for the imported objects by clicking on 
        'Edit->Locate Objects'.
     
   If you wish to change a DB2 database definition so that it is reflected as 
   a source in Visual Warehouse, you can modify the tag file as follow:
   
      - Replace the occurrence of ISWH tag from ISWH(Y) to ISWH(N) 
        for each database you want as a source.
      - Replace the occurrence of the relationship tag from:
           :RELTYPE.TYPE(LINK) SOURCETYPE(SCGTARIR) TARGETYPE(DATABASE) 
        to: 
           :RELTYPE.TYPE(LINK) SOURCETYPE(SCGSRCIR) TARGETYPE(DATABASE)
        for each database you want as a source.
   


APPENDIX A - ERROR MESSAGES

   Error messages that you might receive during the extract program's processing
   and how to fix the problem:
   
   - "Missing ERwin ER1 input file or Visual Warehouse tag output file."
   
     The program requires two parameters in a certain order. The first parameter
     is the ERwin ER1 file and the second is the Visual Warehouse tag file.  If
     you specify the name of an existing tag file, the file will be overridden.
     
   - Window's system "abnormal program termination"
   
     This could be the problem of the input ERwin ER1 file being in a read-only
     state.  This sometimes happen if when saving the ER1 file, there was a 
     problem and ERwin puts the file in a read-only state.  Try issuing the 
     command 'attrib -r inputFile.er1' in a MS DOS command shell to change the 
     state of the ER1 file to writeable and try again.
     
   - "Error opening output file: ..."
   
     Unable to open the Visual Warehouse output tag file.  Check if there's any
     system problem that might prevent the creation or opening of a file on the
     current drive.
    
   - "Error - Unsupported server version: ..."
   
     The input ERwin ER1 file that you are trying to extract from has a target
     server that is not supported by the program.  You can fix this problem by 
     invoking ERwin, opening the ER1 file by clicking on 'File->Open'.  Then
     click on 'Server->Target Server' and choose one the supported version 
     documented above, save the modified ER1 file by clicking on 'File->Save As'
     and then try again. 
     
   - "Unknown ERwAPI error."
   
     An ERwin API error has occurred and the program was unable to obtain more
     information on the error.  Make sure that you have ERwin 3.5.2 installed
     and that you have registered the ERwin API.  Refer to the INSTALLATION 
     section above on how to do this.
     
   - "ERwAPI error: ..."  
   
     Check the error message and take action as appropriate.  Make sure that 
     you have ERwin 3.5.2 installed and that you have registered the ERwin API.
     Refer to the Installation section above on how to do this.
     
   - "Extract program error: ..."
   
     Check the error message and take action as appropriate.  Most likely, this
     is an internal extract program error, and the problem needs to be reported
     to an IBM representative.
     
   - "Unknown extract program error."
   
     An unknown error has occurred.  Most likely, this is an internal error, and
     the problem needs to be reported to an IBM representative.                   
                                 

APPENDIX B - ERWIN TO VISUAL WAREHOUSE MAPPING

   The following is a mapping of some of the main ERwin object attributes 
   to Visual Warehouse tags:
   
      ERwin Database           Visual Warehouse Database    Visual Warehouse GUI
      --------------           -------------------------    --------------------
      Diagram Name             NAME                         Name of Warehouse
      Diagram Author           RESPNSBL                     Contact
      Database Name            DBNAME                       Database name
      Database Version         DBTYPE                       Database type
      Diagram Description      SHRTDESC                     Description

      ERwin Table              Visual Warehouse Table       Visual Warehouse GUI
      -----------              ----------------------       --------------------
      Table Name               NAME                         Table name		
      Table Name               TABLES                       Table name
      Database Name            DBNAME                       n/a
      Schema                   OWNER                        Schema name
      Table Comment            SHRTDESC                     Description
   
      ERwin Column             Visual Warehouse Column      Visual Warehouse GUI
      ------------             -----------------------      --------------------
      Column Name              NAME                         Column name
      Datatype                 NATIVEDT                     Datatype
      Length                   LENGTH                       Length
      Scale                    SCALE                        Scale
      Null Option              NULLS                        Allows Nulls?
      Position                 POSNO                        Column position
      Primary Key              KEYPOSNO                     n/a
      Database Name            DBNAME                       n/a
      Schema                   OWNER                        n/a
      Table Name               TABLES                       n/a
      Column Comment           SHRTDESC                     Description
