DataDict V910

ProvideX Version 9.
10
Data Dictionary
Introduction 3
Data Dictionary Maintenance 4
Updating the Data Dictionary 19
Data Dictionary Utilities 25
Using the Data Dictionary 33
Converting Other Formats 34
Data Dictionary Objects 36
SQL Interface Objects 64
Data Classes 76
Password Protection 78
ProvideX is a trademark of Sage Software Canada Ltd.
All other products referred to in this document are trademarks or registered trademarks of their
respective trademark holders.
©2010 Sage Software Canada Ltd. — Printed in Canada

50 Burnhamthorpe Rd. W., Suite 700 Mississaugua, ON L5B 2C2
All rights reserved. Reproduction in whole or in part without permission is prohibited.
The capabilities, system requirements and/or compatibility with third-party products described herein
are subject to change without notice. Refer to the Sage ProvideX website www.pvx.com for
current information.
Publication Release: V9.10

May 06, 2010
Data Dictionary
The purpose of this document is to explain how the ProvideX data dictionary works,
Introduction
how it is defined, and how it may be used in various applications.
What is it? A data dictionary is a collection of data definitions used by applications to describe
and access a database. These definitions do not contain actual data; rather, they
comprise standardized "bookkeeping" information about the data (metadata). This
includes details on the types, names and structures of all data elements, as well as
their interrelationships within the larger context of the database.
How is it ProvideX includes several facilities for building and accessing a data dictionary. The
Defined? primary method for creating/modifying data definitions is via the Data Dictionary
Maintenance interface in the NOMADS toolset. Equivalent programmatic access is
also available through Data Dictionary Objects. A central repository of data
dictionary definitions is maintained in two ProvideX files:
providex.ddf, defining all the files (or tables) that belong to the database, and
providex.dde, defining specific elements (or columns) that exist within these files.
One important feature about the Providex data dictionary is that the definitions stored
in the repository are also written directly into the corresponding database files.
What is it At the most basic level, a data dictionary is used for Accessing the Data in a
Used For? database. However, the data dictionary has multiple uses in ProvideX, from rapid
application development to the conversion of data.
Embedded IOLists. Because the definitions can be saved to the physical files, a
separate IOList does not have to be written in programs that use the data. ProvideX
accesses the embedded definitions independent of the central data dictionary.
NOMADS. The data dictionary is required for File Maintenance to generate panels
and maintenance programs. It also facilitates the creation of Query definitions.
Views. The ProvideX Views system can employ the data dictionary’s embedded
definitions to generate end-user Views of the data.
ODBC. The data dictionary is fully-compatible with the ProvideX ODBC Driver. The
driver simply reads the embedded IOList to determine the fields and format of the
database file. Otherwise, when the data dictionary is not present, a manually-written
INI file would have to be created for each file in order to access the data.
ProvideX V9.10 Back 3

Data Dictionary Data Dictionary Maintenance
Supported File Types

The ProvideX data dictionary is designed to support normalized files – files in which
all records have the same record layout. The Update File process in the Data
Dictionary Maintenance interface uses the ProvideX KEYED directive to create all
physical files. A key is a string of characters used to identify the records in a file.
Three keyed file formats are available for Data Dictionary Utilities: FLR
(fixed-length records), VLR (variable-length records), and EFF (enhanced file
format). For further information on ProvideX data files, refer to the Introduction in
the Language Reference Manual.
Data dictionary support for multiple-format files, such as those with header and
detail records, is limited to variant records. The ability to define non-normalized
data files is provided only within the data dictionary — not within ProvideX itself
nor within the NOMADS File Maintenance or Query generation facilities. Variant
records are supported primarily for the creation of INI files and SQL database
definitions when migrating applications. Refer to the Data Dictionary Maintenance >
Generate External utilities: INI File Generation and SQL Create Table.
Data Dictionary Maintenance

Dat Dictionary Maintenance
BMK
As mentioned earlier, NOMADS includes a utility for building and maintaining the
data dictionary. Click Dictionary > Maintenance from the NOMADS menu bar.
Alternately, you can type DD (or DD tablename) at the ProvideX Command prompt.
The basic steps for creating definitions in the data dictionary include: identifying the
database file, defining the elements, defining the keys, and copying the updated
definition to the physical file. The Data Dictionary Maintenance interface presents
all the different options and fields necessary to complete these steps:
For Updating the Data Dictionary and embedding the
Main Panel definition in the physical file. Settings include table name,
key definition, access logic, and notes.
Within the main panel there are two tabbed panels for specifying further details about
the data files and their elements:
Options and fields for describing the physical file,
General File Information
including pathname, group, file type, and block size.
Options and fields for defining all the data elements
Data Elements within the current the definition, as well as for the
global dictionary.

Main Panel
The options and settings listed below are available from the main panel:
Menubar Items
The main panel includes the following drop-down menu items:
File Some of these items also appear as buttons in the main panel:
Change Dictionary Changes the path to a new providex.ddf.
Rename Table Changes table to a new name.
Delete Table Deletes the currently-loaded table.
Notes Provides free-form area for recording notes on the table.
Define Keys Sets up primary and alternate keys for the physical file.
IO Procedures Sets up logic for controlling file access.
Update File Embeds data dictionary into the physical file.
Create SQL Key Defn File. Creates providex.kdf in the same directory as
the providex.ddf and providex.dde files. This
file contains SQL key definitions for a providex data
dictionary table, keyed by the logical table name (64
characters). If the KDF file exists, the user is prompted
to delete and re-create the file.
Exit Exits the Data Dictionary Maintenance interface.

Edit This drop-down is enabled when used with the Data Elements tab:
Add Element Inserts a data dictionary element.
Delete Element Deletes a data dictionary element.
Add Globally Adds the selected element to the Global Dictionary.
Options Provides additonal data dictionary options:
SQL Key Definition Update Determines whether the SQL Key Definition
file will automatically be updated when the ProvideX
Data Dictionary key definition is changed. See SQL
Key Definition Update Options, p.23.
Utilities Provides additional data dictionary tools and security control. The
following are fully documented under Data Dictionary Utilities, p.25:
Print Opens Print Data Dictionary Definition panel.
Compare Definitions Opens Data Dictionary Compare panel.
Generate External Sub-menu for accessing:
INI file contents
SQL Create Table
Key Definitions
Import Dictionary Opens the Copy Data Dictionary Definition panel.
Buttons and Fields

The main panel includes the following buttons and fields:
Table Name Descriptive name for your data source (maximum 64 characters)
used to identify its definition in the data dictionary; e.g.,
Customer. Existing tables can also be viewed via:
Tree view of table names by Group
Query view of tables by table name
Advance table name based on current view.
See also, Creating a Definition, p.20
Notes Provides a free-form area for recording notes on the table and its
use. (maximum 1024 characters).
SQL Keydef Creates/removes SQL key definition for selected table. Button is
hidden if providex.kdf does not exist. To create the KDF file,
select File>Create SQL Key Defn File from the menubar. SQL Key
Definition, p.24.
Define Keys Button gives you the option to set up primary and alternate
keys for the physical file. See Defining Keys, p.16.
IO Procedures Button displays a window where you can enter the name of a
program that contains logic for controlling file access.
Update File Button for embedding data dictionary into the physical file.

General File Information

The first tab in the Data Dictionary Maintenance interface describes features about
the physical database file; i.e., pathname, group, file type, and size.
Description: Short description of the table contents.

Group: Group name for assigning files to a common theme or
application; e.g., Accounting, Billing, GL.
Physical file Pathname of the actual database file – either a Fixed value or
Expression; e.g.,
Fixed: XX_AR Expression: %COMPANY$+"_AR"
Type: File type to create. Dropbox choices include:
Variable Length VLR (variable-length record).
Enhanced Format (2GB limit) Limited EFF.
Enhanced Format (>2GB limit) Unlimited EFF.
Fixed Length FLR formatted files.
For more information, see Supported File Types, p.4.
Block Size: Maximum file size in kilobytes. The Default setting allows
ProvideX to decide the recommended file size for the file type;
e.g., VLR (1-31), FLR (1-32), and EFF (4-63).
Separator: Field to be used in the file (standard is $8A$).
Extended Records Checkbox indicates that records will be written as multiples of
the size specified during file creation.
Compression Type Dropbox indicating simple compression to record data. Type
options include None, Data, and Zlib. Not applicable to FLR
files.

Data Elements
The second tab in the Data Dictionary Maintenance interface provides various
options and settings for defining elements in the physical files.
Data Elements... Lists all of the data elements for the current table. Double-click
on an element to access Element Description settings.
Inserts or deletes a data dictionary element. See Element
Description, p.9.
Moves the currently-selected data dictionary element up or
down a position in the list.
Adds or moves the currently-selected element from the Data
Elements list to the Global Dictionary list, or vice versa.
Global Dictionary... Lists global elements – elements that are common in several
files. When an element is defined globally, you will be able to
select and load its definition into various file definitions using
the right side of the Data Elements sub-panel in the Data
Dictionary Maintenance interface.
Global dictionary element definitions are stored in the data
dictionary files, providex.ddf and providex.dde and can
be accessed and modified by selecting {Global Dictionary}
from the list of logical file names in the Table Name field.
Non-Normalized Checkbox allows the definition of non-normalized data files.
See Non-Normalized Data, p.15.
Record Format: Record type description for non-normalized data files.
Note: Some of the above settings as well as some data dictionary utilities can be
invoked via drop-down menus in the Data Dictionary Maintenance menu bar.

Element Description
This sub-panel under Data Elements is used to supply details about the
currently-selected element. It is divided into four tabbed folders for defining the
Display, User Aids, Query and ODBC attributes for each element in the data file.
Name: Unique name of the element – this is the variable name used in the
primary IOList. Naming conventions for variables apply.
It is possible to restrict element names. To exclude names, such as
SQL keywords, create a list of rejected names (one item per line) in
the text file dde_exclude.txt located in the *ext directory; i.e.,
PathToProvidex/lib/_ext/dde_exclude.txt. If you choose
your own file/location for this list, the path must be loaded into
the %DDE_Exclude$ variable. When this file is present, new
names will be checked against the restricted list and rejected if
found. No action is taken for elements that already exist. Text in
this file is treated as case-insensitive and spaces are stripped.
Alternate Name: Alternate name for use in the alternate IOList (for legacy
programs). If an alternate IOList is defined, then you must define
an alternate name for all elements in the file. The alternate name
must be a variable name (e.g., A$ or A$[1]). Supports only
Fields that use the Delimited format mask.
Class: Associated data class for pre-loading information (e.g., type, size,
description, input methodology, default values, etc.). Class can
also be used to associate a control type (multi-line, drop box, list
box, check box or radio button) with the element for use within
NOMADS subsystems. See Data Classes, p.76.

