Category: ZIM 4GL Language Reference

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

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

Selects data for a report and specifies overall report format.

Syntax

REPORT [num] FROM [setspec] [GRAPHIC [TEMPLATE name]] [orientation] [PAUSE n]

[format options] [-> clause]

Parameters

Comments

The REPORT FROM command produces a set whose members are used as the source of data values for the report. The various clauses in the REPORT FROM command also specify the overall format of the report and determine if the report is line-oriented or column-oriented.

The format option PAGELAYOUT is only valid for graphical reports and specifies the layout of the page to be used for displaying or printing the report. is an expression that evaluates to a string containing eight parameters separated by semicolons like this example:

REPORT FROM Customers GRAPHIC TEMPLATE tCust PAGELAYOUT “2140;1950;1;1;0;0;0;0”
Other report commands…
ENDREPORT

The values in PAGELAYOUT mean (in tenths of millimeters): Height of the page; Width of the page; Number of Rows (for labels); Number of Columns (for labels); Top Margin; Left margin; Vertical distance between labels; Horizontal Distance between labels.

See Also

BREAK (Reports)

ENDREPORT

How to Use The Report Generator

Report Item Format Options

Creates an object in an application directory.

Syntax #1

Creates an object in an application directory.

CREATE object name [IN dirname][$fn <filenumber>] [DELETE | KEEP]

CREATE object name [IN dirname]

Parameters

Syntax #2

Creates an index.

CREATE INDEX ownername.fieldname [UNIQUE]

Syntax #3

Creates a field.

CREATE FIELD ownername fieldname

Parameters

Comments

The application directory named in a CREATE command must have been accessed in update mode (see ACCESS) and all information needed to define the object must exist in the Object Dictionary. For CREATE to proceed, the explicit dirname in the CREATE command (or the implicit directory zim) must match the owner-directory specified for object in the Object Dictionary; or, there must be no owner-directory specified for object in the Object Dictionary. In the latter case, object can be created in any or in every application directory available in the database (except foreign directories).
A field or form field cannot have the same name as an existing variable, EntitySet, relationship, role, directory, application document, window, constant, result set, form, menu, or display in the same application directory. Several fields or several form fields can have identical names, provided that each identically named field belongs to a different ownername.
There is an internal limit of 65000 CREATEs per Zim directory in Zim.  If this limit is exceeded, a 3029 error is generated. For more information, see Zim Error Codes.  To resolve this error, export all objects and import these objects into a newly initialized Zim database.  In a newly initialized database, the CREATE counter is reset to 0.

Example

create entityset Employees in Personnel

Creates an EntitySet called Employees in the application directory Personnel.

create index Employees.FirstName

Creates an index for an un-indexed field FirstName in the Employees EntitySet.

See Also

ERASE

PERMISSION

RENAME

Enables conditional execution of commands.

Syntax

IF expression1

commands1

[ ELSEIF expression2

commands2]

[ELSE

commands3]

ENDIF

Parameters

Comments

An IF command must always have a corresponding ENDIF.

If expression1 evaluates to $True, commands1 are executed, then execution resumes at the first command following ENDIF. If expression1 evaluates to $False, the ELSEIF expressions (if included) are evaluated in order. Any number of ELSEIF clauses can appear between IF and ENDIF. The commands associated with the first ELSEIF expression that evaluates to “true” are executed, then execution resumes at the first command following ENDIF. If none of the expressions evaluate to “true”, the commands associated with the ELSE clause (if included) are executed. If the ELSE clause is omitted, execution resumes at the first command following the ENDIF without any commands in the IF structure being executed.

If you exit from a procedure in the middle of an IF structure, the software closes the open IF command.

If you explicitly transfer control out of a procedure after an IF command has been executed, but before the corresponding ENDIF command has been executed, the open IF structure is automatically closed. Also, if the end of the current procedure is reached before a corresponding ENDIF is encountered, the open IF structure is closed.

If you forget to use a necessary ENDIF, all subsequent commands in the current procedure are treated as part of the IF structure, and all of those commands are executed only if execution control has been passed to the corresponding IF, ELSEIF, or ELSE clause.

Example

IF commands are useful for controlling groups of alternative commands. For example, the following application program fragment can be used to drive a form:

window set accelerator Return Enter Escape

while    % continue looping (until user presses Escape)

 form open menuform

 form display

 form input

 if Event.EventName = “Escape”

  return  % exits from program

 endif

 if menuform.selnum = 1

    DoEmp  % calls program DoEmp

  continue % returns to the start of the WHILE loop

 endif

:

endwhile

ELSEIF used to test a series of alternatives.

if Age < 18

:

elseif Age between 18 and 55

:

elseif Age between 56 and 65

:

else

