DataEase Internal Functions

String := GetDBName(Dir,DBID)

Explanation

Dir and DBID are text values.

Given a DOS sub-directory name and a database ID, GetDBName will open the RDRR file associated with the database ID and return the long name of the database. If the sub-directory name is invalid or a database does not exist in the subdirectory with the specified ID, then the function returns a blank value.

Example

To retrieve the long name of database 'R' that is stored in the sub-directory 'C:\DATABASE\TEST', you would use the following formula:

GetDBName("C:\DATABASE\TEST","R") 

To scan a directory for databases, you could use the following procedural code:

define "DBID" text 1 . define "DBName" text 25 .

DBID := "A" .

While DBID <= "Z" do DBName := GetDBName("C:\DATABASE\TEST",DBID) . If DBName not = blank then -- FOUND ONE Message DBName Window . end . DBID := ASCIIChar(Ord(DBID,"")+1) . --CORECDF functions. Increment DBID. end .

Use It For

To build your own database status reports; To scan directories for databases.

Long := GetDeletedRecs(Dir,DBID,FormName)

Explanation

Dir, DBID and FormName are text values.

Given valid DOS sub-directory name(Dir), Database ID (DBID), and form name (FormName), this function will return the number of deleted records in the file (number:long). If any of the parameters is somehow invalid, the function will return a -1 result.

Example

To determine the number of deleted records stored in the form 'Customers' occurring in database 'R' in the DOS sub-directory 'C:\DATABASE\TEST', you would use the following derivation formula:

GetDeletedRecs("C:\DATABASE\TEST","R","Customers")

Use It For

To build your own database status reports; To determine when forms should be reorganized.

