Category: ZIM 4GL Language Reference

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

Permissions

A permission mask is assigned to all application directories, to all EntitySets and relationships, and to all fields in EntitySets and relationships. The permission mask indicates the type of access that particular user IDs are to have to the object.

The possible permissions for EntitySets and for relationships are READ, ADD, CHANGE, and DELETE. ADD, CHANGE, and DELETE automatically enable you to READ the data.

The possible permissions for directories and for fields are READ and UPDATE. UPDATE automatically enables you to READ the data.

Ownership

The creator of each directory, EntitySet, or relationship is the owner of that object and of the fields in it. The owner of the Object Dictionary EntitySets, created when the new application database is initialized, is any user whose UserID is 0.

Owners can set and change the permission mask for the objects they own. Individual permission masks can be set for

For example, the owner of an EntitySet can grant permission for all users in his or her group to ADD data to an EntitySet, but might restrict other users (not part of the group) to READ only. In addition, the owner can restrict access to certain fields in the EntitySet: for example, by assigning READ access for users in the group and no access for other users.

Permission Checking

Each time that a user tries to access the data in a directory, an entity set, a relationship, or a particular field, the permission mask that is in force for the object is checked against the system variables $ZUserID and $ZGroupID.

First $ZUserID is checked to see if the user is the owner of the object. If the user is the owner, the object’s owner permission mask is used to determine if the user can perform the requested operation. If the user is not the owner but is in the owner’s group, the object’s group permission mask is used to determine if the user can perform the requested operation. Otherwise, the object’s others permission mask is used to determine the user’s access.

Effects on Commands

The applicable permission mask has an effect on command execution. You must have READ or UPDATE permission to access an application directory. You must have UPDATE permission to CREATE, ERASE, or RENAME objects in an application directory.

For example, if you enter

access EmployData update

change NewEmps1 from Employees

add NewEmps2 from Employees

create index NewEmps2.FirstName

you must have at least READ permission in order to access the directory EmployData. To make changes to the definitions of the objects in that directory, you need UPDATE permission.

You must have READ permission for the two commands involving the Employees EntitySet. In addition, you must have CHANGE permission for NewEmps2 and ADD permission for NewEmps2. You must also have READ permission for any fields in Employees that you are using, and UPDATE permission for the fields in NewEmps1 and NewEmps2 whose values you are adding to or changing.

When you create an index for NewEmps2.FirstName, you must have UPDATE permission for the directory EmployData (assuming that NewEmps2 is defined in that directory).

If you enter

delete all Employees where LName = Smith

you must have DELETE permission for Employees.

If you lack a required permission at the directory, EntitySet, or relationship level, the command does not execute; an error message is issued. If, at the field level, you attempt to read data from a field for which you do not have READ permission, the result you obtain is $Null; if you attempt to assign a value to a field for which you do not have update permission, the assignment is not made. No error messages are issued.

Changing Default or Established Permissions

When an object (other than a directory) is created, it has all possible permission for the owner, READ permission for the owner’s group, and no permission for all others. By default, newly created directories give READ and UPDATE permission to all users.

To change the permission masks, the owner (or the super user) uses the PERMISSION command. The permissions mentioned in the PERMISSION command are always added to the existing permission mask for that object.

In the following example

permission Employees other read add

permission WorkOn group read add change delete

permission Projects other

permission LName group update

permission Salary group other

permission ENum owner read

Employees and Projects are EntitySets, WorkOn is a relationship, and LName, Salary, and ENum are fields. Note that you can leave permissions blank; the affected users cannot access the objects at all.

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

The purpose of this document is to specify how to write a Zim class.

What is the ZCS?

The Zim Class Specification provides a standard for the defining and implementing classes in Zim. Standards have been defined for:

✓ Class Interface

✓ Naming Conventions

✓ Layout and Style

Background

The Zim Class Specification is a refinement of the Zim Object Framework (ZOF). Originally ZOF not only described a method for defining and implementing classes in Zim, but also proposed a framework of base and system classes.

The specification component of ZOF has been extracted and converted to a ’white paper’ called the Zim Class Specification. Any frameworks will be delivered as separate components, written to the ZCS specification. The ZCS specification is evolving and will be enhanced to incorporate other features over time.

Benefits

By using the Zim Class Specification, Zim developers will benefit from employing object based techniques. These benefits include:

✓ Faster development

✓ Increased Quality

✓ Easier maintenance

✓ Enhanced modifiability

✓ Reuse of software and designs, frameworks

✓ Systems more change resilient, evolvable

✓ Reduced development risks for complex systems, integration spread out

