This chapter describes the use of Rdb and CDD/Repository within an application.

8.1 Database

SysWorks Developer supports the use of an Rdb database in a number of ways. Firstly, a number of database instances may be considered as follows:

• Compiletime
  The compiletime database of an application includes the domain and table schema definitions. It may also include other schema definitions but should not include storage areas and maps. The convention with SysWorks is to locate this database in the application library directory. If the schema needs to be shipped as part of the application installation kit, a backup of the database should be made to the software directory and hence the kit rather than including it directly in the kit.
• Runtime
  The runtime database of an application includes the compile time domain and table schema plus any physical schema. The convention with SysWorks is to locate this database in the application data directory and its journals in the journal directory. Where multile storage area files exist and these are to be placed on different disk volumes, multiple data directories should be created on different logical sub-disks.

Note that the physical schema of a runtime database may differ bewteen environments. An example of this is:

• Development
  The development runtime database includes physical schema such as constraints and indices but not storage areas and maps. It can be used for functional testing.
• Testing
  The testing runtime database includes the development schema plus the storage areas and maps. It can then be used for functional and volume testing.
• Production
  The production database may have some schema such as constraints removed and other extra schema such as extra indices for performance reasons.

The database source may come from one of three locations as follows:

• Script
  With this technique database domains and tables and optionally indices and triggers are placed in SQL scripts. The convention with SysWorks is to place each definition in a separate script. This results in minimum rebuilds because only modules which use a particular changed domain or table need to be recompiled. Note however that the compiletime database is rebuilt when any of its scripts change.
  
• Database
  With this technique the database schema is presented to the application in the form of a database. This is typically used where a database modelling or administration group manages the schema and wishes to provide the application with a ready made database.
  SysWorks provides tools for use with this technique which create a set of scripts as described above. The resultant scripts may be placed in the CMS library as though the script technique was being used, or they may be placed into the library directory.
• Repository
  As a variant on the database techinue, some sites may provide the database schema in the repository. This technique is supported by SysWorks by creating a database from the repository then using the database technique described above. Note however that this technique is not recommended since the repository does not directly support many of the database concepts such as keys and constraints.

Note that the database and repository technique reduce down to the script technique.

8.1.3 Central Control

As indicated earlier some sites may wish to have database schema managed centrally. An alternative to providing a database or repository is to provide the scripts directly to the application. One method for doing this whilst retaining control is to use a second application CMS library which is owned by the central group but can be read by the application. This CMS library can be placed in the CMS$LIB search list.

8.1.4 Conventions and Tools

The convention with SysWorks is to name each of these scripts according to the following format:

• appl_domain_DOM.SQL
• appl_index_IDX.SQL
• appl_table_TBL.SQL
• appl_trigger_TRG.SQL

If the database to script tool is used, this naming convention will be adhered to.

During the BUILD SCAN phase, SysWorks generates SQL scripts which are lists of the source scripts. These list scripts may be useful in creating the compiletime database schema. The generated scripts are:

• appl_DOMAINS.SQL
• appl_INDICES.SQL
• appl_PROTECTIONS.SQL
• appl_ROUTINES.SQL
• appl_TABLES.SQL
• appl_TRIGGERS.SQL

Except for the appl_PROTECTIONS.SQL script, each of the above is SQL script which executes all of the appropriate SQL source scripts in alphabetic order. The appl_PROTECTIONS.SQL script contains a series of SQL statements which apply the standard application security model to the database and the tables within the database.

The following root database script which by convention has a file name and type of appl_DATABASE.SQL provides an example of how these generated scripts may be used:

create database filename fin_lib_dir:fin_database; set transaction read write; @fin_lib_dir:fin_domains @fin_lib_dir:fin_tables @fin_lib_dir:fin_protections commit;

The following MMS script fragment from the FIN application DESCRIP.MMS script provides an example of how to use SysWorks and MMS to create the compiletime database and provide an installation database backup file.

ALL depends_on - . . DATABASE,- . . DATABASE depends_on FIN_SFT_DIR:FIN_DATABASE.RBF @ ! No action required FIN_SFT_DIR:FIN_DATABASE.RBF depends_on FIN_LIB_DIR:FIN_DATABASE.RDB rmu/backup $(mms$source) $(mms$target) FIN_LIB_DIR:FIN_DATABASE.RDB depends_on - FIN_WRK_DIR:FIN_DATABASE.SQL,- FIN_LIB_DIR:FIN_SCHEMA.TAG

8.2 Repository

SysWorks supports the use of CDD/Repository by generating CDO scripts from the database domain and table scripts. Only database scripts which change will have new CDO scripts generated. By keeping each database domain and table in a separate scripts, a minimum number of actions will be required to incrementally build the application.

