Configure Metadata - SuperCROSS

Metadata is extra information about columns and fields that is stored in the database. This can include alternate names for fields, extra descriptions, and alternative languages (multilingual support).

This section shows a worked example of one way to set up metadata for SuperCROSS. There are a number of steps you need to follow to set up metadata:

Step 1 - Create a Database to Store your Metadata

The first step is to create a database for storing the metadata information.

You do not need to create any tables in the database; these will be created by the scripts you run in the next step. Simply create a new empty database in your preferred relational database system.

This example will use Microsoft SQL Server. We have created a new empty database called Metadata:

You will also need a JDBC driver so that SuperSTAR can connect to your database. Download a JDBC driver for your chosen relational database system.

Step 2 - Edit and Run the Configuration Scripts

SuperSTAR is supplied with some configuration files for setting up metadata. You need to edit these files to suit your system.

Edit BuildMetadataTemplate.bat

The first file you need to modify is a windows batch file called BuildMetadataTemplate.bat. In a default installation, this file is located in C:\ProgramData\STR\SuperADMIN\MetaData\MetaDataUtilities

This is a script that will connect to both SuperSTAR and your new metadata database. It copies the structure of the SuperSTAR database to your metadata database, ready for you to start populating it with your metadata.

Open BuildMetadataTemplate.bat in a text editor.

Make a backup copy of this file before making any changes.

At the top of the file there are a number of lines that define various parameters the script will use. You need to modify the following lines to provide the appropriate details for your system:

SET DB_DRIVER_CLASS=

SET DB_DRIVER_CLASS="com.microsoft.sqlserver.jdbc.SQLServerDriver"

SET DB_DRIVER_LOCATION=

SET DB_DRIVER_LOCATION="C:\drivers\SQLServer\sqljdbc_4.0\sqljdbc4.jar"

SET DB_URL=

SET DB_URL="jdbc:sqlserver://MYSERVER;databaseName=Metadata;user=mydbuser;password=myuserpassword;"

SET REPOSITORY=

SET REPOSITORY=metadatadbid

You can also make the following changes if you wish, or just leave these parameters set to the default values:

SET VALUESET=20

SET OVERWRITE=true

SET EXPORT_VALUESET=true

When you have finished, save your changes to BuildMetadataTemplate.bat.

Edit databases.txt

This is a text file that specifies which SuperSTAR databases you want to create metadata for. In a default installation, this file is located in C:\ProgramData\STR\SuperADMIN\MetaData\MetaDataUtilities

Edit the file so that each line contains the details of a database you want to create metadata for. You can either create this file manually or use the createdatabaselist command in SuperADMIN.

The database list file must use the following format:

<database_id>|<display_name>|<full_path_to_SXV4>

Where:

• <database_id> is the ID of the database in the SuperSTAR catalogue.
• <display_name> is the database display name.
• <full_path_to_SXV4> is the full path to the .sxv4 file that contains the database but without the .sxv4 file extension.

For example, the shipped databases.txt file is as follows. This would create metadata tables and columns for the sample People and Retail Banking databases:

people|people|C:\ProgramData\STR\SuperSERVER SA\databases\People
bank|bank|C:\ProgramData\STR\SuperSERVER SA\databases\RetailBanking

When you have finished editing databases.txt, save the file.

You are recommended to save this file in the same location as the standard shipped file. If for any reason you want to save the file to a different location, you will have to find the line SET DB_FILE_LIST="databases.txt" in BuildMetadataTemplate.bat and update it to point to your new filename and location.

Edit metacolumns.txt

This is a text file that specifies the columns that will be created for metadata in the repository. In a default installation, this file is located in C:\ProgramData\STR\SuperADMIN\MetaData\MetaDataUtilities

Each line in the file defines a column to create in the metadata database, in the following format:

<column_name> <language> <type> <length>

Where:

