Category: ZIM 4GL Language Reference

Writes the BOM preamble to document files.

Syntax

SET UTF8HEADER ON|OFF

Comments

By default, this option is set to ON, meaning, a BOM preamble (3 bytes) is written to document files, indicating a UTF-8 file.

On input, Zim automatically processes the BOM preamble, if any.

Example

set utf8header on
set output MyDoc
list all MyCustomers
set output terminal

The output file will have a 3-byte preamble indicating a UTF-8 file.

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.

Specifies the current input document.

Syntax

SET INPUT docname [FILEPATH options]

Parameters

Comments

The SET INPUT defines an input for subsequent Zim commands referring to the defined docname. The input is maintained open until it is explicitly closed by a SET INPUT TERMINAL or another document name.

Usually, the docname is defined as structured with a big field (big enough for the required application) so that the contents of the records read can be processed.

The FIFO option reads from an internal stack of records previously written via the SET OUTPUT command. The <FIFO name> is any name used to identify this FIFO. Usually, many programs (producers) can write to a FIFO whereas only on program (consumer) can read from a FIFO. It works similarly to an entity set with the difference that all operations are in memory (faster and with no locks) and, once a record is read, that record disappears from the stack. This means that you cannot create a set from these records as they are lost immediately. It’s contents are usually collected via a COMPUTE 1 … EVALUATE or LIST 1 EVALUATE, most of the time, one by one.

Under Windows, if a path contains subdirectories, they must be converted from “/” to “\\”. Otherwise, Windows will interpret them as command switches as seen in the examples below.

Examples

set input MyDoc
list 1 MyDoc
compute 1 MyDoc evaluate (let MyVariable = MyDocField)
... process MyVariable ...
list 1 MyDoc
set input terminal

The above example is very useful as it allows continuous records to be read from MyDoc without starting from its beginning all the time. The first record of MyDoc is listed, the second is processed, while the third is again listed. Finally, the document is closed.

The next example shows the combination of INPUT and OUTPUT documents. The output is MyReport. All records from FirstFile.txt are listed in the output. Then, 20 records from Zimprof are listed. Next, 10 records from SecondFile.txt are listed and, finally, all records from AnotherDoc are also listed. To wrap up, both INPUT and OUTPUT are closed by assigning them to TERMINAL.

set out MyReport
set input MyDoc filepath "file://c:\\myDir\\FirstFile.txt"
list all MyDoc
list 20 zimprof
set input MyDoc filepath "file://c:\\myDir\\SecondFile.txt"
list 10 MyDoc
list all AnotherDoc
set input terminal
set output terminal

This example reads and processes all input arriving from a serial port (only for Linux).

set input MyDoc filepath "port:///dev/tty99:115200:8:N:1:N"
while ...
   compute 1 MyDoc evaluate (let MyVariable = MyDocField)
   ... process MyVariable ...
endwhile
set input terminal

Executes an OS command and captures its output (i. e. STDOUT).

% In this case, data is formatted.
% You can add the lines directly but you need to filter the useful ones.
set input MyDoc filepath "pipe://dir ..\\Images\\*.jpg"
list all MyDoc

Directory: C:\users\cebre\pictures

Mode   LastWriteTime     Length  Name
------ ----------------- ------- -------------------
-a---- 21-Oct-2023 09:45 2885941 20200827_114259.jpg
-a---- 21-Oct-2023 09:42 2555772 20200827_114311.jpg

set input terminal

This example reads and processes records stored in a FIFO:

set input MyDoc filepath "fifo://myfifo"
while ...
   compute 1 MyDoc evaluate (let MyVariable = MyDocField)
   ... process MyVariable ...
endwhile
set input terminal

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

An IN comparison is logically true if expression is equal to at least one of the values in the specified list.
A NOT IN comparison is logically true if expression is not equal to any of the values in the specified list.
In either case, the comparison ends as soon as a logically true instance is found.

The syntax of a call to a procedure is

procname (expression)

Parameters

Comments

The list of expressions must be enclosed in parentheses; even when no expressions are required, the parentheses must still appear.
At the prompt level, you can issue a call to the main procedure of any procedure program.
Within a procedure program, you can issue a call to

• any local procedure in the current program
• the main procedure in the current program
• the main procedure in any other procedure program

Any procedure in a procedure program can issue a call to itself.
In a call to a procedure, you must supply one expression for each parameter specified in the PROCEDURE or LOCALPROCEDURE command that describes the called procedure. The number and type of expressions listed in the call to a particular procedure must match the number and type of parameters in the PROCEDURE command in order for the procedure to execute. The value of expression can be assigned to the corresponding parameter (IN parameters), or expression can take on the value of the corresponding parameter when the procedure ends (OUT parameters), or both (INOUT parameters).
When you specify more than one expression, each must be separated from the next by a comma.

Names for objects defined in the Object Dictionary must conform to the following conventions:

Examples of Object Names

Compare these to the following invalid names:

There are two types of permissions – object permissions (EntitySets, relationships, and directories) and field-level permissions. Field level permissions take precedence over object permissions. The permissions are set as follows: The following chart summarizes the permissions needed in order to successfully execute a given form of data manipulation on an object where permissions are currently in place. Definitions are as follows:

• Owner refers to the user who created an object.
• Group refers to any user who shares a common group ID with the object’s owner.
• Other refers to any user who does not share a common group ID with the object’s owner.

Note: Any user with a GroupID equal to 0 is considered to be a superuser. Superusers are not governed by permissions currently in place on objects, fields, or both. Thus, an object is created by a person logged in as superuser, then permissions applied to the Group are ignored since every user in the creator’s group is a super user. It is not advisable to create objects while logged in as a superuser, in order to take full advantage of Zim’s security features. Different permissions can be assigned to objects, fields, or both for users inside the owner’s group (Group) and to users outside the objects’ owner group (Other).

where R = read, A = Add, C = Change, and D = Delete (1) Null values for all fields with no update permission