The generated CDO script files have a file type of .CDO_GEN and are normally placed in the application library directory.

8.2.1 Fields

Each SQL domain script of the form appl_domain_DOM.SQL will have a CDO script of the form appl_field_FLD.CDO_GEN generated. Note that the actual field name is left the same as the domain name i.e. no application prefix of object type suffix is used. This is one of the few exceptions to the general rule whereby every object starts with the application code and finishes with an object type suffix.

For example FIN_ACCOUNT_NO_DOM.SQL may define the ACCOUNT_NO domain in the database schema and the generated FIN_ACCOUNT_NO_FLD.CDO_GEN would define the ACCOUNT_NO field in the repository.

An application may define fields in addition to the domain equivalences. Such fields would be defines in CDO sources of the form appl_field_FLD.CDO. Note that more than one field can be defined in a single source. This is useful for field definitions where conditional fields (eg. Cobol 88 levels) are defined with a datatype field or when a series of related fields are more conveniently defined together.

8.2.2 Records

Each SQL table script of the form appl_table_TBL.SQL will have a CDO script of the form appl_record_REC.CDO_GEN generated. Note that the actual record name is of the form appl_table_REC and that this limits the length of a table name to 26 minus the size of the application code characters in length.

For example FIN_ACCOUNT_TBL.SQL may define the ACCOUNT table in the database schema and the generated FIN_ACCOUNT_REC.CDO_GEN would define the FIN_ACCOUNT_REC record in the repository. Where a column is defined for a table using an explicit datatype or a domain with a different name, the generator will define fields for the columns before the record definition.

For the following example FIN_ACCOUNT_TBL.SQL:

create table account ( account_no account_no, account_desc general_desc, account_total bigint(2) );

The generated FIN_ACCOUNT_REC.CDO_GEN script would be:

define field ACCOUNT_DESC based on GENERAL_DESC. define field ACCOUNT_TOTAL datatype quadword scale -2. define record FIN_ACCOUNT_REC. ACCOUNT_NO. ACCOUNT_DESC. ACCOUNT_TOTAL. end FIN_ACCOUNT_REC record.

An application may define records in addition to the table equivalences. Such fields would be defines in CDO sources of the form appl_record_REC.CDO. Note that more than one record can be defined in a single source, although this is not recommended. Records source may also contain field definitions. This is recommended for fields which are private to the record. Where a field is used by two or more records, a separate field source should be used.

This chapter descibes the various language and product specific actions, features and requirements when using SysWorks.

Table 9-1 provides a summary of the language support provided with SysWorks.

Table 9-1 Language Support Summary

Language or Product	Source File Types	Compile	Target Directory	Target File Types
ACA Services	.COL, .CRL	Yes	Library	.C, .MMS_INC
			Software	.CO, .CR
	.CRL_IND	No	Library	.CRL, .MMS_INC
ACMS	.ADF, .GDF, .MDF, .TDF	Yes	Architecture Independent Library	.MMS_INC, .OPT, .OPT_INC, .TAG_CDD
			Software	.ADB, .MDB, .TDB
	.ADF_INC, .GDF_INC, .MDF_INC, .TDF_INC	No	Architecture Independent Library	.MMS_INC
Ada 1	.ADA	Yes	Library	.MMS_INC, .OBJ, .OLB. .TAG_EP
Basic 1	.BAS	Yes	Library	.MMS_INC, .OBJ, .OLB, .TAG_EP
C	.C	Yes	Library	.MMS_INC, .OBJ, .OLB, .TAG_EP
	.H	No	Library	.MMS_INC, .TAG_INC_1, .TAG_INC_2
C++	.CXX	Yes	Library	.MMS_INC, .OBJ, .OLB, .TAG_EP
	.HXX	No	Library	.MMS_INC, .TAG_INC_1, .TAG_INC_2
	.IXX	No	Library	.MMS_INC, .TAG_INC_1, .TAG_INC_2
CDD	.CDDL, .DDL	Yes	Architecture Independent Library	.MMS_INC, .TAG_CDD
CDD/Plus & CDD/Repository	.CDO	Yes	Architecture Independent Library	.MMS_INC, .TAG_CDD
Cobol	.COB, .TXT	Yes	Library	.MMS_INC, .OBJ, .OLB, .TAG_EP, .TLB
Command Language Definition	.CLD	Yes	Library	.MMS_INC, .OBJ, .TAG_EP
	.CLD_INC	No	Library	.MMS_INC, .TAG_EP
	.CLD_INC_SRC	Yes	Software	.CLD_INC