Int := GetFieldDataType(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return a number indicating the data type assigned to the field. The number indicates the field's data type according to the following table:

If any of the parameters passed to the function are in any way invalid, the function will return a value of -1.

Example

To retrieve the field type of a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', a derivation formula would look like:

GetFieldDataType("C:\DATABASE\TEST","R","Customers","Balance")

Assuming Balance was a number (Integer, Fixed Point or Float), the value returned would be 3.

Use It For

Constructing your own database status reports; printing custom application documentation.

String := GetFieldDerivationText(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return the field derivation formula, if any, for the field. Note that only the first 255 characters of the formula will be returned; additional characters are discarded. If the parameters are in any way invalid OR if there is no formula for the field, the function will return blank.

Example

A derivation formula to retrieve the field derivation formula for a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldDerivationText("C:\DATABASE\TEST","R","Customers","Balance")

Use It For

Constructing application documentation reports.

Int := GetFieldDispWidth(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return the width (in characters) the field's data will occupy on the screen when formatted for display.

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the formatted display length for a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldDispWidth("C:\DATABASE\TEST","R","Customers","Balance")

Use It For

Creating custom system documentation; import/export/conversion analysis; status reports.

Int := GetFieldEntryStat(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return a value indicating the prevent entry characteristic of the field.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the entry status a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldEntryStat("C:\DATABASE\TEST","R","Customers","Balance")

String:= GetFieldHelpText(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return the field's help text, if any. Note that only the first 255 characters of the help text will be returned; additional characters are discarded. If the parameters are in any way invalid OR if there is no help text for the field, the function will return blank.

Example

A derivation formula to retrieve the field help text for a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldHelpText("C:\DATABASE\TEST","R","Customers","Balance")

Use It For

Constructing application documentation.

String := GetFieldHiLimitText(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return the field high limit formula, if any, for the field. Note that only the first 255 characters of the formula will be returned; additional characters are discarded. If the parameters are in any way invalid OR if there is no formula for the field, the function will return blank.

Example

A derivation formula to retrieve the field high limit formula for a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldHiLimitText("C:\DATABASE\TEST","R","Customers","Balance")

Use It For

Constructing application documentation reports.

Int := GetFieldIndex(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return a number indicating the field's unique, relative field number in the form. If the parameters are in any way invalid the function will return -1.

Example

A derivation formula to retrieve the field index number for a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldIndex("C:\DATABASE\TEST","R","Customers","Balance")

Use It For

Constructing application documentation reports.

Int := GetFieldIndexedStat(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return a value indicating whether or not the field is indexed.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the indexed status of a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldIndexedStat("C:\DATABASE\TEST","R","Customers","Balance")

String := GetFieldLabel(Dir,DBID,FormName,FieldIndex)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a number representing a field index for a field occurring in that form, this function will return the name of the field associated with the index. This is useful for scanning a form for its field names prior to extracting additional field information from the form.

If the parameters are in any way invalid, the function will return a value of blank .

Example

A derivation formula to determine the field name of the fifth field(note that field indexes begin with 0) in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldLabel("C:\DATABASE\TEST","R","Customers",4)

A DQL procedure to scan the field names occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

define "FieldName" text 20 .
define "FieldIndex" number .
FieldName := "X" .
FieldIndex := 0 .
While FieldName not = Blank do
  FieldName := GetFieldLabel("C:\DATABASE\TEST","R","Customers",FieldIndex) .
  Message FieldName .
  FieldIndex := FieldIndex + 1 .
end . 

Use It For

Building custom application documentation by scanning unknown form contents.

String:= GetFieldLoLimitText(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return the field low limit formula, if any, for the field. Note that only the first 255 characters of the formula will be returned; additional characters are discarded. If the parameters are in any way invalid OR if there is no formula for the field, the function will return blank.

Example

A derivation formula to retrieve the field low limit formula for a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldLoLimitText("C:\DATABASE\TEST","R","Customers","Balance")

Use It For

Constructing application documentation reports.

Int:= GetFieldNumericType(Dir,DBID,FormName,FieldName)

Explanation

This function is only valid for fields that return a GetFieldDataType value of 3. Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and the name of a numeric field occurring in that form, this function will return a number indicating the numeric type assigned to the field. The number indicates the field's numeric data type according to the following table:

If any of the parameters passed to the function are in any way invalid, the function will return a value of -1. On Numeric String field types, the value returned will be undefined.

Example

To retrieve the numeric type of a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', a derivation formula would look like:

GetFieldNumericType("C:\DATABASE\TEST","R","Customers","Balance")

Assuming Balance was a number (Integer, Fixed Point or Float), the value returned would be 3.

Use It For

Constructing your own database status reports; printing custom application documentation.

Int := GetFieldOffset(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return a number indicating the field's relative byte offset within each DBM record. If the parameters are in any way invalid, the function will return -1.

Example

A derivation formula to retrieve the field offset for a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldOffset("C:\DATABASE\TEST","R","Customers","Balance")

Use It For

Constructing application documentation reports; determining offsets for writing low-level data access/conversion routines.

Int:= GetFieldRequiredStat(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return a value indicating whether or not the field is flagged as being Required.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the Required status of a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldRequiredStat("C:\DATABASE\TEST","R","Customers","Balance")

Int:= GetFieldUniqueStat(Dir,DBID,FormName,FieldName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will return a value indicating whether or not the field is flagged as being unique.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the unique status of a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFieldUniqueStat("C:\DATABASE\TEST","R","Customers","Balance")

Int:= SetFieldRequired(Dir,DBID,FormName,FieldName,OnOff)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will accept a value in the OnOff parameter indicating whether or not the field is to be flagged as being Required or not required.

The numeric value passed in OnOff may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of 0. A return value of 1 indicates that the function succeeded. This function will not succeed if the form file referenced has not been locked via a call to LockFormFile.

Example

A derivation formula to set the Required attribute of a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST' to 'Required', would appear as:

SetFieldRequired("C:\DATABASE\TEST","R","Customers","Balance",1)

Int:= SetFieldIndexed(Dir,DBID,FormName,FieldName,OnOff)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will accept a value in the OnOff parameter indicating whether or not the field's 'Indexed' attribute is to be turned on or off.

The numeric value passed in OnOff may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of 0. A return value of 1 indicates that the function succeeded. This function will not succeed if the form file referenced has not been locked via a call to LockFormFile.

Example

A derivation formula to set the Indexed attribute of a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST' to 'Indexed', would appear as:

SetFieldIndexed("C:\DATABASE\TEST","R","Customers","Balance",1)

Int:= SetFieldPrevent(Dir,DBID,FormName,FieldName,OnOff)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will accept a value in the OnOff parameter indicating whether or not the field's 'Prevent Entry' attribute is to be turned on or off.

The numeric value passed in OnOff may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of 0. A return value of 1 indicates that the function succeeded. This function will not succeed if the form file referenced has not been locked via a call to LockFormFile.

Note: Use SetFieldVirtual to make a field virtual.

Example

A derivation formula to set the Prevent attribute of a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST' to 'Prevent Entry', would appear as:

SetFieldPrevent("C:\DATABASE\TEST","R","Customers","Balance",1)

Int := SetFieldVirtual(Dir,DBID,FormName,FieldName,OnOff)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, a form in that database and a field occurring in that form, this function will accept a value in the OnOff parameter indicating whether or not the field's 'Virtual' attribute is to be turned on or off.

The numeric value passed in OnOff may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of 0. A return value of 1 indicates that the function succeeded. This function will not succeed if the form file referenced has not been locked via a call to LockFormFile.

Note: This function automatically sets the field's 'Prevent Entry' attribute to true if OnOff is 1. Likewise, 'Prevent Entry' is cleared if this function is used to turn off a field's virtual attribute.

Example

A derivation formula to set the Virtual attribute of a field named 'Balance' occurring in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST' to 'Prevent Entry & Virtual', would appear as:

SetFieldVirtual("C:\DATABASE\TEST","R","Customers","Balance",1)

Int := GetFormAutoTab(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating how the 'Suppress Auto Tab after Field Fills' question is answered in the form's property dialogue.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the suppress auto tab property of a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormAutoTab("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation.

Int := GetFormClearAfterF2(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating how the 'Clear Form After Entering a Record' question is answered in the form's property dialogue.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the clear form property of a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormClearAfterF2("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation.

Int := GetFormDefaultView(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the default view property for the form.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the default view property of a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormDefaultView("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation.

Int := GetFormDeleteSecurity(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the minimum user security level required to delete records from this form.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the minimum security level required to delete records from a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormDeleteSecurity("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation. Auditing application security.

Int := GetFormDEVersion(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the version of DataEase used to create the form definition.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

NOTE: Despite the ability of this function to read other types of DE form definitions, DE45SYS is intended for use on version 4.5x databases only. Using DE45SYS on any other version(s) of DataEase databases is unpredictable.

Example

A derivation formula to determine the DataEase version used to create a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormDEVersion("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation.

String := GetFormDOSName(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return the DOS name of the form definition file. This allows you to quickly identify which DOS files belong to which forms.

If the parameters are in any way invalid, the function will return a value of blank .

Example

A derivation formula to determine the DOS filename form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormDOSName("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation.

Int := GetFormEncryptStatus(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the encryption property assigned to the form.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the encryption property of a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormEncryptStatus("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation. Auditing application security.

Int := GetFormEngineType(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the database engine type for the form. This information is only pertinent to DataEase SQL implementations.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the engine type property of a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormEngineType("C:\DATABASE\TEST","R","Customers","Balance")

Use It For

Generating custom application documentation.

Int := GetFormEnterSecurity(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the minimum user security level required to enter records in this form.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the minimum security level required to enter records in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormEnterSecurity("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation. Auditing application security.

Long := GetFormFlags(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the internal DataEase flags associated with the form.

The form flags are bit mapped values and, therefore, require the use of the LogAnd function (BITSCDF) to properly decode. Using LogAnd and assuming the result of GetFormFlags is stored in a variable called X, the values may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Some common values returned by GetFormFlags:

Example

A derivation formula to determine the form flags for a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormFlags("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation. Auditing application security. Technical application development.

String := GetFormHelpText(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return the form's help text, if any. Note that only the first 255 characters of the help text will be returned; additional characters are discarded. If the parameters are in any way invalid OR if there is no help text for the form, the function will return blank.

Example

A derivation formula to retrieve the form help text for a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormHelpText("C:\DATABASE\TEST","R","Customers")

Use It For

Constructing application documentation.

Int := GetFormModSecurity(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the minimum user security level required to modify records in this form.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the minimum security level required to modify records in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormModSecurity("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation. Auditing application security.

Long := GetFormRecLength(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return the number of bytes occupied by each record in the form.

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the record length for a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormRecLength("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation. Technical application development.

String := GetFormNameByNumber(Dir,DBID,RecNum)

Explanation

This function is intended to be used with the ScanRDRR function to scan a form directory from beginning to end, retrieving information about each active form described in the directory. Given a DOS subdirectory name, the database ID identifying an application residing in that directory, and a record number indicating a specific record number in the application's forms directory (RDRRxxxx.DBM), this function will return the name of the form associated with that record. You may then use the name to retrieve additional information about the form and its fields.

ScanRDRR iteratively returns the record number of the 'next' active record in a database's forms directory.

If the parameters passed to the function are in any way invalid, the function will return a blank value.

Example

A derivation formula to determine the form name stored in the fifth record in the forms directory of a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormNameByNumber("C:\DATABASE\TEST","R",5)

A procedure to scan an application's forms directory could be written as:

define "LastSeen" number .
define "X" number.
Define "FormName" text 20 .


LastSeen := 0 .
LastSeen := ScanRDRR("C:\DATABASE\TEST","R",LastSeen) .
While LastSeen not= -1 do
   FormName := GetFormNameByNumber("C:\DATABASE\TEST","R",LastSeen) .
   Message FormName Window .
   LastSeen := ScanRDRR("C:\DATABASE\TEST","R",LastSeen) .
end . -- While

Use It For

Generating custom application documentation. Technical application development.

Int := GetFormRederiveCurrents(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the 'Preserve old CURRENT DATE, etc. on modify?' property for the form.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the default re-derivation property of a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormRederiveCurrents("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation.

Long := GetFormStatus(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the active or deleted status of the specified form.

The value of GetFormStatus may be interpreted as follows:

Example

A derivation formula to determine the status of a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormStatus("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation. Auditing application security. Technical application development.

Int := GetFormViewSecurity(Dir,DBID,FormName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return a value indicating the minimum user security level required to view records in this form.

The numeric value returned may be interpreted as follows:

If the parameters are in any way invalid, the function will return a value of -1 .

Example

A derivation formula to determine the minimum security level required to view records in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetFormViewSecurity("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation. Auditing application security.

String := GetJustDOSPrefix(Dir,DBID,FormName)

Explanation

This function is similar to GetFormDOSName, except, given valid names of a DOS sub-directory, a DataEase database ID, and a form in that database, this function will return the DOS name of the form definition file WITHOUT AN EXTENSION. The prefix is the same for all DOS files associated with a form, such as the index (.I*), data (.DBM) and error (.E*) files. This allows you to quickly identify which DOS files belong to which forms.

If the parameters are in any way invalid, the function will return a value of blank .

Example

A derivation formula to determine the DOS prefix for a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetJustDOSPrefix("C:\DATABASE\TEST","R","Customers")

Use It For

Generating custom application documentation.

Int := GetNumFields(Dir,DBID,FormName)

Explanation

This function will return the number of fields defined in a DataEase form.

Example

A derivation formula to determine the number of fields defined in a form called 'Customers' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetNumFields("C:\DATABASE\TEST","R","Customers")

A DQL procedure to scan a form for all of its fields could use GetNumFields as follows:

Define "Fields" number .
Define "FieldCount" number .
Define "FieldName" text 20 .


Fields := GetNumFields("C:\DATABASE\TEST","R","Customers") .
FieldCount := 0 .


While FieldCount < Fields do
  FieldName := GetFieldLabel("C:\DATABASE\TEST","R",FieldCount) .
  message FieldName .
  FieldCount := FieldCount + 1 .
end .

Use It For

Custom application documentation, scanning forms, technical applications.

Long := GetNumForms(Dir,DBID)

Explanation

This function will return the number of active forms defined in a DataEase application.

Example

A derivation formula to determine the number of forms defined in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetNumForms("C:\DATABASE\TEST","R")

Use It For

Custom application documentation, technical applications.

Long := GetNumRecs(Dir,DBID,FormName)

Explanation

Dir, DBID and FormName are text values.

Given valid DOS sub-directory name(Dir), Database ID (DBID), and form name (FormName), this function will return the total number of records, including those marked deleted, in the file (number:long). If any of the parameters is somehow invalid, the function will return a -1 result.

Example

To determine the total number of records stored in the form 'Customers' occurring in database 'R' in the DOS sub-directory 'C:\DATABASE\TEST', you would use the following derivation formula:

GetNumRecs("C:\DATABASE\TEST","R","Customers")

Use It For

To build your own database status reports; To determine when forms should be reorganized by determining the percentage of deleted records..

String := GetProcDOSName(Dir,DBID,ProcName)

Explanation

Given valid names of a DOS sub-directory, a DataEase database Ididentifying a database in that directory, and the name of a procedure defined in the database, this function will return the name of the DOS file that holds the procedure.

If the parameters are in any way invalid, the function will return a value of blank .

Example

A derivation formula to determine the DOS filename for a procedure called 'Customer List' occurring in a database identified as 'R' occurring in the DOS sub-directory 'C:\DATABASE\TEST', would appear as:

GetProcDOSName("C:\DATABASE\TEST","R","Customer List")

Use It For

Generating custom application documentation. Technical application development.

Long := GetTotalDBSize(Dir,DBID)

Explanation

This function computes the total number of bytes of disk storage consumed by the database specified.

Example

A derivation to compute the total number of bytes of disk storage used by database 'R' stored in the DOS sub-directory 'C:\DATABASE\TEST' would appear as follows:

GetTotalDBSize("C:\DATABASE\TEST","R")

Determining storage usage, custom management reports, pre-backup requirements planning.

Long := LockFormFile(Dir,DBID,FormName)

Explanation

This function is used to signal the DE45SYS CDF library that your procedure intends to gather multiple items of information from a form file using repeated calls into the CDF library. Normally, each call to a DE45SYS function that retrieves internal form information opens the form definition file, initializes internal tables, retrieves the desired data, and closes the file. If several calls are to be made to the same form, this results in a severe performance penalty. LockFormFile opens the form file in question and initializes the internal table, so that each subsequent call to the library for this form's information can skip these steps.

While a lock is in place, the database application referenced by the lock cannot be active. That is no users can actually be using the application.

It is imperative that any use of LockFormFile have a corresponding call to ReleaseFormFile, which closes the form file.

Performance is improved about 4x when using LockFormFile. Please note that LockFormFile is effective only for functions that return field information or form property information; functions that return RDRR-specific information are not affected.

Example

A DQL procedure to retrieve multiple field definition items from a form could be constructed:

define "X" number .
define "S" text 255 .


X := LockFormFile("C:\DATABASE\TEST","R","Customers") .


X := GetFormRederiveCurrents("C:\DATABASE\TEST","R","Customers") .
X := GetFormAutoTab("C:\DATABASE\TEST","R","Customers") .
X :=GetFormClearAfterF2("C:\DATABASE\TEST","R","Customers") .


X := ReleaseFormFile("C:\DATABASE\TEST","R","Customers") .

Use It For

To improve the performance of your own custom management applications. To use any of the Set functions.

Int := ReleaseFormFile(Dir,DBID,FormName)

See LockFormFile

Long := ScanRDRR(Dir,DBID,LastSeen)

Explanation

Given valid names of a DOS sub-directory, a DataEase database ID, and a value for LastSeen (see below), this function is used to iteratively scan the application's form directory and returns the record number pointing to the next form directory record. GetFormNameByNumber will return the name of an RDRR entry associated with the record identified by the result returned by ScanRDRR.

'LastSeen' tells ScanRDRR at which record number the search should begin. ScanRDRR will return the record number of the next active RDRR entry beyond LastSeen. To begin a search at the start of the RDRR file, LastSeen should initially be set to 0. Then, assign LastSeen the result of ScanRDRR until LastSeen is equal to -1:

LastSeen := ScanRDRR(DirName, DBID, LastSeen).
If LastSeen= -1 then    -- End of file reached

If the parameters are in any way invalid, or there are no more active records in the RDRR file, the function will return a value of -1 .

Example

A derivation formula to get the record number of the first active form record from the forms directory of database 'R' in DOS subdirectory 'C:\DATABASE\TEST' would appear as :

ScanRDRR("C:\DATABASE\TEST","R",0)

A DQL procedure that scans a database's entire forms directory could be written as:

define "LastSeen" number .
define "X" number.
Define "FormName" text 20 .


LastSeen := 0 .
LastSeen := ScanRDRR("C:\DATABASE\TEST","R",LastSeen) .
While LastSeen not= -1 do
   FormName := GetFormNameByNumber("C:\DATABASE\TEST","R",LastSeen) .
   Message FormName Window .
   LastSeen := ScanRDRR("C:\DATABASE\TEST","R",LastSeen) .
end . -- While

Use It For

Generating custom application documentation. Technical application development.

Int := UndeleteAllRecords(Dir,DBID,FormName)

Explanation

This function is used to mark all of a form's records as active. NOTE: YOU MUST PERFORM A FORM REORGANIZATION ON THE SUBJECT FORM AFTER PERFORMING THIS FUNCTION in order to maintain database integrity. Moreover, UndeleteAllRecords can ONLY recover records deleted since the last form reorganization occurred. Records marked as deleted are automatically purged during a form reorganization and are, therefore, unrecoverable.

This function is provided as a recovery mechanism for records deleted in error or due to data corruption.

The function returns a value of -1 on failure.

Example

To undelete all records in a form called 'Customers', in database 'R' occurring in DOS subdirectory 'C:\DATABASE\TEST', a derivation formula would appear as:

UndeleteAllRecords("C:\DATABASE\TEST","R","Customers") 

Use It For

Disaster recovery.

Long := CalcFileChecksum(Filename : string)

Explanation

This function is used to calculate a CRC32 checksum value for the named DOS file. A CRC32 checksum is a 32-bit value that is derived by examining each byte in a file. The value is indicative of the file's content. This function can be used to compare file versions over time to see if a file's contents have been changed.

Example

A derivation to calculate the CRC32 checksum value for the file 'C:\DATABASE\TEST\CUSTBAAA.DBA':

CalcFileChecksum("C:\DATABASE\TEST\CUSTBAAA.DBA")

A procedure to calculate the checksum value of a DataEase form could include the following section:

FormFileName := GetFormDOSName("C:\DATABASE\TEST",'R',"Customers") .
FullPathName := JT(DatabaseDir,"\",FormFileName,"","") .
FormChecksum := CalcFileChecksum(FullPathName) .

Use It For

You can use CalcFileChecksum to craft an application that checks to see which forms and procedures in an application have been changed and will automatically build a DataEase install (DIN) file for installing the updated files at your client sites. Create a database of forms and procedures, use the functions in this library to record the checksums of each form and procedure definition. Then, after modifications have been made, make another pass against the updated application and, finally, compare the checksums from the second pass with those calculated from the first pass to determine what's been changed. Of course, you will want to account for new and deleted forms and procedures as well as relationship and menu configurations.

For a turnkey version of just such an application, we recommend that you purchase ZZ Does It from Witco Resources ( 203-838-9890) for $179 (USD).

Int := CreateImportFile( ImportFileName, SourceFileName, DestinationForm, ImportFormat, UpdateType, Order, FieldSeparator, RecordSeparator, FixedPoint )

Explanation

This function is used to create DataEase Import specifications 'on-the-fly'. Each of the input parameters correspondents to a field entry requested when designing an import specification interactively and are interpreted as follows:

ImportFileName - This is the name of the file the new import will be stored in (usually with a DBI extension). If a file already exists under this name, it will be overwritten.

SourceFileName - This is the name of the file that contains the data to beimported.

DestinationForm - This is the name of the form into which the imported records will be written.

Import Format - indicates the format type of the source file. Set the value of ImportFormat as follows:

UpdateType - Indicates how existing records in the Destination form will be affected by the import. Set this value as follows:

Order - Indicates the ordering of fields in the source file. Set this value as follows:

FieldSeparator - This is the ASCII code of the character to be interpreted as a field separator in Variable-Length imports. THIS IS A NUMERIC VALUE. Using a numeric ASCII code allows non-typeable characters (such as Tab) to be specified as field separators. To use the code of a typeable character, use the Val function (i.e.Val("T"))

RecordSeparator - This is the ASCII code of the character to be interpreted as a record separator in Variable-Length imports. THIS IS A NUMERIC VALUE. Using a numeric ASCII code allows non-typeable characters (such as Tab) to be specified as separators. To use the code of a typeable character, use the Val function (i.e.Val("T"))

FixedPoint - This value indicates whether the import should automatically insert a decimal point into fixed-point field data and should be one of the following:

String := GetImpDest( Filename )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and returns the name of the DataEase form specified as the target of the import procedure.

Example

To determine the target form of an import called 'UPDATE.DBI' stored in the current directory:

GetImpDest("UPDATE.DBI")

'Master Inventory' is an example of a value that could be returned by such a reference.

Use It For

Documenting current procedures.

int := SetImpDest( Filename, DataEaseFormName )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and the name of a DataEase form and alters the import specification's target form selection to match 'DataEaseFormName'. The function returns a value of 0 on success, non-zero error code on failure.

Example

To set the target form name in an import specification file called 'UPDATE.DBI' stored in the current directory to 'Item Master File':

SetImpDest("UPDATE.DBI", "Item Master File")

'Master Inventory' is an example of a value that could be returned by such a reference.

Use It For

Dynamically modifying an import specification just prior to execution.

String := GetImpFixedPoint( Filename )

Explanation

This function queries an existing import specification file and returns the setting of the import's 'Insert decimal point for fixed-point fields?' question. The value returned will be one of the following:

Example

To determine whether the import specification 'UPDATE.DBI' will insert a decimal point in fixed-point field data:

GetImpFixedPoint("UPDATE.DBI")

If the value returned is 0, then no decimal point is inserted. If the value is 1, then a decimal point is inserted during the import process.

Use It For

Documenting current procedures.

String := SetImpFixedPoint( Filename, Setting )

Explanation

This function sets an existing import specification's 'Insert decimal point for fixed-point fields?' setting as specified by the value of Setting, which must be one of the following:

Example

To cause the import specification 'UPDATE.DBI' to automatically insert a decimal point in fixed-point field data:

SetImpFixedPoint("UPDATE.DBI", 1)

Use It For

Dynamically building import specifications.

String := GetImpSrc( Filename )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and returns the name of the DOS file specified as the source of the imported data.

Example

To determine the source file of an import called 'UPDATE.DBI' stored in the current directory:

GetImpSrc("UPDATE.DBI")

'C:\PARTS\TXNS.DAT' is an example of a value that could be returned by such a reference.

Use It For

Documenting current procedures. Checking for a file's presence before attempting an import, etc.

Int := SetImpSrc( Filename, SourceFileName )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and the full pathname representing an import source file and modifies the import specification's source file field accordingly. Function will return a value of 0 if successful.

Example

To set the source file of an import called 'UPDATE.DBI' stored in the current directory to 'C:\TXNS\PARTS.IMP':

SetImpSrc("UPDATE.DBI","C:\TXNS\PARTS.IMP"))

Use It For

Modifying an import dynamically before execution.

Int := GetRecSep( Filename )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and returns the ASCII code value of the character specified as the record separator in the specification. Note that this is only valid for import specifications defined as having a 'variable length' source file . The value returned is the ASCII code of the character used to break records and will always be either a printable character or a carriage-return (13) for imports defined with DataEase' interactive import definition editor. Note that it is possible to define any character for a delimiter using CreateImportFile (see above).

Example

To determine the record delimiter of a variable-length import called 'UPDATE.DBI' stored in the current directory:

GetRecSep("UPDATE.DBI")

To convert the ASCII code to a printable character (if it IS printable):

Char(GetRecSep("UPDATE.DBI"))

Note you can provide some sort of test to see if a character is printable or not if you are building internal application documentation.

13 is an example of a value that could be returned by such a reference.

Use It For

Documenting current procedures.

Int := SetRecSep( Filename, ASCIICharacterValue )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and an ASCII code value for the character to be specified as the record separator. Note that this is only valid for import specifications defined as having a 'variable length' source file .

The value supplied in ASCIICharacterValue should be a numeric ASCII code of the character used to separate records in the import source file. Note that it is possible to define any possible character for a record separator delimiter.

To use a typeable ASCII character code, we recommend that you use the supplied 'Val' function to convert the symbolic character to its ASCII code equivalent.

Example

To set the record delimiter of a variable-length import called 'UPDATE.DBI' stored in the current directory to '|' :

SetRecSep("UPDATE.DBI", Val("|"))

Use It For

Modifying import specifications as required.

Int := GetFldSep( Filename )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and returns the ASCII code value of the character specified as the field separator in the specification. Note that this is only valid for import specifications defined as having a 'variable length' source file . The value returned is the ASCII code of the character used to break fields and will always be either a printable character or a carriage-return (13) for imports defined with DataEase' interactive import definition editor. Note that it is possible to define any character for a delimiter using CreateImportFile (see above).

Example

To determine the record delimiter of a variable-length import called 'UPDATE.DBI' stored in the current directory:

GetFldSep("UPDATE.DBI")

To convert the ASCII code to a printable character (if it IS printable):

Char(GetFldSep("UPDATE.DBI"))

Note you can provide some sort of test to see if a character is printable or not if you are building internal application documentation.

13 is an example of a value that could be returned by such a reference.

Use It For

Documenting current procedures.

Int := SetFldSep( Filename, ASCIICharacterValue )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and an ASCII code value for the character to be specified as the field separator. Note that this is only valid for import specifications defined as having a 'variable length' source file .

The value supplied in ASCIICharacterValue should be a numeric ASCII code of the character used to separate fields in the import source file. Note that it is possible to define any possible character for a record separator delimiter.

To use a typeable ASCII character code, we recommend that you use the supplied 'Val' function to convert the symbolic character to its ASCII code equivalent.

Example

To set the field delimiter of a variable-length import called 'UPDATE.DBI' stored in the current directory to '|':

SetFldSep("UPDATE.DBI", Val("|"))

Use It For

Modifying import specifications as required.

Int := GetFldOrder( Filename )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and returns a numeric value that indicates the 'By Field Name' or 'By Field Order' choice setting as described in the import file. Note that this is only valid with certain import specifications.

The value returned will be one of the following:

Example

To determine the field order setting an import called 'UPDATE.DBI' stored in the current directory:

GetFldOrder("UPDATE.DBI")

Use It For

Documenting current import procedures.

Int := SetFldOrder( Filename, FieldOrderChoice )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and a numeric value representing a field order choice as described below and modifies the import specification's field order setting accordingly. Note that this is only valid with certain import specifications.

The possible values to be provided in FieldOrderChoice should be one of the following:

Example

To modify the field order setting in an import called 'UPDATE.DBI' stored in the current directory to 'By Field Name':

SetFldOrder("UPDATE.DBI",1)

Use It For

Modifying import specifications from within a procedure or field derivation.

Int := GetImpFormat( Filename )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and returns a numeric value that indicates which of the possible source file format selections are defined for the import. Note that this is only valid with certain import specifications.

The value returned will be one of the following:

Example

To determine the source file format in an import specification called 'UPDATE.DBI' stored in the current directory:

GetImpFormat("UPDATE.DBI")

Use It For

Documenting and reporting on current import procedures.

Int := SetImpFormat( Filename, SourceFormatValue )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and a value representing a valid source file format and sets the specification's file format to match. Note that thisis only valid with certain import specifications.

SourceFormatValue should be set to one of the following:

Example

To set the source file format in an import specification called 'UPDATE.DBI' stored in the current directory to 'Variable-Length':

SetImpFormat("UPDATE.DBI",5)

Use It For

Modifying import procedures dynamically.

Int := GetImpUpdate( Filename )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and returns a value representing the choice of updating options selected for the specification.

On success, the function will return one of the following values. If the import specification is not found, -1 will be returned:

Example

To retrieve the update choice in an import specification called 'UPDATE.DBI' stored in the current directory:

GetImpUpdate("UPDATE.DBI")

Use It For

Documenting import specifications.

Int := SetImpUpdate( Filename, UpdateChoiceValue )

Explanation

This function accepts the full path name of an existing import specification (including its extension) and a value representing a choice of updating options and sets the specification's update option field.

UpdateChoiceValue should be set to one of the following:

Example

To set the source update choice in an import specification called 'UPDATE.DBI' stored in the current directory to 'Update Matching':

SetImpUpdate("UPDATE.DBI",2)

Use It For

Modifying import procedures dynamically.