Data Dictionary Maintenance

Updating the Data Dictionary

Be aware that all changes made to the definition (table) currently loaded in Data Dictionary Maintenance are written immediately to the providex.ddf and providex.dde files as they are entered.

Embedding a Definition

To embed the current definition into the physical database file, click the Update File tool bar button. Depending on the contents of the current definition, PxPlus will determine how to update the physical file with the current definition:

• If the file does not exist, PxPlus creates it and then embeds the definition.

• If the file contains data and its existing definition (key structure, separator and embedded data dictionary) corresponds with the newly created definition, PxPlus will embed the new definition (without touching the data).

• If the file attributes/data elements have changed in such a way that a data conversion is required, an Update physical window with Update Options will display.

This process can also be achieved programmatically. See Automating the Embedded (Physical) Definition.

Update Options

To update the physical file after changes are made to the current definition, click the Update File tool bar button. If the changes do not require a data conversion, a message will display to confirm that the dictionary has been updated. If a data conversion is required, the Update physical window with update options will display:

This window consists of the following:

(File Changes)

(Display Only) Area that describes the file changes.

Update Options

Convert existing data

(Default) Updates the file using the changes described in the upper File Changes area.

A message will ask if you want to make a backup of your original data file before PxPlus overwrites it. Responding Yes brings up a Backup File window for entering a backup file name (*.BAK).

Clear existing data

Purges data in the existing file.

Rewrite data dictionary only

Updates the embedded definition using the changes described in the upper File Changes area but without touching the data. This does not change the actual keys or records inside the file.

Important Note:
To avoid loss of data, it is best to use the Rewrite data dictionary option when embedding a definition for the first time.

Only Convert existing data once the physical file has been tested to ensure the new definition matches the contents exactly.

Performs the selected update option.

Cancel

Closes the Update physical window without updating.

To update multiple native (PxPlus) files, see Update Physical Files utility.

Creating a Definition

Create a new definition in the data dictionary (providex.dde and providex.ddf files) by entering a name in the Name field of the Main Panel. If the entered name does not exist, you will be asked to create a new definition. Enter the path of a data source in the Physical File field.

If the data source contains an embedded definition, then Data Dictionary Maintenance can automatically extract the contents of that definition and populate all the corresponding fields with existing information.

This process can also be achieved programmatically. See Automating the Data Dictionary Update.

Automating the Data Dictionary Update

CALL "*dict/dd_updt;Update_DD", pathname$, newpath$, errmsg$

Where:

pathname$	Pathname of the database file containing the source definition.
newpath$	Pathname to be stored in the providex.ddf (if other than pathname$). If this value is null, then pathname$ is assumed.
errmsg$	Error message to be issued if the update procedure aborts.

The Update_DD routine in PxPlus can be called from an application in order to update the data dictionary files (providex.ddf and providex.dde) using information extracted from an existing embedded definition.

Automating the Embedded (Physical) Definition

CALL "*dict/dd_updt;Update_Physical",ERR=stmtref,table$,newpath$,flags$,errmsg$,pswd$,level

Where:

stmtref

Program line number or statement label to which to transfer control.

table$

Logical name of the file to be updated.

newpath$

Pathname of the file to be updated if other than the one specified in the path field in the providex.ddf; otherwise, this value is null.

flags$

Data dictionary flag values:

*null*	Updates dictionary - recreates and converts existing file.
D	Updates the embedded data dictionary only.
A	Aborts if duplicate keys are found.
S	Suppresses update of time stamp in providex.ddf.
B	Aborts if block size is invalid.
X	Suppresses recreating an existing empty file when "D" (embed dictionary only) is set.
V	Verbose mode display a progress bar when copying a file.

Any combination of the above can be used (e.g. "DX","SAD","SADB", etc.).

(The "V"erbose flag was added in PxPlus 2020.)

errmsg$

Error message to be issued if the update procedure aborts.

pswd$

Password to be applied to the file.

level

Access level:

0	Password always required.
1	Password required for write access.
2	Password always required/data is encrypted.
3	Password required for write access/data is encrypted.

The Update_Physical routine can be used to update the embedded definitions using information from the data dictionary files (providex.ddf and providex.dde).

• If the file does not exist, PxPlus creates it and embeds the definition.

• If the file exists but has no data, the file is recreated with the new definition, unless the flag$ variable includes "DX".

• If the file contains data, the new definition is embedded based on flag values, the file is recreated and the records converted to the new format. See Example below.

Important Note:
Unlike the Update File tool bar button, there will be no warnings or options for handling discrepancies between old and new definitions.

The Update_Physical routine can be used in the batch conversion of database files from external/legacy formats to the PxPlus data dictionary. See Converting Other Formats.

Example:

The following sample program creates all the files defined in a data dictionary and embeds the individual definitions (tables) into the corresponding files:

! DD_CRPHY - ! Create Physical Files from the Data Dictionary
! This program creates all files in the data dictionary in the current directory
!
     print 'CS','blue',"Create Physical Data Files from Dictionary",'RM'
     d_flag$="" ! Set flag to create/convert/update
     ddf_fn=hfn;
     open (ddf_fn,iol=*)"providex.ddf" ! Open DD header file
     select * from ddf_fn begin "000001"
          ddf_key$=kec(ddf_fn)
          if stp(PhysicalPath$)="" \
               then print 'SB','magenta',"Warning: "+ddf_key$+"-"+Name$+" has no path. Cannot create.",'RM';
                      continue ! Check for incomplete record
          if mid(tbl(mid(PhysicalPath$,1,1)="=",PhysicalPath$,evs(PhysicalPath$(2))),1,1)="@" \
               then continue
! filter out Views
          print "Creating ",ddf_key$," - "+Name$,@(50)," >> ",PhysicalPath$
          call "*dict/dd_updt;Update_Physical",Name$,"",d_flag$,errmsg$
        if stp(errmsg$,2)<>"" \
               then print 'red',errmsg$,'RM'
     next record
     print "File update complete"
     close (ddf_fn)
     end