Category: ZIM 4GL Language Reference

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.

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

Unlock the Power of Conditional Logic with Zim Case Expressions

Elevate your Zim application development with our powerful case expressions feature. Designed to streamline your coding process and enhance functionality, case expressions provide a robust solution for handling conditional values effortlessly.

Key Benefits:

• Efficient Coding: Simplify your code with concise case expressions, reducing complexity and improving readability.
• Reliable Value Assignment: Ensure non-null values in critical operations, preventing errors and enhancing application stability.
• Dynamic Adjustments: Implement dynamic logic that adapts to changing conditions, delivering flexible and responsive applications.
• Graceful Handling of Missing Data: Provide fallback options for missing values, ensuring comprehensive and informative outputs.

Case Expressions in Zim

Syntax:

{ expression1 , expression2 }

Parameters:

• expression1: Any value expression.
• expression2: Any value expression.

Return Value:

• The value of the first expression that is not $Null.

Technical Expansion:

Evaluation Process:

• Sequential Evaluation: The expressions within the braces are evaluated from left to right. This ensures that the first non-null value is selected, providing a reliable mechanism for conditional value assignment.
• Nested Expressions: Case expressions can be nested, allowing for complex conditional logic to be handled efficiently. This is particularly useful in scenarios where multiple conditions need to be evaluated in sequence.

Usage Scenarios:

• Conditional Value Assignment: Case expressions are ideal for assigning values based on conditions. For example, determining a status based on height:

  let Status = {'tall' where Height > 6, 'short'}

This simplifies the code and ensures that the correct status is assigned based on the height condition.

• Ensuring Non-Null Values: In situations where a field or widget might be $Null, case expressions can provide a default value, ensuring that operations proceed smoothly:

  let Salary = {fAddEmps.Salary, 0}

• Dynamic Action Determination: Case expressions can be used to determine actions based on conditions, such as adjusting a year based on the month:

  break 1
    {$year(InvDate) + 1 where $month(InvDate) >= 5, $year(InvDate)}
    heading ...

• Handling Missing Values: In reports or outputs, case expressions can handle missing values gracefully, providing a fallback option:

  detail line "Employee Number: " {EmpNum, "N/A"}

Advanced Features:

• Platform Independence: Case expressions are versatile and can be used across different platforms, ensuring consistent behavior in various environments.
• Performance Optimization: By minimizing the code required for conditional logic, case expressions can improve the performance of applications, reducing processing time and resource usage.

Experience the Difference: Transform your Zim applications with the efficiency and reliability of case expressions. Whether you’re streamlining conditional logic, ensuring non-null values, or handling dynamic adjustments, our case expressions feature is your key to superior development.

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