Category: ZIM 4GL Language Reference

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

Syntax

$addmonths(date,number)

where

Return Value

Number, representing a DATE value.

Comments

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

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

If date or the result of the $addmonths 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:

$addmonths($date,3)

Evaluates to 19990325.

$addmonths($date,-3)

Evaluates to 19980925.

$addmonths($date,20)

Evaluates to 20000825.

$addmonths(19980131,1)

Evaluates to 19980228 (note truncation).

See Also

$adddays

$addweeks

$addyears

$day

$dayname

$todate

$weekday

+ (Add/Positive)

About Functional Expressions

Arithmetic with Dates

Generates a pseudo-random number, uniformly distributed within the range 0 to 1.

Syntax

$random(number)

Parameters

Return Value

Number, with the same number of decimal places as number.

Comments

Use $random to generate a series of random numbers, by calling the function first with a seed value, and thereafter with $Null. The value returned by $random is a number in the range 0 to 1, with the same number of decimal places as number.

To pass the null property to $random, create a variable of a number data type (INT, LONGINT, VASTINT, numeric) and with the desired number of decimal places. Use this variable on subsequent calls to $random after seeding. (Remember that an uninitialized variable is always $Null.)

If you seed the random number generator with the same number on two or more different occasions, you obtain the same series of “random” numbers on the first call and subsequent ($Null) calls to $random.

Under some operating systems, the seed number is ignored; an internally generated seed is used instead.

When number is $Null, the random number generator is not reseeded.

Example

let seed = 9.999
let i = $random(seed)  % i might be set to 0.798 here
let seed = $null
let i = $random(seed)  % i might be set to 0.768 here

let i = $time
let i = $random(i)       % first call
  :
let i = $random(UninitVariable) % subsequent calls

Notice that $random($time) always returns 0 or 1, because $Time has no decimal places. Variable i is used to provide the necessary decimal places.

Extracts a segment from the end of a character string.

Syntax

$right(source,length)

Parameters

Return Value

Character string, consisting of length characters from source, starting length character positions from the end of source.

Comments

Use $right to produce a string consisting of length characters from source, starting length character positions from the end of source.

If source is not of a character data type, it is converted to a character data type before the function is applied.

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

If length is longer than source, the result is source.

Example

$right("abcdefgh",5)

Evaluates to “defgh”.

$right(1234,2)

Evaluates to “34”.

$right(1234567890,8)

Evaluates to “34567890”.

See Also

$concat

$delete

$insert

$left

$position

$replace

$substring

$translate

About Character Literals

About Functional Expressions

Conversion Between Data Types

Returns the unique values from a series of successive values.

Syntax

$distinct(expression)

Parameters

Return Value

This function returns the unique values from a series of successive values. For each instance of its argument, $distinct returns a value that depends on the immediately previous value of the argument. If the previous and current values of the argument are equal, $distinct returns $Null. Otherwise, $distinct returns the current value of the argument.

Comments

It is important to sort the argument’s source values before using $distinct, because the value returned by the expression depends on the order in which the source values are processed.

Example

find Emps sorted by LastName
list all format LastName Salary

Prints the last names and salaries of all employees.

find Emps sorted by LastName
list all format $distinct(LastName) Salary

Prints the last names and salaries only of the employees who appear first in the list with a particular name.

find Emps sorted by LastName
list all where $distinct(LastName) is not $null format LastName

Prints a list of the last names of employees without repeating identical names.

report from Emps sorted by DeptNo LastName
break 1 DeptNo
footing
"No. of distinct last names in " deptno
"is" $count($distinct(LastName))
endreport

When used in a BREAK heading or footing, $distinct is reset for each break group. As a result, the first record in each break group is considered to be new, even if the value of the argument to $distinct is the same as the last value in the previous group. In the above report, even if the last employee in one department is named Smith and the first employee in the next is also Smith, the values are still considered to be distinct.

See Also

Functional Expressions

INTERSECT

MINUS

UNION

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