ThisMenu

A data structure that provides information about the state of the system and of the current menu at the time of the last event in that menu.

The ThisMenu data structure provides information about the state of the system and of the current menu at the time of the last event in the current window.

The ThisMenu structure contains a number of fields that are reset when the current window changes. An application program can use the information in the fields to determine what action, if any, to take.

The fields in the ThisMenu structure are:

MenuChanged, MenuItemNum, MenuItemTag, MenuNum, MenuTag

Syntax #1 – MenuChanged

Indicates if any menu item in the current menu had been modified by the application user at the time of the last

thismenu.menuchanged

Return Value

“1” ($True), or “0” ($False). Can be reset by an application program.

Description

Set to “1” ($True) if the value of any menu item in the current menu changed after the application user was placed in control of the interface. Otherwise, set to “0” ($False).

Syntax #2 – MenuItemNum

The identification number of the selected menu item on the menu at the time of the last event in the current window.

thsimenu.menuitemnum

Return Value

A number. Can be reset by an application program.

Description

The identification number of the selected item on the menu at the time of the last event in the current window.

The combination of ThisMenu.MenuItemNum and ThisMenu.MenuNum can uniquely identify a particular menu selection.

Syntax #3 – MenuItemTag

The tag of the selected menu item on the menu at the time of the last event in the current window.

thismenu.menuitemtag

Return Value

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

Description

The identification tag of the selected item on the menu at the time of the last event in the current window.

Syntax #4 – MenuNum

The identification number of the current menu at the time of the last event in the current window.

thismenu.menunum

Return Value

A number. Can be reset by an application program.

Description

The identification number of the current menu at the time of the last event in the current window.

The combination of ThisMenu.MenuItemNum and ThisMenu.MenuNum uniquely identify a particular menu selection.

Syntax #5 – MenuTag

The tag of the current menu at the time of the last event in the current window.

thismenu.menutag

Return Value

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

Description

The identification tag of the current menu at the time of the last event in the current window.

See Also

FORM INPUT

FORM SET

MENU INPUT

MENU SET

SCREEN CLEAR

SCREEN RESET

ThisForm

ThisWindow

WINDOW CLOSE

WINDOW OPEN

WINDOW SET

WINDOW SET CURRENT

Grants permission to other users to access your data.

Syntax #1

Sets permission for access to EntitySets or relationships.

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

Parameters

Syntax #2

Sets permission for access to fields or application directories.

PERMISSION object who [READ] [UPDATE]

Parameters

Comments

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

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

Example

permission Employees owner add change

Gives only add or change permission to the owner.

permission Employees other

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

permission Employees.LastName group read update

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

permission MyDir group update

permission MyDir other

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

See Also

object permissions

Enables repeated execution of a block of command.

Syntax

WHILE [expression]

commands

ENDWHILE

Parameters

Comments

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

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

An open WHILE loop is automatically closed if

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

Example

% Commands to select and display form fDispEmp

%

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

find all Employees       % Create set of all Employees

while $setcount > 0      % Loop until end of set

  change fDispEmp from current  % Fill form with emp. data

  form display nolabel input    % Display form and start input

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

  return           % If so, finish

  endif

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

  change current from fDispEmp % Update current member

  endif

  next            % Go to next record

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

endwhile

while Age > 20

 … other commands …

% Missing endwhile statement

… more commands …

last command in procedure

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

form open fCustomers

while

 form display input

 … more commands …

 if Event.EventName = “Escape”

  break

 endif

…more commands …

endwhile

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

See Also

Boolean Expressions

Conditional Expressions

CONTINUE

Lists data from the database.

Syntax

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

Parameters

Comments

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

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

The width of each column is determined by these rules:

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

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

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

Example

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

The complex expression is enclosed in parentheses.

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

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

list

The current member of the current set is listed.

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

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

See Also

OUTPUT

REPORT FROM

SELECT

SET PAGESIZE

SET PAGEWIDTH

SET PAUSE

Produces or deletes object dependency information.

Syntax

DEPENDENCY [RESET] [FOR] [object]

Parameters

Comments

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

Example

Consider a one-line application document called Test:

list e1

To produce dependency information for Test, enter

> set dependency on      % on by default

> parse TestProg

> dependency for TestProg

that outputs

O Test Document ZIM ZIM Directory ZIM

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

See Also

$compilestatus

COMPILE

PARSE

SET DEPENDENCY

SET OUTPUT

SET XREF

Sends a command to the operating system.

Syntax

SYSTEM expression [RESET|CLOSE] [INVISIBLE] [BACKGROUND | REMOTE]

Parameters

Comments

SYSTEM sends the command represented by expression to the operating system. For expression to be successfully executed, it must be meaningful to the operating system. Any software required for the execution of expression must be available to the system.
The SYSTEM command runs synchronously by default; the BACKGROUND subcommand can be used to force any SYSTEM command to execute asynchronously.

Note: For batch files, precede the command with an exclamation mark (!).