• <column_name> is the name of the column to create. You can chose whatever name you like for the column; it will not be displayed to the end user in SuperCROSS, but you will see this in the RDBMS when you are populating your metadata, so you should choose something that will make it easy to remember which column is which (e.g. en_name, en_desc, fr_name, etc).
• <language> is a language code. You can choose whatever codes you like (e.g. en, fr, de, etc). In a later step you will edit a configuration file that tells SuperCROSS what languages the codes represent.
• <type> is the column type, either name or desc.
• <length> is the maximum length of the column in characters.

For example, the following sample shows how to create columns to store English and French metadata with up to 250 characters in the name and 500 characters in the description:

en_name en name 250
en_desc en desc 500
fr_name fr name 250
fr_desc fr desc 500

When you have finished editing metacolumns.txt, save the file.

You are recommended to save this file in the same location as the standard shipped file. If for any reason you want to save the file to a different location, you will have to find the line SET META_COLUMNS="metacolumns.txt" in BuildMetadataTemplate.bat and update it to point to your new filename and location.

Run BuildMetadataTemplate.bat

Once you have finished editing all three files, you run the configuration batch file. It will use the information from your SuperSTAR databases to populate your metadata database:

1. Open a Windows Command Prompt and change to the directory where the batch file is located.
2. Run BuildMetadataTemplate.bat
3. Wait for the file to complete and advise that it has "Finished populating RDBMS":

2013-07-29 14:28:40,596 [main] INFO  au.com.str.metautilities.builders.BuildMetadataTemplate - Finished populating RDBMS. It took 3 seconds

Check your metadata database to confirm that the script has created the database tables:

There should be one new table for each SuperSERVER classification table.

Step 3 - Configure the Metadata Server

The next step is to configure the SuperSTAR Metadata Server.

Before you can run Metadata Server, you need to set up an ODBC data source so that the SuperSTAR Metadata Server can connect to your metadata database. Follow these instructions to set up an ODBC data source to connect Metadata Server to SQL Server .

Before starting the Metadata Server, you need to change some configuration settings in Metadata Server's metadata.config.xml. In a default installation, this file is located in C:\ProgramData\STR\SuperSERVER SA

Make a backup copy of this file before making any changes.

Open metadata.config.xml in a text editor.

Connection

Locate the Driver section of the file and edit the ConnectionString to match the details of your connection to the database, as follows:

• DSN is the Data Source Name that you specified when you set up the ODBC driver to your database (e.g. obdc_metadata).
• REP is the repository ID that you set in BuildMetadataTemplate.bat (e.g. metadatadbid).
• UID and PWD are the username and password to use to connect to the database.
• STRSCHEMA is optional. You can use this to specify a schema name for databases that require a table name qualification (for example, DB2). If the schema is specified it will be used to qualify the table names that are used by the ODBC layer. If this does not apply to your database, omit the STRSCHEMA parameter.

<KEY name="Driver">
  <KEY name="SimpleDriver">
    <STRING name="ConnectionString">DSN=odbc_metadata;REP=metadatadbid;UID=mydbuser;PWD=myuserpassword;STRSCHEMA=SCHEMA</STRING>
    <STRING name="Driver">SimpleMetaAccessDLL.dll</STRING>
  </KEY>
  <STRING name="ActiveDriver">SimpleDriver</STRING> <!-- Metadata Driver for directly connecting to ODBC -->
</KEY>

You should also confirm that the SuperADMINConnection details are correct for your environment:

<KEY name="SuperAdminConnection">
  <!-- Setup for mdcorbaserver -->
  <STRING name="SA_HOST">localhost</STRING> <!-- SuperADMIN host machine -->
  <NUMBER name="SA_PORT" value="9230"/> <!-- SuperADMIN port number machine -->
  <NUMBER name="MDServer_PORT" value="8005"/> <!-- Port number for mdcorbaserver -->
</KEY>

When you have finished making changes, save metadata.config.xml.

Step 4 - Start the Metadata Server Application

By default the actual Metadata Server is not started and you must start it manually.

Go to the Windows start menu and select SuperSTAR > SuperSERVER SA > Metadata Server SA.

Metadata Server will start and advise that it is connected to SuperADMIN:

If Metadata Server does not run correctly, you may need to run it with administrator privileges.

Do not close this Window as that stops the Metadata Server.

