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

To prepare a terminal set-up that defines exactly how to produce certain Zim keyboard actions from your terminal keyboard, you must define specific keyboard information.  This information includes specific terminal usage for your specific operating system(s).

Operating System-Specific Aspects of Terminal Definition

Windows

To run Zim under Windows no terminal keyboard definitions are required.

UNIX

Under UNIX, the zimtcap files are located in the directory identified by Zim’s environment variable.  Zim and zimtcap obtain the value for termname in termname.ztcap from the current value of the TERM environment variable. If no value has been specified for TERM, or the file termname.ztcap cannot be found, you cannot execute ZIM.

If you choose zimtcap option 2 (Create a new terminal description) zimtcap creates a new zimtcap file. If you current terminal is defined in terminfo or termcap, zimtcap extracts the available information and places it into the new zimtcap file.  

Executing zimtcap

Under UNIX, Zim determines the characteristics of a terminal by consulting terminal description files, called zimtcap files. Each zimtcap file is stored under the name

termname.ztcap

where the value for termname (terminal name) and the location of the file is operating system-specific.

Each zimtcap file defines the characteristics of its termname to ZIM by indicating the terminal keys that perform specific functions (for example, Home, F1) and by indicating how certain terminal attributes are set.

The zimtcap utility program is provided with the ZIM software and is used to create or edit zimtcap files.

Note: The zimtcap program must be executed at the same type terminal for which you are creating the zimtcap file.

When running zimtcap, your are presented with a menu that includes seven options:

These options are described below.

Display Current Description

This zimtcap option enables you to open the current zimtcap file and display the file contents on your terminal screen.

Note: A zimtcap file for your terminal must exist before you can select this option. To create a default zimtcap file for your terminal refer to option 2 (Create a New Terminal Description) below.

Create a New Terminal Description

This zimtcap option enables you to create a new zimtcap file for your terminal. This file contains the default values for your terminal.

Edit Terminal Attributes

This zimtcap option enables you to edit the terminal attributes, such as number of screen rows or columns, contained in the current file.

Note: A zimtcap file for your terminal must exist before you can select this option. To create a default zimtcap file for your termina,l refer to option 2 (Create a New Terminal Description).

Edit Cursor Positioning

This zimtcap option enables you to change the definition of how cursor positioning is handled by your terminal.

Note: A zimtcap file for your terminal must exist for before you can use this option. To create a default zimtcap file for your termina,l refer to option 2 (Create a New Terminal Description).

To set the cursor position, the zimtcap program sends a string with the following format,

L1 p1 SEP p2 LO

where L1 is the Lead In sequence of characters;

LO is the Lead Out sequence;

and SEP either is not present or is a sequence of characters separating the cursor coordinates p1 and p2..

On some terminals, the row is sent first (i.e. p1 is the row) and on others, the column is sent first (i.e. p1 is the first column). On some terminals, positions are sent as single characters and on others, they are sent as one or two digit numbers in character form. In either case, the actual row and column value can be offset by some value.

ZIMTCAP prompts you for these attributes.

Note: When entering offsets for rows and columns, remember that the top left-hand corner of the screen is considered to be row 1, column 1.

Edit Output Definitions

This zimtcap option enables you to define the character sequences that must be sent to the terminal in order to turn certain attributes, such as inverse video, on and off.

Note: A zimtcap file for your terminal must exist before you can select this option. To create a default zimtcap file for your terminal, refer to option 2 (Create a New Terminal Description).

Edit Output Definitions

This zimtcap option enables you to change the assignment of terminal keys to various Zim actions (for example PageUp and F1 action).

Note: A zimtcap file for your terminal must exist before you can select this option. To create a default zimtcap file for your terminal, refer to option 2 (Create a New Terminal Description).

When zimtcap prompts you for the name of each action, type the key (or sequence of keys) that require to represent that action within Zim. Terminate each definition by pressing Return. To keep the current definition for any action, press Return without typing any key (or sequence of keys).

Exit

This option enables you to exit from zimtcap. All changes made are saved.

Terminal Key Definitions for Zim Actions

The following table defines the terminal key mappings to Zim actions.

* It is common for special terminal keys to generate character sequences that begin with the escape character.  In these cases, it is common to implement the Zim action Escape as a sequence of two escape keystrokes in order to distinguish it from the others.

Executes a command against a target server or executes a remote procedure on a Zim Server.

Syntax 1

REMOTEEXEC server expression

Parameters

Syntax 2

REMOTEEXEC server PROCEDURE ProcedureName (arg1, arg2, ...) USING obj1 obj2 ...

Parameters

Comments – Syntax 1

Expression is evaluated and then executed against the specified server.

If the expression evaluates to a SELECT command, data is retrieved (if records meet the selection criteria), but the records cannot be accessed.

If the command contained in the expression fails, the server’s error message is available in the system variable $SQLErrMsg.

This command was originally SERVEREXEC although only supported for backward compatibility.

Special REMOTEEXEC Cases

The following cases of REMOTEEXEC apply only when Zim is connected to Zim Server.