:

endif

Because the first ENDIF statement is missing, the second IF statement is executed only if the conditional expression for the first is false. If the second IF statement is executed, and evaluates to true, that IF statement is ended by the RETURN command; otherwise, both IF statements end when the last command in the procedure is executed.

if Age > 21

 ..first group of commands…

else

 …second group of commands…

% endif should go here, but was missed

if Salary > 20000

 …first group of commands…

 return

% another endif is missing here

See Also

Boolean Expressions

Conditional Expressions

CASE

Creates a memory set based on the telemetry from a connector.

Syntax

CREATE MEMORY SET FROM «connector document»

Parameters

Comments

The CREATE MEMORY SET command converts the information in a 1202 message into an in memory zim EntitySet. It creates the set and field definitions at run time using the metadata in the message and populates the set using the data in the message.

Remarks

The memory set is called $MemorySet and is specifically useful only for connector documents. There can be only one $MemorySet at a time and the creation of a new one replaces the existing one. The definitions that are created are not available for inspection (the are not really in the directory).

Example

Not using $MemorySet:

> set connector document SMS_RECEIVE to ‘F!amccue!9011’

> set output format commadelimited

> list all SMS_RECEIVE   (get the first message from the connector)

>”SegmentRN”,”GroupId”,”SegmentID”,”SegmentType”,”DataName”,”DataType”,”DataValue”

>”         0″,”0″,”0″,”OUTPUT”,”START_BACKLOG”,”STDOUT”,”16135551012″

>”      SYNC”,”0″,”0″,”SYNCINFO”,”8820″,”ADDR”,”16135551012″>

> list all SMS_RECEIVE (get the next message from the connector)

>”SegmentRN”,”GroupId”,”SegmentID”,”SegmentType”,”DataName”,”DataType”,”DataValue”

>”         0″,”0″,”0″,”DATA”,”REFERENCE”,”CHAR”,”0″

>”         0″,”0″,”1″,”DATA”,”PART”,”CHAR”,”1″

>”         0″,”0″,”2″,”DATA”,”PARTS”,”CHAR”,”1″

>”         0″,”0″,”3″,”DATA”,”MESSAGE_CLASS”,”CHAR”,”MESSAGE”

>”         0″,”0″,”4″,”DATA”,”MY_NUMBER”,”CHAR”,”16135551012″

>”         0″,”0″,”5″,”DATA”,”SIM_SLOT”,”CHAR”,”1″

>”         0″,”0″,”6″,”DATA”,”SENDER_ADDRTYPE”,”CHAR”,”SMS_PHONE”

>”         0″,”0″,”7″,”DATA”,”SENDER_EMAIL”,”CHAR”,”16135552208″

>”         0″,”0″,”8″,”DATA”,”DATE”,”CHAR”,”2003/01/15″

>”         0″,”0″,”9″,”DATA”,”TIME”,”CHAR”,”11:34:34″

>”         0″,”0″,”10″,”DATA”,”BODY”,”CHAR”,”this is a test”

>”SYNC”,”0″,”0″,”SYNCINFO”,”8820″,”ADDR”,”16135551012″

list all SMS_RECEIVE  (get the next message from the connector)

>”SegmentRN”,”GroupId”,”SegmentID”,”SegmentType”,”DataName”,”DataType”,”DataValue”

>”         0″,”0″,”0″,”OUTPUT”,”END_BACKLOG”,”STDOUT”,”16135551012″

>”      SYNC”,”0″,”0″,”SYNCINFO”,”8820″,”ADDR”,”16135551012″

Using the $MemorySet

> set connector document SMS_RECEIVE to ‘F!amccue!9011’

> set output format commadelimited

> create memory set from SMS_RECEIVE

> list all $memoryset

>”START_BACKLOG”,”8820″

>”16135551012″,”16135551012″

> create memory set from SMS_RECEIVE

> list all $memoryset

>””REFERENCE”,”PART”,”PARTS”,”MESSAGE_CLASS”,”MY_NUMBER”,”SIM_SLOT”

>”SENDER_ADDRTYPE”,”SENDER_EMAIL”,”DATE”,”TIME”,”BODY”

>”0″,”1″,”1″,”MESSAGE”,”16135551012″,”1″,”SMS_PHONE”

>”16135552208″,”2003/01/15″,”11:34:34″,”this is a test”,”1615551012″

> create memory set from SMS_RECEIVE

> list all $memoryset

>”END_BACKLOG”,”8820″

>”16135551012″,”16135551012″

Related Information

Whitepaper on The Open 1202 Protocol, Version 01.00 July 2002

Breaks the body of a report into summary groups.

Syntax

BREAK level expression \

[HEADING [orientation] reportitem \

[:format:] [WHERE Boolean Expression]] \

[FOOTING [orientation] reportitem [:format:] \

[WHERE Boolean Expression>]

Parameters

Comments

Breaks can be organized into the hierarchy: 0, 1, 2, and so on. The higher the level number, the more minor the break.

Each change in the value of expression triggers a break at the associated level. The break levels below it in the hierarchy are also triggered; that is, a level 1 break triggers a level 2 break, and a level 3 break, and so on.

The report items in the break heading can include individual data values only from the first member of the current group.

The report items in the break footing can include individual data values only from the last member of the current group. However, summary data computed over all members of the group can be displayed in the footing. Use aggregate functions.

Each time the break level is triggered, headings specified in a corresponding COLUMN BREAK command, DETAIL LINE command, and PAGE HEADING command are also displayed.

Note: Multiple HEADING or FOOTING specifications are separated from one another by commas.

Example

This is an example of a conditional footing:

 break 2 OrderNo

 footing

 ‘**Large Order’ $total(Amount) WHERE $total(Amount) > 10000, ‘ ‘ $total(Amount)

See Also

COLUMN BREAK

DETAIL LINE

ENDREPORT

PAGE HEADING

REPORT FOOTING

REPORT FROM

REPORT HEADING

Declares a block of commands to be a handler for a given exception condition.

Syntax

ON condition

commands

ENDON

Parameters

Comments

The ON … ENDON structure enables you to detect and handle exception conditions that can arise in your application. The exception handler is executed only if the associated exception condition arises.

Note: An application program can explicitly trigger an exception handler using the SET EXCEPTION command.

Exception handlers are declared and recognized only within a procedure. All exception handlers must be declared at the start of the procedure, immediately following the PROCEDURE or LOCALPROCEDURE command.

An exception handler cannot be nested inside another exception handler. As a result, exception conditions that arise during the execution of an exception handler do not trigger a subsequent exception handler.

You cannot nest exception handlers; that is, you cannot declare an exception handler within another exception handler without another exception handler declaration.

When execution control shifts to a procedure, exception handler declarations are noted, but the body of each exception handler is ignored for the moment. Execution begins at the first command following the last exception handler declaration. When an exception condition arises and a corresponding exception handler exists, the exception handler is triggered: execution of the commands in the procedure are suspended, and execution control is transferred to the body of the exception handler.

Note: All programming structures (CASE, IF, WHILE) that are opened within an exception handler must be closed within that handler.

RECURSIVE EXCEPTION CONDITIONS

An exception handler cannot be triggered from within an exception handler. In other words, exception conditions that arise during execution of the body of an exception handler are ignored. For example, a DEADLOCK condition raised during the execution of an ERROR exception handler does not trigger the DEADLOCK exception.

Similarly, the SET EXCEPTION command cannot be used in the body of an exception handler.

EXCEPTION HANDLER HIERARCHY

Under certain circumstances, a number of exception conditions can arise at the same time.

For example, if the application user presses the break key while an error message is being issued, the BREAK and ERROR conditions both are raised. Deadlock in multi-user applications always results in multiple exception conditions, because the deadlock produces a warning message (i.e., resulting in both a DEADLOCK and an WARNING condition being raised).

Simultaneous exception conditions are handled in the following order:

• Deadlock
• Break
• Error
• Warning

If multiple exception conditions arise, the software looks for an exception handler for the condition with the highest precedence. If there is no handler for that condition, the software then looks for an exception handler for the condition with the next-highest precedence, and so on.

Only the exception handler that is uppermost in the hierarchy is triggered.

HANDLING TERMINAL BREAKS

An application user can prematurely stop execution of a procedure by pressing the “break” key, causing a terminal break.

When a terminal break occurs, the software normally terminates the command that is currently executing and performs a RETURN (i.e., returns to the parent procedure). However, if a BREAK exception handler is available when a terminal break occurs, the software stops the command that is currently executing and triggers the BREAK handler instead. The BREAK handler can then deal with break signals in a customized manner.

To prevent terminal breaks from raising a BREAK condition, use the SET BREAKABLE command.

Example

Exception handlers must appear first within a procedure:

procedure MyProc (Param1, Param2)

 on break

  … commands that handle the “break” condition …

 endon

 … procedure commands …

endprocedure

You can declare more than one exception handler in a procedure:

procedure MyProc (Param1,Param2)

 on deadlock

  … commands that handle the “deadlock” condition …

 endon

 on error

 … commands that handle the “error” condition …

 endon

 … procedure commands …

endprocedure

Execution flow in the procedure varies depending on the conditions that are encountered in the body of the procedure (following the last ENDON).

See Also

GOTO NEXT

GOTO PREVIOUS

SET EXCEPTION