Categoria: Functions

Generates the “sounds-like” value of a string.

Syntax

$soundex(source)

Parameters

Return Value

Character string (alpha).

Comments

$soundex yields a “sounds-like” value for source. The value is created using an heuristic algorithm and is based on English pronunciation.

When $soundex is applied to two separate strings and they generate the same “sounds-like” value, then the two original strings can be assumed to sound the same. $soundex can be used to compare and find strings that sound the same but are spelled differently.

The result of $soundex is of data type ALPHA, therefore comparisons involving soundex values are case-insensitive.

Example

find all Customers where $soundex(LastName) = $soundex("Burton")

The above command returns customer records for names like Burton, Berton, Bertyn, Bertin, BURTON, BERTIN, and so on.

find all Customers where sLastName = $soundex("Burton")

The preceding command takes advantage of indexed searching by setting up sLastName as an indexed virtual field that contains the soundex values of LastName in the Customers EntitySet.

let SoundsLike = $soundex("Smith")
find all Customers where sLastName = SoundsLike?

The preceding code fragment uses prefix searching (? wildcard) with soundex values.

See Also

? (Wildcard)

About Character Literals

About Functional Expressions

Copies files from the client side to the server side.

Syntax

$copytoserver(source file name, destination file name, file type)

where

Return Value

The value return by this function is the file address of the destination if it is executed correctly; otherwise, it will return a $Null value.

Comments

This function is designed to work under ZIMTC and copies file from the client side to the server side using the file type specified. Files of the binary type are sent as they are, without their contents being checked (like images, videos, etc). On the other hand, files of the text type are copied using text file conventions for Windows and Unix.

Both the source and the destination file names can be either relative or absolute file paths. The following remarks apply to these paths:

If the destination file name contains sub-directories that don’t exist, they are created.

The ZIM executable ignores this function as it makes no sense copying a file to itself.

Example

This example copies the text file from the database path to a fixed location in the server’s machine.

out $copytoserver("mytext.txt", "c:\mextext.txt", "T")

Related Topics

$copytoclient

Returns the position of the current member of a result set.

Syntax

$currentmember(setname)

Parameters

Return Value

Number, with no decimal places.

Comments

$currentmember returns the (numerical) position of the current member within the specified result set. To explicitly specify the current set, use “CurrentSet” (including the quotation marks), as CurrentSet is a reserved word and the function is expecting a character string.

To ensure against unexpected results, choose set names carefully. At run time, the software distinguishes sets only by their names, even if they are permanent set names created in different application directories.

If, for example, you produce a set called Set1 in directory PersonnelData, and later you produce another set called Set1 in directory TestData, the second version of Set1 replaces the first version. Function $currentmember works only on the most recent version of the set.

Example

let vMemberNum = $currentmember("Set1")

If the current member of Set1 is the fifth member, then variable vMemberNum is set to 5.

while
... process current member ...
if $currentmember("TempSet") = $lastmember("TempSet")
break
endif
next TempSet
endwhile

The WHILE loop processes TempSet one member at a time, breaking out when the last member of the set has been processed.

See Also

$lastmember

Converts an ordinal number into a character.

Syntax

$tochr(number)

Parameters

Return Value

Each of the decimal numbers from 0 to 255 represents a character output by your workstation. $tochr converts a given number to the corresponding character.

Note: The ascii character 0 returns an ascii null value. Zim sees the null character as an End of Line character and stops outputting data. In addition, the ascii character 32 (a space) translates to a 0 since the $tochr function expects a number as the parameter. So, $tochr (” “) translates to $tochr(0) and results in the null value. No matter how encountered, a null value in a string truncates the string at the first null character encountered.

If number is negative or greater than 255, the result of the function is $Null.

The character produced by the $tochr function can be converted back to a decimal number by the $toord function.

Comments

Ordinal number refers to the decimal numbers 0 to 255 that you computer uses to represent the characters available on your system.

Example

$tochr(32)

Evaluates to a space (on ASCII machines).

$tochr($toord("Z"))

Evaluates to “Z”.

See Also

$left

$substring

$toalpha

$todate

$tonumber

About Character Literals

About Functional Expressions

Conversion Between Data Types

Calculates a date value by adding years to (or subtracting years from) a specified date value.

Syntax

$addyears(date,number)

Parameters

Return Value

Number, representing a DATE value.

Comments

Use $addyears to perform arithmetic with date values. The $addyears function calculates a date value by adding a number representing years to a date value. If number is negative, the effect is to subtract the years from the date.

The + (add) and – (subtract) operators can be used to achieve the same results.

If date or the result of the $addyears expression is an invalid date (e.g., 19930231), it is adjusted to produce a valid date (e.g., 19930228).

Example

If $Date has the value 19981225, then

$addyears($date,5)

Evaluates to 20041225.

$addyears($date,-5)

Evaluates to 19931225.

$addyears(19980229,1)

Evaluates to 19990228.

See Also

$adddays