✓ Appeals to human cognition, naturalness

Although an object is an instance of a class, it is easier to describe a Zim object first. An object is the encapsulation of attributes and behaviour.

Attributes values are stored on an Attribute Structure implemented using a form entity. State values are also stored on this structure (e.g. object modified).

Behaviour is described by methods, which are executed from a text or binary file.

A class is a template for multiple objects. In Zim, the instantiation of an object occurs when a class is assigned attributes. Only one object at a time can be instantiated. Zim does not currently support multiple instantiation.

Zim Classes can be divided into two main categories, User Interface and Business Classes.

User Interface Classes

User Interfaces (UI) Objects consists of windows, displays, forms, menus, toolbars and the behavioural code to operate these objects. UI Classes provides views of sets produced by Business Classes.

For example, the UI class zCustomerUI provides a view of the set sCustomer produced by zCustomer, a business class. There can be multiple views of the same set, for example zCustomerFormUI, which provides a view of a single record and zCustomerTableUI, which provides a view of multiple records.

There may also be other UI classes that do not provide an interface to a set, for example, a printer set-up dialog.

Business Classes

A business class derives its name from the set. For example, the set sCustomer is encapsulated by the business class zCustomer. Of course a set could be a complex object, for example, Order Header and Order Items which would be translate to the class zOrder.

Attributes and behaviour

To create a class the attributes and behaviour must be described. An attribute structure is defined in the object dictionary for the purpose of storing attribute values – state information and parameters. The attribute structure name is derived from the root class name prefixed with a lowercase ‘a’. For example, the class zCustomer has an attribute structure aCustomer.

The behaviour is described using the Zim language as before. Previously, behaviour was described in procedures and local procedures, behaviour is now described in methods.

Creating a Class

A class in Zim consists of a document and an attribute structure defined in the Object Dictionary. The class declaration is defined in the document text file.

A class declaration:

class zCustomer(viMethod, viSelf) endClass

As you can see PROCEDURE and ENDPROCEDURE are no longer used. These have been replaced with two new keywords CLASS and ENDCLASS. viMethod and viSelf are explained later in this document.

An attribute structure is defined once a class has been created. Attributes store an instance of the data object.

The attribute structure for zCustomer, aCustomer, might have the following fields:

Defining a method

method mAdd(viSelf)
endMethod

The keywords METHOD and ENDMETHOD have replaced LOCALPROCEDURE and ENDPROCEDURE.

The above method declaration does not contain any behaviour. The class zCustomer below shows the class implementation, including behaviour for the add method.

%—————————————————————–
method mAdd(viSelf)
add Customer from aCustomer
endMethod

%—————————————————————–
method mDelete(viSelf)
delete sCustomer where ID = aCustomer.ID
endMethod

%—————————————————————–
method mpCustomer(viMethod, inout vtSelf)
change aCustomer let pMethod = viMethod
endMethod

%—————————————————————–
method mpFinalize(viSelf)
endMethod

%=================================================================
class zCustomer(viMethod, viSelf)
mpCustomer(viMethod,viSelf)
case
when aCustomer.pMethod = ‘add’
  mAdd(viSelf)
when aCustomer.pMethod = ‘ delete’
  mDelete(viSelf)
endCase
mpFinalize(viSelf)
endClass

Method Dispatcher

Method dispatcher calls the appropriate method defined in messages that are sent to the class.

The method dispatcher is placed in the class body as a CASE statement. No behaviour is coded in the method dispatcher, only in the methods of the class.

Public methods, methods that can be called by another class, have a fixed protocol of one parameter, viSelf.

Private methods, methods that can be only called by the containing class, have no fixed number of parameters. These methods are never called in the method dispatcher or in the class body, except for constructor and destructor methods.

Section 4.3 Layout and Style describes a template for the dispatcher.

Constructor and Destructor Methods

Each class has two standard private methods – constructor and destructor.

The constructor method, which derives its name from the base name (e.g. zCustomer – mpCustomer), is invoked when the class is instantiated or called. The destructor method, mpFinalize, executes any clean up operations.

Protocol

A class has two parameters:

viMethod is used to pass the method to be executed by the class. The method is passed to the class as a parameter and is directly assigned to the attribute structure to improve readability and ensure upward compatibility. This notation is similar to other object-oriented languages that reference methods using the dot notation; e.g. customer.add().

viSelf is used to pass the calling class base name. Passing this name allows a super-class that inherits a method to call or access the attributes of the subclass for run-time inheritance.

The base name is the name of the logical class. For example, the logical class CustomerTableUI is implemented as zCustomerTableUI (the class) and aCustomerTableUI (the attribute structure) in Zim.

