Category: ZIM 4GL Language Reference

Any meaningful combination of the following options can be applied to any value displayed in a report:

Triggers an exception handler in the absence of an exception condition.

Syntax

SET EXCEPTION condition

Parameters

Comments

A SET EXCEPTION command mimics the specified condition, triggering the associated exception handler, if such a handler has been declared (by the ON command). The SET EXCEPTION command cannot be used in the body of an exception handler. The SET EXCEPTION command has no effect on system variables such as $InTransaction, $ErrCode, or $ErrLevel. The SET EXCEPTION command is not affected by the SET RESET and SET RESTORE commands.

Example

localprocedure LocProc (inout $Deadlock)
   on deadlock
      let $Deadlock = $true
      return
   endon
   ... other commands ...
endprocedure
procedure MainProc ()
   on deadlock
      goto RetryTransaction
   endon
   ... other commands ...
RetryTransaction:
   transaction
   ... other commands ...
   LocProc ($Deadlock)
   if $Deadlock = $true
      set exception deadlock
   endif
   ... other commands ...
   endtransaction
endprocedure

In the preceding example, SET EXCEPTION mimics a DEADLOCK condition, triggering the declared deadlock exception handler in one procedure when the deadlock has actually occurred in another procedure.

See Also

ON

A macro is a dynamically declared name that represents a character string. When a macro call is encountered in an application program the macro call is replaced by the current character string value of the macro. Macros are sometimes called replacement parameters or substitution variables.
The following topics discuss how to work with macros in applications:

The name of the file containing the online help.

Syntax

$helpfile

Return Value

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

Description

$HelpFile gives the name of a file containing online help topics.
Set by the application program to the name of a file containing the online help information. By changing the value of $HelpFile, an application can use different help files at different times during a session. The default help file is ZIM.HLP.
The file name should include the directory path. The special file path indicator characters can be used.

Example

let $helpfile = "c:\myapp\applic.hlp"

Although every application has its own unique requirements, the individual components of applications are often very similar. For example, menus, pop-up windows, and data entry forms and displays are common components of most applications. Pop-up windows, for instance, can vary in size, location and contents, but the commands to present them to the application user and to process the result of user interaction are essentially the same. While Zim provides a great deal of flexibility in how applications can be designed and developed, experienced Zim programmers typically develop a programming style for various components of their applications. Consistency of style means that the application program code for one application object can be copied and modified when another, similar object is needed. If a new pop-up window is needed, for example, the object definition and processing code for a similar, existing pop-up can be copied, and the necessary minor changes made. This approach can reduce development time considerably.

Template Definition

The template feature for Zim is a formal mechanism for producing reusable program code. A template is an application program that contains the basic code for defining, presenting, and processing an application component such as a standard pop-up window. In addition, the template contains fragments of code that

• customize the basic code
• generate the application objects (e.g., windows, forms, variables) needed by the application components

Template Syntax

A template is similar to any other application program, in that it contains a series of command statements. However, a template is also different, in that it contains sections of code bounded by special template delimiters: << and >>. The template delimiters are always placed at the start of a line; nothing else should appear on the same line. In this example,

… commands 1 …

<<

… commands 2 …

>>

… commands 3 …

the software handles the command statements that appear between the template delimiters differently depending on if the program is being executed, parsed, or compiled, or if it is being run under the GENERATE command. During normal execution, commands 1 and commands 3 execute normally. Commands 2 are ignored. With the PARSE or COMPILE command, commands 1 and commands 3 are parsed or compiles in the usual manner. Commands 2 are ignored. With the GENERATE command, commands 1 and commands 3 execute normally. Commands 2 are sent as output, after macro substitution, to the current output device.

Program Call Syntax

The syntax of the call to the template program in the GENERATE command is identical to the structure of a call to a standard application program of the same type. The rules for passing values to the parameters in a template program containing a formal procedure operate in exactly the same way as for an application program containing a formal procedure.

Program Execution

Program execution is handled slightly differently under GENERATE. Execution always proceeds interpretively, even if the template program has been compiled. When the software encounters the << template delimiter alone on a line, execution is suspended, and the subsequent lines are written – after macro substitutions – to the current output destination. Execution resumes when the software encounters the >> template delimiter alone on a line.

Physical Line Handling

Normally, each physical line in the template is sent as a separate line to the current output destination. To cause successive physical lines in the template to be joined into one line in the output, end the appropriate lines in the template with the dollar sign ($). At the output destination, the physical line containing the dollar sign and the next physical line appear concatenated on one physical line. If a line must end with a dollar sign for another reason, direct the software to interpret the dollar sign literally by placing a backslash (\ – Escape) preceding the dollar sign.

