Categoria: ZIM 4GL Language Reference

Presents online help information.

Syntax

HELP [topic]

Parameters

For files that invoke the winhelp executable

Note: For Explorer-style hypertext Help files, topic is a character string or a number, or an expression that evaluates to a character string or a number which identifies a particular help topic in the help file. It invokes the name of one of the .html files that were used to build the . chm file.

Comments

The HELP command displays online help about a given topic. By default, the command accesses the help file, ZDL.CHM, in the directory containing the software. To use another help file, set the system variable $ HelpFile to the name of the desired help file.

In the Windows environment, the HELP command determines, based on the extension of the help file, whether to invoke the Internet Explorer’s hypertext help viewer ( hh.exe) or to invoke the Windows help driver ( winhelp.exe) to display the help topics.

Winhelp help files

If the help topic is specified as a character string, the HELP command passes the string to the help driver as a keyword. If an exact match is not found, the help driver displays a warning message, following the topic search window.

If the character string contains the pattern-matching wildcard character $, HELP passes the string to the help driver, up to the first $ character, as a keyword prefix. Keywords that match the prefix are displayed in a topic search window for selection.

If the help topic is specified as a number (any numeric data type), HELP passes the number to the help driver as a topic identifier. If the identifier is invalid, the help driver displays a warning message, followed by the topic search window.

If no help file can be found, the software raises an error.

Hypertext help files

The hypertext help viewer accepts only strings as topic names and they must match the html files that were used to build the . chm file.

See Also

$HelpFile

Starts and defines a procedure.

Syntax

PROCEDURE procname ([IN|OUT|INOUT] parm) [LOCAL (var)]

Parameters

Comments

PROCEDURE declares the start of a procedure program. (A procedure program can have many local procedures, but only one main procedure.)

The call to the procedure must contain a corresponding expression for each parameter. The order of the expressions in the call must match the order of the parameters in the procedure declaration. If the number of expressions in the call differs from the number of declared parameters, then the call is ignored. Within the procedure, formal parameters are treated as if they were variables.

A PROCEDURE command must always have a corresponding ENDPROCEDURE command that marks the end of the procedure.

The number of formal parameters, plus the number of local variables, must not exceed the maximum parameters entry in the configuration file. The parameter size entry in the configuration file determines the maximum size of each formal parameter and local variable.

Example

procedure MyProc (item1, in item2, out item3, inout item 4)

Item1 and item2 are formal IN parameters, item3 is a formal OUT parameter, and item4 is a formal INOUT parameter.

procedure Summarize (DeptName, out AvgSalary) local (WorkVar)

WorkVar is a local variable (known only to procedure Summarize).

See Also

LOCALPROCEDURE

Defines and marks the start of a local procedure within an application program.

Syntax

LOCALPROCEDURE procname> ([IN|OUT|INOUT] parm)[LOCAL(var)]

Parameters

Comments

The body of a local procedure is a sequence of commands. A LOCALPROCEDURE must always end with a corresponding ENDPROCEDURE command.

Local procedure declarations must appear at the beginning of their application program document, before the main procedure or before the commands of a macro program. A local procedure cannot be nested within the body of another procedure or local procedure. Local procedures obey all the same call/return rules as standard procedures, and possess the same capabilities as a standard procedure.

A local procedure can call other procedures in the same application program document or in other program documents. However, a local procedure can be called only by other procedures defined in the same program document.

Example

localprocedure LocalProc1 ()

 transform LocalProc2 ()

endprocedure

%——————————————-

localprocedure LocalProc2 ()

 output “Hi from LocalProc2”

endprocedure

%——————————————-

procedure MainProc (Param1, Param2)

  LocalProc1 ()

  LocalProc2 ()

endprocedure

The main procedure calls two local procedures. The first local procedure transfers control to the second through a TRANSFORM command.

See Also

ENDPROCEDURE

PROCEDURE

Breaks the body of column-oriented reports into summary groups.

Syntax

COLUMN BREAK level [HEADING reportitem [:format:]]

[FOOTING reportitem [:format:]]

Parameters

Comments

The COLUMN BREAK command breaks the body of a column-oriented report into summary groupings.

Each time a BREAK command triggers a break at a specified level, the COLUMN BREAK for that level and all levels lower in the hierarchy are triggered.

Report items in the COLUMN BREAK heading can include individual values from the first member of the current group. Report items in the COLUMN BREAK footing can include individual values only from the last member of the current group. However, summary data computed over all members of the group can be displayed in the footing. Use aggregate functions.

If both the heading and footing clauses are omitted, a column break at the indicated level causes report formatting to recommence at the left-hand side of the page, beneath any previously formatted columns.