$addmonths

$addweeks

$todate

$weekday

$year

+ (Add/Positive)

– (Subtract/Negative)

About Functional Expressions

Arithmetic with Dates

Captures a bitmap image of the screen and writes it to a file.

Syntax

$screensave(filename)

Parameters

Return Value

Returns “1” ($True) if no errors were detected when the image was written to filename. Otherwise, returns “0” ($False).

Comments

Filename must be the name of a disk file, including the path location. A document name cannot be used.

$transmitkey Object

Syntax: $transmitkey

Return Value: Character string

Description:

The $transmitkey object captures the name of the last EXIT or TRANSMIT key pressed during form input operations. This object is essential for managing form navigation and submission, especially when custom key bindings are involved.

Key Concepts:

1. EXIT and TRANSMIT Keys:
   • These keys are defined using the FORM SET or WINDOW SET ACCELERATOR commands.
   • EXIT Key: Typically used to exit or cancel the form input process.
   • TRANSMIT Key: Used to submit the form data.
2. Form Input Termination:
   • Normally, a TRANSMIT key cannot terminate FORM INPUT if any “required” fields are empty.
   • Exception: If the TRANSMIT key is pressed while the cursor is in a modified transmit field or an “always transmit” field, the field will transmit, causing FORM INPUT to terminate.
   • If required fields are still empty after this action, $transmitkey will be set to an empty string ("").
3. Resetting $transmitkey:
   • The $transmitkey object can be reset at any time to clear its value. This is useful for ensuring that the object accurately reflects the most recent key press.

Practical Usage:

Defining Keys:

To define EXIT and TRANSMIT keys, you use the FORM SET or WINDOW SET ACCELERATOR commands. For example:

FORM SET ACCELERATOR EXIT F2
FORM SET ACCELERATOR TRANSMIT F1

In this example, the F2 key is set as the EXIT key, and the F1 key is set as the TRANSMIT key.

Handling Key Presses:

You can check the value of $transmitkey to determine which key was pressed and take appropriate actions. For example:

IF $transmitkey = "F1" THEN
    // Handle the F1 key press (TRANSMIT)
    CALL ProcessFormSubmission()
ELSE IF $transmitkey = "F2" THEN
    // Handle the F2 key press (EXIT)
    CALL CancelFormInput()
ENDIF

In this example, different actions are taken based on whether the F1 or F2 key was pressed.

Special Considerations:

• Modified Transmit Fields: These are fields that can trigger form submission even if other required fields are empty. This is useful for scenarios where partial data submission is allowed.
• Always Transmit Fields: These fields always trigger form submission when the TRANSMIT key is pressed, regardless of the state of other fields.

Example Scenario:

Imagine a form with several required fields. If the user presses the TRANSMIT key (F1) while in a modified transmit field, the form will attempt to submit. If any required fields are still empty, $transmitkey will be set to an empty string, indicating that the submission was not successful.

FORM SET ACCELERATOR TRANSMIT F1
FORM SET ACCELERATOR EXIT F2

// User presses F1 while in a modified transmit field
IF $transmitkey = "F1" THEN
    IF AllRequiredFieldsFilled() THEN
        CALL SubmitForm()
    ELSE
        $transmitkey = ""  // Reset because required fields are empty
    ENDIF
ENDIF

This ensures that the form submission logic is robust and handles incomplete data appropriately.

Displays the Printer Setup common dialog box.

Syntax

$printersetup()

Return Value

Evaluates to “1” ($True) if no errors were detected in the dialog. Otherwise, evaluates to “0” ($False).

Comments

This function is available only on Windows systems. The Printer Setup common dialog box contains a list of printers mounted to your Windows network. To access printers not listed in the dialog box, see your system administrator.

See Also

$setproperty
PRINT

Get the properties of an ActiveX object.

Syntax

$ObjGet[Property] (Object, PropertyName,<>)

Parameters

Return Value

Returns a result that can be a string or an ActiveX object.

Comments

If a parameter’s name is “Picture” then the parameter should be named. For more information, see $ObjRunMethod function. Zim has extended object properties with left, top, width and height options (integers) and AutoDrag (boolean).

Warning

COM objects are being discontinued by Microsoft and may not be available in future releases of Zim-X.

Obtain information about a particular parameter created by the current event raised by a COM component.

Syntax

$ObjEventParameter (ParameterNumber)

Return Value

Returns a result that can be a component object or a string for the passed parameter number.

Comments

The Event structure displays information about the last event that caused form input to terminate. The proprietary events of an object can trigger Zim to terminate form input. To trigger this, use the command

FORM SET (OBJECTEVENT . . .)

When the proprietary events of an object cause forms input to terminate, the eventname field is set to the name of the event and the event type is set to formfield.

Often the proprietary events of an object pass along extra information in the form of parameters. These parameters can be queried using the $ObjEventParameter function.

Warning

COM objects are being discontinued by Microsoft and may not be available in future releases of Zim-X.