To copy a file from the client to the server:

REMOTEEXEC "ZIMSERV" "!copytoserver  "

To copy a file from the server to the client:

REMOTEEXEC "zimserv" "!copyfromserver" " "

Note: To erase a file on the server, you could copy a zero-length file over the server side file, or send “SET OUTPUT . . .”  using REMOTEEXEC.
The limit on record size is about 4000 bytes.

Note: You must insert spaces around the in the command.

Note: Currently, these commands do not copy files inside directories nor the directories themselves.

Note: By default, all files transferred follow the text format, meaning that line terminators are correctly converted from Windows to Unix and vice-versa. By using the “/b” or “/B” parameter, the files are transferred “as is”, in binary mode. This is useful for images, etc.

Comments – Syntax #2

A remote procedure is a normal Zim procedure that is executed on Zim Server, but is invoked from a Zim client. Remote procedures are very similar to procedures that are executed locally, but they are invoked by executing a REMOTEEXEC command instead.

Field names passed as arguments to the remote procedure are not evaluated from the Zim client’s current set. They are assumed to be fields on the server whose values are inherited from the current set on the server. Client side field values must be passed in as variables.

The USING clause specifies those sets that are accessible to the Zim client after the remote procedure creates them on the server. They must be known in Zim before the remote procedure is called. They can be temporary or permanent set names. For temporary set names, a command such as ‘parse “find customers issue orders ->coset”‘ should be executed to define the set in Zim.

Global variables, forms, and form entities must be known on both client and server. Their values (or the values of their form fields or variables for forms and form entities) are sent to the server prior to the remote procedure call and then returned to the client when the procedure call is complete.

Zim evaluates the expression, checks that it is valid and connected to that Server, and then sends the set information, variable values, and procedure call syntax to the server. The actual procedure call that is executed on Zim Server is

(arg1, arg2, …)

After the procedure finishes, updated set information and variable values are returned to the Zim client.

Examples

remoteexec "oracle" "alter rollback segment big_seg"

transaction

  remoteexec "oracle"

  "set transaction use rollback segment big_seg"v

 ... large update transaction ...

endtransaction

remoteexec "oracle" "alter rollback segment big_seg offline"

See Also

$SQLErrCode

CONNECT

SET IMPLICITTRANS

Changes the settings of certain device properties of the registry variables file.

Syntax

$setproperty(section, property, newsetting)

Parameters

Return Value

A character string containing “1” ($True) if the arguments to the function were valid and newsetting was applied. Otherwise, it returns “0” ($False).

Comments

If more than one $setproperty is used during the generation of a report, then only the last $setproperty is in effect when the report is printed.

Care should be taken when changing the setting of registry values, as improper manipulation can result in program or system failure.

The following are possible values for section, property and their corresponding newsetting:

“SESSION”:

If running the Zim executable, the section “REG:[…]” sets the registry values in the machine where Zim Server is running because Zim only runs in the same machine as Zim Server runs.

If running the Zim Thin executable, the section “REG:[…]” sets the registry values in the machine where Zim Thin is running.

In order to set registry values in the machine where Zim Server is running when running Zim Thin, you must use the section “SERVREG:[…]” which has the same meaning and syntax as “REG:[…]”.

Examples

let vSet = $setproperty ("printer", "fontsize", "12")

Sets the font size of the default printer to 12.

let vSet = $setproperty ("REG:[MYSET]", "My Setting", "I like this one.")

Sets “I like this one.” in the property “My Setting” belonging to the sub-section “MYSET”. This kind of setting is useful for applications to keep track of values used in the Zim application.

let vSet = $setproperty ("SESSION", "Parameter Size", "2000")

Sets the database configuration option “Parameter Size” to 2000.

See Also

$getproperty
$printersetup

A data structure that provides information about the state of the system and the most recent event.

The Event data structure provides information about the most recent event and about the state of the system when that event occurred.

The components of the Event data structure are set when an event occurs in the user interface. An application program can use the information in the fields to determine what action, if any, to take.

The fields in the Event structure are

– AltKey

– CtrlKey

– EventName

– EventTag

– EventType

– FieldTag

– FormTag

– KeyPressed

– MenuItemTag

– MenuTag

– MouseClick

– ScrollingKey

– ShiftKey

– WindowTag

Syntax #1 – AltKey, CtrlKey, ShiftKey

Provides information about the state of the Alt, Ctrl, or Shift key during the last event

event.altkey

event.ctrlkey

event.shiftkey

Return Value

Character string (binary). Can be reset by the application program.

Description

The variables provide information about the state of the Alt, Ctrl, and Shift keys during the last event.

The string is set to ‘1’ ($True) if the indicated key was down when the last event occurred. Otherwise, it is set to ‘0’ ($False).

Syntax #2 – EventName

event.eventname

Where eventname is one of

• Break, Canceled, Click, Closed, DoubleClick, GotFocus, HangUp, LostFocus, LostFocusModified, Modified, PanicExit, RightClick, Timeout, WindowFocusSwitch, or
• the name of an accelerator key, such as F1, if the event type was accelerator

