ddlCompileDBD() - Compile DBD from symbolic file image

ddlCompileDBD() - Compile DBD from symbolic file image

Prototype:

   void ddlCompileDBD(
      CONTROL *ctl,
      char *OptnStr,
      char *ArgList);

Permitted values in OptnStr:

   /D - delete old database before creating new one;
   /N - do not create database
   /R - reformat database
   /S - recreate database while preserving existing data
   /Y - initial create database
   /Z - used with /R and /S to preserve indexes;
        [this option implies an unverified assumption that
        there are no changes to the index configuration]

Note that one of the "Create Data Base" options must be specified: either /D, /N, /R, /S or /Y. Refer to the DBD Compile Options document for a more complete description.

Form of ArgList:
<source-filename>
<source-filename> is the name of the source file

Refer to the database definition document for the description of the database definition language.

Description:

The compile process analyzes the DBD text and creates the files that house the actual database. The compile process creates these files:

                <dbname>.ctl                   Control space
                <dbname>.ddd                 Data space
                <dbname>.ttt                    Structure space - trees
                <dbname>.lll                     Structure space - lists
                <dbname>.mmm               Memo field space (if DBD has memo fields)
                <dbname>.sss                  Multiple user control

where <dbname> is the first 48 characters of the name specified in the "DATA BASE NAME IS" statement.
These files are created in the same folder that houses the DBD unless directed otherwise via "File" clauses in the DBD.

Detailed Description of DBD Compile Process:

The DBD Compile process consists internally of 4 Compile Passes. Compile Passes #1 thru #3 read and parse the symbolic DBD source file; check for errors; and build an internal DBD control object.

If either of these Compile Passes detects an error; or detects a user cancel signal via the ddlCancelCallback(), the compile process terminates and any previously existing data base remains unchanged.

Compile Pass 4 performs the actual build step expressed by the "Create Data Base" options described above.

For option /N, no further build step is desired; the Compile Process terminates;

For option /D, any existing data base files are deleted; and the build process continues as with the /Y option. If an error or user cancel occurs while the old database files are being deleted, the ddlCompileDBD() function terminates. In this case, the old data base is in an indeterminate state. [Note that it is not considered an error in this case if one or more of the expected old data base files is not found.]

For option /Y, a check is made for any existing data base files; if any existing data base files are found, the build process is terminated; otherwise, all of the required data base files are created. If an error or user cancel occurs at any time during the creation of the new data base, all newly created and partially created files are deleted and the ddlCompileDBD() command terminates.

For option /S, the old data base is compared with the new, with respect to table order, table size (max records) and table record size; if these comparisons are true for all tables, then the existing .ddd file is accepted as the new .ddd file; if these comparisons are not true, the compile process ends with an error. In this case, the old data base is still intact.

Option /S allows one or more tables to be added at the end of the dbd; provided that extra room is available in the DRL (Deleted Record List). Additional space can be reserved in the DRL by including
      DBOPTION Gnnn
where nnn is the additional record count space to be reserved. The actual increase in the file size is nnn/8.

User cancel is not enabled at any time during the /S option DBDCOMP.

For option /S without option /Z, all structures are reinitialized.

For option /S with option /Z, all existing detached structures are not reinitialized. The remaining structures are initialized.

For option /R, the existing .ddd file is copied to a new file with a temporary extension .nnn. The .nnn file contains the reformatted data.

For each table being copied, any DBD LOADFILE command is performed simultaneously with the copy.

If the copy terminates due to error or user interruption, the compile process is terminated with the existing data base intact. If the copy completes without error and without user interruption:
       . Further user interrupts are disabled thru the remainder of the DBDCOMP;
       . The existing .ddd file is renamed to an extenion .ooo;
       . The .nnn file is renamed to an extension .ddd and it becomes the new data file;
       . The .ooo file is deleted

For option /R without option /Z, all structures are reinitialized.

For option /R with option /Z, all existing detached structures are not reinitialized. The remaining structures are initialiized.

Specification of /R, /S and /Z edit rules

   /R EDit Rules
      For tables:
         . Add or delete a table;
         . Change table order
         . Increase or decrease table size
         . Add or delete table TEMP attribute
      For columns:
         . Add or delete a column [non-virtual or virtual, key or non-key]
         . Change column order
         . Change column data type or size
         . Change key to non-key, non-key to key
         . Change virtual to non-virtual, non-virtual to virtual
         . Change key attributes
   /R EDit Rules with /Z
      [Discrete structures are preserved in these cases:]
      [NA indicates that there is no issue wrt structures for this operation]
      [NS indicates that structure preservation is not supported for this operation]
      [PR indicates that structure is preserved]
      For tables:
         . Add or delete a table;   [NA]
         . Change table order   {NA]
         . Increase or decrease table size   [NS]
         . Add or delete table TEMP attribute   [NA]
      For columns:
         . Add or delete a column [non-virtual or virtual, key or non-key]   [NA]
         . Change column order   [PR]
         . Change column data type or size   [NS]
         . Change key to non-key, non-key to key   [NA]
         . Change virtual to non-virtual, non-virtual to virtual   [PR]
         . Change key attributes   [NS]
         . Innocent bystanders   [PR]
   /S EDit Rules
      For tables:
         . Change table name
      For columns:
         . Change column name
         . Change key to non-key, non-key to key
            [except not change non-virtual to virtual or virtual to non-virtual]
         . Change key attributes
            [except not change non-virtual to virtual or virtual to non-virtual]
   /S EDit Rules with /Z
      [Discrete structures are preserved in these cases:]
      [NA indicates that there is no issue wrt structures for this operation]
      [NS indicates that structure preservation is not supported for this operation]
      [PR indicates that structure is preserved]
      For tables:
         . Change table name   [NA]
      For columns:
         . Change column name   [NS]
         . Change key to non-key, non-key to key   [NA]
         . Change key attributes   [NS]
         . Innocent bystanders   [PR]