External only Checkbox indicating that the element forms part of an external
key and is not duplicated in the data portion of the record. For
example, Key: CST_ID$ Data: CST_NM$, CST_ADDR$,
CST_PHONE$. In this case, CST_ID$ forms the key and is not
duplicated in the data portion of the record.
Required Checkbox indicating that the element is a required field and must
contain data before the record can be written in File Maintenance.
UpperCase Checkbox indicating that the data should always be in upper
case letters. Used by NOMADS subsystems.
Display
Short Description Brief description of the element, which can be a Fixed value,
Expression or Message Library Reference.
Type: Field indicates whether the element is Numeric or String.
Format Mask: Options define the format for writing the data field to the file; i.e.,
Delimited Delimited by field separator. Sample IOL format: DELIMITED$,
NUMERIC_DLM
Padded Padded with spaces based on the defined length. Numerics are
padded with leading zeros. Sample IOL format:
PADDED$:[LEN(6)], NUM_PADDED:[NUM(7)]
Fixed Padded to the specified length when written, but stripped of
trailing spaces when read. Sample IOL format:
FIXED$:[CHR(7)], NUM_FIXED:[NUM(7)]
Substring Similar to fixed, but if the stored data is shorter than the specified
length, a READ will return up to but not including the field
separator. (Used in conjunction with Last Substring. This format
is often used for flag fields. Sample IOL format:
SUBSTRING$:[LEN(5,SEP=SEP)]

Last Similar to fixed, but delimited by field separator. Sample IOL

Substring format: LAST_SUBSTRING$:[LEN(SEP,SIZ=4)]
Binary Signed binary, maximum 6 bytes, no delimiter binary numeric.
Numeric Sample IOL format: Binary_Num:[BIN(Length,Scale)]
e.g., Length=2 stores a value ranging from -32768 to +32767
Stores 1 as $0001$; stores -1 as $FFFF$.
Decimal Maintains the sign, decimal is explicit, no delimiter. Sample IOL
format: [DEC(Length,Scale)]
e.g., Length=10.2
Stores -1 as ^^^^^-1.00 (where ^ is a space);
Stores 123.45 as ^^^^123.45 (where ^ is a space)
Decimal Maintains the sign, decimal is explicit, delimited (same as
Delimited Decimal, but followed by a delimiter). Sample IOL format:
[DEC(Length,Scale,SEP=SEP)]
Signed Maintains the sign, decimal is implied, no delimiter. Sample
Fixed IOL format: [SGN(Length,Scale)]
Numeric e.g., Length=10.2
Stores -1 as 000000100-; stores 123.45 as 000012345+
Unsigned Unsigned binary, maximum 6 bytes, no delimiter. Sample IOL
Integer format: [INT(Length,Scale)]
e.g., Length=2 stores a value ranging from 0 to 65535.
Stores 1 as $0001$; stores 65535 as $FFFF$
Note: There is also a Space-Padded format for numeric table elements, which results
in a non-delimited fixed-length numeric field padded with spaces on the left. It
applies the existing LEN( ) format. This type is not supported by the ODBC driver
and it is only available in Data Dictionary Maintenance interface if the global
variable %ALLOW_NON_ODBC_TYPE_LEN is set to non-zero.
Data Storage Formats
String Formats IOL Format (l=length) Size Dlm Sign Decimal Pad
Delimited Variable Y N/A N/A N/A
Fixed [CHR(l)] Fixed N N/A N/A Right/Space
Padded [LEN(l)] Fixed N N/A N/A Right/Space
Substring [LEN(l,SEP=sep$)] Fixed N N/A N/A Right/Space
Last Substring [LEN(sep$,SIZ=l)] Fixed Y N/A N/A Right/Space

Data Storage Formats

IOL Format
Numeric Formats Size Dlm Sign Decimal Pad
(l=length, s=scale)
Delimited Variable Y Explicit Explicit N/A
Fixed [NUM(l,s)] Fixed N None Implied
Padded [NUM(l,s)] Fixed N None Implied Left/Zero
Substring [NUM(l,s)] Fixed N None Implied Right/Zero
Last Substring [NUM(l,s,SEP=sep$)] Fixed Y None Implied
Signed Fixed Left/Zero
[SGN(l,s)] Fixed N Explicit Implied
Numeric Right/Zero
Decimal [DEC(l,s)] Fixed N Explicit Explicit Left/Space
Decimal Delimited [DEC(sep$,SIZ=l,s)] Fixed Y Explicit Explicit Right/Zero
Binary Numeric* [BIN(l,s)] Fixed N Implied Implied Left/$00$
Unsigned Integer* [INT(l,s)] Fixed N N/A Impled Left/$00$
Examples (Note: Space characters are represented by "^", and field delimiters by "|")
String Formats Length Stores null as … Stores "abc" as …* Stores "abcdef" as …*
Delimited 5 | abc| abcdef|
Fixed 5 ^^^^^ abc^^ abcde
Padded 5 ^^^^^ abc^^ abcde
Substring 5 ^^^^^ abc^^ abcde
Last Substring 5 ^^^^^| abc^^| abcde|
Numeric Formats Length Stores 0 as …* Stores -1.1 as …* Stores 12345.678 as … *
Delimited 6.2 0| -1.1| 12345.678|
Fixed 6.2 000000 000110 234567
Padded 6.2 000000 000110 234567
Substring 6.2 000000 000110 234567
Last Substring 6.2 000000| 000110| 234567|
Signed Fixed 6.2 00000+ 00110- 34567+
Decimal 6.2 ^^0.00 ^-1.10 Error #43
Decimal Delimited 6.2 ^^0.00| ^-1.10| Error #43
1 / 32767 -1 / 65535
Binary Numeric 2 $0000$ $0001$ / $7FFF$ $FFFF$
Unsigned Integer 2 $0000$ $0001$ / $7FFF$ $FFFF$
Note: The following Format Mask options apply to key fields that are external only;
i.e., not found in the data portion of the record.
Padded Key Field padded with spaces based on the defined length.
Fixed Key Field padded to the specified length, unless it is the last key
component. For redundant external key fields (i.e., fields that
form both external key as well as part of data portion of record)
define the format as it should be defined for the data portion.

Depending on the format chosen, the format for the

corresponding key field defaults to the following:
Data Field Format Resulting Key format
Delimited Fixed [CHR(n)]
Padded [LEN(n)] Padded [LEN(n)]
Fixed [CHR(n)] Fixed [CHR(n)]
Substring [LEN(n,SEP=SEP] Padded [LEN(n)]
Last Substring [LEN(SEP,SIZ=n)] Padded [LEN(n)]
Length: Set the maximum length of the data field. Numeric field lengths
can be defined using implied decimal format. For example, 6.2:
6 represents total length of the field, including explicit signs and
decimals, where applicable; 2 represents scaling factor or
number of decimal places.
Occurs: Dimension, if element represents an array (e.g., 1:3). If a single
number (e.g., 3) then represents a single element in the third
position of an array (e.g., X$[3]) rather than the entire array.
Arrays are not supported by File Maintenance and Query utilities.
Default Value: The value to be loaded when the field is first initialized. This can
be a Fixed value, Expression or Message Library Reference.
Validation Comma separated validation rules; e.g., 1-3,9 or Y,N,M. This
can be Fixed text or an Expression.
Print Format Output format mask, either Fixed text (string literal) or Expression.
User Defined Data / tag field used to pass information on such things as
Tag Field formatting, error messages, validation rules. This can be Fixed
text (string literal) or an Expression (evaluated when the object is
created). NOMADS places the contents of this field in a variable
using the element name with a .TAG$ extension.
User Aids

Help Reference Help text to be launched when the user presses Shift - F1 .
Choose from one of two drop list items to access form fields for
specifying the different definitions (either External or Internal).
External Standard (default) help definition. This assigns a predefined
help file that can be Fixed text (string literal) or an Expression
(or string variable). Specify the starting point in the help file by
Reference or by Keyword. The Popup check box allows you to
set the display to be a pop-up rather than independent window.
Internal Simplified help stored in the library file. This help consists of
text only, either Fixed, Expression, or Message Library
Reference. Because the help text is preserved in the library
itself, it eliminates the need to create separate help files.
Notes..... Detailed description of the element for documentation purposes
only. (maximum 240 characters)
Query
Panel Checkbox to process a query panel (from the specified Library) –

either a Fixed name or an Expression (evaluated at runtime).
Program Checkbox to execute a specified query program – either a Fixed
name or an Expression (evaluated at runtime).
Spinner Controls Numerics only. Checkbox for associating a spinner control with the
element in place of a query. Sets the Increment value for scrollbar
movement as well as the Start (initial) and End (maximum) values.
For example, if Increment = 1, Start = 1, and End = 9999, then the
initial value would be 1, scrollbar movement would
increase/decrease by 1 and the maximum would be 9999.

ODBC
ODBC Hide/NoShow Options

Show Column Default check box indicates no data suppression.
Hide Column Checkbox indicates that the field will not be presented to the user.
Primarily, it is used for filler values.
No Show Checkbox indicates that the field name will be presented to the user;
however, the data will never be returned.
Non-Normalized Data
If Non-Normalized is checked off in the Data Elements panel, then you will be able
to define the records in a non-normalized data file.
Support for this capability is provided only within the Data Dictionary
Maintenance interface, not within ProvideX or NOMADS subsystems. This option
is intended primarily for the creation of INI files and SQL database definitions when
migrating applications. See also, Supported File Types, p.4.

Defining Keys
Click the button in the Main Panel to set up primary and alternate
keys for the physical file. As mentioned earlier, a key is a string of characters used to
identify the records in a file.
Primary Key
If a primary key hasn’t yet been defined, you will be given the option to set one up.
Select the Data Fields and the sort order that make up the primary key. Key
segments can be composed of one or more strings or substrings.
Select External, if the key is external, otherwise the key will be considered internal.
An external key can be made up of segments and can include a mixture of
external-only and duplicated elements.
The Unique option is checked by default. Fields and settings for defining primary
and alternate keys are fully described in the section Key Definition Panel, p.17.

Alternate Key
Once a primary key is defined, you will be able to include up to 15 alternate keys
with a total of 96 segments (FLR/VLR). EFF files can have a maximum of 255 keys
and 255 segments per key.
Key Definition Panel

You can either define a new key, or modify an existing key from the list. The key
definition panel identifies the selected key in the title bar, either as a Primary Key, or
as an Alternate Key (displaying the key # number / KNO ).
Data Fields Lists defined Data Elements for the selected file. You can select
these to construct key.
Key Segments Lists of all the data elements which currently make up the key.

Add Ascending Inserts the selected element from the Data Fields list into the Key
Segments list. Sort order for this portion of the key is ascending.
Add Descending Inserts the selected element from the Data Fields list into the Key
Segments list. Sort order for this portion of the key is descending.
Add Binary Auto Defines binary auto increment for the key, record- based, by the
Increment record offset (base 1) and length (1,2, or 4 bytes). Segments may be
designated as swapped (same as SWP( ) type 7, Intel x86 type
swapping only).
Remove Removes the selected segment from the key definition.

Key Options Check boxes for specifying the following:
Unique: Must be unique.
Null Key / Null char: If all characters of the key match the null
character, the key is not added to the key tree. The Null char is
represented by the ASCII hexadecimal value.
Partial Field Defines portion of a data field (substring options). Field Offset
indicates where the substring begins (first position offset = 1). If Field
Length = 0, the data element is read from the offset value and all
remaining characters in the data element will be used as the key
segment.
Field Offset: Beginning of the substring; i.e., first position offset = 1.

Field Length: Number of characters in the substring. If 0 (zero), the
data element is read from the offset value and all remaining
characters in the data element will be used as the key segment.
Segment Options Sets different segment options for the selected segment.

Auto Increment: Zero-filled, right-justified ASCII numeric (e.g.,

"0001") or space-filled, right-justified ASCII numeric (e.g., " 1").
This is for sequential numbering of records in the order they are
inserted.
Byte Swapped: Designates segments as swapped, which is the
same as SWP( ) type 7 (Intel x86 type swapping only).
Case Sensitivity: Allows key segments to be stored in uppercase or
lowercase.
Null Segment/Character: Definition attribute for any segment. If all
characters of a segment match the null character, the key is not
added to the key tree. Character is represented by ASCII
hexadecimal value.
Signed Integer: Key segment stored as a signed binary integer.
Updating the Data Dictionary

Be aware that all changes made to the definition (table) currently-loaded in the Data
Dictionary Maintenance interface are written immediately to the ProvideX .ddf
and .dde files as they are entered.
Embedding a Definition
To embed the current definition into the physical database file, click the
button. Depending on the contents of the current definition, ProvideX will determine
how to update the physical file with the current definition.
• If the file doesn't exist, ProvideX 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,
ProvideX 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, you will be presented with update options. Refer to the
illustration on the following page.

This can also be achieved programmatically. See Automating the Embedded

(Physical) Definition, p.21.
Convert existing data Update the file using the changes outlined in the area above.
You will be prompted with a message to make a backup of
your existing file before ProvideX overwrites it.
Clear existing data Purge data in the existing file.
Rewrite data Update the embedded definition using the changes outlined
dictionary only in the area above, but without touching the data. This does not
change the actual keys or records inside the file.
Important: 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.
Creating a Definition
Create a new definition in the data dictionary (.dde and .ddf files) by entering a
name in the Table Name field of the Main Panel. If the entered name does not exist,
you will be given the option 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 the Data Dictionary
Maintenance interface 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, p.21.

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 ProvideX 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", table$,newpath$,flags$,errmsg$,pswd$,level
Where:
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 timestamp in providex.ddf
B aborts if block size is invalid.
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 doesn't exist, ProvideX creates it and embeds the definition.
• If the file exists but has no data, the file is recreated with the new definition.

• 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. Refer to the example below.
Note: Unlike the 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 ProvideX data dictionary. For more information,
see Converting Other Formats, p.34.
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

Options The following options are accessed via the Options dropdown on the Data
Dictionary Maintenance menubar.
SQL Key Definition Update Options

This option is used to open the SQL Key Definition Update Options panel (shown
below). This allows you to set an update option for the SQL Key Definition file
providex.kdf. The update option determines how or if the KDF file will
automatically be updated when the ProvideX Data Dictionary key definition is
changed. To edit the ProvideX Data Dictionary key definition, see Defining Keys,
p.16.
The available options are:

If Record Exists The providex.kdf file will only be updated with the ProvideX
Data Dictionary key definition if a record already exists in the KDF
file. This is the default.
Always Always update the providex.kdf file.
Manually Never updates the providex.kdf with the ProvideX Data
Dictionary key definition. To manually update the KDF file, see SQL
Key Definition, p.24.
The update option will be saved in the nomads.ini file under the section [Data
Dictionary Options]; i.e.,
SQL Keys Update=update option value
Where update option value can be:
1 - If record exists
2 - Always
3 - Manually

SQL Key Definition

The SQL Keydef button is used to create/remove an SQL key definition for the selected
table. The external database key definition for the selected table will be automatically
displayed.
The Delete button will be disabled if the record does not exist in the providex.kdf
file.
Key Definition Mismatch

If SQL Key Definition Update Options is set to Manually, and the SQL key
definition record does not match the ProvideX key definition, then the following
panel will be displayed:

Data Dictionary Data Dictionary Utilities
Data Dictionary Utilities

Dat Dictionary Util ties
BMK
Access to additional data dictionary tools and security control is available via the
drop-down menu in the Data Dictionary Maintenance interface:
Drop-Down Menu
The following drop-down menu items are described below: Print, Compare
Definitions, INI File Generation, SQL Create Table, Merge, and Import
Dictionary, Key Definitions.
Print
The Print Data Dictionary Definition panel is accessed using the Print link in the
Utilities Drop-Down Menu. This allows you to generate output in a standard format
that lists all of the elements in the definitions that have been selected for printing.
Available Tables Lists definitions (tables) in the current data dictionary that are
available for printing.
Selected Tables List the tables that have been selected for printing. Use the Select
All, Include, and Remove buttons to add/remove selected items.
Print Option Checkboxes provide the choice between a Detailed Report or a
Summary Report.

Destination Checkboxes for choosing a destination. Options

include: Viewer, PDF, or Printer. The default is the ProvideX
Viewer. However, if you select an alternate destination, that
destination will become the default for that session (or until you
select a different destination.)
Compare Definitions
The Data Dictionary Compare panel is accessed using the Compare Definitions link
in the Utilities Drop-Down Menu.
This utility can be used to compare two tables from the same or different, data
dictionaries, or physical files (or a combination of both). It compares file attributes,
fields, and key structures in one table with the fields in another. All common field
names (and record formats for non-normalized files) will have their characteristics
compared. The utility reports all changes as well as any new or deleted fields..
Source 1: Path name of the ProvideX.ddf or physical file with

embedded dictionary that you want to compare from.
Table Name 1: Table you wish to compare from. Leave blank to indicate all.
Source 2: Path name of the ProvideX.ddf or physical file with
embedded dictionary that you want to compare against. Enter *
to use the physical files associated with the tables from Source 1.
Table Name 2: Table you wish to compare against. Leave blank to indicate all.
Suppress details on new/deleted files
Checkbox suppresses table information that is found in Source 1.
and not in Source 2 or vise versa.
Analyze Begins the analysis.

Automated Call
The Compare utility can also be called from a ProvideX program.
CALL "*dict/compdict;ANALYZE",source1$,table1$,source2$,table2$,result$,suppress$
Where:
source1$ Full path of the ProvideX.ddf or physical file with embedded
dictionary that you want to compare from.
table1$ Table you wish to compare from. Leave blank to indicate all.
source2$ Path name of the ProvideX.ddf or physical file with embedded
dictionary that you want to compare against. Enter * to use the physical
files associated with the tables from Source 1.
table2$ Table you wish to compare against. Leave blank to indicate all.
result$ A SEP-delimited string containing "what is being compared"+ SEP
+"source1 result"+ SEP + "source2 result"
suppress$ The flag "1" will suppress details on new/deleted files.
INI File Generation

The Create INI File definition panel is accessed using the Generate External link in
the Utilities Drop-Down Menu. This utility allows for the generation of INI file
contents directly from the data dictionary. Usually there would be no need for an INI
file if you have a file that contains an embedded data dictionary; however, there are
some occasions when an INI file format is useful.
When generating the contents for an INI file from a table with multiple record
formats, the system will generate a logical table name consisting of the table name,
an underscore, and the record name. All spaces within table names will be converted
to underscores. The contents of the INI file are output to the screen for viewing
purposes, with additional options to output to a file or the clipboard.

Automated Call
The INI File Generation utility can also be called from a ProvideX program.
CALL "*dict/defini",contents$, errmsg$, tablename$, ddf_path$
Where:
contents$ INI file contents are returned in this variable.
errmsg$ Warning and error messages are returned in this variable.
tablename$ Logical table name
ddf_path$ Pathname of the providex.ddf file (defaults to simple pathname)
SQL Create Table

The Generate SQL Create Table commands panel is accessed using the Generate
External link in the Utilities Drop-Down Menu. This utility simplifies the process of
converting the data dictionary to a SQL-based database such as ORACLE or
Microsoft SQL.
The utility outputs CREATE TABLE directives for defining database tables that are
consistent with the ProvideX data dictionary. By default, this output includes all the
fields within a table definition, including fields in non-normalized tables.
In the case of non-normalized files, duplicate element names are output once, and
the first occurrence of the element name defines the element's format. Table Index
definitions will also be created using either the Key name as supplied in the Data
Dictionary definition or a generated name based on the Table name followed by an
underscore and key number. The CREATE statements are output to the screen for
viewing purposes, with additional options to output to a file or to the clipboard.

Automated Call
The SQL Create Table utility can also be called from a ProvideX program.
CALL "*DICT/GENSQL",contents$, errmsg$, tablename$, ddf_path$, quo_char$
Where:
contents$ SQL CREATE commands are returned in this variable.
errmsg$ Warning and error messages are returned in this variable.
tablename$ Logical table name
ddf_path$ Pathname of the providex.ddf file (defaults to simple pathname)
quo_char$ Character to enclose tables, columns, indexes names (defaults to null)
Merge The Data Dictionary Merge panel is accessed using the Merge link in the Utilities
Drop-Down Menu.
This utility allows table definitions to be merged from one set of dictionary files
(ddf/dde) to another. Processing a merge involves defining a merge option to deal
with cases where the table being merged already exists in the destination dictionary
files. You can select an option to replace the contents of the table definition in the
destination file, merge the contents of the source and destination files (with the
source definition taking precedence), or skip the table.
The left side of the panel lists the dictionary tables displayed by file groupings in a
tree view format. Clicking on a particular table will cycle through the options for
dealing with duplicate tables. Clicking on a file group will cascade the setting for the
group to its associated tables, and clicking on the source path at the top of the tree

will select for the entire tree. The panel on the right displays the element descriptions
and indexes for a selected table. A description of option symbols appears in the
Legend popup, which can be invoked by clicking .
Preview Button
Press to display a report view list box showing the pending result of
merging a table highlighted in the tree view, using the specified merge option.
In the following example the Merged result would show the addition of a dictionary
element Custom and a new key #4)Custom+CST_ID.
Merge Button
Press to initiate the merge logic. During a merge, the status bar at the
bottom of the panel will be updated with the name of the table being processed.
Merge processing will be accomplished using the Merge( ) method, of the object
described later.
Automated Call
The Merge utility can also be called from a ProvideX program.
CALL "*dict/merge;MERGE_TABLES",SrcDDF$,SrcTable$,DestDDF$,MergeOpt$
or
CALL "*dict/merge;MERGE",SrcChan,SrcTable$,DestChan,MergeOpt$
Where:
SrcDDF$ Path to the dictionary source file (providex.ddf).
SrcChan Open channel to the dictionary source file (.ddf).
SrcTable$ Name of the table to be merged from the source dictionary. If
omitted, then all tables are merged.

DestDDF$ Path to the dictionary destination file.

DestChan Open channel to the dictionary destination file.
MergeOpts$ Option for dealing with tables in both source/destination files:
"1" = Replace contents of the destination table with those of source.
"2" = Merge contents of both tables, precedence given to the source.
"3" = Skip the table
Import Dictionary
The Copy Data Dictionary Definition panel is accessed using the Import Dictionary
link in the Utilities Drop-Down Menu.
This utility is used to copy a file definition from a different ProvideX data dictionary (in
another directory) into the current file definition. If a file named in Physical File has an
embedded data dictionary, then the definition can be loaded automatically; however,
definitions from other data dictionary (ddf/dde) file sets must be imported using this utility.
Note: This utility is used for importing ProvideX data dictionaries only. For converting
formats from outside of ProvideX, refer to Converting Other Formats, p.34.
To import a definition, enter a new or existing Table Name in the Main Panel of the
Data Dictionary Maintenance interface, then select the definition to be copied.
Copy To: Table that the definition will be copied into. This is the Table
Name from the main Data Dictionary Maintenance panel.
Copy From: Directory where the data dictionary (ddf/dde) file sets reside.
Press to select a different directory.
Dictionary: List of file definitions residing in the Copy From directory. Select a
definition and press to import into your target file.

Key Definitions
The Generate External Database Key Definitions panel is accessed using the
Generate External link in the Utilities Drop-Down Menu. This utility generates SQL
key definitions for data dictionary tables.
The key definitions are stored in a new providex file providex.kdf. The file is
keyed by the logical table name (64 characters) and is created in the same directory
as the providex.ddf and providex.dde files.
Once a Dictionary Source has been selected, the table names (sorted by the data
dictionary group name) are displayed in a tree view control with the dictionary
source name displayed on the top branch.
To select/de-select a table, click on the check box icon beside the table name. If you
wish to select/de-select all tables for the dictionary source, click on the check box
icon beside the dictionary source name in the tree view.

Data Dictionary Using the Data Dictionary
Using the Data Dictionary

Usingthe Dat Dictionary
BMK
As described in the Introduction, the ProvideX data dictionary can be used for
designing database applications, and is employed in different ways by ProvideX
facilities, such as the Views system, the ODBC Driver, and NOMADS.
However, the primary purpose of the data dictionary is to document the contents of
a database so that it can be easily viewed, queried, and accessed by an application.
The following ProvideX syntax uses the embedded definition to perform these tasks.
Accessing the Data

When the definition is embedded in the physical data file, the need for an IOLIST
statement in your database application is rendered obsolete. An IOList reference is
not required for a READ or WRITE statement. For example, the usual method for
reading data from a data file without an embedded definition would appear as
follows:
OPEN (1)"SomeFile"
READ (1)name$,address$,company$
or
READ (1)IOL=MyIOL
PRINT name$
MyIOL: IOLIST name$,address$,company$
If a data dictionary definition is embedded in the physical file, the same routine
could be handled as follows:
OPEN (1,iol=*)"SomeFile" ! OPEN using Data Dictionary
READ (1)
PRINT name$
The IOL= option defines a standard IOList to be used while the file is open.
ProvideX uses this IOList for all subsequent file READ, WRITE, EXTRACT, or FIND
statements where you do not explicitly supply variable lists. You can also use the
REC= option to supply a prefix to be added to all the variables in the IOL=; e.g.,
Open (1,iol=*,rec="a")"SomeFile" ! OPEN using Data Dictionary
Read (1)
Print a.name$

Data Dictionary Converting Other Formats
Open and Display Options

The asterisk represents an embedded definition. Use a caret to open a file using an
alternate IOList. For more information on the following syntax, refer to the ProvideX
Language Reference.
Opening a File: OPEN (chan,IOL=*)string$
OPEN (chan,IOL=^)string$
Displaying the IOList: PRINT LST(IOL(chan:*))
PRINT LST(IOL(chan:^))
Displaying an IOList
PRINT LST(IOL(chan:KEY))
with External Key
Example The following program illustrates how to open a file and read its contents using an
embedded definition. It uses demo files that were installed with ProvideX. You must
be in the path /lib/NOMADS/ for this to work.
00020 BEGIN
00030 OPEN (1,IOL=*)"cstfile" ! Open with data dictionary access
00040 PRINT "Load regular IOLIST ___________________"
00050 READ (1,END=0080) ! No reference to IOL required
00060 GOSUB PRINT_RECORD
00070 GOTO 0050
00080 CLOSE (1)
00160 END
00170 PRINT_RECORD:
00180 PRINT "___"+KEC(1)+"___"
00190 PRINT "Standard iolist"
00200 PRINT "CST_ID$=",CST_ID$
00210 PRINT "CST_NAME$=",CST_NAME$
00220 PRINT "CST_ADDR$=",CST_ADDR$
00230 RETURN
Converting Other Formats

ConvertingOtherFormats
BMK
Data conversion can be one of the most lengthy and difficult procedures involved in
the migration of any database. While there are tools available for importing the
different applications and files into ProvideX, there are no generic utilities for
converting the formatted data to the ProvideX data dictionary. Each external/legacy
database system requires a unique transfer strategy for converting and verifying the
integrity of its data.
This section describes the procedures for mapping the old format to a new ProvideX
data dictionary, and then for embedding the newly-created definitions into their
corresponding data files.

Data Dictionary Converting Other Formats
Mapping the Data

Create and load the new ProvideX data dictionary files (providex.ddf and
providex.dde). Data sources must be represented in the new definition (table) in a
way that accurately matches the original layout. This involves mapping the contents
of the original files to the appropriate fields in a new definition, including all
General File Information and Data Elements.
This process can be achieved manually for each data file via the NOMADS Data
Dictionary Maintenance interface. However, if a conversion is going to involve many
different data files with several elements in each, it might be more practical to write a
program that automatically generates the new data dictionary definitions.
Data Dictionary Layout

If you choose to write a program, the layout for mapping the target fields in the data
dictionary (providex.ddf and providex.dde files) can be downloaded from the
ProvideX website www.pvx.com. Refer to Data Dictionary Layout under the
Documentation > Training/Other tab for the most recent version of this document.
Refer to the sample on the following page.
The principle variables in the data dictionary layout are outlined below.
providex.ddf
Name$ Table name representing the logical file. Refer to the
description under Main Panel, p.5.
PhysicalPath$ Physical file path name. Refer to the description under General
File Information, p.7.
providex.dde
IOLOBJ$ IOList name; e.g., CST_NM$ or CST_ID$:[CHR(6)] or
PRODUCT$:[LEN(SEP,SIZ=20)]. IOList representation of
the element, must correspond to FORMAT$.
Element fields are described under Data Elements, p.8.
Name$ Element name.
Type$ Element type (Numeric or String).
Length$ Element data length.
Format$ Format of data in file (Delimited, Fixed, Padded,
Substring, Last Substring, etc.).
KeyDefinition$ Key definition (keynum:segment:direction:length:offset) if
applicable. The format appears as follows:
keynum - primary (1) or alternate (2, 3, etc.)
seg - segment position (1, 2, 3, etc.)
direction - A (ascending) or D (descending)
length:offset - partial field (substring) start position and offset.
For more information, see Defining Keys, p.16.

Data Dictionary Data Dictionary Objects
The following sample table was cropped from the data dictionary layout:
Embedding New Definitions

Once the new definitions (tables) are created in the data dictionary, they can be
embedded into their corresponding data files one at a time. This task can be
achieved manually via the NOMADS Data Dictionary Maintenance interface, or it
can also be automated by writing a program that calls a routine for embedding the
definitions: *dict/dd_updt;Update_Physical.
For more information on the syntax for using this routine, see Automating the
Embedded (Physical) Definition, p.21.
If you plan to make changes to the original file layout or attributes during the
conversion, do it after the definition has been embedded into the file.
Data Dictionary Objects

Dat Dictionary Objects
BMK
ProvideX includes a set of pre-defined data dictionary objects for working with the
data dictionary. These objects, which are designed for use under ProvideX Object
Oriented Programming (OOP), are described in the sections that follow.
Maintenance Objects
The DataBase and PVXDb objects allow you to create and modify the ProvideX data
dictionary at both the logical (providex.ddf and providex.dde) and physical
file level. Basically, these provide the same functionality programmatically that is
available via the Data Dictionary Maintenance interface:
DataBase Accesses providex.ddf and providex.dde files, returning table,
column and index information for the specified table name (table).

PVXDb Accesses internal definitions that are embedded in a file using a file
handle (fh) to reference each PVX data file.
Methods belonging to these objects are listed and described in the section DataBase
and PVXDb Objects, p.37. These, in turn, delegate functionality to a level of
Subordinate Maintenance Objects, p.43. For sample programs refer to
Maintenance Examples, p.52.
Database Interface Object

The following object provides a database-independent interface for retrieving
and updating table information:
db_manager Accesses table information for retrieval and update between an
external database and providex.ddf and providex.dde files.
Information about this object is provided under Db_Manager Object, p.62. For
sample programs refer to Database Interface Examples, p.63.
DataBase and PVXDb Objects

DataBase and PVXDb are the primary objects for data dictionary maintenance.
Methods belonging to Primary object methods are described in the following tables.
Methods are organized according to functionality: Creating/Updating Files,
Accessing Information, Updating Definitions/Tables.
Creating/Updating Files
The following table lists and describes the methods used for creating, deleting, and
importing data dictionary files.
DataBase Methods Description

Open(“table”) Return file handle to be used for subsequent
Open("table",pass$) READ/WRITE commands. Include password
for physical file, if required. (PVXDb only)
Close(fh) Close the physical table (PVXDb only)
CreateTable(“table”) Create physical table.
DeleteTable(“table”) Delete physical table (leave dictionary entries).
AdjustTable(“table”) Re-applies any dictionary changes to the
AdjustTable("table",pass$,lvl) physical table if the file already exists. If the
physical file has a password then enter the
files password and password level.

DataBase Methods Description

ImportTable(fh) Import file description contained in file or existing
ImportTable(fh, “table”) table. fh is an open channel to the file whose
description will be loaded. table, if specified,
indicates the table name in the data dictionary
DeleteDefinition(“table”) Delete data dictionary definition for table.
CreateDataBase(x$) Create the ProvideX data dictionary control
files. x$ is the full path where the files are to be
created.
SetDataBase(x$) Sets the dictionary source files to be used for
all subsequent methods. x$ is the full path to
the source files.
LoadDictionary(fh, x$) Loads dictionary information into a ProvideX
LoadDictionary(fh,x$,pass$,lvl) file specified by x$. If the physical file has a
password then enter the files password and
password level.
Accessing Information
These methods access information related to a data dictionary definition (table). The
first parameter (fh in examples below) can be a string (table name) or a number
(channel number). A table name indicates that the data dictionary files will be read;
otherwise, the channel number will be used for querying the physical table.
Information Methods Description

GetTableName$(fh) Return logical table name. (Only supports
numeric parameter)
GetTableCount( ) Return the total number of tables presently found
in the providex.ddf.
GetTableInfo(fh) Return TableInfo object that contains information
about the file. This object is static and is reused on
all subsequent calls to this method. It will be
released when the database object is released.
GetTableList$(sep$) Return a list of all the tables presently found in
the currently set providex.ddf.
The default separator is a Hex $8A$ but you can
specify the sep$ to be used.


GetTableListByGroup$ Return a list of all tables presently found in the
(group$,sep$) currently set providex.ddf for the group
specified. If group$ is null, then all tables found
will be returned in group order. The default
separator is a Hex $8A$ but you can specify the
sep$ to be used.
GetGroupList$(sep$) Return list of all the groups presently found in the
currently set providex.ddf. The default
separator is a Hex $8A$ but you can specify the
sep$ to be used.
GetIOList$(fh) Return table’s IOLIST.
GetKeyIOList$(fh) Return table’s external key IOLIST, if any.
GetAltIOList$(fh) Return table’s alternate IOLIST, if any.
GetColumnCount(fh) Return total number of data columns present in
specified table.
GetKeyColumnCount(fh) Return total number of external key columns
present in specified table.
GetColumnName$(fh, n) Return name of column (specified by column
number). Name is type independent. Strings will
not have trailing $. An error will be generated if
the name accessed has an invalid column number.
GetColumnDescription$ Return queried data column’s description.
(fh,n | n$)
GetKeyColumnName$(fh,n) Return queried external key column’s name,
which is type independent. Strings will not have
trailing $.
GetKeyColumnDescription$ Return queried external key column’s description.
(fh, n | n$)
GetColumnVariable$(fh,n|n$) Return the variable name of column (specified by
column number). For string variables the return
value will have a trailing $.
GetKeyColumnVariable$ Return the queried external key column’s variable
(fh,n | n$) name. String variables will return the variable
with a trailing $.


GetColumnInfo(fh, n|n$) Return a ColumnInfo object that contains a
description of the column. This object is static and
will be reused on all subsequent calls to this
function. It will be released when the database
object is released. You can pass either a column
number or name (which may contain a trailing $).
GetKeyColumnInfo Return external key ColumnInfo object containing
(fh,n | n$) information about the key column. This object is
static and will be reused on all subsequent calls to
this function. It is released when the DB object is
released. You can pass either a key column number
or name. The name may contain a trailing $.
GetColumnNo(fh,n$) Return queried data column’s number.
GetKeyColumnNo(fh,n$) Return queried external key column’s number.
GetColumnList$(fh,sep$) Return list of all the data columns names for the
specified table. The default separator is a Hex
$8A$, but you can specify sep$ to be used.
GetKeyColumnList$(fh,sep$) Return list of all the external key columns names
for the specified table. The default separator is a
Hex $8A$, but you can specify sep$ to be used.
GetIndexCount(fh) Return the number of indices on the table.
GetIndexName$(fh, n) Return the name of the index on the table.
GetIndexInfo(fh, n|n$) Return an IndexInfo object that contains a
description of the index. This object is static and
function. It will be released when the database
object is released. You can pass either a index
name or number (where the primary key is 1).
GetIndexDescription$ Return a list of the column descriptions that were
(fh, n|n$) used to make up the index each separated by a
plus sign. You can pass either a index name or
number (where the primary key is 1).
GetIndexList$(fh,sep$) Return list of all indexes for the specified tables. If
the index doesn’t have a name, then # followed
by the index number will be in the list. The
default separator is a Hex $8A$ but you can
specify the sep$ to be used.
Note: The following only apply to tables with variant records.


SetRecordNo(n) Set record type to be dealt with by all subsequent
GetColumn type methods. If not set, then the
default record type is 1. (Max record number is 36.)
GetRecordNo( ) Return numeric value of the currently set record
type (what SetRecordNo had been set to).
GetRecordName$(fh) Return logical name of the current record type.
GetRecordTypes(fh) Return number of record types for the specified
table.
GetVariantInfo(fh) Returns VariantInfo object that contains
information about the Non-normalized
information. This object is static and will be
reused on all subsequent calls.
Updating Definitions/Tables
These methods will update the data dictionary definition. The first parameter (fh in
examples below) can be a string (table name) or a number (channel number). A table
name indicates that the data dictionary files will be read; otherwise, the channel
number will be used for querying the physical table. When updating the data
dictionary you will need to issue an AdjustTable( ) to make the changes on to the
physical tables. When updating physical tables you may want to issue a
ImportTable( ) to have the change reflected into the data dictionary.
Update Methods Description

AddColumn(fh, obj) Add a new column based on the description
supplied by the ColumnInfo object. The new
column will be assigned the next available position
in the table. Assigning the column number property
has no effect on a AddColumn( ) method.
AddIndex(fh,obj) Add a new index to the table based on the
description in the IndexInfo object. The new
index will be assigned the next index number. In
the case of a physical table, the index will be
loaded and made accessible. Any current
positional information in the table will be lost (the
table will be closed/re-opened). This function
may fail due to concurrent access to the table - it
requires exclusive use of the table.


DropColumn(fh, n | n$) Deletes the specified column from that table. In
DropKeyColumn(fh,n | n$) the case of a physical file, the file will be recreated
and all the data for that column will be lost. Also,
all index information containing this column will
be adjusted. For example,
FieldA + FieldB
Delete Column FieldA
New Index is FieldB
DropIndex(fh, n|n$) Delete specified index for fh. Any current
positional information in the table will be lost (the
table will be closed/re-opened). Note: This
function may fail due to concurrent access to the
table - it requires exclusive use of the table.
UpdateIndex(fh,obj) Update specified index for fh with information
supplied by the idxinfo object. In the case of a
physical table, the index will be loaded and made
accessible. Any current positional information in the
table will be lost (the table will be closed/re- opened).
Note: This function may fail due to concurrent access
to the table – it requires exclusive use of the table.
UpdateColumn(fh,obj) Update specified column with information
supplied bythe ColumnInfo object.
RenameColumn(fh,old$,new$) Rename column.
RenameIndex(fh,old$,new$) Rename the index.
AddTable(obj) Add new table based on the description supplied
by the TableInfo object.
DropTable(n$) Deletes the table and all its related information.
UpdateTable(obj) Update table information based on the
information supplied by the TableInfo object.
RenameTable(fh,oldname$) Renames the table.
UpdateVariant(fh,obj) Updates the variant information for fh with the
information supplied by the VariantInfo object.
AddPassword(fh,pass$,level) Applies the password and access level to a
non-passworded file.
ChangePassword Updates the file with the modified password and
(fh,orig_pass$,new_pass$,level) access level. If no new password is given then the
original password will be used.
RemovePassword(fh, pass$) Removes given password from the file.


Merge(SrcDDF$|SrcChn, SrcTbl$, DesDDF$|DesChn, MergeOpt$)
Merge(SrcDDF$|SrcChn, DesDDF$|DesChn, MergeOpt$)
Merge table definitions from one set of dictionary
files (providex.ddf/.dde) to another.
SrcDDF$ - Path to dictionary source file (.ddf)
SrcChn - Open channel to dictionary source file
SrcTbl$ - Name of table to be merged from source
dictionary. If omitted, then all the tables.
DesDDF$ - Path to the dictionary destination file.
DesChn - Open channel to dictionary destination
file.
MergeOpt$- Options for dealing with tables that exist in
both source/destination files.
"1" = Replace contents of destination
table with those of source.
"2" = Merge contents of the two tables,
with precedence given to source.
"3" = Skip the table
Subordinate Maintenance Objects

Subordinates to the primary maintenance DataBase and PVXDb Objects include:
Idxinfo, Colinfo, Tblinfo, Variantinfo. Methods and properties for these are
described in the tables that follow.
Idxinfo
The purpose of this object is to provide a common means to describe the indexes for
a definition (table) or file.
Idxinfo Methods Description

AddSegment(n) Adds a new index segment at the position
specified by num. If num is null, then a new
index segment will be added at the end. Your
index object's segment number will be
positioned to the new segment n added.
DropSegment(n) Removes a index segment at the position
specified by n. If n is null, then the last index
segment will be removed. Your index object's
segment number will be positioned to the
removed segment.


Segment(n) Simple method to change segments. Returns
object ID after setting segment number. Allows
the user to code:
Obj'Segment(4)'ColumnWidth
or
X$ = Obj'Segment(3)'Attributes$
GetValues$(iol_obj$) Return value of queried property or properties as
a data record; e.g.,
iol_obj$= CPL(“IOList name$”)
X$=Object’GetValues(iol_obj$)
X$=value found in Name$ for this object.
InitValues( ) Initializes the object’s properties. Strings will
be set to null, numeric and Booleans to zero.
SetValues(val$, iol_obj$) Set object’s properties to the value or values
specified.
iol_obj$=CPL(“IOList name$,attributes$”)
val$=”NewName”+SEP+”Enter your Name”
Object’SetValues(val$,iol_obj$) will
return 1 if passed, 0 if failed.
Idxinfo Properties Description

Name$ Name of the index.
IsExternal Boolean indicator for external key. PVX-
hosted DB only.
IsUnique Boolean indicator for unique index.
NullSuppress Suppresses index if key is completely null
(PVX Only).
NullCharacter$ ASCII hexadecimal value. The default is a null
byte ($00$).
SegNo Current segment number being referenced.
SegCount Number of segments for index (read only).
ColumnName$ Name of column based on current segment.


ColumnAttr$ Attribute string for current segment:
A = Ascending
D = Descending
C = Upper Case
L = Lower Case
T = Translate using accent table (PVX Only)
S = Swap byte order - binary field
(PVX Only)
N = Suppress key if column null (PVX Only)
- = Signed Integer
For Auto Increment:
+ = Zero-filled, right-justified ASCII numeric
(e.g., "0001")
# = Space-filled, right-justified ASCII
numeric
(e.g., " 1")
I = Binary integer in native machine format
Field length is limited to 1, 2 or 4 bytes.
ColumnWidth Width to use of current segment’s column
(zero indicates full column)
ColumnNullCharacter$ ASCII hexadecimal value. The default is a null
byte ($00$).
ColumnOffset Offset into current segment’s column (zero-
based)
Attributes$ Attribute string for current index:
U = Unique
K = Suppress key if null.
Colinfo
The purpose of this object is to provide a common definition of a data element and to
provide for common data validation rules
Colinfo Methods Description

InitValues( ) Initializes this object’s properties. Strings will


specified; e.g.,
iol_obj$=CPL("IOList name$,attributes$")
val$="NewName"+SEP+"Enter your Name"
Object’SetValues(val$,iol_obj$)
will return 1 if passed, 0 if failed.
Validate(val | val$) Validate the contents of the column. Will return 1
if valid, 0 if not. Reason for rejection will be in
ErrorCode$/ErrorMessage$.
ViewForceType( ) Internal (ProvideX) use only.
Colinfo Properties Description

AlternateName$ Alternate name for data field used to convert
legacy applications.
Class$ Class used to define data.
ColumnNo Column number.
DefaultValue$ Default value to use when initializing data.
Description$ One line description of data element.
ErrorCode$ Last error condition that occurred.
ErrorMessage$ Descriptive text about the last error.
Extension$ Application specific extension values expressed
as a string of value pairs.
ExternalFormat$ Output display format as per PVX formatting
rules.
Help$ Help text and/or help file reference.
InputLength Length required to allow user to input this data
(read only).


InternalFormat$ Internal format as used by ProvideX. Valid formats
include:
D Default (Delimited column in PVX, standard
VARCHAR in SQL)
F Fixed length
P Padded to length
S Internal sub-string of a larger field
L Last sub-string of a larger field
B Binary data
I Unsigned Integer
G Signed Fixed Numeric
C Decimal Numeric
Z Decimal-Delimited Numeric
R Space padded
IsExternal Boolean indicator for external column.
IsPartOfPrimaryKey Boolean to indicate that this column is part of
the Primary key.
IsPartOfUniquekey Boolean to indicate that this column is part of a
Unique key definition.
IsRequired Boolean to indicate that the data in this column
is mandatory (not null).
IsUpperCase Boolean to indicate that the data should always
be upper case.
Length Length of data in total bytes/digits.
Name$ Name of the column.
Notes$ General programmer notes.
Occurs$ Occurs definition.
ODBCOption$ ODBC presentation.
Null = Show (default for new columns)
H = Hide
N = No Show
Query$ Query information for online system.
Scale Number of decimal points (numeric type only,
0 for string).
Security$ Security classes used to identify the type of user
and control access to file system.


ShortName$ Short name to be used for column headers.
TableName$ Name of the table that this column belongs to
(read only)
Tag$ User defined information.
Type$ Type of data: “S” for string, “N” for numeric.
Validation$ Validation rules. Comma-separated values
and/or ranges.
Variable$ Variable name to be used to store data. Name
plus $ if string (read only).
ViewsExpression$ Used to store column expression during Views
processing.
Tblinfo
The purpose of this object is to provide information about the file.
Tblinfo Methods Description

GetValues$(iol_obj$) Return value of queried property or properties as a
data record; e.g.,
InitValues( ) Initialize this object’s properties. Strings are set to
null, numeric and Booleans are set to zero.
specified.
iol_obj$=CPL(“IOList name$,Description$”)
return 1 if successful, 0 if failed.
Tblinfo Properties Description

Description$ Short description of the table contents.
Extension$ Variable name used to store data. Name plus "$" if
string (read only).
Group$ Allows you to group files by a common theme or
application; e.g., Accounting, Billing, GL.
IOProgram$ Name of the program that contains logic for
controlling file access.


LastChangeBy$ User ID. (read only).
LastChangeDate$ Date and User ID. In the format: CCYY/MM/DD
HH:MM:SS-USERID (read only).
Name$ Logical file name.
Notes$ Provide free-form area for recording notes on the
table and its use (limited to 1024 characters)
PhysicalFile$ The physical file path and filename of your keyed
data file. You can use a fixed value (e.g., CST_FILE)
or expression (e.g., %COMPANY$+"AR").
Security$ Security classes used to identify the type of user
and control access to file system.
Seperator$ The field separator for your file. Default is the
standard ProvideX separator $8A$.
IsDataCompression Boolean indicator for data compression.
IsExtendedRecords Boolean indicator for records larger than 32KB.
IsZlibCompression Boolean indicator for for data compression. (only
applies to VLR and EFF files.
BlockSize$ Specify a block size when creating a data file.
Null or ‘Default’ = let language determine the most
suitable size.
Valid ranges:
1 - 31 = Variable Format
1 - 32 = Fixed Format
4 - 63 = EFF (2GB limit)
4 - 63 = EFF (>2GB limit)


Options$ File Options. Allows you to directly set these
options; e.g., obj’Options$="XC".
Setting any of these values will also change the
Boolean indicator for these values.
C = Data Compression
X = Extended Records
Z = Zlib Compression (applies to Variable and EFF
file types only.)
File Types. Allows you to directly set these options;
e.g., obj’Options$="2".
You may only select one of these options.
V = Variable Format
F = Fixed Format
1 = EFF (2GB limit)
2 = EFF (>2GB limit)
Variantinfo
The purpose of this object is to provide a common means to update or change
non-normalized record information for a definition (table) or file.
Variantinfo Methods Description

AddConditionSegment(num) Add new condition segment at the position
condition segment will be added at the end. Your
variant object's ConditionSegment will be
positioned to the new segment added.
DropConditionSegment(num) Remove condition segment at the position
specified by num. If num is null, then the last
condition segment will be removed. Your variant
object's ConditionSegment will be positioned to
the removed segment.
AddFormatSegment(num) Add new format segment at the position specified
by num. If num is null, then a new format segment
will be added at the end. Your variant object's
FormatSegment will be positioned to the new
segment added.

Variantinfo Methods Description

DropFormatSegment(num) Remove format segment at the position specified
by num. If num is null then the last format
segment will be removed. Your variant object's
FormatSegment will be positioned to the
removed segment.
data record; e.g.,
InitValues( ) Initializes this object’s properties. Strings are set to
specified.
FormatSegment(n) Simple method to change format segments.
Returns object ID after setting format segment.
Allows the user to code:
Obj’FormatSegment(2)’Length=10
or
X$ = Obj’FormatSegment(2)’Name$
ConditionSegment(n) Simple method to change condition segments.
Returns object ID after setting condition segment.
Allows the user to code:
Obj’ConditionSegment(2)’Length=10
or
X$ = Obj’ConditionSegment(2)’ColumnName$
Variantinfo Properties Description

Name$ Name of the record type.
TestCondition$ Condition for this record type.
ColumnName$ Name of column based on current condition
segment.

Variantinfo Properties Description

Offset Offset into current segment’s column (zero based).
ConditionCount Number of condition segments for this
non-normalized definition (read only).
ConditionSegment Current condition being referenced.
FormatCount Number of format types for this non-normalized
definition (read only).
FormatSegment Current format type being referenced.
Maintenance Examples
These sample programs illustrate the functionality of the DataBase and PVXDb
Objects, p.37. Examples include Creating a New Data Dictionary, p.52 and
Embedding a Definition, p.58.
Creating a New Data Dictionary

This program builds a completely new ProvideX data dictionary, creates the physical
file, and then writes records into it.
! Set My Work Directory
cwdir "c:\MyData"
! Create A DataBase Object
db=new("*dict\database")
!
! Check Result
if db=0 then \
msgbox "Unable to create database object"; \
exit \
end_IF
!
! Show all the Propeties and Methods Avialable
print 'cs'
print db'*
!
! Create a new provideX Data Dictionary at location c:\MyData
r=db'CreateDataBase("")
! Check Result
if r=0 then \
msgbox "Unable to create database"; \
exit \
end_IF
!
! Set the DataBase files to use (ProvideX.ddf ProvideX.dde)
r=db'SetDataBase("")
! Check Result
if r=0 then \
msgbox "Unable to set database"; \
exit \

end_IF
! Create a Table Object

t=new("*dict/tblinfo")
!
! Check Result
if t=0 then \
msgbox "Unable to create table object"; \
exit \
end_IF
!
print 'cs'
print t'*
!
! Set Properties
t'Name$="Order Header"
t'Group$="Order Entry"
t'Description$="Our Order Header File"
t'PhysicalFile$="OrdH"
!
!Add New Table to Data Dictionary
r=db'AddTable(t)
! Check Result
if r=0 then \
msgbox "Unable to add table"; \
exit \
end_IF
!
! Create a Column Object
c=new("*dict/colinfo")
!
! Check Result
if c=0 then \
msgbox "Unable to create column object"; \
exit \
end_IF
!
! Show all the Propeties and Methods Available
print 'cs'
print c'*
!
! Set Properties
c'Initvalues()
c'Name$="Number"
c'Description$="Order Number"
c'Type$="S"
c'Length=20
c'InternalFormat$="D"
!
! Add Column to Table
r=db'AddColumn(t'Name$,c)
! Check Result
if r=0 then \

msgbox "Unable to add column"; \

exit \
end_IF
!
! Set Properties
c'Initvalues()
c'Name$="ClientId"
c'Description$="Client ID"
c'Type$="S"
c'Length=6
!
! Check Result
if r=0 then \
exit \
end_IF
!
! Set Properties
c'Initvalues()
c'Name$="Amount"
c'Description$="Taxable Amount"
c'Type$="N"
c'Length=10
c'Scale=2
!
! Check Result
if r=0 then \
exit \
end_IF
!
! Create a Index Object
i=new("*dict/idxinfo")
!
! Check Result
if i=0 then \
msgbox "Unable to create index object"; \
exit \
end_IF
!
print 'cs'
print i'*
!
! Set Properties
i'Name$="ByOrderNumber"
i'IsUnique=1
r=i'AddSegment()

! Check Result
if r=0 then \
msgbox "Unable to create index segment"; \
exit \
end_IF
! Set the Key Segment by Getting the DataBase Column Name of Column
number 1
i'columnName$=db'GetColumnName$(t'Name$,1)
i'ColumnAttr$="A"
!
! Add Index to Table
r=db'AddIndex(t'Name$,i)
! Check Result
if r=0 then \
msgbox "Unable to add index"; \
exit \
end_IF
Drop object i
!
!
! Check Result
if i=0 then \
exit \
end_IF
!
print 'cs'
print i'*
!
! Set Properties
i'Name$="ByClientThenOrderNumber"
i'IsUnique=1
r=i'AddSegment()
! Check Result
if r=0 then \
exit \
end_IF
number 1
i'ColumnAttr$="A"
!
r=i'AddSegment()
! Check Result
if r=0 then \
exit \
end_IF
number 1

i'ColumnAttr$="A"
r=db'AddIndex(t'Name$,i)
! Check Result
if r=0 then \
exit \
end_IF
Drop object i
!
!Lets Create the Physical File
r=db'CreateTable(t'Name$)
! Check Result
if r=0 then \
msgbox "Unable to create Physical File"; \
exit \
end_IF
!
!Drop the DataBase Object
Drop object db
Drop object t
Drop object c
!
open (1,iol=*)"ordh"
number$=dim(19,"0")+"1"
ClientId$="MAS90"
Amount=123.12
Write (1)
number$=dim(19,"0")+"2"
ClientId$="BEST"
Amount=43.05
Write (1)
number$=dim(19,"0")+"3"
ClientId$="PVX"
Amount=567.45
Write (1)
close (1)
!
print 'cs'
print "Iolist of ordh: "+lst(iol(1))
print "List of Key Names: "+fin(1,"key_names")
print "List of Records by Key 0"
Read Record (1)r$
Print R$
Read Record (1)r$
Print R$
Read Record (1)r$
Print R$
!
close (1)

Read Record (1,kno=1)r$
Print R$
Print R$
Print R$
!
db=new("*dict\database")
!
! Check Result
if db=0 then \
msgbox "Unable to create database object"; \
exit \
end_IF
!
! Set the DataBase files to use (ProvideX.ddf ProvideX.dde)
r=db'SetDataBase("c:\MyData")
! Check Result
if r=0 then \
exit \
end_IF
!
! GetTableCount
print "Number of tables found in this ProvideX Data Dictionary are
",db'gettableCount()
print "Number of columns in table '",db'gettablename$(1),"' are
",db'getcolumncount(db'gettablename$(1))
print "These columns are: ",db'getcolumnlist$(db'gettablename$(1),",")
! Create a column object comprised of the information found in Table
Order Header column 2
c=db'getcolumninfo(db'gettablename$(1),2)
print "Column '",c'name$,"' length=",c'length,"
description=",c'description$
print ""
print "Number of indexes in table '",db'gettablename$(1),"' is
",db'getindexcount(db'gettablename$(1))
print "The names of these indexes are
",db'getIndexlist$(db'gettablename$(1),",")
! Create a index object compreised of the information found in Table
Order Header index 2
i=db'getindexinfo(db'gettablename$(1),2)
print "Index '"+i'name$+"' has ",i'segcount," segments"
i'segment(1)
print "Segment 1 is made up of column "+i'columnname$
i'segment(2)
drop object db
end

