Category: SET Commands

Specifies the current input document.

Syntax

SET INPUT docname [FILEPATH options]

Parameters

Comments

The SET INPUT defines an input for subsequent Zim commands referring to the defined docname. The input is maintained open until it is explicitly closed by a SET INPUT TERMINAL or another document name.

Usually, the docname is defined as structured with a big field (big enough for the required application) so that the contents of the records read can be processed.

Example

set input MyDoc
list 1 MyDoc
compute 1 MyDoc evaluate (let MyVariable = MyDocField)
... process MyVariable ...
list 1 MyDoc
set input terminal

The above example is very useful as it allows continuous records to be read from MyDoc without starting from its beginning all the time. The first record of MyDoc is listed, the second is processed, while the third is again listed. Finally, the document is closed.

The next example shows the combination of INPUT and OUTPUT documents. The output is MyReport. All records from FirstFile.txt are listed in the output. Then, 20 records from Zimprof are listed. Next, 10 records from SecondFile.txt are listed and, finally, all records from AnotherDoc are also listed. To wrap up, both INPUT and OUTPUT are closed by assigning them to TERMINAL.

set out MyReport
set input MyDoc filepath "file://c:\\myDir\\FirstFile.txt"
list all MyDoc
list 20 zimprof
set input MyDoc filepath "file://c:\\myDir\\SecondFile.txt"
list 10 MyDoc
list all AnotherDoc
set input terminal
set output terminal

This example reads and processes all input arriving from a serial port (only for Linux).

set input MyDoc filepath "port:///dev/tty99:115200:8:N:1:N"
while ...
   compute 1 MyDoc evaluate (let MyVariable = MyDocField)
   ... process MyVariable ...
endwhile
set input terminal

Executes an OS command and captures its output (i. e. STDOUT).

% In this case, data is formatted.
% You can add the lines directly but you need to filter the useful ones.
set input MyDoc filepath "pipe://dir ..\\Images\\*.jpg"
list all MyDoc

Directory: C:\users\cebre\pictures

Mode   LastWriteTime     Length  Name
------ ----------------- ------- -------------------
-a---- 21-Oct-2023 09:45 2885941 20200827_114259.jpg
-a---- 21-Oct-2023 09:42 2555772 20200827_114311.jpg

set input terminal

Modify certain attributes of fields.

Syntax

SET <fieldname> REQUIRED ON|OFF

SET <fieldname> FIELDLISTWIDTH <number>

SET <fieldname> HEADING <charstring>

SET <fieldname> MASKFIELD <charstring>

SET <fieldname> REMNAME <charstring>

Parameters

Comments

This SET command enables users to modify certain attributes of fields without doing an ERASE and CREATE command. These SET commands modify the operational state of the fields and are in effect until the field’s owner is erased.
The SET REQUIRED command changes if a field can have the value $null. This is equivalent to changing the REQD field to “yes” or “no”.
SET FIELDLISTWIDTH alters the list width of a field.
SET HEADING and SET MASKFIELD alter the heading and mask patterns for a field. Setting HEADING and MASKFIELD to the zero length string ” effectively deletes any heading or mask that was previously defined.
SET REMNAME specifies a new remote name for the field or deletes the existing remote name if the new setting is ”.
The SET SELECTIVITY is identical to the existing SET SELECTIVITY command, except that the is specified before the attribute SELECTIVITY rather than after.

See Also

SET SELECTIVITY

Turns the output of cross-reference information on or off during parsing and compiling.

Syntax

SET XREF ON|OFF

Comments

The XREF option is set OFF by default.

When XREF is ON, the software sends dependency information to the current output when an application program is parsed or compiled. One line of output is generated for every object explicitly referenced by the program. The information is not saved (unlike the information produced when SET DEPENDENCY is ON).

The SET XREF command is not affected by the SET RESET and SET RESTORE commands.

Each line of output contains six sections of information, with fourteen fields in total:

• Section 1 consists of one field that contains the output flag.
• Section 2 contains information about the specific object that is being parsed or compiled.  This section consists of three fields, the Document Name (name of program), the Object Type (for the document name) and the Zim Directory Name (directory in which the object is located).
• Section 3 contains information about the ownership of the specific object that is being parsed or compiled.  This section consists of three fields, the owner Object Name,  the owner Object Type and the owner Object Directory.
• Section 4 contains information about the internal object (object within a specific object ) that is being parsed or compiled.  This section consists of three fields the internal Object Name, the internal Object Type and the internal Object Directory.
• Section 5 contains information about the owner of the internal object that is being parsed or compiled. This section consists of three fields, the Object Name of the internal object owner, the Object Type of the internal object owner and the Object Directory of the internal object owner.
• Section 6 consists of one field that contains the line number or sequence number in which the reference occurred.

Example

A simple application program can contain the following two lines:

% This is a test program named ServBye
list fields format SN FieldName

In which case, the commands shown below produce the indicated output:

> set xref on
> set output terminal
> parse ServBye
P ServBye Document ZIM ZIM Directory ZIM Documents EntitySet ZIM ZIM Directory ZIM 1

See Also

COMPILE

DEPENDENCY

PARSE

SET OUTPUT

Resets most global application settings to their default state.

Syntax

SET RESET

Comments

The SET RESET command returns most global application settings to their default values.
The global application settings reset to their defaults by SET RESET include

The SET RESET command does not record the state of the following settings:

See Also

SET RESTORE

SET SAVE

Establishes the format for data output.

Syntax

SET OUTPUT FORMAT [ NORMAL  |  COMMADELIMITED  |  XML  |  XMLSIMPLE  |  JSON  |  JSONSIMPLE ]

Comments