Please review Section 3.6 for an example of run-time inheritance.

The message to an object consists of:

• data values assigned to the attribute structure

• any named sets

• the class call

• method

• self parameter

Inheritance

Inheritance provides a classification of objects that exploits their commonality. A hierarchy is formed where a child object inherits attributes and behaviour from a parent object. A parent may have many children, and that parent’s parent may have many children.

Figure 1: A class hierarchy

An example of a class hierarchy that is derived from an organization domain may look like this:

Figure 2: Class hierarchy derived from an organization domain

In this example, the Manager object inherits the attributes firstName and lastName from the object Person. It also inherits the methods (behaviour) new (specifies how to create a new person) and applyforLeave.

By creating a hierarchy, the Zim developer can programme by extension rather than by re-invention [LaLonde 90].

ZCS does not define any standard inheritance mechanism. Zim developers can choose between generated (early binding) or run-time (late-binding) inheritance.

Generated inheritance uses the class hierarchy to generate a single executable class from parent source files. For example, zManager maybe generated by three templates, tPerson, tEmpoyee, and tManager to produce one class file.

Runtime inheritance uses the class hierarchy to execute parent classes on the fly. For example, to execute the method applyForLeave, zManager calls zEmployee passing its parameters to the parent class.

The viSelf component of the protocol provides the mechanism for run-time inheritance. In generated inheritance this would be ignored, but not omitted. This allows a generated class library to call a class library based on run-time inheritance.

An Example of Run-time Inheritance

Please note the following is only an example and that the ZCS does not standardise a method for inheritance.

Continuing the example from the previous section, the class zManager inherits the method ’applyForLeave’ from zEmployee.

Figure 3: Manager inherits behaviour from Employee

In this example, the UI component zManagerUI calls zManager to ’applyForLeave’. The call (know as a delegation) within zManagerUI is implemented in Zim like this:

zManager(’applyForLeave’, ’’)

Note that viSelf is blank because the call is made across the hierarchy (a delegated call) not up the tree (an inherited call). The code for zManager appears below. Notice that the method ’applyForLeave’ does not exist in zManager and the method dispatcher calls zEmployee using the otherwise component of the case statement.

Note that zEmployee is an abstract class. This means that the class will only be executed using an inheritance call, not a delegated call. zEmployee is an abstraction of zManager.

The code for zManager is shown below followed by zEmployee.

%—————————————————————–
method mAssignEmployee(viSelf)
add ManagerEmployee from aManager
endMethod

%—————————————————————–
method mpManager(viMethod, inout vtSelf)
change aManager let pMethod = viMethod
let vtSelf = {vtSelf where vtSelf < ’’, ’zManager’}
endMethod

%—————————————————————–
method mpFinalize(viSelf)
endMethod

%=================================================================
class zManager(viMethod, viSelf)
mpManager(viMethod,viSelf)
%Methods
case
when aManager.pMethod = ‘assignEmployee’
  mAssignEmployee(viSelf)
otherwise
zEmployee(aManager.pMethod, viSelf)
endCase
mpFinalize(viSelf)
endClass

%—————————————————————–
method mApplyForLeave(viSelf)
change employee where ID = aEmployee.ID let ApplyForLeave=$true
endmethod

%—————————————————————–
method mpEmployee(viMethod,viSelf)
let = $replace(viSelf, 1, 1 a)
change aEmployee from a# let aEmployee.pMethod = viMethod
endMethod

%—————————————————————–
method mpFinalize(viSelf)
change a# from aEmployee
endMethod

%=================================================================
class zEmployee(viMethod, viSelf)
mpEmployee(viMethod,viSelf)
case
when aManager.pMethod = ‘applyForLeave’
  mApplyForLeave(viSelf)
endCase
mpFinalize(viSelf)
endClass

There are five points to note in the code of zEmployee.

1. mpEmployee moves the attributes across from aManager to aEmployee.

2. zEmployee manipulates the structure of aEmployee only.

3. mFinalize moves the modified attributes back to aManager.

An example of a class library using a complete run-time inheritance mechanism is the ZCL.

Please remember there are other variations of run-time inheritance that can be implemented. For example inheritance may be table driven. A child looks up a parent in a table and then the class is made to the parent. The parent still needs to know the child (for transferring of attribute values) and this is passed via viSelf.

Packages

Packages are a means to group classes into logical groups. The equivalent in Zim is the object directories. The directory allows you to manage a large group of classes and avoid naming conflicts. Classes are created in a directory exactly the same as other Zim objects.

The following table contains a list of the Zim constants, types, locations, and values.