IBM ERwin MetaData Extract Program
Version 2



1. INTRODUCTION

   This document describes how to use the IBM ERwin MetaData Extract
   Program to extract the metadata from an ERwin ER1 file and generate an
   IBM Data Warehouse or Information Catalog tag file.



2. SOFTWARE REQUIREMENTS

   Following are the software requirements in order to run the extract program:
   
      - Windows NT 3.5 or higher
      - ERwin 3.5.2 with Service Pack 2
      - Template files (.tag) in the directory pointed to by the environment 
        variable VWS_TEMPLATES
      - Type files (.typ) in the directory pointed to by the environment 
        variable DGWPATH
   
   Following are the software requirements in order to import the tag file:

   For IBM Data Warehouse:	
      - IBM DB2 Universal Database Version 7.1 
   For Information Catalog:
      - IBM DB2 Warehouse Manager 


3. INSTALLATION
   
   The IBM ERwin MetaData Extract Program defaults to install under the 
   IBM DB2 directory unless specified otherwise.  The extract program
   folder will also be added to the current IBM DB2 folder.  
   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.
      erwext.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 IBM DB2
   folder, or by executing the erw_ext command from an MS DOS command shell.  


   
4. FUNCTIONALITY  
   
   The IBM ERwin MetaData Extract Program extracts all physical objects such 
   as databases, tables and columns stored in the input ERwin ER1 file and 
   writes the metadata model to an IBM Data Warehouse or an Information Catalog tag file. 
   For Information Catalog, the logical model, consisting of entities and attributes, are
   also extracted and generated.  It also creates all the relevant relationship
   tags between objects such as between databases and tables and tables and 
   entities and so on.  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.  For model name, it uses the ER1 file name.  To 
   read about more details regarding the mapping of ER1 attributes to IBM Data Warehouse
   or Information Catalog tags, please refer to Appendix B and Appendix C below.
   
   The extract program supports all ERwin ER1 models with SQL DBMS servers of 
   DB2, Informix, Oracle, Sybase, ODBC and SQL Server.  If you received a error
   regarding an unsupported version of database server, you need to change the 
   target server from within ERwin, save the file and try again.  Refer to 
   Appendix A on how to do this and for more information on error messages.
   


5. USAGE

   To generate an IBM Data Warehouse or Information Catalog tag file, simply execute 
   erw_ext.exe and provide two main parameters.  The first parameter should be 
   the ERwin ER1 file to be extracted from and the second parameter should be 
   the name of the output tag file.  The extract program defaults to generate an
   IBM Data Warehouse tag file with the MERGE option.  Use the following
   to determine the syntax for using the extract program:
     
      erw_ext inputFile.er1 outputFile.tag [-vw] [-dg] [-m] [-u] [-a] [-d]
      
      where:
      -vw  - To generate an IBM Data Warehouse tag file
      -dg  - To generate an Information Catalog tag file
      -m   - Specify the action on the object as MERGE
      -u   - Specify the action on the object as UPDATE
      -a   - Specify the action on the object as ADD
      -d   - Specify the action on the object as DELETE
   
   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.  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 IBM DATA WAREHOUSE

   There are two ways of importing a tag file into IBM Data Warehouse.  You can
   use the IBM Data Warehouse Center or use the command line.  To use the IBM Data
   Warehouse Center, follow these steps:
   
      - Invoke the 'IBM Data Warehouse Center' from the IBM DB2 Control Center
      - Right click on 'Warehouse->Import Metadata', this will open the 
        'Import' dialog.
      - Browse to search for the tag file, then click on 'OK'
      - 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->Find'.
     
   To import a tag file language file using the command interface, enter the 
   following command at a DOS window:
   
      iwh2imp2 tag-filename log-pathname target-control-db userid password

      where:
      tag-filename      - the full path and file name of the tag language file
      log-pathname      - the full path name of the log file
      target-control-db - the name of the target database for the import
      userid            - the user ID used to access the control database
      password          - the password used to access the control database
   
   If you wish to change a DB2 database definition so that it is reflected as 
   a source in IBM Data 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.
        
   For more information, please refer to the IBM Data Warehouse documentation.


   Note: Upon completion of the import of a tag file, you may receive the following:

         Message: DWC13238E The object of type "COLUMN" identified by "DBNAME(___)
	 OWNER(___) TABLE(___) COLUMNS(___)" is defined twice in the tag language file.

	 This is an informational message, and your import was completed successfully.
	 This message may come about as a result of an entity having foreign keys with the same
	 name, an entity having similarly named columns that may have been affected by truncation, 
	 or other such circumstances.
	 Please check your model for duplicate column names, and make adjustments as appropriate.

	 
   

7. IMPORT TAG FILE INTO INFORMATION CATALOG

   There are two ways of importing a tag file into Information Catalog.  You can use the
   Information Catalog Administrator or use the command line.  To use the Information Catalog 
   Administrator, follow these steps:
   
      - Invoke any 'Administrator' in Information Control Manager in 'Programs->DB2' 
      - Click on 'Catalog->Import...', this will open the 'Import' dialog.
      - Click on 'Find...' to search for the tag file, then click on 'Import'
      - After the import is completed, you can double-click on the 'Subjects'
        icon which brings up a dialog with all the models and databases that
        were imported. 

   To import a tag file language file using the command interface, enter the 
   following command at a DOS window:
   
      DGUIDE /USERID userid /PASSWORD password /DGNAME dgname /IMPORT filename
         /LOGFILE filename /ADMIN /RESTART (B|C)
         
      where:
      /USERID   - the user ID used to access the control database
      /PASSWORD - the password for this user ID
      /DGNAME   - the Information Catalog's name
      /IMPORT   - the full path and file name of the tag language file
      /LOGFILE  - the full path name of the log file
      /ADMIN    - indicates that you're logging in as an administrator
      /RESTART  - indicates that import will start at the beginning of the tag file (choice B)
                  or start from the last committed point (choice C, the default)

   For more information, please refer to the Information Catalog documentation.

   

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 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 tag output 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.
     
   - "Tag file ... could not be opened."
   
     Unable to open the output tag file.  Check if there's any system problem
     that might prevent the creation or opening of a file on the current drive.
     
   - "Path to template files not found."
   
     Unable to get the path to where the template tag files are stored.  The 
     environment variable VWS_TEMPLATES is not set.  This is probably due to 
     the problem that IBM Data Warehouse is not installed.
    
   - "Path to type files not found."
   
     Unable to get the path to where the type tag files are stored.  The 
     environment variable DGWPATH is not set.  This is probably due to the 
     problem that IBM Data Warehouse is not installed.
    
   - "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.                   
     
   - "Extract program terminated due to error(s)."
   
     An error has occurred that prevents to completion of the extract program.
     Please refer to additional error messages to solve the problem.              



APPENDIX B - ERWIN TO IBM Data Warehouse MAPPING

   The following is a mapping of some of the main ERwin object attributes 
   to IBM Data Warehouse tag files:
   
      Database - WarehouseDatabase.tag or SourceDatabase.tag
      ERwin                    IBM Data Warehouse     IBM Data 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

      Table - Table.tag
      ERwin                    IBM Data Warehouse     IBM Data Warehouse GUI
      -----                    ----------------       --------------------
      Table Name               NAME                   Table name		
      Table Name               TABLES                 Table name
      Database Name            DBNAME                 n/a
      Table Owner              OWNER                  Schema name
      Table Comment            SHRTDESC               Description
   
      Column - Column.tag
      ERwin                    IBM Data Warehouse     IBM Data 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
      Table Owner              OWNER                  n/a
      Table Name               TABLES                 n/a
      Column Comment           SHRTDESC               Description
      


APPENDIX C - ERWIN TO Information Catalog MAPPING

   The following is a mapping of some of the main ERwin object attributes 
   to Information Catalog tag files:
   
      Database - Database.tag
      ERwin                    Information Catalog    Information Catalog GUI
      -----                    ---------              -------------
      Diagram Name             NAME                   Database name
      Diagram Author           RESPNSBL               Database owner
      Database Name            DBNAME                 Database name
      Database Version         DBTYPE                 Database type
      Diagram Description      SHRTDESC               Short Description
                            
      Table - TableOrView.tag
      ERwin                    Information Catalog    Information Catalog GUI
      -----                    ---------              -------------
      Table Name               NAME                   Table name		
      Table Name               TABLES                 Table name
      Database Name            DBNAME                 Database name
      Table Owner              OWNER                  Table owner
      Table Comment            SHRTDESC               Short Description
      ERwin API                TABLVIEW               Definition reps a view
                               
      Column - ColumnOrField.tag
      ERwin                    Information Catalog    Information Catalog GUI
      -----                    ---------              -------------
      Column Name              NAME                   Column name
      Datatype                 DATATYPE               Datatype of column
      Length                   LENGTH                 Length of column
      Scale                    SCALE                  Scale of column
      Null Option              NULLS                  Can column be null?
      Position                 POSNO                  Column position
      Primary Key              KEYPOSNO               Pos of col in primary key
      ERwin API                ISKEY                  Is column part of key?
      ERwin API                UNIQKEY                Is column a unique key?
      Database Name            DBNAME                 Database name
      Table Owner              OWNER                  Table owner
      Table Name               TABLES                 Table name
      Column Comment           SHRTDESC               Short Description
      ERwin API                ISTEXT                 Is data text?
      ERwin API                IDSRES                 Resolution of date
                               
      Model - Model.tag        
      ERwin                    Information Catalog    Information Catalog GUI
      -----                    ---------              -------------
      ER1 file name            NAME                   Model name
      Diagram Author           RESPNSBL               For further information..
      Diagram Description      SHRTDESC               Short Description
                               
      Entity - Entity.tag      
      ERwin                    Information Catalog    Information Catalog GUI
      -----                    ---------              -------------
      Entity Name              NAME                   Entity name
      Notes                    SHRTDESC               Short Description
      Defintion                LONGDESC               Long Description
      Entity Owner             RESPNSBL               For further information..
                                 
      Attribute - Attribute.tag
      ERwin                    Information Catalog    Information Catalog GUI
      -----                    ---------              -------------
      Attribute Name           NAME                   Attribute name
      Notes                    SHRTDESC               Short Description
      Definition               LONGDESC               Long Description
      Datatype                 DATATYPE               Datatype of member
      Length                   LENGTH                 Length of member
                              
