Category: Functions

Extracts a segment from the front of a character string.

Syntax

$left(source,length)

Parameters

Return Value

Character string, consisting of a string containing length characters from source, starting in the first position.

Comments

Use $left to produce a string consisting of length characters from source, starting in the first position.

If source is not of a character data type, it is converted to a character data type before processing.

If length is zero or negative, the result is the null string. If length is longer than source, the result is source.

Example

$left("abcdefgh",5)

Evaluates to “abcde”.

$left(9999,1)

Evaluates to ” “, because numbers are converted to character strings containing seventeen characters before being processed by $left.

$left(1234567890,10)

Evaluates to ” 123″. Number literals convert to character strings containing seventeen characters before being processed by $left.

See Also

$concat

$delete

$insert

$position

$replace

$right

$substring

$toalpha

$tocharacter

$translate

Applies a mask pattern to the specified data item.

For a more detailed explanation of mask patterns and their relation to data types, see Masking.

Syntax

$mask(item,pattern)

Parameters

Return Value

Character string, containing the masked value.

Comments

• Mask patterns consist of special characters and fixed text characters;
• Fixed text characters are always output as is;
• The set of special characters available for use to mask a particular data value is determined by the data type of value being masked (character string, date, or number );
• Most special characters are typically replaced by characters from item, but they can also output characters in their own right (e.g., the floating currency symbol: $, which can be customized);
• The Language Customizer utility (ZIMLANG) can be used to redefine how certain special characters are displayed or output.
  For example, in numeric masks, the currency symbol $ normally outputs a dollar sign, but it can be configured to output other symbols, such as the pound sign £ or yen sign ¥.

Examples

list all Employees format FirstName LastName
($mask(DeptNum,”?epartment Number ??”))

Displays values of DeptNum, such as “D09”, as “Department Number 09”, instead of “D09”.

list all Employees format FirstName LastName
($mask(Salary,”$$$$$$9.99″))

Displays all values of Salary with a floating dollar sign.

$mask ($date, “MM-DD-YY”)

Evaluates to “08-18-98” if $Date is 19980818.

Converts an expression to the character data type and sets the length of the result.

Syntax

$tocharacter(expression,length)

Parameters

Return Value

Character (char), length bytes long.

Comments

Use $tocharacter to convert expression to the CHAR data type in an area length bytes long. If length is negative, the result string is set to the maximum possible length.

String comparisons involving this function are case-sensitive.

If expression is a number, the number is converted to character string form in an area length bytes long. If the given area is not large enough to hold the converted value, an error results.

Example

Assume LastName is “Smith “.

$tocharacter(LastName,3)

Evaluates to “Smi”.

$tocharacter(LastName,12)

Evaluates to “Smith “.

$tocharacter(50,2)

Evaluates to “50”.

$tocharacter(200+300,20)

Evaluates to ” 500″ (17 leading spaces).

$tocharacter(500,-2)

Evaluates to ” 500″ (14 leading spaces).

list all Emps format $tocharacter(FirstName,6), $tocharacter(LastName,9)

$tocharacter changes the width of values being output with a LIST command.

Locates the first occurrence of a pattern in a character string.

Syntax

$position(source,pattern)

Parameters

Return Value

Number, being the position of the first character in source that matches the first character of pattern, when pattern is found in source.

Comments

$position returns a number that identifies the start position of pattern in source. If pattern is not found in source, $position returns 0.

If either source or pattern is not of a character data type, it is converted to a character string before the operation begins. If source is of data type ALPHA or VARALPHA, the operation is case-insensitive; otherwise, the operation is case-sensitive.

Example

$position(var1,"ab")

Evaluates to 4 if var1 is “defabc”.

$position("abcdef","zz")

Evaluates to 0.

find all Customers where $position(Comments, "overdrawn") > 0

Determines if the word overdrawn appears in the Comments field for any one of your Customers.

See Also

$concat

$delete

$insert

$left

$replace

$right

$substring

$translate

About Character Literals

About Functional Expressions

Inserts a character string into another character string.

Syntax

$insert(source,position,string)

Parameters

Return Value

Character string consisting of source, with string embedded starting at the specified position.

Comments

Use $insert to produce a string consisting of source, with string embedded starting at position.

In a string, the position of the first character is always 1. If position is beyond the end of source, then string is appended to source. If position is zero or negative, then source is left unchanged.

Example

$insert("12345",3,"abc")

Evaluates to “12abc345”.

$insert("abc",1,"de")

Evaluates to “deabc”.

$insert("abc",4,"def")

Evaluates to “abcdef”.

