Category: ZIM 4GL Language Reference

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.

Example

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

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]")

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

Except in certain limited instances (e.g., security passwords, values held in objects of data type CHAR and VARCHAR), the software is case insensitive. Insensitivity to case means that the software makes no distinction between uppercase and lowercase letters in any part of a statement. For example, the following statements are identical, provided LastName is not a CHAR or VARCHAR field:

list all employees where lastname = ‘smith’

LIST ALL EMPLOYEES WHERE LASTNAME = ‘SMITH’

lIsT aLl EmPlOyEeS wHeRe LaStNaMe = ‘SmItH’

list all employees where LastName = ‘Smith’

Normally, in a statement, you can use the combination of uppercase and lowercase letters that makes the statement most readable.

Any value expression used in an application – including the names of objects that represent values – must conform to one of the available data types.

Data Types and Objects

Objects that represent values (constants, variables, fields and form fields) have an explicit data type attribute defined in the Object Dictionary. Value expressions that are not defined objects take implicit data types. The data type of an object or expression determines the values that an object or expression can represent and how the software handles the value. The software recognizes nine different data types:

Output masks are employed to format the output of fields, form fields, and data values in output operations. The MASK format option in Zim Reports specifies an output mask pattern for a report item. The $mask function specifies an output masking pattern to be applied to fields, form fields, and data values and returns a character string with the result of the masking operation. The Field Mask attribute defines the expected output format of a field’s data value when it is printed or listed in Zim Reports, or by the list or output commands.   Mask patterns used with any of the three options described above are constructed in the same manner using the same set of available characters. However, the set of characters available varies according to the data type of the item being masked. For more information on mask patterns and their relation to data types, see Masking.

Selected Examples of Mask Patterns for Numbers

In the following examples, leading or trailing spaces are indicated by / in the Output column.

Output of Sign Placeholders

Behaviour of Fixed Text Characters

Behaviour of Float Characters

Mask Patterns and the Language Customizer

Certain characters inserted into the output value by a mask are defined internally in the software. The Language Customizer (ZIMLANG) administrative utility is used to redefine the internal characters and strings used by the software in a variety of circumstances, such as output masks.

For example, the currency placeholder $,  is by default the dollar sign $. However, it can be redefined to output other symbols, such as the Euro sign €, the pound sign  £, etc. To achieve this, the Language Customizer can redefine the currency symbol output by the currency placeholder.

When using the Language Customizer to edit the software’s internal characters and strings, note the following:

• In application programs, output masks are always specified using the standard mask pattern characters. This rule applies to mask patterns specified in reports, in field and form field definitions, and in the $mask function.
• In user interface displays and output, the characters output by a mask pattern are determined by the software’s internal values.

For example, in Zim application programs, the dollar sign $ is universally used as the currency placeholder. However, the currency symbol output by the placeholder depends on the current language customization (if any).