See Also

DETAIL LINE

ENDREPORT

REPORT FOOTING

REPORT FROM

REPORT HEADING

Enables conditional execution of commands.

Syntax

CASE

WHEN expression

commands1

[OTHERWISE

commands2]

ENDCASE

Parameters

Comments

A CASE command must always have a corresponding ENDCASE. Any number of WHEN clauses can appear between CASE and ENDCASE.

The WHEN phrases between CASE and ENDCASE are evaluated in order. Execution control transfers to the commands associated with the first WHEN clause whose expression is determined to be logically true. If none of the WHEN phrases contain an expression that evaluates to “true”, the commands associated with OTHERWISE (if used) are executed. Execution then resumes at the first command following ENDCASE.

If a WHEN expression includes fields from the current set, then the expression uses the values found in the current member of the current set.

If a BYE, RETURN, STOP, or TRANSFORM command exits a procedure in the middle of a CASE structure, the “open” CASE command is automatically closed. Also, if the end of the current procedure is reached before a necessary ENDCASE is encountered, the “open” CASE command is closed.

If the ENDCASE is missing, all subsequent commands in the current procedure are treated as part of the CASE structure.

Example

If the value for salary is neither less than 20,000, nor between 20,00 and 30,000, the first and second set of commands are skipped, and the third set of commands executed.

case

when salary < 20000

… first set of commands …

when Salary between 20000 and 20000

… second set of commands …

otherwise

… third set of commands …

endcase

The following program fragment illustrates how WHEN conditions in a CASE command can handle an application user’s choice of accelerator keys in an application. Depending on the key pressed by the application user, a particular procedure is executed.

form display input

case

when Event.EventName = “F3”

return

when Event.EventName = “F1”

AddNewRecord ()

when Event.EventName = “F2”

ChangeRecord ()

when Event.EventName = “F4”

DeleteRecord()

otherwise

GiveHelp ()

endcase

Finds records that match specified conditions, producing a result set.

Syntax

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

Parameters

Comments

Sets found using the FIND command are not stored permanently; they exist only for the current application session or until a DISPOSE SET command is executed.
If the -> clause is omitted, a result set is still produced. The unnamed result set can be referred to as CurrentSet for as long as it remains the current set.
Changes made to a record in an EntitySet or relationship are reflected in the result set, and vice versa.
$ SetCount and $ MemberCount are assigned a value equal to the number of members in the result set found by the FIND command.

Example

To find all employees whose last name is Smith, enter

find all Employees where LastName = “Smith” -> SmithSet

If you are working interactively at the command prompt, you could find it convenient to use the current unnamed result set when narrowing down a set of records. In the repeated FIND command, the second and third commands use the current set as their implicit setpsec:

> find Employees where Location = “Canada”

2019 selected

> find where LastName = “S”?

146 selected

> find where DeptNum = “D01”

7 selected

The name CurrentSet can also be used explicitly.
In application programs, you should explicitly name the result sets that you create with a FIND command. This technique is especially useful if you plan to compile a program that contains FIND commands:

procedure GetSet1 (a, b)

if a=b

find all Employees WorkIn Department -> KeepEmps

else

find all Employees WorkIn Department where LastName = a -> KeepEmps

endif

list all KeepEmps

endprocedure

You can use the FIND command to locate data, as shown in the following example:

find all Employees where LName = fEmployees.LastName

if $ setcount > 0

list all

else

  output “Nobody who works here is named: ” fEmployees.LastName

endif

You can also use FIND with forms as shown below:

find fItems where fItems.Qty > 0  % find values entered

See Also

$MemberCount

$SetCount

COMPUTE

INTERSECT

MINUS

UNION

Grants permission to other users to access your data.

Syntax #1

Sets permission for access to EntitySets or relationships.

PERMISSION object who [READ] [ADD] [CHANGE] [DELETE]

Parameters

Syntax #2

Sets permission for access to fields or application directories.

PERMISSION object who [READ] [UPDATE]

Parameters

Comments

Only the owner of an object can reset that object’s permissions.

To access a directory, you must have READ or UPDATE permission. To CREATE, ERASE, or RENAME objects in a directory, you must have UPDATE permission. By default, all users have UPDATE permission in a directory.

Example

permission Employees owner add change

Gives only add or change permission to the owner.

permission Employees other

Gives no access by users outside the owner’s group.

permission Employees.LastName group read update

Users in owner’s group can read but not update.

permission MyDir group update

permission MyDir other

Users in the owner’s group can read the MyDir directory and can create, erase, or rename objects in it. Other users are to have no access to MyDir.

