Category: Functions

Updates a JSON record.

Syntax

$updatejson(source, selection-criteria, replacement)

Parameters

Return Value

The character string after applying the replacement. If there are no matched criteria or if the source does not contain a well-formed JSON data structure, a $NULL value is returned.

Comments

If the selection-criteria is $null or a zero-length string, the replacement is appended to the JSON string.

If there is a selection-criteria, but the replacement is $null or a zero-length string, the entire portion belonging to the selection is deleted.

If both the selection-criteria and the replacement are not zero-length strings, the selection is found in the source and replaced by the replacement.

Example

Given the following JSON record:

out $updatejson('{"Example": ["Total": 123,"Title": "XYZ"]}',"", '"Sum": 456')

Will produce the output:

{"Example": ["Total": 123,"Title": "XYZ","Sum": 456]}

$updatejson('{"Example": ["Total": 123,"Title": "XYZ"]}',"Total", "")

returns:

{"Example": ["Title": "XYZ"]}

Replacing the keyword and its contents:

out $findjson('{"Example": ["Total": 123,"Title": "XYZ"]}',"Title", '"Sum": 456')

Outputs:

{"Example": ["Total": 123,"Sum": 456]}

See Also

$getjson

Conditional Color Assignment Using $rgb()

Purpose

In Zim, you can use conditional logic to dynamically change the color of form objects based on runtime conditions such as user input, system status, or validation results. This is achieved using the if, elseif, else, and endif control structures in combination with the $rgb function.

Syntax

if condition
    action
elseif condition
    action
else
    action
endif

Example: Status-Based Field Coloring

if $status = "error"
    form set (fillcolor rgb $rgb(255, 0, 0)) MyForm.MyFormField
elseif $status = "warning"
    form set (fillcolor rgb $rgb(255, 165, 0)) MyForm.MyFormField
else
    form set (fillcolor rgb $rgb(0, 255, 0)) MyForm.MyFormField
endif

Explanation

• If the status is "error", the field is colored red.
• If the status is "warning", the field is colored orange.
• For all other statuses, the field is colored green.

Use Cases

• Form validation feedback (e.g., highlight invalid fields).
• User role–based UI customization (e.g., different colors for admin vs. guest).
• System alerts and notifications (e.g., color-coded warnings).
• Real-time sensor feedback (e.g., temperature thresholds triggering color changes).

Best Practices

• Keep RGB values consistent with your UI design system.
• Use descriptive variable names for conditions.
• Avoid deeply nested conditionals—break logic into reusable procedures if needed.

Reads a text file containing a JSON structure and places its compressed contents in a variable.

Syntax

$getjson(<a variable>, <a document name>)

Parameters

Return Value

It always returns a single character with the value “0”.

Comments

The receiving variable name must be large enough to hold the entire compressed JSON text file. It will also contain the string “ZIMJSON” as an indication that the text was obtained from a text file and that it is compressed.

The function $GetJSON does not validate the JSON syntax present in the document. Therefore, the function can also be used to compress any kind of text file.

Example

Given the following JSON file pointed by a ZIM:X document called MyDocument:

{
    "employee": {
        "name":       "sonoo",
        "salary":      56000,
        "married":    true
    }
}

The command:

OUT $GetJSON(MyVar3000, MyDocument)

Will return:

ZIMJSON = {"employee":{"name":"sonoo","salary":56000,"married":true}}

See Also

$findjson

Finds data within a JSON record using selection criteria.

Syntax

$findjson(source, argument-1, argument-2, ..., argument-n)

Parameters

Return Value

The character string resulting from all arguments searched in succession. If there are no matched criteria or if the source does not contain a well-formed JSON data structure, a $NULL value is returned.

Comments

The source must contain well-formed JSON data according to the JSON protocol; otherwise, a $NULL value is returned by the function.

Example

Given the following JSON file:

out $findjson('{"Example": [123,"XYZ"]}',"Example")

Will produce the output:

[123,"XYZ"]

because the selection criteria was the entire “Example” index. However:

out $findjson('{"Example": [123,"XYZ"]}',"Example[2]")

returns:

"XYZ"

The above example is equivalent to:

out $findjson('{"Example": [123,"XYZ"]}',"Example", "Example[2]")

If you don’t know the index name of the JSON string:

out $findjson('{"Example": [123,"XYZ"]}',"")

Will produce the output:

"Example"

See Also

$getjson

A temporary file system path where ZIMQTC stores intermediate files and caching information.

Return Value

A character string. Cannot be reset by an application program.

Description

This file path usually points to the Users directory (locally) in the client machine and is accessible by the user running ZIMQTC as the sole owner of the files therein.
It can be used to store files needed by the Zim application as the means of having an intermediary point between the client machine and the server machine. Notice that the address set to $UserPath may change from session to session and may contain files that are only valid during the current session.

See Also

$ClipPath
$DBPath
$ImagePath
$WorkPath
$ZimPath
$StartPath

The function $escapeXML translates the parameter looking for characters that might disrupt a XML output.

Syntax

$EscapeXML(expression)

Parameters

Return Value

A character string translated according to XML standards.

Example

OUT $ESCAPEXML("ab<cd")

ab<cd

See Also

SET OUTPUT FORMAT XMLSIMPLE

SET XML ROWELEMENT

SET XMLHEADER

Returns the number of members in a result set.

Syntax

$lastmember(setname)

Parameters

Return Value

Number with no decimal places.

Comments

$lastmember returns the (numerical) position of the last member in the specified result set (in effect telling you how many members the set contains). To explicitly specify the current set, use “CurrentSet”, including the quotation marks, as the function is expecting a character string, and CurrentSet is a reserved word.

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 $lastmember works on only the most recent version of the set.

Example

To display the number of members in Set1, enter

output ($lastmember("Set1"))
25 % Displays the number of members in Set1.
procedure ProcessSet ()
   if $lastmember("EmpSet") = 0
      return
   endif
   ...more commands...
endprocedure

If a procedure processes a set created elsewhere, it is not necessary to pass the size of the set as a parameter; $lastmember can be used instead.

See Also

$currentmember

$SetCount

About Functional Expressions

Centers a non-blank character string.

Syntax

$center(string) | $centre(string)

Parameters

Return Value

Character string, consisting of string centered in a space $length(string) characters long. Leading or trailing blanks in string are ignored during centering. If string contains an odd number of characters, it centers with a bias to the left.

Comments

String is centered in an area that is $length(string) characters long. All leading and trailing blanks in string are ignored. If string contains an odd number of characters, the string is centered with a bias to the left.

Example

$center("abcde ")

Evaluates to ” abcde “. Centering five characters in a 10-character field produces a string that contains two spaces on the left and three spaces on the right.

$center(var3)

Evaluates to ” 3 “. If var3 is an INT variable whose value is 3, the resulting value is a string of eight characters, with three spaces to the left of the 3 and four spaces to the right. (INT values occupy eight character spaces when converted to character strings.)

See Also

$leftjustify

$length

$rightjustify

About Character Literals

About Data Types

About Functional Expressions

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.