Step 5 - Change your SuperSERVER Database to be Multilingual

By default, a SuperSERVER database is not multilingual. To change this so you can use your alternative metadata values in the client, you need to change a setting in SuperADMIN.

1. Login to SuperADMIN.

2. Use the command

cat <database_id> multilingual true
   
   (where <database_id> is the ID of your database)
   
   For example:

   CODE

   cat bank multilingual true

Step 6 - Configure SuperCROSS

You need to make several changes to SuperCROSS in order to use Metadata.

Configure the Client

By default, SuperCROSS is not configured to use the Metadata Server. When you start SuperCROSS after making the change in SuperADMIN you will see symbols like ## in the database listing:

You need to change a configuration setting in SuperCROSS to enable the use of the Metadata Server:

1. Start SuperCROSS and open any database or table.
2. Select Edit > Options. The Options window displays.
3. Select the Configuration tab and click Metadata.
4. Change Disabled to Enabled and click OK.
   
   

   

5. Restart SuperCROSS to apply the change.

Configure SuperCROSS Languages

If you are using metadata to enable multilingual tables, then you need to edit the language definitions in the SuperCROSS metadata configuration file, metadata.config.xml. In a default installation, this file is located in C:\ProgramData\STR\SuperCROSS.

This a different file to the one you edited in the earlier step. The previous file was the configuration file for Metadata Server. This file is the configuration file for SuperCROSS and is located in the SuperCROSS directory.

Make sure SuperCROSS is not running. Every time you close SuperCROSS, it writes out its current metadata configuration to metadata.config.xml. If you edit the file while SuperCROSS is running, the changes will not be picked up by the client, and when you subsequently close SuperCROSS your changes will be overwritten by the old settings from the client.

Make a backup copy of this file before making any changes.

Open metadata.config.xml in a text editor, and locate the language map section, which will be similar to the following:

<KEY name="Lang-Map">
    <STRING name="cy">Welsh</STRING>
    <STRING name="de">German</STRING>
    <STRING name="en">English</STRING>
    <STRING name="fr">French</STRING>
    <STRING name="it">Italian</STRING>
</KEY>

This section lists all the available languages that can appear in the File > Table Language menu in SuperCROSS.

A language will appear in that menu and be available for the user to select if both of the following are true:

• The language is listed in the language map section of the SuperCROSS metadata configuration file.
• Columns for the language exist in the metadata database.

Update this section so that it includes a <STRING> element for each language that you have set up in your metadata database.

• Use the name parameter to specify the language code that you used in metacolumns.txt when you set up your metadata database.
• Use the text within the <STRING> element to control the text that will be displayed on the menu in SuperCROSS. Please note that non-ASCII characters are not currently supported in this menu.

When you have finished making changes, save and close metadata.config.xml.

Configure Super.ini

You are also recommended to make a change to one of the SuperCROSS configuration files. If you do not make this change, SuperCROSS displays a window similar to the following when you click on a database name:

To avoid this, you need to edit the file super.ini. In a default installation this file is located in C:\ProgramData\STR\SuperCROSS

Make a backup copy of this file before making any changes.

1. Open the file in a text editor.

2. Locate the following line at the end of the file:

   CODE

   [Metadata]
   NotShowMetaDlg=0

   

   If the [Metadata] section does not appear in the super.ini file, add this section to the end of the file.

3. Change the value to 1:

   CODE

   [Metadata]
   NotShowMetaDlg=1

4. Save and close super.ini.

Step 7 - Create and Verify the actual Metadata values

Now that metadata is configured, you can edit your actual metadata values in the database. Simply add the relevant metadata information to your database.

The following examples show some ways you can use metadata.

Example: Adding a Description

The following screenshot from SQL Server shows some additional information added to the description field for one of the values of Occupation:

You can view this information in SuperCROSS by right-clicking the value and selecting Meta-Information > Value.

Example: Adding Multilingual Metadata

The following screenshot from SQL Server shows some French field names added to the database:

In SuperCROSS, you can use the File > Table Language menu to change the table language:

You must restart Metadata Server and the SuperCROSS client to see any changes from your metadata database reflected in the client.