The value of OUTPUT FORMAT is NORMAL by default. That is, the LIST and OUTPUT commands create output whose format exactly follows the Object Dictionary definitions of the individual fields being output. The SET OUTPUT FORMAT command can be reset to enable these commands to output data in comma-delimited format, XML, or XMLSIMPLE formats.

When using the comma-delimited format, database fields are separated from one another by the current delimiter character. This is normally a comma but can be changed using the SET DELIMITER command. Character-type fields have trailing blanks removed and are enclosed within a pair of text delimiters. This is normally double quotation marks but can be changed using the SET TEXTDELIMITER command. Numeric fields have leading blanks removed.

When using the XML format, database fields are printed using XML conventions. Each XML “record” describes all fields in full detail of the actual record being printed. In other words, each row being printed has sub-rows displaying each field of the row. In turn, each sub-row displays the content of each field.

When using the XMLSIMPLE format, database fields are printed using XML conventions in a simple format. Each XML “record” only describes the field names and their corresponding values.

Fields that are $Null are output using the current SET NULLVALUE string (without text delimiters). If NULLVALUE is a space character, fields that are $Null are output as a pair of text delimiters.

The formats JSON and JSONSIMPLE produce a JSON-structured output. JSONSIMPLE compresses all blanks whereas JSON outputs in a formatted way.

Remarks

The XML,  XMLSIMPLE, JSON, and JSONSIMPLE format options are only designed for output.

A header can be attached to the output document by using the command SET XMLHEADER.

The identification of each row being printed can be changed by means of the command SET XML ROWELEMENT.

Example

set save
set heading off
set nullvalue "$null"
set output fieldlistwidth off
set output maskfield off
set output virtualfield off
set output format commadelimited
set output UnstructuredDoc
list all Customers
set restore
set output maskfield on    % not saved by save/restore
set save
set output format xmlsimple
set xml rowelement "MyRow"
set output MyDoc
list 1 Doc
set restore

See Also

LIST

OUTPUT

Enables or disables the requirement of typing the decimal point.

Syntax

SET DECIMALPOINT ON|OFF

Comments

The DECIMALPOINT option is set ON by default.

DECIMALPOINT only has an effect on entry fields during FORM INPUT:

When DECIMALPOINT is ON:

typed digits fill the input mask from the right-most digit leftwards

there is no need to type the decimal point since its presence is assumed

mimics the functionality of TUI for numeric values with decimal point

When DECIMALPOINT is OFF:

typed digits fill the input mask from the first digit to the left of the decimal point leftwards

typed digits are assumed to belong to the integer part of the numeric value

decimals are assumed to be 0.

if there are decimals in the input numeric value, the decimal point must be typed

Example

set decimalpoint on

set decimalpoint off

Examples: Numeric value of an Entry Field with input mask =”9999.99” after a FORM INPUT.

See Also

SET ERRORS

Specifies index selectivity for indexed fields.

Syntax

SET SELECTIVITY fieldname value1 value2 value3

or

SET < fieldname> SELECTIVITY value1 value2 value3

Parameters

Comments

Index selectivity represents the fraction of records that you would expect to retrieve with a particular kind of search. For example, for an indexed field called Gender, you can expect an equality search to have a selectivity ratio (value1) of 0.500 (about half the records contain “male”; the other half, “female”). The strategy analyzer uses the values you supply to determine the best use of indexed fields in a retrieval operation.
The SET SELECTIVITY option has no effect on the Fields EntitySet in the Object Dictionary.
The SET SELECTIVITY option is not affected by the SET RESET and SET RESTORE commands.

Example

set selectivity Emps.Gender 0.5 0.5 0.5

set selectivity Emps.Age 0.02 0.1 0.5

The preceding commands indicate that Age is a more selective field than Gender. In a command such as find Emps where Age = 39, only about 2 per cent of the records in Emps are expected to be retrieved.

See Also

SET SIZE

Saves the current global application settings in their current state for later use.

Syntax

SET SAVE

Comments

The SET SAVE command records the current state of all global settings, and pushes the group of settings onto a stack of previously saved settings (if any).
The SET RESTORE command pops the top group of settings off the stack, thus restoring the values saved in that group.
The global application settings saved to the stack by SET SAVE include

The SET SAVE command does not record the state of the following settings:

Example

set save

set output MyDoc

set headings off

set pause off

set pagewidth 100

set pagesize 100

list all Employees

set restore

In the preceding example, SET SAVE saves the current state of the global settings before OUTPUT, HEADINGS, PAUSE, PAGEWIDTH, and PAGESIZE are adjusted to send data to an application document. SET RESTORE then returns the settings to their previous values.

See Also

SET RESET

Restores the top group of settings in the stack of saved global settings created by SET SAVE.

Syntax

SET RESTORE

Comments

The SET SAVE command records the current state of all global settings, and pushes the group of settings onto a stack of previously saved settings (if any).
The SET RESTORE command pops the top group of settings off the stack, thus restoring the values saved in that group.
The global application settings reset to their defaults by SET RESTORE include

The SET RESTORE command does not record the state of the following settings:

Example

set save

set output MyDoc

set headings off

set pause off

set pagewidth 100

set pagesize 100

list all Employees

set restore

In the preceding example, SET SAVE saves the current state of the global settings before SET OUTPUT, SET HEADINGS, SET PAUSE, SET PAGEWIDTH, and SET PAGESIZE are adjusted to send data to an application document. SET RESTORE then returns the settings to their previous values.

See Also

SET RESET

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

Syntax

SET FOR UPDATE ON|OFF

Comments

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

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

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

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

Example 1

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

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

Example 2

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

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

Scenario 1

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

If two users are running the same program, then:

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

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

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

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

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

. User 2 is still waiting…

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

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

Scenario 2

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

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

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

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

. User 2 still waiting…

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

. User 2 still waiting…

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

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