Return Value

Character string (alpha). Can be reset by the application program.

Description

The Event data structure provides information about the most recent event and about the state of the system when that event occurred.

The components of the Event data structure are set when an event occurs in the user interface. An application program can use the information in the fields to determine what action, if any, to take.

Syntax #3 – EventTag

event.eventtag

Return Value

Character string (ALPHA). Can be reset by the application program.

Description

The variable identifies, by its tag, the object in which the last user interface event occurred. The variable can be

Syntax #4 – EventType

event.eventtype

Return Value

Character string (ALPHA). Can be reset by the application program.

Description

The variable identifies the type of user interface event that last occurred.

– window

– menu

– menuitem

– form

– formfield

– accelerator

– system

Syntax #5 – FieldTag

event.fieldtag

Return Value

Character string (ALPHA). Can be reset by the application program.

Description

The variable identifies, by its tag, the current field at the time of the last event.

Syntax #6 – FormTag

event.formtag

Return Value

Character string (ALPHA). Can be reset by the application program.

Description

The variable, identifies, by its tag, the current form at the time of the last event.

Syntax #7 – KeyPressed

event.keypressed

Return Value

Character string (CHAR). Can be reset by the application program.

Description

The variable indicates, by name, the pressed key that caused the last event to occur.

Note: The keynames associated with accelerator events, such as F1, are recorded in EventName.

Example

If the user presses the a key in a form field and a Modified event is intercepted by the application program, then Event.KeyPressed is set to a.

Syntax #8 – MenuItemTag

event.menuitemtag

Return Value

Character string (ALPHA). Can be reset by the application program.

Description

The variable identifies, by its tag, the selected item on the menu in the current window at the time of the last event.

Syntax #9 – MenuTag

event.menutag

Return Value

Character string (ALPHA). Can be reset by the application program.

Description

The variable identifies, by its tag, the current menu at the time of the last event.

Syntax #10 – MouseClick

event.mouseclick

Return Value

Character string (binary). Can be reset by the application program.

Description

The variable indicates if a mouse button acceleration caused an event to occur.

It is set to ‘1’ ($True) if the event was caused by pressing a mouse button that is defined as an accelerator for the window. Otherwise, it is set to ‘0’ ($False).

Syntax #11 – ScrollingKey

event.scrollingkey

Return Value

Character string (ALPHA). Can be reset by the application program.

Description

The variable indicates if an event corresponds to a defined SCROLL key.

It is set to ‘1’ ($True) if an event corresponds to an accelerator key that is also a defined SCROLL key for the window. Otherwise, it is set to ‘0’ ($False).

Accelerators and SCROLL keys are defined using WINDOW SET commands.

Example

The application fragment that follows enables employee records to be scrolled through a form and the data to be updated. The combined actions are accomplished by defining certain keys both as accelerators and SCROLL keys. When one of these keys is pressed, the corresponding accelerator event occurs. The application program uses ScrollingKey to detect that a SCROLL key was pressed and performs the scrolling action after saving the updated data.

window set scroll Up F7 Down F8

window set accelerator F7 F8 escape

form open fEmployee

form set scroll fEmployee from EmpSet

form display

while

form input

if event.scrollingkey = $true

if thisform.formchanged = $true

  change EmpSet from fEmployee

   endif

  form scroll

  continue

endif

… other commands …

endwhile

Syntax #12 – WindowTag

event.windowtag

Return Value

Character string (ALPHA). Can be reset by the application program.

Description

The variable identifies, by its tag, the current window at the time of the last event.

See Also

FORM INPUT

FORM SET

MENU INPUT

MENU SET

RightClick

ThisForm

ThisMenu

WINDOW SET

A data structure that provides information about the state of the current form at the time of the last event in the current window.

The ThisForm data structure provides information about the state of the current form at the time of the last event in the current window.

The ThisForm structure contains a number of fields that are reset when a window containing a form or display becomes the current window. An application program can use the information in the fields to determine what action, if any, to take.

The fields in the ThisForm structure are

• DisplayTag
• FFFieldNum
• FieldChanged
• FieldTag
• FormChanged
• FormNum
• FormTag
• ReqError
• ReqFieldNum
• ReqFormNum
• ReqSubscript
• ReqTag
• Subscript
• ValError
• ValFieldNum
• ValFormNum
• ValSubscript
• ValTag

Syntax # 1 – DisplayTag

The tag of the display that had focus at the time of the last event in the current window.

thisform.displaytag

Return Value

Character string identification tag of the current display. Can be reset by an application program.

Description

Identifies, by identification tag, the display that had focus at the time of the last event in the current window.

Syntax # 2 – FieldChanged

A code indicating if the form field that had focus at the time of the last event in the current window was modified by the application user.

thisform.fieldchanged

Return Value

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

Description

Set to “1” ($True) if the value of the field that had focus changed after the application user was placed in control of the interface. Otherwise, set to “0” ($False).

Syntax # 3 – FFFieldNum

The identification number of the form field that had focus at the time of the last event in the current window.

thisform.fffieldnum

Return Value

A number. Can be reset by an application program.

Description

The identification number of the form field that had focus at the time of the last event in the current window.

The combination of ThisForm.FormNum, ThisForm.Subscript, and ThisForm.FFFieldNum can uniquely identify a particular form field in a particular form.

Example

form set (cursor) (ThisForm.formnum,ThisForm.fffieldnum,ThisForm.subscript)

Syntax # 4 – FieldTag

The tag of the form field that has focus at the time of the last event in the current window.

thisform.fieldtag

Return Value

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

Description

The identification tag of the focus form field at the time of the last event in the current window.

The combination of ThisForm.FormNum, ThisForm.Subscript, and ThisForm.FFFieldNum can uniquely identify a particular form field in a particular form.

Syntax # 5 – FormChanged

A code indicating if any form field in the form or display had been modified by the application user at the time of the last event in the current window.

thisform.formchanged

Return Value

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

Description

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

Syntax # 6 – FormNum

The form number of the form that had focus at the time of the last event in the current window.

thisform.formnum

Return Value

A number. Can be reset by an application program.

Description

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

The combination of ThisForm.FormNum, ThisForm.Subscript, and ThisForm.FFFieldNum can uniquely identify a particular field in a particular form.

Example

form set (cursor) (ThisForm.formnum,ThisForm.fffieldnum,ThisForm.subscript)

Syntax # 7 – FormTag

The identification tag of the form that had focus at the time of the last event in the current window.

thisform.formtag

Return Value

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

Description

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

The combination of ThisForm.FormNum, ThisForm.Subscript, and ThisForm.FFFieldNum can uniquely identify a particular field in a particular form.

Syntax # 8 – ReqError, ReqFieldNum, ReqFormNum, ReqSubscript, ReqTag

thisform.reqerror

thisform.reqfieldnum

thisform.reqformnum

thisform.reqsubscript

thisform.reqtag

Return Value

Character string (binary). Can be reset by an application program. (ReqError)

Character string (alpha). Can be reset by an application program. (ReqTag)

Number (INT). Can be reset by an application program. (ReqFieldNum, ReqFormNum, ReqSubscript)

Description

The variables indicate if all required form fields had values at the time of the last event in the current window.

ThisForm.ReqError is set to ‘1’ ($True) if any required form field in the current form or display has not been completed when an event occurs. Otherwise, it is set to ‘0’ ($False).

If ThisForm.ReqError is ‘1’, then the other variables are set to the form number (ThisForm.ReqFormNum), form field number (ThisForm.ReqFieldNum), subscript (ThisForm.ReqSubScript), and tag (ThisForm.ReqTag) of a required form field that has no value.

Example

while

 form input

  ...commands...

  if ThisForm.reqerror = $true

   form set (focus) (ThisForm.reqformnum,ThisForm.reqfieldnum,ThisForm.reqsubscript)

  continue

 endif

endwhile

If “required” fields in the current form have not been completed, focus is set to one of those fields on the next input request.

Syntax # 9 – Subscript

The instance of the form where focus was located at the time of the last event in the current window.

thisform.subscript

Value

A number. Can be reset by an application program.

Description

Identifies, by number, the instance of the form where focus was located at the time of the last event in the current window (when several instances of the form appear in a display). If the form appears only once, ThisForm.Subscript is always 1.

For example, if a form is repeated eight times in a display, ThisForm.Subscript might be set to any number from 1 to 8. The particular number indicates in which repetition of the form the focus was located.

The combination of ThisForm.FormNum, ThisForm.Subscript, and ThisForm.FFFieldNum can uniquely identify a particular field in a particular form.

Example

form set (cursor) (ThisForm.formnum,ThisForm.fffieldnum,ThisForm.subscript)

find Products where ProdCode = fProducts.ProdCode[ThisForm.subscript]

Syntax # 10 – ValError, ValFieldNum, ValFormNum, ValSubscript, ValTag

thisform.valerror

thisform.valfieldnum

thisform.valformnum

thisform.valsubscript

thisform.valtag

Value

Character string (binary). Can be reset by an application program. (ValError)

Character string (alpha). Can be reset by an application program. (ValTag)

Number (INT). Can be reset by an application program. (ValFieldNum, ValFormNum, ValSubscript)

Description

The variables indicate if all form fields had valid values at the time of the last event in the current window.

ThisForm.ValEror is set to ‘1’ ($True) if any form field in the current form or display contains an invalid value when an event occurs. Otherwise, it is set to ‘0’ ($False).

If ThisForm.ValError is ‘1’, then the other variables are set to the form number (ThisForm.ValFormNum), form field number (ThisForm.ValFieldNum), subscript (ThisForm.ValSubscript), and tag (ThisForm.ValTag) of a form field that has an invalid value.

Example

while

 form input

 ...commands...

 if ThisForm.valerror = $true

  form set (cursor) (ThisForm.valformnum,ThisForm.valfieldnum,ThisForm.valsubscript)

  continue

 endif