A variable is a programming object defined in the Object Dictionary for the application.
Variables are used to store values temporarily during an application session.
A variable is assigned a size and a data type in its definition, but until assigned a value during an application session, the variable is valueless (that is, $Null).

Value expressions represent character or number values.
A value expression is an expression that, when evaluated, yields either a number or a character string.
Value expressions are subdivided into

• atomic expressions
• arithmetic expressions
• functional expressions

A value expression can be very simple, containing only one argument. Such expressions are called atomic expressions. An atomic expression is a value expression that consists solely of
literals (explicit numbers or character strings)
permanent object names (constants, global variables, system variables, fields, form fields)
temporary names (local variables, parameters)
Value expressions can also be quite complex, containing many arguments combined by means of arithmetic operators (arithmetic expressions), or software functions (functional expressions), or both. Parentheses can be used to explicitly control the order of evaluation in complex value expressions.
When a statement contains a value expression, the software evaluates the expression and returns the resulting value. Consequently, a value expression can be used almost anywhere that you can use a literal.

Assigning and Reassigning Values to Atomic Expressions

An atomic expression is a value expression that consists solely of a literal constant, named constant, variable name (including subscript, if applicable), field name, form field name, or formal parameter name.
During an application session, an application program can explicitly set and reset the values of certain atomic expressions, specifically: global and local variables, selected system variables, parameters to formal procedures, and macros. The command that explicitly assigns values to these expressions is the LET command.
Note: To assign values to database fields, you must use an ADD, CHANGE, INSERT, or UPDATE command (which can contain LET as a subcommand).
The LET command can be used as shown in the following example:
let var1='abcd' var2=10.5 var3=var4
The LET command can also make its assignments during the evaluation of a complex value expression that appears within another command statement. The special assignment expression format is created by enclosing the LET command in parentheses.

How To Use Literal Constants

A literal constant is a number or character string written directly into an application program.

Writing Valid Number Constants

Number constants can consist only of the digits 0 to 9 and a decimal point (if required).
Number constants are automatically assigned the data type VASTINT and the number of decimal places shown in the number (if any).

Writing Valid Character Constants

Character constants can contain any digits, letters, or symbols, including reserved characters and hex codes.
Character strings should be enclosed in quotation marks (either single or double), but the quotation marks can be omitted if the string contains only digits, letters, dollar signs ($), and underscores (_), and if the string is not identical to a reserved word.

Examples of Number Literals

3.14159
10
.999

Examples of Character Literals

abcde
"$10.99"
1234A
""

The Report Generator takes a report specification and creates a report for viewing or printing.
The elements that must or can be provided to the Report Generator in the report specification are

How To Construct Report Specifications

A report specification is a series of commands that describe the set of data to be used in the report, the values to be extracted from the data set, and the formatting to be applied to each value and to the report in general.
The general form of a report specification is
REPORT FROM…
report commands
ENDREPORT
Reports can be line-oriented or column-oriented in their formatting.

How To Use Report Commands

Between REPORT FROM, that initiates the report and specifies the set of database records on which the report is to be based, and ENDREPORT, that marks the end of the report specification, any meaningful combination of the following commands can be used.

REPORT HEADING, REPORT FOOTING

Identifies and formats the data that is to appear at the very start and end of the report.
Always line-oriented by default, even in column-oriented reports. Can be column-oriented if desired.

PAGE HEADING, PAGE FOOTING

Identifies and formats the data that is to appear at the top and bottom of each page of the report.
Always line-oriented.

PAGE LEFT, PAGE RIGHT

In column-oriented reports, specifies “headings” that are to appear at the left-hand and right-hand sides of each page of the report.

DETAIL LINE

Extracts and formats values from the set of records specified in the REPORT FROM command, and manages the headings for each set of values.
Obeys the orientation specified in the REPORT FROM command.

BREAK

Specifies the conditions for dividing detail lines into groups and subgroups, and specifies the headings and footings that are to be output for each group.
The break headings and footings obey the orientation specified in the REPORT FROM command. In column-oriented reports, break headings and footings can be line-oriented if desired. Break headings and footings can differ in orientation.

COLUMN BREAK

In column-oriented reports, specifies the headings and footings that are to be output each time DETAIL LINE values carry over to a new tier of the report.

How To Specify the Report Set