Embedding a Definition
This program uses the pvxdb object to manipulate the embedded data dictionary
definition and update the provideX.ddf and provideX.dde with new information.
! Set My Work Directory
cwdir "c:\MyData"
! Create A Pvxdb Object
db=new("*dict\pvxdb")
!
! Check Result
if db=0 then \
msgbox "Unable to create pvxdb object"; \
exit \
end_IF
!
print 'cs'
print db'*
!
! Set the Physical file to use (ProvideX.ddf ProvideX.dde)
ph=db'open("ordh")
! Check Result
if ph=0 then \
exit \
end_IF
!
! Create a Column Object
c=new("*dict/colinfo")
!
! Check Result
if c=0 then \
msgbox "Unable to create column object"; \
exit \
end_IF
!
print 'cs'
print c'*
!
! Set Properties
c'Initvalues()
c'Name$="OrderDate"
c'Description$="Order Date"
c'Type$="S"
c'Length=8
!

r=db'AddColumn(ph,c)
! Check Result
if r=0 then \
exit \
end_IF
!
!
!
! Check Result
if i=0 then \
exit \
end_IF
!
print 'cs'
print i'*
!
! Set Properties
i'Name$="ByOrderDate"
i'IsUnique=1
r=i'AddSegment()
! Check Result
if r=0 then \
exit \
end_IF
number 1
i'columnName$=db'GetColumnName$(ph,4)
i'ColumnAttr$="A"
!
r=i'AddSegment()
! Check Result
if r=0 then \
exit \
end_IF
number 1
i'columnName$=db'GetColumnName$(ph,1)
i'ColumnAttr$="A"
r=db'AddIndex(ph,i)
! Check Result
if r=0 then \