Note: There is no sense issuing the command SYSTEM with CMD, COMMAND or SH and the option BACKGROUND because it will require user interaction but there is no visible window to do it. The result is that Zim will wait for an event (closing the operating system window) that will never occur.

Note: The CLOSE option is ignored in Zim 9. Until Zim 7.x, it was intended to be able to copy Zim files around while guaranteeing that they would not be in a volatile state. Now, ZimServer possesses all Zim files and they cannot be closed or moved around at will because this creates breaches in the database security. In a well maintained working environment, users never have access to the Zim database files located in the server machine, thus ensuring maximum safety and security of the database. The only exception is when dealing with PER USER files: in this case, there is the statement INITIALIZE PERUSER which creates per user file on the fly without the need of copying any Zim files around nor saving “blank” copies of these files.

Example

find Customers where LastName = “Smith” and FirstName = “John”

system $concat(“archive “, fCustomers.cc, “.dat”)

If the cc value is 7592, then this command invokes a program called “archive” to archive the data file by passing the command archive 7592.dat to the operating system.

system “erase c:\\file.dat”

In systems where the path delimiter character is the backslash, remember that the backslash is also the escape character in character strings. Two backslashes are required, as shown above, to send the backslash to the operating system.

set escapechar off

system “erase c:\\file.dat”

set escapechar on

In the above example, SET ESCAPECHAR is used to turn off use of the escape character in character strings. Or, use SET SPECIALSCAN to switch off use of all reserved characters in text strings.

Note: See the user documentation for your operating system.

See Also

EDIT

GRAPH

INITIALIZE PERUSER

Erases an object from an application directory.

Syntax #1

Erases an object from an application directory.

ERASE object name [FROM dirname] [KEEP]

Parameters

Comments

The ERASE command erases an object from an application directory. If dirname is not specified, object is erased from the base application directory, zim.

The target directory must have been accessed in update mode. You cannot erase objects from foreign directories.

For ERASE to proceed, the explicit dirname in the ERASE command (or the implicit directory zim) must match the owner-directory of object. Qualifying the name of object is a recommended programming practice.

Syntax #2

Erases an index belonging to a specified object.

ERASE INDEX ownername.fieldname

Parameters

Syntax #3

Erases a field belonging to a specified object.

ERASE FIELD ownername fieldname

Parameters

Comments

Only virtual fields can be erased.

If you erase an EntitySet or relationship with fields, all data in that object is lost. To save the data, copy it to another object (usually an EntitySet or application document), or use the UNLOAD or RELOAD programs to temporarily store the data elsewhere.
If you erase an application document, the data in the associated disk file remains untouched.

Example

erase entityset Employees from Personnel

Erases the EntitySet Employees from the Personnel directory.

erase relationship BelongsTo

Erases the relationship BelongsTo from the Zim application directory.

See Also

CREATE

CURSOR

PERMISSION

RENAME

Establishes a connection to Zim Integrated Server or an SQL database.

Syntax

connect to [ “ZIMSERV” | “JDBCSAM” | alias name ] using (database name, SQL server name,

userid, password, server name, domain name)

Comments

All parameters are strings or expressions that produce a string.

In the case of a multiple connection to more than one server possessing the same SAM name, an alias name should be defined in the configuration file “zimalias.zim”.

Example

For user “JOE” with password “PASSWORD” to connect to a Zim server, enter

connect to using (“Inventory”, “”, “JOE”, “PASSWORD”, “Joes_Server”, “LinuxAirport”)

To connect to MySQL (or any other SQL database server), you must use the JDBC SAM:

connect to using (“Sales”, “MySQL”, “TheUser”, “ThePassword”,”5455″)

If connecting to two servers of the same SAM name at the same time, one of them must be defined as an alias

See Also

DISCONNECT

Instructs SQL commands to be generated with the FOR UPDATE OF option.

Syntax

SET FOR UPDATE ON|OFF

Comments

When connected to any SQL servers, the SQL syntax generated to perform operations on the remote server can be controlled to add the FOR UPDATE OF option on the primary key fields to SELECT commands.

The option ON turns this generation on and remains in effect until another command, this time with the option OFF, is issued. Therefore, all SELECT statements generated by Zim after the switch is turned on will have the FOR UPDATE OF clause until the switch is turned off.

This is useful to guarantee that records will be locked for update within the next SQL commands.

This option setting only applies to SELECT statements generated by Zim in order to perform actions on connected SQL servers.

Example 1

SET FOR UPDATE ON
SET SQLTRACE ON
FIND MyEntA
SELECT FieldA FROM MyEntA FOR UPDATE OF FieldA
FIND MyEntB
SELECT FieldB FROM MyEntB FOR UPDATE OF FieldB
SET FOR UPDATE OFF
FIND MyEntA
SELECT FieldA FROM MyEntA

The FIND statements between the ON and OFF settings will be sent to the connected SQL server with the FOR UPDATE OF clauses.

Example 2

The following Zim program shows a small procedure that takes a control number and then adds a record using this control number as a primary key. The numbers at left are for subsequent reference only.

