Category: Functions

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

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.

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