exit \
end_IF
!
!Drop the DataBase Object
Drop object db
Drop object c
Drop object i
!
number$=dim(19,"0")+"1"
read (1,key=number$)
OrderDate$="20050101"
Write (1)
number$=dim(19,"0")+"2"
Write (1)
number$=dim(19,"0")+"3"
Write (1)
close (1)
!
print 'cs'
print "Iolist of ordh: "+lst(iol(1))
print "List of Key Names: "+fin(1,"key_names")
Read Record (1)r$
Print R$
Read Record (1)r$
Print R$
Read Record (1)r$
Print R$
!
close (1)
Print R$
Print R$
Print R$
!
close (1)


Print R$
Print R$
Print R$
!
db=new("*dict\pvxdb")
!
! Check Result
if db=0 then \
msgbox "Unable to create pvxdb object"; \
exit \
end_IF
!
! Open Physical file
ph=db'Open("ordh")
! Check Result
if ph=0 then \
exit \
end_IF
!
! GetTableCount
print "Number of columns in table '",db'gettablename$(ph),"' are
",db'getcolumncount(ph)
print "These columns are: ",db'getcolumnlist$(ph,",")
! Create a column object compreised of the information found in Table
c=db'getcolumninfo(ph,2)
print ""
print "Number of indexes in table '",db'gettablename$(ph),"' is
",db'getindexcount(ph)
print "The names of these indexes are ",db'getIndexlist$(ph,",")
! Create a index object comprised of the information found in Table Order
Header index 2
i=db'getindexinfo(ph,2)
i'segment(1)
i'segment(2)
drop object db
end

