Core Function Reference

Int := FaxPCLFile(
FilenameToFax,
ActivityLogFile,
FontDirectory(required),
PhoneNumber,
StationID,
MessageText,
ComPort#,
BaudRate,
FaxModemType)

Explanation

This function allows you to fax HP PCL format files directly from DataEase. This means that you can use DataEase to create a PCL format file - by printing a report to disk using a HP Laserjet Printer definition - that you can then transmit using a fax modem, all from within DataEase.

To use FaxPCLFile, you must have a Class 1, Class 2 or Intel CAS-compatible fax modem installed in your computer. Please consult your fax modem manual to determine your modem's capabilities.

FaxPCLFile opens the file you specify, converts it to its own generic fax format (.APF) and then transmits the file using the communication parameters you specify. As part of the conversion process, FaxPCLFile must have access to Hewlett-Packard bitmapped soft font files. We have included a minimum number of these font files with HandTools which should be sufficient for most general-purpose needs. If you have special font requirements, then you will need to supply the HP bitmap font you require in this directory. Be sure to rename the font file such that it has a .FNT extension, since *.FNT is the mask used to scan and download fonts from the specified font directory.

Note your fax files may contain bitmapped graphic images as well as text.

StationID and MessageText will appear in the top margin of your faxed pages along with page number information.

The ActivityLogFile specifies the name of a file that will be used to log session activity. If you want to monitor the information on the screen, you may specify 'CON:' as the filename. If you want to discard the log information, simply specify blank for ActivityLogFile.

The PhoneNumber is what is passed to the modem for dialing and should contain any prefix digits, etc required to successfully dial the number.

ComPort# is the COM port on which your fax modem is installed. 1=COM1:, 2=COM2, etc.

BaudRate is the baud rate at which your fax modem communicates with your computer.

FaxModemType is one of the following:

Consult your fax modem manufacturer's specifications for details.

Example

Suppose you ('ABC Company') have a procedure that prints a letter to the disk file 'OPENITEM.PRN' specifying an HP Laserjet printer definition that you wish to fax to a recipient at 214-555-8822. Further, you want to monitor the progress of the call on the screen, you have a Class 2 14.4/9600 fax modem installed on COM2, your font files are installed in 'C:\FONTS' and your phone number is 214-555-1234, which you will use as a station ID. You could write a control procedure as follows:

define "X" number .


run procedure "Print Item" . -- Create OPENITEM.PRN
X := FaxPCLFile( "OPENITEM.PRN", "CON:", "C:\FONTS", "9,1-214-555-8822",
               "214-555-1234", "ABC Company", 2, 14400, 2) .


IF X not = 0 then
  Message "There was an error" window .
end .