Datatrieve	.DTR	Yes	Architecture Independent Library	.MMS_INC, .TAG_CDD
DECdocument	.GRA, .SDML	Yes	Library	.HLP, .MMS_INC, .TAG_SDML, .TXT
	.SDML_INC	No	Library	.MMS_INC, .TAG_SDML
			Documentation	.DECW$BOOK, .DECW$BOOKSHELF, .GIF, .HLB, .HTML, .PS, .RELEASE_NOTES
DECwindows	.UIL	Yes	Architecture Independent Library	.MMS_INC
			Software	.UID
FMS	.FRM	Yes	Library	.MMS_INC, .OBJ
Fortran	.FOR	Yes	Library	.MMS_INC, .OBJ, .OLB, .TAG_EP
HTTP	.SHTML	Yes	Documentation	.MMS_INC
			Documentation	.HTML
	.GIF_CPY, .HTIMAGE_CPY, .HTM_CPY, .HTML_CPY, .HTMLS_CPY, .HTMLX_CPY, .IMAGEMAP_CPY, .SHTML_CPY	Yes	Documentation	.GIF, .HTIMAGE, .HTM, .HTML, .HTMLS, .HTMLX, .IMAGEMAP, .SHTML
Java	.JAVA	Yes	Architecture Independent Library	.MMS_INC
			Software	.CLASS
Linker	.OPT, .OPT_APP, .OPT_INC	Yes	Library	.MMS_INC, .OPT_EXP
			Software	.EXE
Macro-32	.MAR, .MLB	Yes	Library	.MMS_INC, .OBJ, .OLB, .TAG_EP
			Software	.MLB
ObjectBroker	.IDL	Yes	Library	.C, .MMS_INC
			Software	.IR
Pascal	.PAS	Yes	Library	.MMS_INC, .OBJ, .OLB, .PEN, .TAG_EP
PL/1 1	.PLI	Yes	Library	.MMS_INC, .OBJ, .OLB
PowerHouse	.QKS, .QTS, .QZS	Yes	Architecture Independent Library	.MMS_INC, .TAG_INC
	.QKS_INC, .QTS_INC, .QZS_INC	No	Architecture Independent Library	.MMS_INC, .TAG_INC
			Software	.QKC, .QTC, .QZC
Rdb	.RDO	No	Architecture Independent Library	.CDO_GEN, .MMS_INC, .TAG
	.RBA, .RC, .RCO, .RFO, .RPA	Yes	Architecture Independent Library	.MMS_INC, .OBJ, .OLB, .TAG_EP
	.SAD, .SBA, .SC, .SCO, .SFO, .SPA, .SPL	Yes	Architecture Independent Library	.MMS_INC, .OBJ, .OLB, .TAG_EP
	.SQL	No	Architecture Independent Library	.CDO_GEN, .MMS_INC, .TAG
	.SQLMOD	Yes	Architecture Independent Library	.MMS_INC, .OBJ, .OLB, .TAG_EP
Runoff	.RND	Yes	Architecture Independent Library	.MMS_INC
			Documentation	.DOC
	.RNH	Yes	Architecture Independent Library	.HLP, .MMS_INC
			Documentation	.HLB
	.RNM, .RNR	Yes	Architecture Independent Library	.MMS_INC
			Documentation	.MAN, .RELEASE_NOTES
TDMS	.FRM_TDMS, .RDF	Yes	Architecture Independent Library	.MMS_INC, .TAG_CDD
	.LDF	Yes	Architecture Independent Library	.MMS_INC, .TAG_CDD
			Software	.RLB
DECdocument	.GRA, .SDML	Yes	Architecture Independent Library	.BRF, .MMS_INC
			Documentation	.DECW$BOOK, .PS, .RELEASE_NOTES, .TXT
	.SDML_INC	No	Architecture Independent Library	.MMS_INC

• Source files.
  Usually found in the work directory, but if they are generated they will be found in the library directory . Typical file types include .C, .COB, .COM_SRC, .COM_APP, .H, .FOR, .SDML, .SDML_INC and .UIL Should start with application code except for special cases. If not generatyed, they should reside in the CMS library.
• Intermediate files.
  Usually found in the library directory. Typical file types include .LIBS, .MAP, OBJ and .OLB.
• Tag files.
  Usually found in the library directory. Typical file types include .TAG_CDD, .TAG_EP, .TAG_INC_1 and .TAG_INC_2. These files are used to manage dependencies which are either inefficient or impractical to manage with direct MMS dependencies.
• Target files.
  Usually found in the software or documentation directories. Typical file types include .COM, .EXE, .HLB, .HLP, .PS and .UID.