The set specification is specified in the REPORT FROM command.
Only those records that fit the set specification are reported. One DETAIL LINE is produced for each record. The records are reported from top to bottom in sequential order. Typically, therefore, the set specification includes a SORT clause to place the records into a logical order.
Sorting is essential if breaks are to be included in the report. (As each record is processed, the break indicator is checked to determine whether a break has occurred.)

How To Specify Report Headings and Footings

Report headings are specified in the REPORT HEADING command; report footings, in the REPORT FOOTING command.
Report headings are processed before any records identified by the set specification are read.
The items specified in the report heading are output only once, at the start of the report.
Report footings are processed after all records identified by the set specification are read.
The items specified in the report footing are output only once, at the end of the report.

How To Specify Page Headings and Footings

Page headings and footings are specified in the PAGE HEADING, PAGE FOOTING, PAGE LEFT, and PAGE RIGHT commands.
Page headings and footings are processed when a page boundary is reached.
The items specified in the page headings/footings are output on every page of the report. The values can vary, however, depending on the source of the items (e.g., the current member from the set specification) and their format (e.g., NOPRINT, SUPPRESS).

How To Specify Breaks and Break Headings and Footings

Breaks, with their associated headings and footings are specified in the BREAK (Reports) command.
Breaks are processed when the break indicator expression changes in value. Many break levels can be specified in one report. Break headings and footings are processed when a break occurs at the corresponding level.
The items specified in the break heading are output when the first record of the set specification is processed, and when the first record of each new break group is processed. The values can vary, however, depending on the source of the items (e.g., the current member from the set specification) and their format (e.g., NOPRINT, SUPPRESS).
The items specified in the break footing are output when the last record of each break group is processed, and when the last record of the set specification is processed. The values can vary, however, depending on the source of the items (e.g., the current member from the set specification) and their format (e.g., NOPRINT, SUPPRESS).

How To Specify Item Position and Format

The items output by the various report commands can be explicitly specified, drawn from the records identified in the set specification, or produced by the evaluation of an expression that involves groups of such values, plus operators and functions, as desired.
Each item is individually positioned and formatted using report format options.
Other formatting of items can be accomplished using character functions such as $trim and $concat.

How To Specify the Report Page Structure

The general structure of a report page is specified in the REPORT FROM command.
Structural details that can be controlled include the overall width and depth of the page, the four margins (top, bottom, left, and right), the spacing between subsequent items on the same line, and the orientation of the entire report (line-oriented or column-oriented).

Conditional expressions use the conditional operators to compare operands (typically, value expressions). When evaluated, conditional expressions yield a logical result (true or false), depending if  the condition is satisfied.

Conditional Operators

Note: The AND and BETWEEN expressions are not the Boolean AND.

Examples of Conditional Expressions

EmpNum > 1254

Logically true when EmpNum is 1254.

DepNum >= EmpNum

Logically true when DepNum is greater than or equal to EmpNum

FirstName = ‘Smith’

Logically true when FirstName is Smith.

DeptDesc <> ‘Sports’

Logically true when DeptDesc is anything but Sports.

EmpNum between 1000 and 2000

Logically true when EmpNum is in the range 1000-2000.

LastName like ‘% ith$’

Logically true when LastName matches the given pattern.

Event.EventName in (‘F1′,’F2′,’Escape’)

Logically true when EventName is in the list.

>ProdCode not between 542 and 863

Logically true when ProdCode is outside the range 542-863.

LastName not in (‘Smith’,’Jones’)

Logically true when LastName is not in the list.

FirstName not like ‘ Sm%’

Logically true when Firstname fails to match the pattern.
Simple conditional expression can be combined into more complex Boolean expressions by using Boolean operators. Also, the Boolean NOT can be used to achieve the same result as the NOT version of BETWEEN, LIKE, and IN.

Boolean expressions use Boolean operators to compare operands (typically, conditional expressions). When evaluated, Boolean expressions yield a logical result (true or false), depending on the nature of the Boolean operator and the values of the conditional expressions.
The standard rules of precedence for Boolean evaluation are used.
The software ceases to evaluate a Boolean expression as soon as the final result can be correctly predicted. For example, with OR, if the first conditional expression is logically true, then the Boolean expression must be logically true. The software does not bother to evaluate the remaining conditional expressions.
In the expression

LastName = ‘Smith’ or DeptNum = ‘Sports’

if LastName = ‘Smith’ is logically true, then DeptNum = ‘Sports’ is not evaluated.

Note: Taking Boolean evaluation logic into account can be important to the functioning of an application program. For example, if any of the value expressions in the Boolean expression is written in the special assignment format, the assignment is not made if the portion of the Boolean expression containing the assignment is not evaluated.

Boolean Operators