Db_Manager Object
This object provides a database-independent interface for retrieving and updating
table information. Each method includes an argument to identify the source (or
destination) database. The value of this argument can be specified using the
following code:
dbConstants=new("*dict/db_constants")
tag$="ado"
aDatabaseID=dbConstants'getDatabaseID(tag$)
The database tag$ may be one of the following:
ado Microsoft SQL-Server interface (ADO)
db2 IBM DB2 interface (DB2)
oci Oracle interface (OCI)
odb ODBC interface
mysql MYSQL interface (MYSQL)
pvxddf ProvideX DDF/DDE Files
pvxdb ProvideX embedded Data Dictionary information from a physical file
Db_Manager contains 3 primary methods, described in the following table:

ReadDefn( ) Reads the table definition from the providex.ddf
/ providex.dde files, an external database, or a
physical file with an embedded dictionary
definition (determined by SourceDB parameter) and
stores it in a temporary location.
CreateTable( ) Retrieves the table definition from the
temporary location and either creates a physical
file with an embedded dictionary definition, a
table in an external database, or the
providex.ddf / providex.dde definitions
(determined by DestinationDB parameter).
DropTable( ) Drops a table from either the providex.ddf /
providex.dde files, an external database or a
physical file with an embedded dictionary
definition (determined by DestinationDB
parameter).

