Category: Commands

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

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.

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: