Data Dictionary Objects 

Database Methods

Description

AdjustTable("table")

AdjustTable("table", pass$, lvl)

Reapplies any dictionary changes to the physical table if the file already exists. If the physical file has a password, then enter the file's password and password level.

Close(fh)

(PVXDb Only) Close the physical table.

CreateDataBase(x$)

Create the PxPlus data dictionary control files.

x$ is the full path where the files are to be created.

CreateTable("table")

Create the physical table.

DeleteDefinition("table")

Delete data dictionary definition for table.

DeleteTable("table")

Delete the physical table (leave dictionary entries).

ImportTable(fh)

ImportTable(fh, "table")

Import file description contained in file or existing 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.

LoadDictionary(fh, target$)

LoadDictionary(fh, target$, pass$, lvl)

Loads/updates the dictionary information for the table identified by fh into the file specified by target$.

It should be noted that the dictionary information will be taken from the Database definition and not the physical file referenced by fh. The physical file target$ must exist, and if it has a password, its password and password level are required.

Open("table")

Open("table", pass$)

(PVXDb Only) Return file handle to be used for subsequent READ/WRITE commands. Include password for physical file, if required.

SetDataBase(x$)

Sets the dictionary source files to be used for all subsequent methods.

x$ is the full path to the source files.

Information Methods

Description

GetAltIOList$(fh)

Return table's alternate IOList, if any.

GetColumnCount(fh)

Return total number of data columns present in the specified table.

GetColumnDescription$(fh, n | n$)

Return queried data column's description.

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 $).

GetColumnList$(fh, sep$)

Return a list of all the data columns' names for the specified table. The default separator is a Hex$8A$; however, you can specify sep$ to be used.

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.

GetColumnNo(fh, n$)

Return queried data column's number.

GetColumnVariable$(fh, n | n$)

Return the variable name of column (specified by column number). For string variables, the return value will have a trailing $.

GetGroupList$(sep$)

Return a list of all the groups presently found in the currently set providex.ddf. The default separator is a Hex $8A$; however, you can specify the sep$ to be used.

GetIndexCount(fh)

Return the number of indices on the table.

GetIndexDescription$(fh, n | n$)

Return a list of the column descriptions that were used to make up the index, each separated by a + (plus sign). Columns in descending order are appended with "/d". You can pass either an index name or number (where the primary key is 1).

(The appending of "/d" to indicate descending order was added in PxPlus 2022.)

GetIndexInfo(fh, n | n$)

Return an IndexInfo object that contains a description of the index.

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 an index name or number (where the primary key is 1).

GetIndexList$(fh, sep$)

Return a list of all indexes for the specified tables. If the index does not have a name, then # followed by the index number will be in the list. The default separator is a Hex $8A$; however, you can specify the sep$ to be used.

GetIndexName$(fh, n)

Return the name of the index on the table.

GetIOList$(fh)

Return table's IOList.

GetKeyColumnCount(fh)

Return total number of external key columns present in the specified table.

GetKeyColumnDescription$(fh, n | n$)

Return queried external key column's description.

GetKeyColumnInfo(fh, n | n$)

Return external key ColumnInfo object containing information about the key column.

This object is static and will be reused on all subsequent calls to this function. It will be released when the DB object is released. You can pass either a key column number or name. The name may contain a trailing $.

GetKeyColumnList$(fh, sep$)

Return a list of all the external key columns' names for the specified table. The default separator is a Hex $8A$; however, you can specify the sep$ to be used.

GetKeyColumnName$(fh, n)

Return queried external key column's name, which is type independent. Strings will not have trailing $.

GetKeyColumnNo(fh, n$)

Return queried external key column's number.

GetKeyColumnVariable$(fh, n | n$)

Return the queried external key column's variable name. String variables will return the variable with a trailing $.

GetKeyIOList$(fh)

Return table's external key IOList, if any.

GetTableCount( )

Return the total number of tables presently found in 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$; however, you can specify the sep$ to be used.