Different parameter values are used for these methods depending on the source or
destination database. For complete details, please refer to the ProvideX Class
Documentation on the ProvideX website:
http://www.pvx.com/support/#support-docs-pvxclasses.
Sample programs are provided under Database Interface Examples (below).
Database Interface Examples

The following sample programs illustrate the functionality of the Db_Manager
Object.
Example 1
Retrieving the table definition from a Microsoft SQL-Server database (ADO):
db=new("*dict/db_manager")
Table$="Customer"
ConnectOpt$="user=sa;pswd=admin;db=test"
DSN$="ws2003-x86-pdb.pvx.com"
TableOk=db'ReadDefn(dbConstants'getDatabaseID("ado"),Table$,ConnectOpt$,DSN$)
Removing/creating a new table definition in providex.ddf / providex.dde files:
Ddfpath$="c:\pvx\demo\data"
FilePath$="cstfile"
UpdateTable=0
GroupName$="Customers"
Db'droptable(dbConstants'getDatabaseID("pvxddf"),Table$,ddfpath$) ! remove
table definition if it exists
Db'CreateTable(dbConstants'getDatabaseID("pvxddf"),ddfpath$,FilePath$,UpdateT
able,GroupName$)
Updating the table in the ddf/dde files:
FilePath$=""
UpdateTable=1
GroupName$=""
db'CreateTable(dbConstants'getDatabaseID("pvxddf"),ddfpath$,FilePath$,UpdateT
able,GroupName$)
Example 2
Retrieving the table definition from the providex.ddf / providex.dde files:
Db=new("*dict/db_manager")
Table$="Customer"
TableOk=db'ReadDefn(dbConstants'getDatabaseID("pvxddf"),Table$,Ddfpath$)

Data Dictionary SQL Interface Objects
Updating the physical file:

FilePath$="cstfile"
UpdateTable=1
db'CreateTable(dbConstants'getDatabaseID("pvxddf"),FilePath$,UpdateTable)
Updating the table in the Microsoft SQL-Server database (ADO)
ConnectOpt$="user=sa;pswd=admin;db=test"
DSN$="ws2003-x86-pdb.pvx.com"
UpdateTable=1
db'CreateTable(dbConstants'getDatabaseID("ado"),Table$,ConnectOpt$,DSN$,U
pdateTable)
SQL Interface Objects

SQL Interface Objects
BMK
ProvideX also includes a set of OOP objects that are designed for accessing and updating
external SQL databases in much the same way as ProvideX Data Dictionary Objects,
p.36. The following support external database interfaces in ProvideX:
db_ado Interface for connecting to a Microsoft SQL-Server database.
db_db2 Interface for connecting to an IBM DB2 database.
db_oci Interface for connecting to an Oracle database.
db_odb Interface for generic open database connectivity.
db_mysql Interface for connecting to a MYSQL database.
Some of these objects replace older versions (described under Legacy SQL Objects).
For complete documentation on the methods and properties that comprise these
objects, refer to the ProvideX Class Documentation on the ProvideX website:
Legacy SQL Objects

The following legacy objects are still available for use: .
odbsql Legacy open database connectivity object. Use db_odb for improved
functionality.
ocisql Legacy object to access a Oracle database file. Use db_oci for improved
functionality.
db2sql Legacy object to access a DB2 database file. Use db_db2 for improved
functionality.

The methods and properties from the legacy objects remain compatible with the new
objects. These are described in the sections that follow.
Note: The new objects also contain several methods and properties (for additional
functionality) that are not listed in the tables below. All of the new material is fully
documented under ProvideX Class Documentation on the ProvideX website:
Methods are organized according to functionality: Connectivity, Table Operations,
Column Operations, and Index Operations. For descriptions of subordinates to the
primary SQL database objects, refer to the section Subordinate SQL Objects, p.69.
Properties Description
ConnectOption$ Current connect options.(Read-Only); e.g.,
print sql’Connectoption$
USER=guest;PSWD=******
LastMethodErrMsg$ Contains reason why last executed method
failed.(Read-Only)
LastSqlStatment$ Contains last SQL statement that caused the
method to fail.(Read-Only)
LastOsErrorMsg$ Contains PVX MSG(-1) of the last error.
(Read-Only)
LastPvxErr Contains last encountered PVX
error.(Read-Only)
Methods - Connectivity Description

SetConnectOption(Opt$,Val$) Set, modify and remove the OPEN options
for connecting to an Oracle server, ODBC
driver, or DB2 server; e.g.,
sql’SetConnectOption("USER","guest")
– sets option
sql’SetConnectOption("USER","user1")
– modifies option
sql’SetConnectOption("USER","")
– removes this option only
Note: Options that may have more than one
value must be set individually.
sql’SetConnectOption("KEY","Name")
– sets option
sql’SetConnectOption("KEY","Company")
– adds another KEY option.

Methods - Connectivity Description

SetConnectString(Val$) Set all the connect options with one
statement; e.g.,
sql’SetConnectString("USER=scott
;PSWD=foobar;KEY=Name;KEY=ID")
ReturnConnectOption(Opt$) Return list of all the value(s) set by this
connect option. Default separator is a Hex
ReturnConnectOption(Opt$,Sep$) $8A$ but you can specify Sep$ to be used.
ClearConnectOption( ) Clear all connect options.
Connect(SID$|DSN$) If odbcsql, then name of the ODBC
database DSN.
If ocisql, then Oracle system ID of file to
open. If not supplied, then the value of the
environment variable ORACLE_SID is used.
If db2sql, then you supply the name of a
DB2 database.
Note: During the connect method all
options set in the ConnectOption will be
passed to the Connect statement. If a table
name is set during the connect then all
update, rename, delete, add and modify
methods will not be allowed.
Methods - Table Operations Description

GetTableCount( ) Return number of tables presently found.
GetTableList$(Sep$) Return list of all the tables presently found
in the currently set connection. Default
separator is a Hex $8A$ but you can specify
Sep$ to be used.
GetTableInfo(Table$) Return table information object containing
information about the Table. This object is
static and will be reused on all subsequent
calls to this method. It will be released
when the database object is released.
GetIOList$(Table$) Return tables IOList
AddTable(obj) Add new table based on the information
supplied by the table object. If the database
connection rules require at least one column
then a dummy column will be created (i.e.,
Default Column + Table Objects Name. This
dummy column will be type char.

Methods - Table Operations Description

AddTable(obj,ColObjs$) Add new table based on the information
supplied by the table object. Add each
AddTable(obj,ColObjs$,IdxObjs$) column based on the comma-separated list
of column objects passed in. Add each
index based on comma-separated list of
index objects passed in. For example,
ColumnObjs$=(100002,100003,100004)
IdxObjs$=(100005)
Sql’AddTable(obj, ColObjs$,
IdxObjs$)
DropTable(Table$) Delete table and all its related information.
RenameTable(OldName$,NewName$) Rename the table.
Methods - Column Operations Description

GetColumnCount(Table$) Return total number of data columns
present in specified table.
GetColumnName$(Table$,Col Return queried data column’s name, which
Num) is type independent. Strings will not have
trailing $.
GetColumnVariable$(Table$, Return queried data column’s variable
ColNum |ColName$) name. String variables will return the
variable with a trailing $.
GetColumnInfo Return column object containing
(Table$,ColNum|ColName$) information about the data column. This
object is static and will be reused on all
subsequent calls to this function. It will be
released when the database object is
released. You can pass either a data column
number or name. The name may contain a
trailing $.
GetColumnList$(Table$,Sep$) Return list of all data column names for the
specified table. Default separator is a Hex
$8A$ but you can specify Sep$ to be used.
GetColumnNo(Table$,ColName$) Return queried data column’s number.
AddColumn(Table$,obj) Add new column based on the description
supplied by the column object. Note that no
control is given over the column number
that will be assigned to the column or its
placement in the table.

Methods - Column Operations Description

DropColumn(Table$,ColNum Delete data column and its information
|ColName$) from the table.
UpdateColumn(Table$,obj) Update column information based on the
changes occurred by the column object.
RenameColumn(Table$, Rename the column.
OldName$,NewName$)
Methods - Index Operations Description

Note: If a key was set in the connect option then only this information will be
returned.
GetIndexCount(Table$) Return total number of indexes present on
the specified table.
GetIndexName$ Return name of the specified index. If the
(Table$,IndexNum) index doesn’t have a name, then a #
followed by the index number will be
returned.
GetIndexDescription$(Table$, Return list of column descriptions that were
IndexNum | IndexName$) used to make up the index, each separated
by a plus sign. If no description exists then
the column name will be used.
GetIndexInfo(Table$, Return Index object containing information
IndexNum | IndexName$) about the index. This object is static and
function. It will be released when the object
is released. You can pass either an index
number or name.
GetIndexList$(Table$,Sep$) Return list of indexes for the specified
tables. If the index doesn’t have a name,
then # followed by the index number will
be in the list. Default separator is a Hex
$8A$ but you can specify Sep$ to be used.
AddIndex(Table$,obj) Add new index to the table based on the
information in the index object. The new
index will be assigned the next highest
index number.
DropIndex(Table$,IndexNum | Delete index and its information from the
IndexName$) table.

Methods - Index Operations Description

UpdateIndex(Table$,obj) Update index information based on the
changes occurred by the Index object.
RenameIndex(Table$, Rename index.
OldName$,NewName$)
Subordinate SQL Objects

Subordinates objects include the following: Idxinfo, Colinfo, Tblinfo. The methods
and properties belonging to these objects are described in the tables that follow.
Idxinfo
The purpose of this object is to provide a common means for describing indexes in a
table or file.

AddSegment(n) Adds a new index segment at the position
index segment will be added at the end. Your
index object's SegNo will be positioned to the
new segment added.
DropSegment(n) Removes a index segment at the position
specified by num. If num is null, then the last
index segment will be removed. Your index
object's SegNo will be positioned to the
removed segment.
Segment(n) Simple method to change segments. Returns object
ID after setting SegNo. Allows the user to code:
Obj'Segment(4)'ColumnWidth
or
X$ = Obj'Segment(3)'Attributes$
InitValues( ) Initializes the object’s properties. Strings will


specified.

Name$ Name of the index.
IsExternal Not used
IsUnique Boolean indicator for unique index.
NullSuppress Not used
NullCharacter$ Not used
SegNo Current segment number being referenced.
SegCount Number of segments for index (read only).
ColumnName$ Name of column based on current segment.
ColumnAttr$ Attribute string for current segment:
A = Ascending
D = Descending
ColumnWidth Width to use of current segment’s column
(zero indicates full column)
ColumnNullCharacter$ Not used
ColumnOffset Offset into current segment’s column (zero
based)
Attributes$ Attribute string for current index:
U = unique.
“” = Not-unique.

Colinfo
The purpose of this object is to provide a common definition of a data element and to
provide for common data validation rules.

InitValues( ) Initializes this object’s properties. Strings will
specified.
Validate(val | val$) Validate the contents of the column. Will return 1
if valid, 0 if not. Reason for rejection will be in
ErrorCode$/ErrorMessage$.

Name$ Name of the column.
Variable$ Variable name to be used to store data. Name
plus $ if string (read only).
Description$ Not used.
ShortName$ Short name to be used for column headers.
Type$ Type of data: “S” for string, “N” for numeric.
ColumnNo Column number.
Security$ Not used
Scale Number of decimal points (numeric type only).
Occurs$ Not used


InternalFormat$ Valid formats include:
ODBC Types: "AUTONUMBER", "BIGINT", "BINARY",
"BIT", "CHAR", "CHARACTER", "COUNTER",
"CURRENCY", "DATE", "DATETIME", "DATE/TIME",
"DECIMAL", "DOUBLE PRECISION", "FLOAT",
"HYPERLINK", "IMAGE", "INT", "INTEGER", "LONG
VARCHAR", "MEMO", "MONEY", "NCHAR", "NTEXT",
"NUMBER", "NUMERIC", "NVARCHAR", "OLE OBJECT",
"REAL", "SMALLDATETIME", "SMALLINT",
"SMALLMONEY", "SQL_VARIANT", "TEXT",
"TIMESTAMP", "TINYINT", "UNIQUEIDENTIFIER",
"VARBINARY", "VARCHAR", "YES/NO".
OCI Types: "CHAR", "VARCHAR2", "NCHAR",
"NVARCHAR2", "NUMBER", "DATE", "RAW", "LONG RAW",
"LONG", "ROWID", "BLOB", "CLOB", "NCLOB", "BFILE",
"UROWID", "FLOAT", "XMLTYPE".
DB2 Types: "LONG VARCHAR", "BLOB", "CLOB",
"BIGINT", "CHARACTER", "DATE", "DECIMAL",
"DOUBLE", "INTERGER", "REAL", "SMALLINT", "TIME",
"TIMESTAMP", "VARCHAR".
ExternalFormat$ Not used
InputLength Length required to allow user to input this data
(read only).
Help$ Not used
Notes$ Not used
Query$ Not used
Validation$ Not used
Class$ Not used
DefaultValue$ Not used
AlternateName$ Not used
Tag$ Not used
IsExternal Not used
IsRequired Not used
IsUpperCase Not used
ODBCOption$ Not used
Extension$ Not used
ViewsExpression$ Not used
ErrorCode$ Not used


ErrorMessage$ Not used
Tblinfo
The purpose of this object is to provide information about the file.

data record; e.g.,
InitValues( ) Initialize this object’s properties. Strings are set to
specified.

Description$ Short description of the table contents.
Extension$ Not used
Group$ Not used
IOProgram$ Not used
LastChangeBy$ Not used
LastChangeDate$ Not used
Name$ Logical file name.
Notes$ Not used
PhysicalFile$ Not used
Security$ Not used
Seperator$ Not used
IsDataCompression Not used
IsExtendedRecords Not used
BlockSize$ Not used
Options$ Not used

Sample Program
This sample program illustrates the functionality of the SQL objects (properties and
methods) that were listed and described in the previous sections. It uses the odbsql
object to display information about the data base and read records from the orders
table found in a Microsoft Access data base.
! Create A Sql ODBC Data Base Object
s=new("*dict\odbsql")
!
! Check Result
if s=0 then \
msgbox "Unable to create sql object"; \
exit \
end_IF
!
print 'cs'
print s'*
!
! Connect to a Microsoft Access DataBase which is called Access and I
would like to be connect to table Orders
ph=s'Connect("Access;Orders")
! Check Result
if ph=0 then \
msgbox "PVX error: "+str(s'lastpvxerr) + sep + "OS Error Message:
"+s'oserrormsg$ ;\
exit \
end_IF
!
!Show Tables all tables in Access Data Base
! GetTableCount
tb$="Orders"
print sep+sep
print "Total number of tables : ",s'gettableCount()
print "Table List : ",s'gettablelist$(",")
print "Table 'Orders' has ",s'getcolumncount(tb$)," columns"
print "Column list : ",s'getcolumnlist$(tb$,",")
! Create a column object compreised of the information found in Table
c=s'getcolumninfo(tb$,2)
print ""
print "Number of indexes in table '",tb$,"' is ",s'getindexcount(tb$)
print "The names of these indexes are ",s'getIndexlist$(tb$,",")
! Create a index object comprised of the information found in Table Order
Header index 2
i=s'getindexinfo(tb$,2)
i'segment(1)
for t=1 to i'segno

print "Segment ",t," is made up of column "+i'columnname$

i'segment(t)
next t
!
print sep+sep
Print "Table 'Orders' iolist: ",s'getiolist$(tb$)
Print "Lets read the first record and put the data into the iolist"
l$=cpl(s'getiolist$(tb$))
read record (ph,err=*break)r$
read data from r$ to iol=l$
print "OrderID= ",orderid
!
! Drop sql object
drop object s

Data Dictionary Data Classes
Data Classes
Dat Clas es
BMK
Data classes are used to implement standardized definitions for commonly used
elements, such as dates, monetary amounts, etc. In other words, you can build a data
class according to a standard and then simply use the generic class as a basis for any
new data element. Use the Data Classifications interface (via NOMADS) to create and
modify data class definitions.
ProvideX maintains class definitions in a separate file called providex.dcl. If you

include a Class in the Element Description for a definition in the Data Dictionary
Maintenance interface, the information from that class definition will be loaded
automatically into the element description fields. The element fields that are loaded
include the short description, data type, length, default value, validation rules, print font,
query library and panel and tag field. Most of these fields are used by NOMADS and its
sub-systems.
Also, a data class can be associated with various types of controls (multi-lines, list
boxes, radio buttons, etc.). The Panel Designer and File Maintenance use this
information to generate the desired control type when creating panels.
Data Classifications Interface

Data Dictionary Data Classes
Class Name Key to the providex.dcl data classification file. When you
assign a new data class name, you can use the characters A-Z, 0-9,
the underscore or a period. Blanks are not allowed. Maximum
length 30 characters.
Query view of existing data classes
Advance through available class names.
Description Generic description of the data class (Fixed value, Expression or
Message Library Reference). This will be copied to the data
dictionary when the data class is used in an Element Description.
Control Type Default control type used to represent the data that belongs to your
defined data class (primarily for the NOMADS Panel Designer
and File Maintenance). Choose from the following control types:
Input Field, Drop Box, List Box, Radio Button, Check Box.
This tells the File Maintenance generator which type of control
is to be used for representing the data element. It defaults to an
Input Field (multi-line). By default, any elements defined in the
data dictionary will be represented as a multi-line in the
generated file maintenance panel.
If the Internal Data Type is for a String variable, the value in the
Size field will define the maximum string length. For a Numeric
variable, enter nnn.dd where nnn is the maximum number of
digits (including decimal) and dd is the number of digits after
the decimal point (i.e., the PRECISION). For radio buttons and
check boxes, the size is 1.
Internal Data Type Internal format of the data when manipulated by a program, either
String or Numeric.
Size: Maximum size of stored data element. For string variables, this is the
maximum string length. For numeric variables, enter nnn.dd where
nnn is the maximum number of digits (including decimal) and dd is
the number of digits after the decimal point (i.e., PRECISION of
number). For radio buttons and check boxes, the size = 1.
Popup Menu: Assigns popup menu to a data class (Fixed value or expression, to
be evaluated at runtime when the popup signal occurs). A check
mark indicates that a popup menu is currently assigned to the data
class. This button invokes a panel for assigning Prior Popup logic,
a predefined popup object or user-defined program.

Data Dictionary Password Protection
If selected, Prior Popup logic will be executed before the popup

menu is displayed. If On Select logic exists for the control with
the popup menu, this will be triggered before the popup event.
Select the Panel option to display a preset list of popup objects
available for the highlighted library. The Program option is for
adding a user-defined program.
The options available in the Display, Attributes, Values/Validation and Query tabs
varies dependent on the Control Type selected. Most of these options are used by the
NOMADS Panel Designer and File Maintenance to set up controls, and are covered
in more detail in the NOMADS Manual under Dictionary-Based Development.
As pertains to the Data Dictionary, the following fields are used.
Tab
Control Type
Display Attributes Values/Validation Query
Input Field Initial value User tag field Rules Lib/Panel,
(MULTI_LINE) Input format program, or
spinner.
DROP_BOX Not used User tag field Default Setting Lib/Panel, or
LIST_BOX program.
RADIO_BUTTON Default Value User tag field N/A N/A
CHECK_BOX N/A User tag field Default Setting N/A
Password Protection
Pas wordProtection
BMK
This interactive utility allows you to add, change or remove passwords in ProvideX
data dictionary files:

The Data File Password Utility panel, fields and options are described in the pages
that follow.
Table Name Selected table name. If the file is already passworded, then a
password entry dialogue box would be displayed; e.g.,
*cmd/system/get_pswd. If the password entered is invalid,
the Data File Password Utility will exit automatically.
Remove password
Check box for removing an existing password on a file.
from table
New Password New password to be applied to the file.
Password required
Toggle for password to be required for all IO operations.
to access table
Permit READ only
Toggle for read-only access when no password is supplied.
access without
Password is required for write access only.
password
Encrypt data Indicates that the data that is written to the file is encrypted.
Mask Password Hides the password from view.


DataDict V910

Uploaded by

Copyright:

Available Formats

You might also like

DataDict V910

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DataDict V910

Uploaded by

Copyright:

Available Formats

ProvideX Version 9.

©2010 Sage Software Canada Ltd. — Printed in Canada

All rights reserved. Reproduction in whole or in part without permission is prohibited.

Publication Release: V9.10

how it is defined, and how it may be used in various applications.

ProvideX V9.10 Back 3

Supported File Types

Data Dictionary Maintenance

ProvideX V9.10 Back 4

ProvideX V9.10 Back 5

Buttons and Fields

ProvideX V9.10 Back 6

General File Information

Description: Short description of the table contents.

ProvideX V9.10 Back 7

ProvideX V9.10 Back 8

ProvideX V9.10 Back 9

ProvideX V9.10 Back 10

Last Similar to fixed, but delimited by field separator. Sample IOL

ProvideX V9.10 Back 11

Data Storage Formats

ProvideX V9.10 Back 12

Depending on the format chosen, the format for the

ProvideX V9.10 Back 13

Panel Checkbox to process a query panel (from the specified Library) –

ProvideX V9.10 Back 14

ODBC Hide/NoShow Options

ProvideX V9.10 Back 15

ProvideX V9.10 Back 16

Key Definition Panel

ProvideX V9.10 Back 17

Remove Removes the selected segment from the key definition.

Field Offset: Beginning of the substring; i.e., first position offset = 1.

ProvideX V9.10 Back 18

Auto Increment: Zero-filled, right-justified ASCII numeric (e.g.,

Updating the Data Dictionary

ProvideX V9.10 Back 19

This can also be achieved programmatically. See Automating the Embedded

ProvideX V9.10 Back 20

Automating the Data Dictionary Update

The Update_DD routine in ProvideX can be called from an application in order to

Automating the Embedded (Physical) Definition

ProvideX V9.10 Back 21

Note: Unlike the button, there will be no warnings or options for

ProvideX V9.10 Back 22

SQL Key Definition Update Options

The available options are:

ProvideX V9.10 Back 23

SQL Key Definition

Key Definition Mismatch

ProvideX V9.10 Back 24

Data Dictionary Utilities

ProvideX V9.10 Back 25

Destination Checkboxes for choosing a destination. Options

Source 1: Path name of the ProvideX.ddf or physical file with

ProvideX V9.10 Back 26

INI File Generation

ProvideX V9.10 Back 27