Release 10.1A: OpenEdge Development:
Progress Dynamics Administration

> ## Setting up new databases with the DCU

> The main focus of the DCU is setting up the Repository database. Therefore, it is simple to extend a DCU session to also set up your application database as well. Every deployment should be able to create a new database. You can customize a deployment to create a new application database as follows:

> 1. Create a custom session type and generate a configuration file for it.

> 2. Create a custom DCU driver file for the new session type.

> 3. Add a page to the DCU driver file to collect install information.

> 4. Add a node for the new database in the DCU driver file.

> 5. Create a database creation upgrade file for your application database.

> ##### Creating a custom session type

> It is good practice to have a separate session type for each application you deploy. The Session Type Control enables you to extend existing session types to create customized ones.

> | To create a new DCU session type:

> 1. In the Session Type Maintenance window, choose Basic DCU ProgressSetup.

> 2. Choose Add record to create a new session type. The new session type automatically extends `ProgressSetup`.

> 3. Name the new session type and save it. For example, you might specify a session type name for the DynSports sample application as DynSportsSetup.

> 4. Create overrides for the `ProgressSetup` session properties under the new session type. For example:

> Session property | Sample value
> --- | ---
>     setup_type
>     DynSportsSetup
>     setup_type_file
>     db/dynsports/dfd/DynsportsSetup01.xml
>     window_title
>     DynSports Configuration Utility

> 5. Generate a configuration file using your new session type. By convention, the filename is `application-name` `setup.xml`. For example, `dynsportssetup.xml`.

> By changing the `DCUSETUPTYPE` and `ICFCONFIG` parameters to your new session type and configuration file, you can now override the DCU with your custom deployment.

> ##### Creating a custom DCU driver file

> Your custom configuration uses the DCU driver file that you named in the `setup_type_file` session property. Your next step is to create that file. While you could build one from scratch, you can also alter a standard DCU driver file.

> | To create a custom DCU driver file:

> 1. Save a copy of the latest standard DCU driver file to the directory and filename specified in the `setup_type_file` session property of your custom session type.

> 2. Change the `<setup>` node to your custom session type. For example:

>     <setup SetupType="DynSportsSetup">

> 3. In the `Welcome` page description, change the contents of the editor control’s `<DefaultValue>` to reflect your application. For example, you might change the standard text to the following for the DynSports application:

>     Welcome to the DynSports Configuration Utility.
>     This process will set up the databases that are required to run the
>     current version of DynSports.
>     Choose the Next button to start this process. Choose Cancel to leave
>     without modifying anything.

> 4. You can also alter the settings of the following nodes to change the appearance of the DCU to reflect your own application:

> - `<ImageLowRes>`
> - `<ImageHiRes>`
> - `<IconFile>`

> If you run your custom DCU session now, it brings up the altered `Welcome` page. It cannot install your application database yet. It needs to gather path information on where the database files are located.

> ##### Adding a page to the DCU

> The DCU needs to know where the source files for your application database are. One of the existing DCU pages, the `ICFDB` `Parameters` page, captures this type of information for the Repository. You can reuse it to capture the information for your application database.

> The page you are reusing supports upgrading existing databases, as well as creating new databases. This section concentrates on those parts of the page that build a new database. Using the DCU for upgrades is discussed in the "Upgrading existing databases with the DCU" section.

> | To add a new page to the DCU driver file:

> 1. In your DCU driver file, copy the `GetICFDBParams` page description. It begins with the `<page Name="GetICFDBParams">` node and ends with the next `</page>` node.

> 2. Paste a copy of the page description before the `Status` page description.

> 3. Change the page name, title, and page group to reference your application. For example, the beginning of the `DynSports` `Parameters` page description would look like this:

>     <page Name="GetDynSportsParams">
>       <Title>DynSports Parameters</Title>
>       <Group>DynSports</Group>

> 4. Change the `checkForDB` action to use the logical name of you application database. For the DynSports example, it would be the following:

>     <action>
>       <Event>INITIALIZE</Event>
>       <Action>checkForDB</Action>
>       <ActionParam>DynSports</ActionParam>
>     </action>

> 5. Set the Back button to go to the `ICFDB` `Parameters` page. For the DynSports example, it would be the following:

>     <control>
>       <Type>Button</Type>
>       <Panel>Yes</Panel>
>       <Label>&amp;Back</Label>
>       <Name>Back</Name>
>       <Justify>Right</Justify>
>       <action>
>         <Event>CHOOSE</Event>
>         <Action>gotoPage</Action>
>         <ActionParam>GetICFDBParams</ActionParam>
>       </action>
>     </control>

> Note: There are several paths through the ICFDB pages. With conditional processing, you could have the DCU return to the page from which the user came.

> 6. Set the Next button to go to the `Status` page in the Wizard sequence.

> You do not need to modify the other actions that occur when the user chooses the Next button. The `screenScrape` action records the values from the objects. The `connectDatabase` and `verifyDBVersion` actions are conditional and will not occur during the build of a new database.

> 7. Change the text in the editor’s default value to describe your application database.

> 8. Change the remaining ICFDB references to refer to your application database.

> Your customized DCU can now gather the information on where to find the build files for your application database. The last thing you need is an upgrade file that tells how to use the files.

> ##### Adding a database node

> The DCU driver file needs a node for each database in the deployment.

> | To add a node for your application database, copy the ICFDB node and modify the values for your application database. For example, a DynSports database node might look like this:

>     <database>
>       <DBName>DynSports</DBName>
>       <VersionSeq>seq_dynsports_dbversion</VersionSeq>
>       <MinimumVersion>010000</MinimumVersion>
>       <ConnectParams>-1</ConnectParams>
>       <DBDir>#path_db#\dynsports\dynsports.db</DBDir>
>       <DBDump>#path_src#\#dynamics_rootname#\db\dynsports\dump</DBDump>
>       <patch PatchLevel="0" DBBuild="Yes"
>           NodeURL="dynsports/dfd/dynsportsbuild.xml"/>
>     </database>

> ##### Creating a database creation upgrade file

> As before, the simplest method for creating the upgrade file is to copy and customize the standard file.

> | To create a database creation upgrade file:

> 1. Copy and rename the Repository creation upgrade file, `icfdbbuild.xml`. For example, the DynSports file would be `dynsportsbuild.xml`.

> 2. Change the full schema definition filename to the one for your application database. For the DynSports example, it might look like the following:

>     <patchstage UpdateStage="Delta">
>       <Program>
>         <FileType>df</FileType>
>         <FileName>dynsports/dfd/dynsportsfull.df</FileName>
>         <Description>Applying Full DynSports DB Schema</Description>
>         <Rerunnable>no</Rerunnable>
>         <NewDB>yes</NewDB>
>         <ExistingDB>no</ExistingDB>
>         <UpdateMandatory>yes</UpdateMandatory>
>       </Program>
>     </patchstage>

> 3. In the next patch stage, remove the program node for the `Setting Site Number` program. That program is specific to the Repository.

> Your custom DCU can now create a new application database in addition to creating and upgrading the Repository.

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095