GetTableListByGroup$(group$, sep$)

Return a list of all tables presently found in the 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$; however, you can specify the sep$ to be used.

GetTableName$(fh)

(Only Supports Numeric Parameter) Return logical table name.

The following only applies to tables with variant records:

GetRecordName$(fh)

Return logical name of the current record type.

GetRecordNo( )

Return numeric value of the currently set record type (what SetRecordNo had been set to).

GetRecordTypes(fh)

Return number of record types for the specified table.

GetVariantInfo(fh)

Return VariantInfo object that contains information about the non-normalized information. This object is static and will be reused on all subsequent calls.

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. (Maximum record number is 36.)

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 an 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/reopened).

Note:
This function may fail due to concurrent access to the table - it requires exclusive use of the table.

AddPassword(fh, pass$, level)

Applies the password and access level to a non-passworded file.

AddTable(obj)

Add new table based on the description supplied by the TableInfo object.

ChangePassword(fh, orig_pass$, new_pass$, level)

Updates the file with the modified password and access level. If no new password is given, then the original password will be used.

DropColumn(fh, n | n$)

DropKeyColumn(fh, n | n$)

Deletes the specified column from that table. In the case of a physical file, the file will be recreated, and all the data for that column will be lost. In addition, all index information containing this column will be adjusted.

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/reopened).

Note:
This function may fail due to concurrent access to the table - it requires exclusive use of the table.

DropTable(n$)

Deletes the table and all its related information.

Merge(srcddf$ | srcchn, srctbl$, desddf$ | deschn, mergeopt$)

Merge(srcddf$ | srcchn, desddf$ | deschn, mergeopt$)

Merge table definitions from one set of dictionary files (providex.ddf and providex.dde) to another.

RemovePassword(fh, pass$)

Removes given password from the file.

RenameColumn(fh, old$, new$)

Rename column.

RenameIndex(fh, old$, new$)

Rename the index.

RenameTable(fh, oldname$)

Renames the table.

UpdateColumn(fh, obj)

Update specified column with information supplied by the ColumnInfo object.

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/reopened).

Note:
This function may fail due to concurrent access to the table - it requires exclusive use of the table.

UpdateTable(obj)

Update table information based on the information supplied by the TableInfo object.

UpdateVariant(fh, obj)

Updates the variant information for fh with the information supplied by the VariantInfo object.

Idxinfo - Provides 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 n. If n 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 an 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.

GetValues$(iol_obj$)

Return value of queried property or properties as a data record.

Example:

iol_obj$ = CPL("iolistname$")
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.

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$

SetValues(val$, iol_obj$)

Set object's properties to the value or values specified.

iol_obj$ = CPL("iolistname$, attributes$")
val$ = "newname" + SEP + "Enter your Name"

Object'SetValues(val$, iol_obj$) will return 1 if passed, 0 if failed.

Idxinfo Properties

Description

Attributes$

Attribute string for current index:

ColumnAttr$

Attribute string for current segment:

For Auto Increment:

ColumnName$

Name of column based on current segment.

ColumnNullCharacter$

ASCII hexadecimal value. The default is a null byte ($00$).

ColumnOffset

Offset into current segment's column (zero-based).

ColumnWidth

Width to use of current segment's column (zero indicates full column).

IsExternal

(PVX-Hosted DB Only) Boolean indicator for external key.

IsUnique

Boolean indicator for unique index.

Name$

Name of the index.

NullCharacter$

ASCII hexadecimal value. The default is a null byte ($00$).

NullSuppress

(PVX Only) Suppresses index if key is completely null.

SegCount

(Read Only) Number of segments for index.

SegNo

Current segment number being referenced.

Colinfo - Provides a common definition of a data element and provides for common data validation rules

Colinfo Methods

Description

GetValues$(iol_obj$)

Return value of queried property or properties as a data record:

iol_obj$ = CPL("iolistname$")
X$ = Object'GetValues(iol_obj$)
X$ = Value found in name$ for this object

InitValues( )

Initializes this 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("iolistname$, 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 (PxPlus) 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

(Read Only) Length required to allow user to input this data.

InternalFormat$

Internal format as used by PxPlus. Valid formats include:

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.

IsReadOnly

Boolean to indicate that this column is designated as read only or locked.

(The IsReadOnly property was added in PxPlus 2021.)

IsRequired

Boolean to indicate that the data in this column is mandatory (not null).

IsUpperCase

Boolean to indicate that the data should always be uppercase.

Length

Length of data in total bytes/digits.

Name$

Name of the column.

Notes$

General programmer notes.

Occurs$

Occurs definition.

ODBCOption$

ODBC presentation:

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$

(Read Only) Name of the table to which this column belongs.

Tag$

User defined information.

Type$

Type of data:

Validation$

Validation rules; comma-separated values and/or ranges.

Variable$

(Read Only) Variable name to be used to store data. Name plus $ if string.

ViewsExpression$

Used to store column expression during Views processing.

Tblinfo - Provides information about the file

Tblinfo Methods

Description

GetValues$(iol_obj$)

Return value of queried property or properties as a data record:

iol_obj$ = CPL("iolistname$")
X$ = Object'GetValues(iol_obj$)
X$ = Value found in name$ for this object

InitValues( )

Initialize this object's properties. Strings are set to null, numeric and Booleans are set to zero.

SetValues(val$, iol_obj$)

Set object's properties to the value or values specified:

iol_obj$ = CPL("iolistname$, description$")
val$ = "newname"+SEP+"Enter your Name"

Object'SetValues(val$, iol_obj$) will return 1 if successful, 0 if failed.

Tblinfo Properties

Description

BlockSize$

Specify a block size when creating a data file.

Null or 'Default' = Let language determine the most suitable size. Valid ranges are:

Description$

Short description of the table contents.

Extension$

(Read Only) Variable name used to store data. Name plus $ if string.

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.

IsDataCompression

Boolean indicator for data compression.

IsExtendedRecords

Boolean indicator for records larger than 32 KB.

IsZlibCompression

(Applies to VLR and EFF Files Only) Boolean indicator for data compression.

LastChangeBy$

(Read Only) User ID.

LastChangeDate$

(Read Only) Date and User ID in the format: CCYY/MM/DD HH:MM:SS-USERID.

Name$

Logical file name.

Notes$

Provide free-form area for recording notes on the table and its use (limited to 1024 characters).

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:

File Types - Allows you to directly set these options; e.g. obj'Options$="2".

You may only select one of these options:

PhysicalFile$

The physical file path and file name 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.

Separator$

The field separator for your file. Default is the standard PxPlus separator $8A$.

Variantinfo - Provides 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 specified by num. If num is null, then a new condition segment will be added at the end.

Your variant object's ConditionSegment will be positioned to the new segment added.

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.

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$

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.

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.

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$

GetValues$(iol_obj$)

Return value of queried property or properties as a data record:

iol_obj$ = CPL("iolistname$")
X$ = Object'GetValues(iol_obj$)
X$ = Value found in name$ for this object

InitValues( )

Initializes this object's properties. Strings are set to null, numeric and Booleans are set to zero.

SetValues(val$, iol_obj$)

Set object's properties to the value or values specified:

iol_obj$ = CPL("iolistname$, description$")
val$ = "newname"+SEP+"Enter your Name"

Object'SetValues(val$, iol_obj$) will return 1 if passed, 0 if failed.

Variantinfo Properties

Description

ColumnName$

Name of column based on current condition segment.

ConditionCount

(Read Only) Number of condition segments for this non-normalized definition.

ConditionSegment

Current condition being referenced.

FormatCount

(Read Only) Number of format types for this non-normalized definition.

FormatSegment

Current format type being referenced.

Length

Length of data in total bytes/digits.

Name$

Name of the record type.

Offset

Offset into current segment's column (zero-based).

TestCondition$

Condition for this record type.