endwhile

If fields in the current form failed the validation check, focus is set to one of those fields on the next input request.

See Also

DISPLAY DEFINE

Event

FORM INPUT

MENU INPUT

MENU SET

SCREEN CLEAR

SCREEN RESET

ThisMenu

WINDOW CLOSE

WINDOW OPEN

WINDOW SET

WINDOW SET CURRENT

Adds data to EntitySets or relationships.

Syntax #1

Adds a single record to an EntitySet or relationship. Use the LET subcommand to explicitly assign values to the target fields in the record.

ADD objname [LET clause] [EVALUATE clause] [-> clause]

Syntax #2

Adds one or more records from a set specification to an EntitySet or relationship. Data for target fields in the records is take from the specified set. The LET subcommand can be used to direct the source data to particular target fields, and, if desired, to process the source data in some manner before assignment.

ADD [num] objname [FROM source] [LET clause] [EVALUATE clause] [-> clause]

Syntax #3

Adds one or more records from an unstructured application document to an EntitySet or relationship. Data for the target fields in the records is taken from an unstructured application document or a set whose only component is an unstructured application document. The LET subcommand can be used to process the source data in some manner before assignment. You can use the FORMAT clause to direct the source data to particular target fields. The PROMPT clause performs the same function but also sends the field names to the current output destination for display.

ADD [num] objname FROM doc [LET clause] [FORMAT | PROMPT [«field »]] [EVALUATE clause] [-> clause]

Parameters

Comments

If a field is not explicitly assigned a value during an ADD, the field is checked for a defined default value. If available, the default value is assigned; otherwise, $Null is assigned.

Before adding each record, the software ensure that every required field has been assigned a value. If any required field is $Null, an error results, and the corresponding record is not added. To switch this check off, use the SET CHECKNULLS OFF command.

Even before execution of the ADD, while the parser is processing the command, a check is performed to determine if required fields that have no defined default value are being assigned a value. If no value is being assigned, an error is immediately generated. This check is always performed.

Messages marking the progress of an ADD command can be displayed on the terminal. See SET MEMBERCOUNT and SET MEMBERINTERVAL for details.

Refrain from using the ADD command to add records to the Object Dictionary EntitySets for user interface objects (windows, menus, forms/displays, and form field/menu items).
The records contain many fields, often with important inter-field dependencies. Records added using ADD are not validated in the usual way, and incorrect values in the record could cause the software to behave unexpectedly or even crash.
Use the Screen Painter to define all user interface objects.

Rules for Value Assignments to Fields During ADD

The software assigns a value to each target field based on the first of the following situations that holds true for that field:

1. The target field is explicitly assigned a value in a LET subcommand.
2. The structured source object contains an identically-named field whose value is implicitly assigned to the target field.

OR

The unstructured source object contains a value in the sequential position that matches the sequential position of the target field’s name in the FORMAT or PROMPT clause.

OR

The unstructured source object contains a value in the same sequential position of the target field in the records. This occurs when no FORMAT or PROMPT clause is supplied, or when the clause does not specify field names.

1. The target field takes the default value defined for it in the Object Dictionary.
2. The target field is $Null (unassigned).

Once values have been determined for all target fields in the record, the software checks to ensure that a Required field is not $Null. If a Required field is $Null, the software raises an error, and the record is not added. This check can be switched off with a SET CHECKNULLS OFF command.

When an ADD command is parsed, the software checks if Required fields that have no defined default value are being assigned a value. If no value is being assigned,the software raises an error immediately, before any attempt to execute the ADD. This check is always performed.

Special rules apply when the data being added to an EntitySet or relationship comes from an unstructured application document (Syntax #3):

1. The $Null property can be explicitly assigned to a field using one of the following techniques:
   • If the current delimiter is not a space (see SET DELIMITER), then two delimiters side-by-side explicitly indicate an unassigned value ($Null). For example, if a slash (/) is the delimiter, then abc/def// generates three values: abc, def and $Null.
   • An asterisk (*) also explicitly indicates an unassigned value ($Null). For example, abc * def generates three values: abc, $Null and def. To specific an asterisk as a literal character, place a backslash ( – Escape) preceding it. For example, if you want a particular field to have the value 5*6, type 5*6 into the source document.
   • Alternatively, use SET SPECIALSCAN to control how the metacharacters backslash () and asterisk (*) are to be handled when they appear in an unstructured application document that is being used as a data source. When SET SPECIALSCAN is ON, the backslash and asterisk characters have their special meanings. When SET SPECIALSCAN is OFF, the backslash and asterisk characters are treated as ordinary data.
2. If a line in the document fails to provide a value for every field in the record being added, each field not assigned a value becomes $Null.
3. A line of zero length in the source document (i.e., the line consists solely of a carriage return or a newline character) is taken as an end-of-file indicator by default. The ADD command stops unless a SET EOFVALUE command has been issued.

Example

add Employees let  LastName = “Smith” FirstName = “Jeff”

EmpNum = 99 DeptNum = “D04”

Adds a single record, explicitly specifying the data.

add Employees from NewEmps let EmpNum = Enum + 100

Adds records from a structured application document, assigning values from NewEmps to fields in Employees that carry identical names. Adds 100 to Enum field and assigns resulting value to EmpNum.

add Employees from NewEmps format DeptNum LastName FirstName

Adds records from an unstructured (but consistently formatted) application document, noting the order in which the data appears.

add Employees from terminal prompt

Adds records based on responses to a prompt containing the field names from Employees.

add Employees from terminal prompt FirstName LastName

Adds records based on responses to a prompt containing only specified field names. If other fields in Employees have been defined as “required”, this command produces an error.

See Also

$MemberCount

CHANGE

INSERT

ThisWindow

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

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

The ThisWindow structure contains a number of fields that are reset when the current window changes. By trapping these values, the application enables the user to change the current window and later return to pick up where things were left.

If the current window is non-modal, note that the last event in the window is not necessarily the last event in the interface overall.

The fields in the ThisWindow structure are

AltKey, CtrlKey, ShiftKey, EventName, EventTag, EventType, KeyPressed, MouseClick, ScrollingKey, WindowCol, WindowHeight, WindowName, WindowNum, WindowRow, WindowState, WindowTag, WindowWidth

Syntax #1 – AltKey, CtrlKey, ShiftKey

The state of the Alt, Ctrl or Shift key at the time of the last event in the current window.

thiswindow.altkey

thiswindow.ctrlkey

thiswindow.shiftkey

Return Value

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

Description

The variables indicate the state of the Alt, Ctrl and Shift keys at the time of the last event in the current window.

Each variable is set to ‘1’ ($True) if the corresponding key was down when the last event in the current window occurred. Otherwise, each is set to ‘0’ ($False).

Syntax #2 – EventName

Identifies the last event that occurred in the current window.

thiswindow.eventname

One of

Break, Canceled, Click, Closed, DoubleClick, GotFocus, HangUp, LostFocus, LostFocusModified, Modified, PanicExit, Timeout, WindowFocusSwitch, or keyname

Cannot be reset by an application program.

Return Value

Character string (alpha). Can be reset by an application program.

Description

Identifies, by name, the last event to occur in the current window.

This variable is not set in all operating environments.

ThisWindow.EventType gives additional information about the type of event, and ThisWindow.EventTag gives additional information about the type of object involved in the event.

Syntax #3 – EventTag

Identifies the tag of the object in which the last event in the current window occurred.

thiswindow.eventtag

Return Value

The identification tag of the object in which the last event in the current window occurred. Can be reset by an application program.

Description

Identifies the object in which the last event in the current window occurred.

The identification tag selected varies with the type of object involved in the event.

ThisWindow.EventName names the event, and ThisWindow.EventType gives additional information about the type of event.

Can be, depending on the type of object involved

Syntax #4 – EventType

Identifies the type of event that last occurred in the current window.

thiswindow.eventtype

One of

Window, Menu, MenuItem, Form, FormField, Accelerator, System

Return Value

Character string (alpha). Can be reset by an application program.

Description

Identifies the type of event that last occurred in the current window. ThisWindow.EventName names the event, and ThisWindow.EventTag identifies the object in which the event occurred.

Syntax #5 – KeyPressed

Indicates the key that, pressed, caused the event that last occurred in the current window.

thiswindow.keypressed

Return Value

Character string (alpha). Can be reset by an application program.

Description

The name of the key that, pressed by the application user, caused the last event to occur in the current window. Can be reset by an application program.

For example, if the application user presses the a key in a form field and the Modified event is intercepted by the application program, then ThisWindow.KeyPressed is set to “a”.

Note: The name of the key that caused an accelerator event is recorded in the ThisWindow.EventName variable.

Syntax #6 – MouseClick

Indicates if a mouse button accelerator caused the event that last occurred in the current window.

thiswindow.mouseclick

Return Value

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

Description

Set to “1” ($True) if the last event to occur in the current window was caused by the press of a mouse button that is defined as an accelerator for the window. Otherwise, set to “0” ($False).

If SET MOUSE is OFF, ThisWindow.MouseClick is 0.

Syntax #7 – ScrollingKey

Indicates if the accelerator that caused the event that last occurred was also a defined SCROLL key.

thiswindow.scrollingkey

Return Value

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

Description

Set to “1” ($True) if the accelerator key that caused the last event in the current window was also a defined SCROLL key. Otherwise, set to “0” ($False).

Example

window set scroll Up up Down down
window set accelerator up down escape
form open fEmployee
form set scroll fEmployee from EmpSet
form display
while
if thiswindow.scrollingkey = $true
change EmpSet from fEmployee
form scroll
continue
endif
… other commands …
endwhile

In the preceding code fragment, employee records are scrolled through a form and the application user can update the data. ThisWindow.ScrollingKey detects if a scrolling key was pressed, enabling the scrolling action to be performed under program control after any changes to the data are saved.

Syntax #8 – ScrollingKey

thiswindow.scrollingkey

Return Value

Character string (binary). Can be reset by an applicatio
n program.

Description

The variable indicates if the accelerator that cased the event that last occurred was also a defined SCROLL key.

ThisWindow.ScrollingKey is set to ‘1’ ($True) if the accelerator that caused the last event in the current window was also a defined SCROLL key. Otherwise, it is set to ‘0’ ($False).

Syntax #9 – WindowCol, WindowRow

The character column or row position of the current window.

thiswindow.windowcol

thiswindow.windowrow

Return Value

A number. Cannot be reset by an application program.

Description

The variables indicate the physical size of the current window in character rows (WindowHeight) and character columns (WindowWidth).

The physical dimensions of a window determine the visible space inside the window (i.e., the client area). This area changes in size when the dimensions of the window change. An application user can change the size of a window by using the resize feature. A program can change the size of a window using the WINDOW SIZE command.

An application program can position a window using the WINDOW MOVE command.

Syntax #10 – WindowHeight, WindowWidth

The physical height or width of the current window in character rows.

thiswindow.windowheight

thiswindow.windowwidth

Return Value

Number (INT). Cannot be reset by an application program.

Description

The variables indicate the physical size of the current window in character rows (WindowHeight) and character columns (WindowWidth).

The physical dimensions of a window determine the visible space inside the window (i.e., the client area). This area changes in size when the dimensions of the window change. An application user can change the size of a window by using the resize feature. A program can change the size of a window using the WINDOW SIZE command.

Syntax #11 – WindowName

The name of the current window.

thiswindow.windowname

Return Value

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

Description

The variable identifies, by name, the current window.

Example

You can use ThisWindow.WindowName to restore the focus to a window, making it the current window:

let SaveWin = ThisWindow.WindowName
window open Window2
… other commands …
window set current SaveWin

Syntax #12 – WindowNum

The identification number of the current window.

thiswindow.windownum

Return Value

A number. Can be reset by an application program.

Description

The variable identifies, by identification number, the current window.

Syntax #13 – WindowTag

thiswindow.windownum

Return Value

Character string (alpha). Can be reset by the application program.

Description

The variable identifies, by identification tag, the current window.

Syntax #13 – WindowState

Indicates whether the current window is maximized, minimized, or otherwise.

thiswindow.windownum

Return Value

A number. Cannot be reset by an application program.

Description

Indicates the state of the current window at the time of the last event in that window.

See Also

FORM INPUT

FORM SET

MENU INPUT

MENU SET

SCREEN CLEAR

SCREEN RESET

ThisForm

WINDOW SET

Changes data in EntitySets, relationships, forms, or result sets.

Syntax #1

Changes specific fields in one or more records in an EntitySet, relationship, form, or set. The existing values in target fields are changed to specified values. The LET subcommand explicitly assigns values to the target fields. Only fields explicitly named in the LET subcommand are changed.

CHANGE [num] [setspec] [LET clause] [EVALUATE clause] [-> clause]

Syntax #2

Changes one or more records in an EntitySet, relationship, form, or set from data found in a set specification. Data for the target fields in the records is taken from a specified set. The LET subcommand can be used to direct the source data to particular target fields, and, if desired, to process the source data in some manner before assignment.

CHANGE [num] [setspec] [FROM source] [LET clause] [EVALUATE clause] [-> clause]

Syntax #3

Changes one or more records in an EntitySet, relationship, form, or set from data found in an application document. Date for the target fields in the records is taken from an unstructured application document or a set whose only component is an unstructured application document. You can use the FORMAT clause to direct the source data to particular target fields. The PROMPT clause performs the same function, but, in addition, sends the field names and their current values to the current output destination for display. You can use the LET subcommand to process the source data in some manner before assignment.

CHANGE [num] [setspec] FROM doc [LET clause]

[FORMAT | PROMPT [field]] [EVALUATE clause] [-> clause]

Parameters

Comments

Any number of fields can be assigned a value through the LET clause. Any target field that has not explicitly been assigned a data value by LET is supplied with a data value from the field in source that has the same name (if any). If no field in source has the same name as a target field and if no value has been explicitly assigned, then the target field is left unchanged.

The FORMAT clause specifies the order in which data for each field appears. The PROMPT clause performs the same function, but, in addition, it displays the field names and the old values on the terminal. Target fields not assigned data values by LET, FORMAT, or PROMPT are left unchanged.

Special rules apply when data is taken from an unstructured application document to change the values in target fields:

• If the current delimiter is not a space (see the SET DELIMITER command), then two delimiters side-by-side indicate that a field is $Null. For example, if a slash (/) were the delimiter, then abc/def// would generate three assignments: abc, def, and $Null.
• If the current line in the application document does not contain enough values for the fields in the records, the remaining fields are left unchanged.
• An input line of zero length is taken as an end-of-file indicator and stops the CHANGE command, unless a SET EOFVALUE command has been issued.
• An asterisk (*) used with CHANGE indicates that an existing value is to be left untouched. To specify an asterisk as a literal character, place a backslash () preceding it.

Before all fields are assigned their new values, they are checked to ensure that a required field is not $Null. If a required field is $Null, an error is generated and the record is not changed. This check can be turned off with the SET CHECKNULLS command.

Messages marking the progress of a CHANGE command can be displayed on the terminal. See SET MEMBERCOUNT and SET MEMBERINTERVAL for details.

Refrain from using the CHANGE command to modify records to the Object Dictionary EntitySets for user interface objects (windows, menus, forms/displays, and form field/menu items).
The records contain many fields, often with important inter-field dependencies. Records modified using CHANGE are not validated in the usual way, and incorrect values in the record could cause the software to behave unexpectedly or even crash.
Use the Screen Painter to modify all user interface objects.

Rules for Value Assignments to Fields During CHANGE

The software assigns a value to each target field based on the first of the following situations that holds true for that field:

1. The target field is explicitly assigned a new value in a LET subcommand.
2. The structured source object contains an identically-named field whose value is implicitly assigned to the target field.

OR

The unstructured source object contains a value in the sequential position that matches the sequential position of the target field’s name in the FORMAT or PROMPT clause.

OR

The unstructured source object contains a value in the same sequential position of the target field in the records. This occurs when no FORMAT or PROMPT clause is supplied, or when the clause does not specify field names.

3. In all other cases, the value of the target field does not change.

Once new values have been determined for all target fields in the record, the software checks to ensure that a Required field is not $Null. If a Required field is $Null, the software raises an error, and the record is not changed. This check can be switched off with a SET CHECKNULLS OFF command.

Special rules apply when the data in an EntitySet or relationship is being changed using data from an unstructured application document (Syntax #3):

1. The $Null property can be explicitly assigned to a field using the following technique:
   • If the current delimiter is not a space (see SET DELIMITER), then two delimiters side-by-side explicitly indicate an unassigned value ($Null). For example, if a slash (/) is the delimiter, then abc/def// generates three values: abc, def and $Null.
2. If a line in the document fails to provide a value for every field in the record being changed, each field not assigned a value remains unchanged.
3. An asterisk (*) explicitly indicates a field that is to be left unchanged. For example, abc * def generates three values: abc, “no change”, and def. To specify an asterisk as a literal character, place a backslash ( – Escape) before it. For example, if you want a particular field to have the value 5*6, type 5*6 into the source document. Alternatively, use SET SPECIALSCAN to control how the metacharacters backslash () and asterisk (*) are to be handled when they appear in an unstructured application document that is being used as a data source. When SET SPECIALSCAN is ON, the backslash and asterisk characters have their special meanings. When SET SPECIALSCAN is OFF, the backslash and asterisk characters are treated as ordinary data.
4. A line of zero length in the source document (i.e., the line consists solely of a carriage return or a newline character) is taken as an end-of-file indicator by default. The CHANGE command stops unless a SET EOFVALUE command has been issued.

Example

change all Emps from terminal prompt LastName FirstName

LastName  FirstName

Smith   John

:

Prompts with the existing values for each record and waits for input.

LastName  FirstName

Smith   John

:* Jim

LastName  FirstName

Jones   Fred

:

Typing * Jim and pressing Return changes the first name from John to Jim. A prompt for the next record appears.

LastName  FirstName

Jones   Fred

:Johnston

LastName  FirstName

Samuels  Jim

:

Typing Johnston and pressing Return changes the last name from Jones to Johnston. A prompt for the next record appears.

Pressing Return without typing anything terminates the CHANGE command.

change WaterSamples from fWaterSamples

Updates an EntitySet based on the data in a form.

change Employees (unrelated) WorkOn Projects

sorted by LastName from NewProjects

where ProjAssigned = “N”

sorted by ProjDate descending

let Employees.ProjNum = NewProjects.ProjId

Assigns a new project to Employees that are not currently working on a project. The employee records that are unrelated to any project are sorted in LastName order. The sorted records are updated from the set of NewProjects that are not assigned (ProjAssigned=”N”).

change let LastName = “Smith”

Changes the last name in the current member of the current set.

change all Employees where DeptNum = D01 let DeptNum = D02

Changes department number D01 to D02 for the entire set.

form open dInvoice

change all fInvItem from LineItems

form display input

Fills the occurrences of a particular form with data from a particular set.

See Also

ADD

UPDATE

Certain characters and words are reserved for special purposes in the Zim software.

Reserved Characters

These characters are sometimes called meta-characters. Reserved characters include

• quotation marks (” and ‘) that define and enclose character strings
• spaces that are the default field separator (delimiter)
• backslashes () that escape other characters
• percent signs (%) that mark the start of a comment
• question marks (?) that, when not in quotation marks, are a wildcard indicator
• braces ({ and }) that mark and enclose case expressions

Reserved Words

You cannot use any reserved word as a database, application, or filename in Zim. Reserved words include

• any automatically generated filename in the form “prefix_99999″ where the prefix is a name automatically generated by Zim

• the strings, words, commands, and function names are found in the following table: