Categoria: Commands

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

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

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

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

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: