ZIM 4GL Language Reference – Page 4 – 4GL APPLICATION FRAMEWORK

$addmonths

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

Syntax

$addmonths(date,number)

where

date	a date, or an expression that evaluates to a DATE data type
number	a number, or an expression that evaluates to a number

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).

PARSE

Tests a single Zim command, or an application program, for syntactic and semantic accuracy.

Syntax

PARSE commandstring | docname

Parameters

commandstring	Any character string, enclosed in quotation marks, that represents a Zim command to be parsed.
docname	The name of an application document that contains an application program to be parsed.

Comments

The PARSE command enables you to check an individual command or an entire program without executing either the command or the program. Executing a PARSE command does not affect any data values held either in memory or in the database. The PARSE command reports any syntactic or semantic irregularities that the PARSE command uncovers.

The sets created by FIND commands in parsed programs are defined. Only the directories accessed at the time that the PARSE command is executed are used. The ACCESS and RELEASE commands are parsed but not executed.

A program is parsed on a line-by-line basis. A program called from the program being parsed is not parsed, but the software does check to see if the program exists. All parts of commands with conditions are parsed, regardless of the validity of the conditions or the presence of any BREAK, CONTINUE, or TRANSFORM command.

Example

To check a command before running it, use

parse “list all Employees where LastName = Smith”

If you have an application program MyProg that calls the program SubUserCom, enter

parse MyProg

Only the command statements in MyProg are parsed. The software checks that SubUserCom exists, but does not parse it.

LET

Assigns a value to a variable object.

Syntax

LET expression

Parameters

target	A global or local variable, a form field or menu item, a parameter, or a macro can be used. Subscripted (array) variables are valid.
expression	Any value expression. The value of expression is assigned to target. Expression can include literals, constants, global or local variables, form fields, menu items, parameters, or fields in the current set. These objects can be combined using any of the arithmetic operators and functions.

Comments

The LET command is used to assign values to variable objects. To assign values to a field in an EntitySet or relationship, you must use ADD, CHANGE, INSERT, or UPDATE (which can contain a LET subcommand). The LET command is not used to assign values to database fields.

An assignment expression is formed by enclosing the LET command in parentheses.

If expression evaluates to $Null and target is a macro, the macro is assigned the null string. (A null string is a string of zero length, which is not the same as the $Null property.)

Example

let var1[1]=1 var1[2]=2 var1[3]=3

let var1 = $Date var2 = $tolower(LastName) var3[2] = 123

An example of using LET to assign values to variables.

let = “where LastName = Smith”

let= “from terminal prompt”

let <5> = $null

An example of using LET to assign values to macros.

[NOT] BETWEEN

Compares one value to a specified range of values.

Syntax

expression [NOT] BETWEEN expr1 AND expr2

Parameters

expression	An expression that evaluates to either a number or a character string.
expr1	An expression that evaluates to either a number or a character string.
expr2	An expression that evaluates to either a number or a character string.

Return Value

Logical

Comments

If any one of expression, expr1, and expr2 is a number, then a numeric comparison is made; otherwise, the comparison is character-based. Note that the AND in a BETWEEN comparison is not the Boolean AND.

A BETWEEN comparison is logically true if expression is greater than or equal to expr1, and less than or equal to expr2.

A NOT BETWEEN comparison is logically true if expression is either less than expr1, or greater than expr2.

Note: The AND in a BETWEEN comparison is not the Boolean AND.

Example

BioDiversity between 500 and 2000

Logically true if the value of BioDiversity lies between 500 and 2000 (inclusive).

$InTransaction

Indicates if an explicit transaction is in progress.

Syntax

$intransaction

Return Value

“1” ($True), or “0” ($False). Can be reset by an application program.

Description

$InTransaction acts as a flag, indicating if the software is currently processing an explicit transaction.

$InTransaction is set to “1” ($True) if a TRANSACTION (or BEGIN WORK) command has started an explicit transaction. It is set to “0” ($False) when an ENDTRANSACTION or QUITTRANSACTION (or COMMIT WORK or ROLLBACK WORK) command has closed the explicit transaction in progress.

The variable is unaffected by deadlock or implicit transactions.

Example

on deadlock
   if $intransaction = $true
      goto RetryAdd
   else
      goto previous
   endif
endon
   ... other commands ...
RetryAdd:
   transaction
   ... commands in the transaction ...
   endtransaction

In the above example, when a deadlock occurs, $InTransaction determines the course of action that the exception handler takes: restart the explicit transaction (when true) or retry the command that caused the deadlock (when false).

procedure UpdateCode (NewCode) local (DoEndTrans)
   if $intransaction = $false
      transaction
      let DoEndTrans = $true
   endif
   ... other commands ...
   if DoEndTrans = $true
      endtransaction
   endif
endprocedure

In the above example, $InTransaction starts an explicit transaction if one is not already in progress.

COMPUTE

Computes the results of one or more expressions for a set of records.

Syntax

COMPUTE [num] [setspec] EVALUATE clause [-> clause]

Parameters

num	Can be an integer constant (15, 200); a variable, form field, or parameter that evaluates to an integer; the word ALL. If num is omitted, or less than 0, it defaults to ALL.
setspec	The set specification (made up of application documents, EntitySets, relationships, forms, or result sets), designating the records to be changed. If omitted, the current set (if available) is used. Application documents named in the set specification cannot be updated.

Comments

COMPUTE evaluates one or more expressions for a set of records without having to first LIST the data or create a result set of the desired records.

Example

Compute all Employees where LName=Smith \

evaluate \

(let TotSal = $total(Salary)) \

(let MaxSal = $max(Salary)) \

(let MinSal = $min(Salary)) \

(let NoOfEmps = $count(LName)) \

(let AvgSal = $average (Salary))

output TotSal MaxSal MinSal NoOfEmps AvgSal

Processes the EVALUATE clause for every employee whose last name is “Smith”. The OUTPUT command displays the results.

form open dInvoice

form display input

compute fInvItems evaluate (let fInvBott.InvTot = $total(fInvItems.Amt))

form display fInvBott.InvTot

Calls up a display and calculates a total after all items have been added.

INPUT

Gets serial input from the application user.

Syntax

INPUT «target»

Parameters

target

A list of one or more global or local variables, form fields, menu items, parameters, or macros, in any combination. Subscripted (array) variables are valid. Each item must be separated from the next by a space.

Comments

INPUT provides a simple means of reading a line of input from the application user. The line of input is divided into literal strings based on the delimiter character currently in effect. The literals are assigned to the variables and macros specified in target, in order from left to right.

Example

input TestVar fEmpform.LastName Param1 < CommandName> <3>

When the above command pauses for input, the following constants can be input by the application user:

32 Smith abc LIST abc_def

If current delimiter is the space character, the constants are assigned as follows:

TestVar	32
fEmpform.LastName	Smith
Param1	abc
#< CommandName>	LIST
#<3>	abc_def

The following sequence of entries accomplishes the same effect, but uses the comma as the delimiter:

set delimiter “,”

input TestVar fEmpform.LastName Param1 < CommandName> <3>

32,Smith, abc,LIST, abc_def

Attention

When using the following construction, a “:” must be placed at the end of the OUTPUT string:

OUTPUT “Please, respond with Yes or No (Y/N): “;

input vResponse

$random

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

Syntax

$random(number)

Parameters

number

a number, or an expression that evaluates to a number, that acts as a seed for the random number generator

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.

$right

Extracts a segment from the end of a character string.

Syntax

$right(source,length)

Parameters

source	a character string, or an expression that evaluates to a character string
length	a number, or an expression that evaluates to a number

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”.

Syntax

DOWN [num] [setname]

Parameters

num	The number of members farther “down” into setname that the current member pointer is to be moved. Num can be an integer constant (15, 200); a variable, form field, or parameter that evaluates to an integer; the word ALL. The default value for num is 1. If num is negative, DOWN num actually moves the current member pointer “up” in the set.
setname	The name of the result set whose current member pointer you wish to move. If setname is omitted, the current set is used.

Comments

NEXT is a synonym for DOWN.

Example

down 10

Moves the current member pointer 10 members “down” towards the end of the set.

down 5

delete 5

Moves the current member pointer five members “down” and then deletes five members (starting with the new current member).

find Customers -> CustSet

form open fCustomer

form set accelerator F1 F2 Escape

while

change fCustomer from CustSet

form display input

if Event.EventName = “escape”

break

else % use $direction as a handy variable

let $direction = {-1 where Event.EventName = “F1”, 1}

endif

down $direction CustSet

endwhile

Finds a set of customers and then displays the records in the set one at a time.

Syntax

Return Value

Comments

Example

Syntax

Parameters

Comments

Example

See Also

Syntax

Parameters

Comments

Example

See Also

Syntax

Parameters

Return Value

Comments

Example

See Also

Syntax

Return Value

Description

Example

See Also

Syntax

Parameters

Comments

Example

See Also

Syntax

Parameters

Comments

Example

Attention

See Also

Syntax

Parameters

Return Value

Comments

Example

Syntax

Parameters

Return Value

Comments

Example

See Also

Syntax

Parameters

Comments

Example

See Also