1  Procedure Prog2() Local (vl_number, vl_1)
2  on deadlock
3          if $intransaction=$true
4                      out $concat(“record blocked – “, $trim(vl_1))
5                      halt
6                      goto trans1
7          else
8                      goto previous
9          endif
10 endon
11
12 trans1:
13 transaction
14 let vl_1=”Compute tblControl”
15 find tblControl -> s1
16 let vl_number=(LastNumber+1)
17 out vl_1
18 out vl_number
19 halt
20 let vl_1=”Add tblCust”
21 add tblcust let custcode = vl_number  
22                     custname = vl_number
23 out vl_1
24 halt
25 let vl_1=”Change tblControl”
26 ch tblControl let LastNumber = vl_number
27 out vl_1
28 halt
29 endtransaction
30
31 EndProcedure

Scenario 1

By default, SET FOR UPDATE is OFF. This is the behaviour found in previous versions of Zim.

If two users are running the same program, then:

. User 1 starts Prog2 and stops at line 19: Vl_number is 1 and no locks were applied by Oracle;

. User 2 starts Prog2 and stops at line 19: Vl_number is 1 and no locks were applied by Oracle;

. User 1 continues execution: a record will be added in TblCust and execution stops at line 24;

. User 2 continues execution: it waits because Oracle serializes the ADD statement in TblCust;

. User 1 continues execution: TblControl is updated, Oracle locks TblControl and execution is halted at line 28;

. User 2 is still waiting…

. User 1 continues execution: Oracle releases the lock in TblControl, the transaction is committed and the program ends;

. User 2 now proceeds: Oracle will try to add a record but a duplicated record error is raised.

Scenario 2

SET FOR UPDATE is set to ON either before calling Prog2 or in line 11 of Prog2:

. User 1 starts Prog2 and stops at line 19: Vl_number is 2 (assuming that a record was added in Scenario 1) and Oracle locks TblControl;

. User 2 starts Prog2, but enters in a waiting state at line 15, since Oracle serializes the SELECT statement (the record is locked);

. User 1 continues execution: the record will be added in TblCust, Oracle locks TblCust and the execution stops at line 24;

. User 2 still waiting…

. User 1 continues execution: TblControl is updated, Oracle locks TblControl and execution stops at line 28;

. User 2 still waiting…

. User 1 continues execution: Oracle releases the lock in TblControl, the transaction is committed and the program ends;

. User 2 resumes execution: Oracle retrieves a TblControl record, Vl_number becomes 3 and the transaction continues normally;

Branches to another location in an application program.

Syntax

GOTO labelname

Parameters

Comments

GOTO can be used only to branch forward or backward within the same procedure.

To declare a label, type the labelname, followed by a colon, at the appropriate point in the program. The labelname must be the first word on the line where the label is declared. Labels cannot be declared in or before an exception handler.

Exception Handlers and the GOTO Command

The GOTO command can be used within an exception handler to resume execution at an arbitrary point in the procedure body.

In the following example, when a deadlock occurs, the DEADLOCK handler restarts a transaction by using a GOTO command:

procedure MyProc5(Parm1,Parm2)

   on deadlock

     goto RetryTransaction

   endon

RetryTransaction:

   transaction

   … other commands …

   endtransaction

endprocedure

Note that the GOTO command uses a label name. All labels in a procedure must be declared following the last exception handler declaration. A GOTO cannot be used to branch into an exception handler, and an GOTO command executed in an exception handler must branch out of the exception handler to some point within the body of the procedure.

Any command in a procedure could potentially trigger an exception handler. After an exception condition has been handled, a developer typically wants the application program either

• to retry the command that caused the exception, or
• to skip the command that caused the exception and go on to the next command

One way to implement these requirements is to label each command line, and using the GOTO command, conditionally branch out of the exception handler to the appropriate command line. Alternatively, two implicit GOTO labels can be provided to address these requirements: GOTO PREVIOUS and GOTO NEXT.

The PREVIOUS and NEXT labels are defined dynamically to identify, respectively, the command line that caused the exception and the next command line. Note that the GOTO NEXT has the same effect as ENDON.

The GOTO NEXT and GOTO PREVIOUS commands can be used only within the body of an exception handler.

Example

The GOTO command is used to break out of a WHILE loop when an exit condition has been met.

while Quantity > 0

:

while ProdCode is not $null

:

if Event.EventName = “F3” % This key has been defined

   goto Exit       % as the “exit” key.

endif

:

endwhile

:

endwhile

Exit:

:

The GOTO command is used in an exception handler to restart a transaction that has been aborted as a result of a deadlock condition.

procedure MyProc (Param1, Param2)

 on deadlock

   goto retry_transaction

  endon

retry_transaction:

 transaction

 … other commands…

   endtransaction

endprocedure

The sequence of events is

• a deadlock condition occurs while the application is attempting to execute a transaction
• the ON DEADLOCK exception handler is triggered
• the exception handler executes the GOTO command, that causes the software to skip the retry_transaction label
• the application continues to process the commands that follow the label, effectively restarting the execution of the transaction

See Also

GOTO NEXT

GOTO PREVIOUS

ON