Int := DialNumber( ComPort#, BaudRate, PhoneNumber)

Explanation

DialNumber is used to dial a voice phone number with your PCs Hayes-compatible modem. After the PC dials the requested number, you may pick up the receiver on a phone attached to the 'Phone' jack on the modem and speak to the called party.

When the number is dialed, a message window is displayed as follows:

As soon as the modem has finished dialing the phone number (which should be audible through the modem's speaker), the user may pick up the receiver of a phone connected to the 'phone' jack of the modem. Pressing any key causes the modem to be switched to voice mode and the user may then carry on a conversation with the called party.

Port is the com port number of the attached modem (1=COM1, 2=COM2, etc). Baud Rate is a valid baud rate setting for your modem, usually between 110 and 115,200. Phone number is a string representing the phone number. You may embed standard Hayes control characters in the phone number string (',' for pause, etc. See the manual accompanying your modem for more details).

If the CDF encounters an error and fails, it will return a non-zero error code.

Example

To dial a phone number stored in the field 'ContactPhone' in the current form, a derivation might be written as:

if (Call="YES", DialNumber(2,14400,ContactPhone),Blank)

Which would cause the contact's phone number to be dialed any time the 'Call' field was changed to a value of 'YES'.

Use It For

Autodialing.

String := JT(String1, String2, String3, String4, String5) .

Explanation

Conveniently joins up to 5 text strings together with a single function call. Eliminates the need for multiple JoinText calls.

Example

To concatenate "Mr. ", "John", " Doe" together into one string "Mr. John Doe":

JT("Mr. ", "John", " Doe","","")

Use It For

Relief from cramping fingers

String := HTUnique(Filename)

Explanation

HTUnique opens Filename - which it expects to contain a single line representing a number - in exclusive mode, increments the number found by one, and returns the incremented value back to your formula. The purpose of HTUnique is to produce numbers that are guaranteed to be unique in multi-user environments. Such numbers are most often used to produce primary key values for records in a mult-user application. DataEase' native sequence from is inappropriate for such use in multi-user environments.

Note that SHARE.EXE must be loaded for HTUnique to function properly. Use HTCreateControl or a text editor to create Filename initially.

Long := HTUniqueNum(Filename)

Same as HTUnique except that the value returned is a long integer. See HTUnique.

String := HTCreateControl(Filename, InitialValue)

Explanation

This function creates a file and initializes it to contain InitialValue for use by HTUnique. Note that if Filename already exists it will be overwritten.

String := HTSetUniqueNum(Filename, Value)

Explanation

This function performs essentially the same function as HTCreateControl.

String := FormatNum(Mask, Value)

Explanation

This function formats a numeric value according to formattiong codes passed to in the text parameter Mask. FormatNum is useful for preserving the format of a numeric string or a dollar value when it appears in a JoinText function or when you wish to alter or preserve the format when using CRTWrite etc.

Mask may contain any combination of normal characters as well as a sequence of the special characters [# * @ $ - + , .] FormatNum will format Value according to Mask. The text returned is right-justified in the mask field, decimals are rounded if they exceed the allotted decimal digits, and if the number is too large to fit, it is filled with asterisks ala Lotus.

Special characters are interpreted as:

(#)

A digit position if mask contains no * or @ characters, unused digits are returned as blanks. If mask contains no sign positions (+ or -) and the number is negative, a floating minus sign is returned.

FormatNum("Figure: ####", 34.567) returns 'Figure: 35'
FormatNum("####.##", -12.3) returns ' -12.30'
FormatNum("##.##", 1000.0 returns '**.**'

(*)

A digit position. Unused positions are returned as asterisks instead of blanks. The * need only occur once in Mask to activate this effect. A sign will not be returned unless Mask also contains a + or a - .

FormatNum("*##.#", 4.567) returns '**4.57'

(@)

Similar to "*" except that unused digit positions are returned as zeroes.

($)

A digit position. A floating dollar sign is returned in front of the number.

(-)

If the number is negative, a minus sign will be returned at that position.

(+)

The sign of the number is always returned.

FormatNum("+###.##", 1.2) returns '+ 1.20'
FormatNum("*$####.##", -12.34) returns '***12.34-'
>

(, or .)

A decimal or separator comma or period. The role of the comma or period as a separator or decimal point is determined by the LAST such character appearing in mask, which determines the decimal point character for the function:

FormatNum("##,###,###.##", 12345678.91) returns '12,345,678.91'
FormatNum("$#.###.###,##",-12345.6) returns ' -$12.345,60'

NOTE: FormatNum ("###,###,###", 1000.0) returns 1,000,000 NOT 1,000 ! The last comma or period in Mask determines the decimal character ( in this case ','). To get ' 1,000', use FormatNum("###,###,###.", 1000.0).

String := FindFirstDirEntry(SearchFor, Attributes, Trigger)

Explanation-

Given a file specification to search for (which may include wildcards) and an attribute mask, this function returns the name of the file or subdirectory that matches the specification. If no matching files are found or the specification is invalid, then an empty string is returned. Attributes are specified as follows :

   1   = Read-Only
   2   = Hidden
   4   = System
   8   = Volume
   16  = Subdirectory
   32  = Archive bit     

1+2+4+16

To specify normal files only, use 0. To find any directory entry, use 31.

To search for the occurrence of a specific, normal (not a directory, not hidden, not system) file, set SearchFor to the complete pathname and set attributes to 0. If the file is found, its name (just its name, not its pathname) is returned.

  If FindFirstDirEntry("C:\AUTOEXEC.BAT",0,"")=0 then
     message "File Not Found" .
   end

To scan a directory for all file matching a mask that includes wildcards, you may provide a SearchFor embedded with wildcards and call FindFirstDirEntry. If FindFirstDirEntry returns a non-blank filename, repeatedly call FindNextDirEntry for so long as it returns a non-blank filename:

Define "File" text .


File := FindFirstDirEntry("C:\*.*",31,"") . -- All entries
While File Not = blank do
  List Records File .
    File := FindNextDirEntry ("") .
end

The CDF's directory services routines allow you to use DataEase's powerful query and reporting capabilities to provide sophisticated system management reporting and control systems.

String :=FindNextDirEntry(Trigger)

Explanation-

This function should only be used after first successfully calling FindFirstDirEntry. This function continues the search established by FindFirstDirEntry and returns the next filename or subdirectory name matching the specification originally provided to FindFirstDirEntry. Returns empty if no more entries exist or if there was an error.

String := GetFTime(Trigger)

Explanation-

Returns the DOS time stamp in the form of a string "hhmmss" (which is properly converted when assigned to a time field) for the file that was most recently examined by FindFirstDirEntry or FindNextDirEntry. Returns empty if error.

String := GetFDate(Trigger)

Explanation-

Returns the date stamp in the form of a string "mmddyy" (which is properly converted when assigned to a date field) for the file that was most recently examined by FindFirstDirEntry or FindNextDirEntry. Returns empty if error.

Long := GetFSize(Trigger)

Explanation-

Returns the current size of the file that was most recently examined by FindFirstDirEntry or FindNextDirEntry. Returns undefined if error.

Long := GetFAttr(Trigger)

Explanation-

Returns the attributes of the file that was most recently examined by FindFirstDirEntry or FindNextDirEntry. Returns undefined if error. See GetFileAttr below for an explanation of file attributes.

Integer := GetFileAttr(Filename,Trigger)

Explanation-

Given a valid path specification, which may indicate either a file or subdirectory, this function returns the file attribute value for the named directory entry. If the function is successful, the returned value is bit-encoded as described above under the FindFirstDirEntry function.

If there is an error, the function returns -1. Note that any given directory entry may have a combination of attributes. i.e. 7 means the file is a Read-Only, Hidden, System file.

String := SetSysDate(Month, Day, Year, Trigger)

Explanation-

Sets the system BIOS calendar. Returns new setting - unchanged if input invalid.

String := SetSysTime(Hour, Minute, Second, Trigger)

Explanation-

Sets the computer's BIOS System Clock - Returns new setting. Unchanged if input invalid.

Integer := GetMajorDOSVersion(Trigger)

Explanation-

Returns the whole number portion of the currently executing DOS version i.e. DOS 6.22 would return '6'.

Integer := GetMinorDOSVersion(Trigger)

Explanation-

Returns the fractional portion of the currently executing DOS version. i.e. DOS 6.22 would return '22'.

Integer := CopyFile(SourceFilename, DestinationFilename, Trigger)

Explanation-

Copies the source file to the destination file. Returns 0 if successful.

Integer := EraseFile(Filename, Trigger)

Explanation-

Erase the file to the destination. Returns 0 if successful. DOS code if, not.

Integer := RenameFile(OldFilename, NewFileName, Trigger)

Explanation-

Attempts to Rename the existing file specified by Oldfilename to NewFileName. NewFileName should be a valid DOS filename (without a leadin pathname). Returns 0 if successful.

String := GetDefaultDrive(Trigger)

Explanation-

Returns the drive letter of the current default drive. i.e. 'A:', 'B:', 'C:', etc.

String := GetCurDir(DriveLetter, Trigger)

Explanation-

Returns a string containing the full pathname of the current directory the drive specified by DriveLetter i.e. 'C:\DE453'. Leave DriveLetter blank to retrieve the current default drive and directory.

Integer := Ord(Character, Trigger)

Explanation-

Returns ASCII value of Character. I.E. Ord("A","") returns a value of 65, which is the ASCII code for 'A'.

String := ASCIIChar(ASCIICode, Trigger)

Explanation-

Returns the ASCII character representation of numeric code ASCIICode i.e. ASCIIChar(65,"") returns the character 'A'.

Long := GetDiskSize(DriveLetter, Trigger)

Explanation-

Returns the total capacity of the drive specified by DriveLetter (in bytes) Returns -1 if the drive specified is invalid.

Long := GetDiskFree(DriveLetter, Trigger)

Explanation-

Returns the total number of bytes free on the drive specified by DriveLetter. Returns -1 if the drive specified is invalid.

Integer := GetDiskClass(DriveLetter, Trigger)

Explanation-

Returns an integer indicating the type of disk drive specified by DriveLetter. Returns -1 if the drive specified is invalid or not ready.

   Return Values -
   0 - Floppy 360k
   1 - Floppy 720k
   2 - Floppy 1.2Mb
   3 - Floppy 1.44Mb
   4 - Other Floppy
   5 - Bernoulli Box
   6 - Hard Drive
   7 - RAM Disk
   8 - Substitute Drive created with Assign or Subst
   9 - Unknown Drive Type
   10 - Disk unreadable, network or invalid

String := GetDOSEnvString(VariableName, SearchType, Trigger)

Explanation-

Searches the DOS environment for a variable identified in VariableName and returns the variables corresponding string. Returns blank if no such environment variable exists. SearchType specifies the level of effort GetDOSEnvString expends in order to locate the variable specified. If SearchType = 0 then only the current process's (the CDF Library's) environment is searched. If SearchType = 1 the parent process' (DataEase) environment is also searched if the desired variable is not found in the CDF Library's environment. If SearchType is 2, then DOS' master environment is searched if the variable is not found in either the CDF's or DataEase's environment. Unfortunately, CDFs executing under DE16M are given an empty environment and there is as yet no way to retrieve environment variables for such applications.

Integer := ChDir(NewDirectory, Trigger)

Explanation-

Attempts to change the default drive and directory to that specified in NewDirectory. Returns 0 if successful, non-zero if not. If NewDirectory references a drive that is not the current default, the default drive is changed, as well. Use with caution as DE relies on directories staying put.

Integer := MkDir(NewDirectoryName,Trigger)

Explanation-

Attempts to create subdirectory specified in NewDirectoryName. Returns 0 if successful, non-zero if not.

Integer := RmDir(DirectoryName, Trigger)

Explanation-

Attempts to delete the subdirectory specified in path. Returns 0 if successful, non-zero if not.

Integer := ClrScr(Trigger)

Explanation-

Clears the display screen without changing the current attributes (colors). Returns nothing meaningful.

Integer := Color(TextColor, BackgroundColor)

Explanation-

This function is used to construct a value representing a foreground/background color combination as used by various HandTools functions such as ClrScrAttr, ClrWinAttr, etc. Color values are encoded according to the following table:

To derive a color value for use in one of HandTools screen I/O functions, simply use the Color function with two of the above values. For example, to clear the screen to Bright White text on a Blue background with a ' ' texture, use Color as follows:

ClrScrAttr(Color(15,1)," ","")

Note: If you attempt to use a 'Bright' color (greater than 7) as a background color will cause the screen display to blink.

Integer := ClrScrAttr(TextureCharacter, Color, Trigger)

Explanation-

Clears the screen, filling the entire screen area with TextureChar and using Color as the foreground/background attribute. Returns nothing meaningful.

Notes: Use the Color function described above to derive a proper value for the Color attribute.

Example: The following DQL code snippet illustrates clearing the screen to all blue characters on a white background.

Define "Junk" number .
Junk := ClrScrAttr(" ",Color(1,7),"") .

Integer := ClrEOL(Row,Col,Trigger)

Explanation-

Erases all characters on the screen at Row, beginning in the Col column to the right edge of the screen. Returns nothing meaningful.

Long:=SaveScrRgn(ULScreenRow, ULScreenColumn, LRRow,LRColumn, Trigger)

Explanation-

Saves a rectangular region of the display screen bounded on the upper lefthand corner by ULScreenRow and ULScreenColumn and on the lower righthand corner by LRRow and LRColumn and returns a Handle (identifier) for the saved area. The saved area may be later re-drawn on the screen by supplying the Handle to the RestoreScrRgn function. Returns zero if fails.

Integer := RestoreScrRgn(Handle, Trigger)

Explanation-

Restores a rectangular screen region previously saved with SaveScrRegion. Region must be the Handle value returned from the previous SaveScrRgn call. Returns 1 if call fails (Region is invalid). 0 if ok. After calling RestoreScrRgn, the handle Region is invalid.

Integer := CRTWrite(Row, Column, WhatToWrite, HowLongToShow, Trigger)

Explanation-

Writes WhatToWrite(text) to the screen at Row and Column in current screen color. You may specify a value for HowLongToShow(integer), in which case WhatToWrite is displayed for HowLongToShow milliseconds and then is removed from the screen. You may also, optionally, set HowLongToShow to -1, in which case WhatToWrite is displayed until the user presses a key on the keyboard. If HowLongToShow is 0, then the text is written on the screen and control returns to DataEase immediately.

Example

For example to display 'Enter a valid amount' at row 10, column 34 for a quarter of a second (250 milliseconds):

CRTWrite(10,34,"Enter a valid amount", 250,"")

after 250 milliseconds, the message disappears and the screen is returned to its original appearance.

To display 'Press any key to acknowledge' at row 25, column 1 until the user presses a key:

CRTWrite(25,1,"Press any key to acknowledge", -1,"")

Finally, to simply display 'ABC Widget Company' at row 1, column 1 indefinitely:

CRTWrite(1,1,"ABC Widget Company",0,"")

Integer := CRTWriteAttr(Row, Column, Color, WhatToWrite, HowLongToShow, Trigger)

Explanation-

This function is identical to CRTWrite explained above, except that you may also specify a color attribute for the text that you will display. Use the Color function (as described on page 14) to supply the color value. See CRTWrite for more information.

Integer := CRTWriteVerticalAttr(Row, Column, Color, WhatToWrite, HowLongToShow, Trigger)

Explanation-

Functions identically to CRTWriteAttr except WhatToWrite(text) is written vertically down the screen beginning at Row and Column and proceeding down the screen. Please see CRTWriteAttr above for more information.

Integer := CRTWriteRJAttr(Row, Color, WhatToWrite, HowLongToShow, Trigger)

Explanation-

Functions identically to CRTWriteAttr except WhatToWrite is Right-Justified on Row. See CRTWriteAttr above for more information.

Integer := CRTWriteCenterAttr(Row, WhatToWrite, HowLongToShow, Trigger)

Explanation-

Functions identically to CRTWriteAttr described above except that WhatToWrite is centered (horizontally) on Row. See CRTWriteAttr (page 58) for more information.

Integer := CRTWriteTextandScroll(WhatToWrite, Trigger)

Explanation-

Writes WhatToWrite and a carriage return to the screen.

String := ReadCRT(WhereRow, WhereColumn, Length, Trigger)

Explanation-

This function allows your formula or procedure to determine what is being displayed on the screen. This can be useful in making a determination about whether a formula is being called when a main form or a sub form is displayed, what the name of the currently display main form is, etc.

ReadCRT reads the text from the screen beginning at WhereRow and WhereColumn and proceeding left-to-right for Length characters.

Integer := WhereX(Trigger)

Explanation-

Returns the coordinate of the screen row in which the cursor presently rests. Useful for determining the present active field. The value returned will be between 1-25 inclusive.

Integer := WhereY(Trigger)

Explanation-

Returns the coordinate of the screen column in which the cursor presently rests. Useful for determining the present active field. Value returned will be between 1-80 inclusive.

Integer := Sound(Frequency, Duration,Trigger)

Explanation-

Sounds the PC speaker at Frequency for Duration milliseconds. If Duration is zero(0), the speaker is left on and control returns to DataEase. In this case, calling Sound again with a non-zero duration will turn off the speaker.

(Special thanks to David Mercer for suggesting this one. Eh!)

Long := IntFromHex(HexadecimalNumber, Trigger)

Explanation-

Converts a hexadecimal string (up to 8 digits long) to a number(4-Byte). Returns -1 if HexadecimalNumber is invalid.

Long := IHX(HexadecimalNumber)

Explanation-

This is the shorthand equivalent to IntFromHex. It functions in exactly the same manner as IntFromHex except it does not accept a trigger parameter.

IHX("FF")

Integer := MakePoint(Column,Row)

Explanation-

Many of HandTools' CDFs require packed coordinate points as arguments. A packed coordinate is a two-byte integer that has the Column value in its high-order byte and the Row value in its low-order byte. MakePoint provides a convenient method creating packed coordinates as used by the CreateWindowObject function.

To create a packed coordinate representing screen column 10, row 15:

MakePoint(10,15)

String := PadRight(StringToPad, CharacterToUse, TotalLength, Trigger)

Explanation-

Pads the right-hand side of StringToPad with CharacterToUse to a total length of TotalLength characters.

Example

PadRight ("John ","*",8,"") returns "John****". 

String := FillLeft(StringToFill, FillCharacter, TotalLength, Trigger)

Explanation-

Creates a text string TotalLength characters long by inserting FillCharacter at the front of StringToFill until the string is TotalLength characters long.

Example

FillLeft ("John ","#",8,"") returns "####John ".

String :=CenterString(StringToCenter, FillCharacter, TotalLength, Trigger)

Explanation-

Creates a new string TotalLength characters long with StringToCenter centered between FillCharacters.

Example

CenterString(StringToCenter, FillCharacter, TotalLength, Trigger)

Explanation-

Creates a new string TotalLength characters long with StringToCenter centered between FillCharacters.

Example

CenterString ("John",8," ") returns

"  John  "

String := Trim(StringToTrim,Trigger)

Explanation-

Trims leading and trailing whitespace from StringToTrim. Whitespace is defined as spaces and control characters.

Example

Trim("    Joe Blow    ")

yields:

"Joe Blow"

String := TrimTrail(StringToTrim, Trigger)

Explanation-

Trims only trailing whitespace from StringToTrim. Whitespace is defined as spaces and control characters.

Example

TrimTrail("    Joe Blow   ")

Yields:

"    Joe Blow"

String := TrimLead(TextToTrim, Trigger)

Explanation-

Trims only leading whitespace from StringToTrim. Whitespace is defined as spaces and control characters.

Example

TrimLead("    Joe Blow   ")

Yields:

"Joe Blow   "

String := RemoveChar(TextToModify, CharacterToRemove,Trigger)

Explanation-

This function scans TextToModify from left to right and deletes any occurrence of CharacterToRemove from TextToModify.

Example

RemoveChar("JABBER","B","") 

returns

"JAER".

String := ReplaceChar(TextToModify, CharacterToReplace, NewCharacter,Trigger)

Explanation-

Replaces any occurrence of CharacterToReplace occurring in TextToModify with NewCharacter.

Example

ReplaceChar("JABBER","B","V","") 

returns :

"JAVVER".

Integer := Exec(ProgramToRun,Trigger)

Explanation-

Executes the DOS command line specified in ProgramToRun. Returns 0 if the process was actually executed. More common errors are -1 or -4 for no memory. Positive errors are MS-DOS error codes. This call does not compress or swap anything to disk and should be used when performance is desired and you KNOW that there will be enough free memory to run the desired program. See SwapAndExec for a memory saving alternative.

Integer := SwapAndExec(ProgramToRun, Trigger)

Explanation-

Executes the specified DOS command line. Returns 0 if the process was actually executed. More common errors are -1 or -4 for no memory. Positive errors are MS-DOS error codes. This call compresses as much of the CDF library as possible, swapping non-essential components to disk should be used to maximize the amount of free memory for the called program. See Exec for a memory high-performance alternative. Generally this call is used only when you want to execute an external process during form entry, as the program call feature available in standard DQL essentially does the same thing as SwapAndExec.

Integer := GetProgramExitCode(Trigger)

Explanation-

This function will return the exit code generated by the last child process executed by Exec or SwapAndExec. Exit Codes are typically used to indicate an abnormal end of the program but may also be used to convey other types of information, depending on the program. Exit codes may also be examined in batch files with the 'IF ERRORLEVEL == ..' statement. The code returned indicates the code set by the terminating program in the low-order byte, while the high-order byte contains one of the following:

   0 - normal termination.
   1 - terminated by Control-C or Control-Break.
   2 - terminated due to a critical device error (drive not ready, etc)
   3 - terminated and left resident (! a real no-no !)

Integer := Delay(MillisecondsToPause, Trigger)

Explanation-

Pauses everything for approximately MillisecondsToPause. This can be useful in DQL procedures where you wish to display something for a short period of time, etc.

String := InputString(Row, Column, SaveScreen, Trigger)

Explanation-

This function positions the cursor at Row and Column and waits for a string to be entered by the user (terminated by Enter), which is returned by the function. Maximum entry is 255 chars. A low-level primitive routine that is not very smart. If Save is non-zero, the current screen row is saved, the row is erased from col to the right edge of the screen and is restored after entry is completed.

See also: PromptUser, AskYN, FramedMessage

Integer := AskYN( PromptText, Row, Column, Default, Trigger)

Explanation-

Positions PromptText at Row and Column and waits for the user to press 'Y', 'N' or Enter. If the user presses 'Y' then AskYN returns a value of 1. If 'N' is pressed, then AskYN returns a value of 0. Keep in mind that the prompt is surrounded by a window frame, so the minimum and maximum row and column values are 2,2 and 24,(79-Length of prompt)-2 respectively.

Note that Default is a character, either 'Y' or 'N'. If the user presses enter, the value represented by Default is returned.

Example

To ask the user whether or not to continue processing a DQL procedure:

If AskYN("Do you wish to continue processing ?:", 10, 22, "Y","")=0 then
   Exit .
End .

Integer := FramedMessage(MessageToDisplay, Row, Column, HowLongToShow,Trigger)

Explanation-

This function displays a framed window containing MessageToDisplay at Row, Col. If HowLongToShow is 0, FramedMessage waits for a keypress on the keyboard before erasing the window and returning control to DataEase. If HowLongToShow is greater than 0, FramedMessage waits HowLongToShow milliseconds and then erases the window and returns control to DataEase. MessageToDisplay is surrounded by a frame so the minimum and maximum row and column values are 2,2 and 24,(79-Length of Message) respectively.

String := StConcat(FirstTextString, SecondTextString)

Explanation-

Concatenates the two strings together similarly to JoinText. Included because DataEase seems to change their mind often about how JoinText works. StConcat ALWAYS returns the concatenation of the two strings without trimming any white space.

See also: JT

Integer := WaitKey(Trigger)

Explanation-

Simply waits for a key to be pressed on the keyboard. The value returned is the keystroke's scan code.

Long := OpenTextFile(Filename, ModeToUse, Trigger)

Explanation-

Attempts to open the named file for text input and output. Filename can also refer to a DOS device (i.e. "LPT1:" or "CON:"). ModeToUse must be one of the following:

   Mode = 0 open existing, position to BOF
   Mode = 1 append to existing
   Mode = 2 create/overwrite (Confirm destruction)
   Mode = 3 Create/overwrite (no Confirmation)

If you are writing to a device such as CON: (the CRT) or LPT1:, then ModeToUse must be 3.

All modes but mode 1 position the file pointer to its beginning, while 1 (append) seeks to the end of the file.

If OpenTextFile is successful, a handle to the file (long integer) is returned, which must be preserved and used to reference the file during subsequent operations. If filename or mode are invalid, the handle returned will be zero. You may open as many files as you have DOS file handles available for. Open files are closed automatically when the CDF library is unloaded by DataEase.

Use the text I/O features to create audit trails or to debug your DQL procedures. Our, you can use them for special data exporting and importing purposes.

Example

Suppose we want to create a file from a DQL procedure that contains customer numbers:

Define "FileHandle" number .
Define "X" number.


FileHandle := OpenTextFile("LOG.FIL",3,"") .
If FileHandle not= 0 then
  For Customers ;
  X := WriteFileLine(FileHandle, CustID,"") .
  End . -- For
else
  Message "Unable to Open File" Window .
end. -- If 

Integer := CloseTextFile( FileHandle )

Explanation-

Closes a text file previously opened by OpenTextFile. FileHandle must be a valid handle previously obtained from OpenTextFile. After CloseTextFile is executed, FileHandle is no longer valid. The CDF library automatically closes all open text files when the library is unloaded by DataEase.

String := ReadTextFile(FileHandle, Trigger)

Explanation-

Reads one line of text from the open text file referenced by FileHandle. The read begins at the current file position and continues through the next carriage return code. The file pointer is advanced to the character beyond the carriage return. Unfortunately, an empty string can either indicate an invalid handle error or can also be a legitimate result for an empty line, so be careful.

Integer := WriteFileString(FileHandle, TextToWrite, Trigger)

Explanation-

Writes TextToWrite to the text file specified by FileHandle. FileHandle must refer to a file opened with OpenTextFile with a mode of 1, 2 or 3. TextToWrite is written to the file at the current file position and overwrites any text that may be at that position. After writing the text, the file pointer is positioned to just beyond the last character written. No carriage return is written to the file. NOTE: You may only write to files opened with a mode greater than 0.

Integer := WriteFileLine(FileHandle, TextToWrite,Trigger)

Explanation-

Similar to WriteFileString described above except WriteFileLine appends a carriage return sequence to the string before writing. After writing the line, the file pointer is positioned just beyond the end of the carriage return sequence. NOTE: You may only write to files opened with a mode greater than 0.

Integer := GetEOFStatus(FileHandle,Trigger)

Explanation-

Returns a true value (1) if the file specified by FileHandle is positioned beyond the last character written to the file or if the file is empty. Returns 2 if FileHandle is invalid.

Useful for monitoring the end-of-file status when reading from a file with ReadTextFile:

Example

To read each line from a file called CUSTOMER.DAT and insert the text read into a CustomerNames form:

Define "FileHandle" number .
Define "Line" Text 255 .
Define "X" number .


FileHandle := OpenTextFile("CUSTOMER.DAT",0,"") .
If FileHandle not=0 then
  While GetEOFStatus(FileHandle,"") = 0 do
    Line := ReadTextFile(FileHandle,"") .
    Enter a record in CustomerNames
      CustomerName := Line .
  end .
end .

Int:=WriteFormFeed(Handle)

Integer := SeekTextFileTop(FileHandle, Trigger)

Explanation-

Each text file has a position pointer which indicates the relative position in the file at which the next read or write operation will begin. SeekTextFileTop sets the file's position pointer to the beginning of the specified file.

Integer := SeekTextFileEnd(FileHandle, Trigger)

Explanation-

Sets the file's position pointer to the end of the specified file. See also SeekTextFileTop.

Integer := SeekTextFilePos(FileHandle, Position, Trigger)

Explanation-

Sets a file's position pointer to the specified byte-offset into the specified file. FileHandle refers to a file previously opened with OpenTextFile. If Position is larger than 'file size+1' (which is the append position), the request will fail. The first position in a file is 0. Returns 0 if successful.

Integer := SpitLine(FileName, TextToWrite, Trigger)

Explanation-

SpitLine opens the named file, appends TextToWrite to its contents, and closes the file If filename does not exist, then it is created. TextToWrite is written to the end of the file followed by a carriage return, line feed sequence. Note that LPTx and CON are valid filenames which will be interpreted as their DOS device equivalents (printer and screen, respectively).

SpitLine provides a convenient way to log information.

String := WordWrapTextLine(UnbrokenText, MarginWidth, Trigger)

Explanation-

Returns a string containing only the whole words from UnbrokenText that will fit within MarginWidth columns. Whole words are considered to be separated by spaces UnbrokenText's maximum length is 255 characters.

Example

Suppose we wanted to reformat a file of text with a maximum margin width of 80 characters fit within a maximum margin width of 40 characters. A procedure to do this could be written as follows:

Define "InFile" number .
Define "OutFile" Number .
Define "X" number.
Define "InputText" Text 80 .
Define "OutputText" text 40 .


InFile := OpenTextFile("INPUT.TXT",0,"") .
Outfile := OpenTextFile("OUTPUT.TXT",3,0) .


If InFile not=0 and OutFile not=0 then
  While GetEOFStatus(Infile,"")=0 do
    InputText := ReadTextFile(InFile,"") .
    While Length(InputText) > 0 do
      OutputText := WordWrapTextLine(InputText, 40, "") .
      X := WriteFileLine(FileHandle, OutputText) .
      InputText := GetWordWrapOverflow(InputText, 40,"") .
    end .
  end .
  X := CloseTextFile(InFile) .
  X := CloseTextFile(OutFile) .
else
  message "Error opening files" window .
end .

String := GetWordWrapOverflow(UnbrokenText, MarginWidth, trigger)

Explanation-

Returns a string containing the portion of UnbrokenText will not fit within MarginWidth columns without splitting words. The input string's maximum length is 255.

See Example above in WordWrapTextLine.

Integer := CountWords(Text, Trigger)

Explanation-

Returns the number of words in Text. CountWords considers words as contiguous characters separate by spaces.

Integer := PopMsgStr(MsgFileName,
Index,
Row,
Column,
Frame,
FrameColor,
TextColor,
HowLongToShow,
Sound,
Trigger)

Explanation-

PopMsgStr displays a string retrieved from a text file. It provides a convenient means of displaying an application's standard messages, such as error messages. PopMsgStr allows you to record standard application messages in a text file and selectively display them on the screen.

MsgFileName is expected to specify an existing file that contains a list of text strings [max 78 characters each], each terminated by a carriage return. Index specifies the line in the file to display (starting at 1). MsgFileName can be created with any text editor or by a DataEase DQL procedure.

PopMsgStr will display the Index'th text string occurring in MsgFileName. The string is displayed at the specified row and column. If Frame is non-zero, a frame will be drawn around the text in FrameColor screen colors. The text is displayed in TextColor colors. Use the Color function to provide the values for FrameColor and TextColor. If HowLongToShow is > 1 then the message is displayed for approximately HowLongToShow milliseconds. If HowLongToShow is 0, then the message is displayed until a key is pressed on the keyboard.

If Sound is non-zero, PopMsgStr will beep the PC's speaker.

If all goes well, the function returns a value of 0.

If PopMsgStr fails, it returns an error code as follows:

   > 0 : An MS-DOS IOERROR code. Usually MsgFileName did not exist or is locked.
   < 0 : Index was beyond the end of the file

String := GetMsgStr( MsgFileName, Index, Trigger)

Explanation

MsgFileName is expected to reference a DOS file containing lines of text separated by a Carriage-Return. GetMsgStr opens the file specified, advances to the Index'ed line in the file and returns the text found on that line. See PopMsgStr for additional information.

Example

Say you have a DOS file called ERRORS that contains the following text:

This is message #1
This is message #2
This is message #3

Calling GetMsgStr as follows:

GetMsgStr("ERRORS",2,"")

would retrieve the second line in the file:

This is message #2

Use It For

Retrieving standard error, warning or informative message strings.

Int := FilterFile(Filename,LookFor,ReplaceWith)

Explanation

This function scans the file referenced by Filename and replaces all bytes with a value of LookFor with the value ReplaceWith. Note that LookFor and ReplaceWith are numeric values representing byte values from 0-255. The file is read byte-by-byte and each time a byte with a value of LookFor is encountered, it will be replaced with a byte with the value of ReplaceWith. This can be useful for pre-processing import files that contain characters, such as tabs (09) that DataEase does not recognize.

Example

To replace all tab (09) characters occurring in the file 'MYIMPORT' with '|' (124) characters:

FilterFile("MYIMPORT",9,124)