$insert($delete("abcdef,2,2),2,"123")

Evaluates to “a123def”.

See Also

$delete

$fill

$left

$position

$replace

$right

$squeeze

$substring

$translate

Converts an expression to the alpha data type and sets the length of the result.

Syntax

$toalpha(expression,length)

Parameters

Return Value

Character string (alpha), length bytes long.

Comments

Use $toalpha to convert expression to the alpha data type in an area length bytes long. If length is negative, the result string is set to the maximum possible length. If length is zero, the result is the null string.

String comparisons involving this function are case-insensitive.

If expression is a number, the number is converted to character string form in an area length bytes long. If the given area is not large enough to hold the converted value, an error results.

Example

Assume that LastName is “Smith “.

$toalpha(LastName,3)

Evaluates to “Smi”.

$toalpha(LastName,12)

Evaluates to “Smith “.

$toalpha(50,2)

Evaluates to “50”.

$toalpha(20+30,19)

Evaluates to ” 50″ (17 leading spaces).

$toalpha(200+300,20)

Evaluates to ” 500″ (17 leading spaces).

$toalpha(500,-2)

Evaluates to ” 500″ (14 leading spaces).

list all Emps format $toalpha(FirstName,6), $toalpha(LastName,9)

Alters the width of values being output with a LIST command.

See Also

$left

$substring

$tochr

$tonumber

$toord

About Character Literals

About Functional Expressions

Conversion Between Data Types

Deletes a portion of a character string.

Syntax

$delete(source,position,length)

Parameters

Return Value

Character string, consisting of source, less those characters starting at position, for a length of length.

Comments

In a string, the position of the first character is always 1. If position is beyond the end of source, or if position is zero or negative, then no characters are deleted from source.

If length is zero or negative, then no characters are deleted from source.

If there are fewer than length characters from position to the end of source, then all characters from position to the end of source are deleted.

Example

$delete("abcdef",2,2)

Evaluates to “adef”.

$delete("613-555-1234",1,4)

Evaluates to “555-1234”.

See Also

$concat

$fill

$insert

$left

$position

$replace

$right

$squeeze

$substring

About Character Literals

About Data Types

About Functional Expressions

Checks whether a given Zim object exists in a Zim directory.

Syntax

$exist$(Zim directory name, object name, object type)

Parameters

Return Value

It returns a $True value if the object name is defined in the Zim directory and is of the specified object type.

It returns a $False value if the object name is not defined in the Zim directory or is not of the specified object type or the Zim directory name is already accessed.

If the object type is 0 (zero), the function will return the object type of the object for subsequent reading of the status of this object (see example).

If the object type is non-zero and the Zim directory name is empty (“”), then the return value is the owning directory name of that object.

Comments

The types of the object are described as the following table:

Examples

Check whether the directory “Accounting” is defined in Zim:

$exist$("ZIM", "Accounting", 2)

Investigate the type of the object “Customers” in directory Zim and then test whether it exists or not:

let Var = $exist$("ZIM", "Customers", 0)
$exist$("ZIM", "Customers", Var)

Run the methods of an ActiveX object.

Syntax

$ObjRun[Method] (Object, MethodName, «Parameters»)

Parameters

Return Value

Returns a result as per the specification of the object.

Note: Zim attempts to convert to the assigned type. Ensure a proper variable type is assigned.

Comments

Parameters can be named. If they are named, they do not need to be entered in any particular order. Named parameters contain the name of the parameter, an equal sign, and the value of the parameter.

$null can be used to maintain position of optional parameters in unnamed argument list. Unnamed parameters must precede named parameters in argument list.

If you require it, you can have OLE objects return values by reference, since ZIM passes all variables by reference to OLE objects.

Example

The add method of Treeview is described as having the following syntax:

INode* Add(
      [in, optional] VARIANT* Relative,
      [in, optional] VARIANT* Relationship,
      [in, optional] VARIANT* Key,
      [in, optional] VARIANT* Text,
      [in, optional] VARIANT* Image,
      [in, optional] VARIANT* SelectedImage);

Assume you have a form called treeview with a treeview component on it called tree.

Assume vNode is a variable of type object. The syntax to add a node to the treeview’s nodes object is provided below.

compute all myset wh $distinct (custs.cc) is not $null evaluate 
 ( let vNode = $ObjRunMethod ( vNodes, 'Add', 
     % placeholder for relative
     % placeholder for relationship
    $squeeze('', 'c',$trim(custs.cc)), %unnamed argument for Key
    $squeeze('','text=',$trim(custs.company)))) %named argument for Text

Assume the variables sWidth and sHeight are integers and the variable vole is an object. The following example retrieves the object’s width and height given a display with two months high and three months wide:

let vole = $ObjCreate("mscomctl2.monthview.2")
out $ObjRunMethod(vole,"ComputeControlSize",3,2,sWidth,sHeight)

Warning

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

Replaces segments of a character string with new text.

Syntax

$translate(source,pattern,replace)

Parameters

Return Value

Character string, consisting of source, with replace substituted for all occurrences of pattern.

Comments

Use $translate to substitute portions of source with replace. If source, pattern, or replace are not of a character data type, they are converted to a character data type before the function is applied.

If source is of data type ALPHA or VARALPHA, searches for pattern are case-insensitive; otherwise, searches for pattern are case-sensitive.

Example

$translate("the slow brown fox","slow","quick")

Evaluates to “the quick brown fox”.

% translates Smith to Smythe
list all Employees where LastName = "Smith"
format FirstName $translate(LastName,"ith","ythe")

Translates occurrences of Smith to Smythe in the field LastName.

See Also

$concat

$delete

$fill

$left

$position

$replace

$right

$squeeze

$substring

About Character Literals

About Functional Expressions