See Also

object permissions

Enables repeated execution of a block of command.

Syntax

WHILE [expression]

commands

ENDWHILE

Parameters

Comments

The WHILE … ENDWHILE structure enables a block of commands to be repeatedly executed, as long as expression is logically true.

As soon as the software detects that expression is logically false, execution resumes at the first command following the ENDWHILE. To exit a loop before expression evaluates to false, use a BREAK command.

An open WHILE loop is automatically closed if

• you exit a procedure in the middle of a WHILE structure (using a BYE, RETURN, STOP, or TRANSFORM command), or
• a procedure ends before the ENDWHILE is encountered.

Example

% Commands to select and display form fDispEmp

%

——————————————————————-

find all Employees       % Create set of all Employees

while $setcount > 0      % Loop until end of set

  change fDispEmp from current  % Fill form with emp. data

  form display nolabel input    % Display form and start input

  if Event.EventName = “Escape”  % Check for Escape key

  return           % If so, finish

  endif

  if ThisForm.FormChanged = $true % Check if data modified

  change current from fDispEmp % Update current member

  endif

  next            % Go to next record

  let $setcount = $setcount – 1   % Decrement $setcount

endwhile

while Age > 20

 … other commands …

% Missing endwhile statement

… more commands …

last command in procedure

In the preceding example, the commands subsequent to the missing ENDWHILE command are executed as if they were a part of the WHILE structure. When the end of the procedure is reached without encountering the necessary ENDWHILE, it generates an error message.

form open fCustomers

while

 form display input

 … more commands …

 if Event.EventName = “Escape”

  break

 endif

…more commands …

endwhile

Notice in the preceding command that a BREAK (or BYE, RETURN, STOP, or TRANSFORM) command is required to exit a WHILE loop that contains no logic expression.

See Also

Boolean Expressions

Conditional Expressions

CONTINUE

Lists data from the database.

Syntax

LIST [ num] [ setspec] [EVALUATE clause ] [FORMAT expression [HEADING expression]] [-> clause]

Parameters

Comments

The LIST command outputs num members of source to the current output device (usually the terminal).

By default, each column has a heading consisting of the field name. Headings can be suppressed using the SET HEADINGS command.

The width of each column is determined by these rules:

• Unless a “LIST width” has been defined, character values occupy a width equal to their defined object length.
• Unless a “LIST width” has been defined, number values are converted to their character equivalents, using the maximum width required for the particular data type (e.g., INT converts to eight characters).
• If defined, the “LIST width” determines the width of a column (if 0 or $Null, the implicit width is used; if -1, the field is not LISTed).
• If headings are to be output, widths are appropriately extended for longer headings.
• If a character-manipulating function reduces the length of values being output, the output width is not reduced.
• The $toalpha and $tocharacter functions can be used to specify the width of a column in LISTed output.

The HEADING option, always used in conjunction with FORMAT, establishes the heading that will be displayed above the corresponding expression, in place of any other heading that ZIM otherwise would be displaying. This option particularly useful whenever the expression is not a single field, thus normally not displaying any headings.

Output is also controlled by the SET PAGESIZE, SET PAGEWIDTH, and SET PAUSE commands.

Example

list all Employees format LName FName (($date – BirthDate)/365)

The complex expression is enclosed in parentheses.

list all Employees format LName heading “LastName” FName(($date-BirthDate)/365)

It will list three fields whose headings are: “Last Name”, “FName” and “Age of Employee”.

list

The current member of the current set is listed.

list all format $count(“”) LName FName Age

All members of the current set are listed with sequence numbers.

See Also

OUTPUT

REPORT FROM

SELECT

SET PAGESIZE

SET PAGEWIDTH

SET PAUSE

Produces or deletes object dependency information.

Syntax

DEPENDENCY [RESET] [FOR] [object]

Parameters

Comments

Object dependency information is captured during ERASE, CREATE, COMPILE, and PARSE commands if a SET DEPENDENCY ON command has been issued. The DEPENDENCY command either deletes this information or sends it to the current output. When dependency information is output, each dependency occupies one line and the output contains the following fields:

Example

Consider a one-line application document called Test:

list e1

To produce dependency information for Test, enter

> set dependency on      % on by default

> parse TestProg

> dependency for TestProg

that outputs

O Test Document ZIM ZIM Directory ZIM

P Test Document ZIM ZIM Directory ZIM e1 EntitySet ZIM ZIM Directory ZIM

See Also

$compilestatus

COMPILE

PARSE

SET DEPENDENCY

SET OUTPUT

SET XREF