ZIM 4GL Language Reference – Página: 8 – 4GL APPLICATION FRAMEWORK

SET DECIMALS

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.

Keys Pressed	ON	OFF
100	1.00	100.00
12345	123.45	12345.00
123.45	123.45	123.45
.99	99	99

DETAIL LINE

Specifies the fields that are selected for a report

Syntax

DETAIL LINE [colheadings] [GRAPHIC [TEMPLATE name]] reportitem [:format:] [WHERE clause]

Parameters

colheadings	Can be COLUMN HEADING OFF Specifies that column break headings are not to be re-displayed at the top of each report page. LEVEL n [WIDTH n ] LEVEL 0 causes level 0 column break headings to be printed at the top of each report page. This is the default break level. LEVEL n causes column break headings to be printed for each break level n or higher in the hierarchy (n must be an integer greater than or equal to 0). WIDTH n sets the width (in characters) of the space allotted to the column break heading.
TEMPLATE name	For graphical reports, the name of an optional template to define the layout of the report.
reportitem	Any value expression. If the expression is complex, it must be enclosed in parentheses.
format	A set of instructions defining the format for the associated reportitem. Format is enclosed in : (colons) and can consist of any valid combination of format options.

Comments

The DETAIL LINE command is executed for every record of the set specified in the REPORT FROM command.

The column headings for all reportitems specified in the DETAIL LINE command are displayed, subject to any colheadings specification.

Only one detail line is produced for each record of the report set. If more than one DETAIL LINE command is used in a report specification, the DETAIL LINE command that is executed for a particular record in the report set is the first DETAIL LINE without a WHERE clause, or the first DETAIL LINE whose WHERE clause is true for that record.

For more information on format, see Available Format Options.

$copytoclient

Copies files from the server side to the client side.

Syntax

$copytoclient(source file name, destination file name, file type)

where

source file name	an expression that evaluates to a character string containing a valid file address
destination file name	an expression that evaluates to a character string containing a valid file address
file type	an expression that evaluates to a character string that starts either with “B” (from “Binary”) or “T” (from “Text”)

Return Value

The value return by this function is the file address of the destination if it is executed correctly; otherwise, it will return a $Null value.

Comments

This function is designed to work under ZIMTC and copies file from the server side to the client side using the file type specified. Files of the binary type are sent as they are, without their contents being checked (like images, videos, etc). On the other hand, files of the text type are copied using text file conventions for Windows and Unix.

Both the source and the destination file names can be either relative or absolute file paths. The following remarks apply to these paths:

source file is absolute	the file is taken from the absolute path
destination file is absolute	the file is written onto the absolute path. Care should be taken because this absolute path refers to a location in the client’s machine; if there are many different users running, all users must have the same valid address
source file is relative	normally, the current directory is the database directory; therefore, the file will be taken from an address calculated inside the current directory
destination file is relative	the file goes to place that is relative to the current directory in the client session which is always where the Zimtc session has been started; therefore, if the file is needed for subsequent operations, then the same relative path must be used. If the file will be needed after the current session is finished, then it is suggested to provide an absolute path to the destination file as Zimtc does not guarantee that files will be preserved after the session finishes

Because ZIMTC actually acts like a Web Browser in most respects, the client side (managed by ZIMTC) does not have the files needed to perform certain operations which should be located in a place only known by the server. This situation is specially important when the file is needed by an external processing capability like an ActiveX component or any other program that uses a file without the direct control of ZIMTC.

If the destination file name contains sub-directories that don’t exist, they are created.

The ZIM executable ignores this function as it makes no sense copying a file to itself.

Example

This is an invocation of an ActiveX property to edit the file specified. It reads the file from a fixed location but writes it to the directory where the session has been started.

let vResult = $objsetproperty(Object, "image", $copytoclient("c:\myfiles\myimage.bmp", "myfiles\myimage.bmp", "binary"))

This example copies the text file from the database path to a fixed location in the client’s machine.

out $copytoclient("mytext.txt", "c:\mextext.txt", "T")

Set Specification

Identifies particular records in an Zim database.

Syntax

object [WHERE clause] [SORTED BY clause] [KEEP clause]

Parameters

object

The name of an EntitySet, relationship, form, application document, or result set. Role names can be used for EntitySets or relationships. Any number of objects can be specified, provided that they are meaningful in context.

Comments

A set specification (sometimes called a setspec) is a statement that uses EntitySets, relationships, forms, application documents, and result sets as the source of the set being declared. Each object in the set specification is called a component. (Result sets can represent more than one component.)
A set specification can also include a condition that limits record selection (WHERE clause), a sorting statement (SORTED BY clause), and a component projection list that limits the number of components in the resulting set (KEEP clause).
Any number of objects can be declared. But, if you declare more than one object, then you must declare the relationships through which records in those objects are associated.
Each object can be further qualified using any valid combination of the following subcommands:
-> (Dynamic rename), COMPLETE, UNRELATED, USING
and in particular circumstances:
INTERSECT, MINUS, UNION
Set specifications are processed, in order, from left to right.

Example

list all Employees

The simplest type of set specification. The set consists of all of the records in the EntitySet Employees.

list all Employees where LastName = “Smith”

Includes a condition for record selection.

list all Employees sorted by EmpNum

Includes a sorting subcommand.

list all Employees where LastName = “Smith” sorted by EmpNum

Combines a condition and a sort.

list all Employees WorkIn Departments

The relationship that defines the association (WorkIn) must be included because two EntitySets are being declared. All associated records in Employees and Departments are included.

list all Employees WorkIn Departments keep Departments

Adds a component projection list. Of associated records in Employees WorkIn Departments, only the (unique) records from Departments are included in the set.

list all Employees (unrelated) WorkIn Departments

The subcommand UNRELATED modifies the relationship; all records in Employees that are unassociated with Departments are included.

-> (Dynamic Rename)

Dynamic Rename (->)

Overview

Dynamic renaming (->) is a feature used in command structures to rename components within a set specification. This allows for flexible manipulation of data sets, enabling components to be used in different roles across various commands.

Syntax

objname (oldcomponentname -> newcomponentname)

objname: The name of a set, an EntitySet, a relationship, or a role. There must be at least one component in objname.
oldcomponentname: The existing name of a component in objname.
newcomponentname: The new name to be given to the specified component of objname.

Detailed Explanation

When creating a result set, the structure of that set reflects the component names or role names found in the original set specification. If you want to use the result set in a subsequent command and have a component of the set used in a different role, dynamic renaming (->) enables you to rename the component.

Both oldcomponentname and newcomponentname must refer to the same underlying object.

Examples

Example 1: Renaming Employees to Managers

find Employees WorkFor Managers where LName = Smith 
keep Employees -> set1
find Employees WorkFor set1 (Employees -> Managers) 
keep Employees -> set1

In this example, the component Employees is dynamically renamed to Managers in the second command. This allows the Employees component to be used in the role of Managers.

Example 2: Loop Example

find Managers -> MSet
while
  find MSet (Managers -> Employees) WorkFor Managers keep Managers
  if $setcount > 0
    find -> MSet
  else
    break
  endif
endwhile
list all MSet

In this loop, each usage of the Managers component of MSet is dynamically renamed to Employees to select the top managers from an EntitySet of employees. This iterative process continues until no more managers are found.

Comments

Flexibility: Dynamic renaming provides flexibility in how components are used in different roles across commands. This is particularly useful in complex queries and data manipulations.
Consistency: Ensures that the underlying object remains consistent even when its role or name changes. This helps maintain the integrity of the data set while allowing for dynamic adjustments.

Practical Applications

Dynamic renaming can be used in various scenarios, such as:

Data Analysis: Renaming components to fit different analytical roles.
Database Management: Adjusting roles of components for efficient querying and data retrieval.
Software Development: Implementing dynamic role changes in algorithms and data structures.

Why Use Dynamic Renaming?

1. Flexibility in Data Manipulation

Dynamic renaming allows users to adapt the roles of components within a data set on-the-fly. This flexibility is crucial when dealing with complex data structures or when the same data needs to be viewed or analyzed from different perspectives.

2. Simplifying Complex Queries

In scenarios where multiple roles or relationships exist within a data set, dynamic renaming can simplify queries. By renaming components, users can avoid writing redundant or overly complex commands, making the code more readable and maintainable.

3. Enhanced Data Analysis

Analysts often need to pivot data to gain different insights. Dynamic renaming enables them to reassign roles to components, facilitating various analytical approaches without altering the underlying data structure.

4. Efficient Resource Management

In database management, dynamic renaming can help optimize resource usage. By reusing components in different roles, it reduces the need to create multiple copies of the same data, thereby saving storage and processing power.

5. Improved Algorithm Implementation

For software developers, dynamic renaming can be particularly useful in implementing algorithms that require role changes. It allows for more dynamic and adaptable code, which can handle a wider range of scenarios without significant modifications.

Conclusion

Dynamic renaming is a versatile tool that enhances the flexibility, efficiency, and clarity of data manipulation and analysis. It allows users to adapt to changing requirements and complex data relationships seamlessly.

$substring

Extracts a segment of a character string.

Syntax

$substring(source,position,length)

Parameters

source	a character string, or an expression that evaluates to a character string
position	a number, or an expression that evaluates to a number
length	a number, or an expression that evaluates to a number

Return Value

Character string, containing a string extracted from source, whose first character is position characters into source, and whose length is length characters.

Comments

Use $substring to extract a portion of source. The resulting string contains length characters, starting position characters into source.

If source is not a character data type, it is converted to a character data type before the function is applied.

If position is beyond the end of source or if length is zero or negative, the result is the null string.

If position+length is longer than source, the result consists of all characters from position to the end of source.

Example

$substring("the quick brown fox jumped",7,5)

Extracts “ick b” from the string.

$substring(9999,1,1)

Evaluates to ” ” (the number is converted to a string).

$substring(5+4,17,1)

Evaluates to “9” (the number is converted to a string).

HELP

Presents online help information.

Syntax

HELP [topic]

Parameters

For files that invoke the winhelp executable

topic

A character string or a number, or an expression that evaluates to a character string or a number. Identifies a particular help topic in the help file.
If topic is a character string, the HELP command accesses the help file with topic as a keyword. If topic contains the pattern-matching wildcard character “%”, HELP uses the prefix of topic, up to the first “%” as the keyword. A partial key match is done, and matching keywords are displayed in a search window.
If topic is a number, it is assumed to represent a “context ID”. HELP accesses the help file using topic as the “context ID”.
If the keyword or “context ID” provided by topic is invalid, a warning message is displayed, followed by the help topic search window.
If topic is blank or $Null, HELP shows the first topic in the help file.

Note: For Explorer-style hypertext Help files, topic is a character string or a number, or an expression that evaluates to a character string or a number which identifies a particular help topic in the help file. It invokes the name of one of the .html files that were used to build the . chm file.

Comments

The HELP command displays online help about a given topic. By default, the command accesses the help file, ZDL.CHM, in the directory containing the software. To use another help file, set the system variable $ HelpFile to the name of the desired help file.

In the Windows environment, the HELP command determines, based on the extension of the help file, whether to invoke the Internet Explorer’s hypertext help viewer ( hh.exe) or to invoke the Windows help driver ( winhelp.exe) to display the help topics.

Winhelp help files

If the help topic is specified as a character string, the HELP command passes the string to the help driver as a keyword. If an exact match is not found, the help driver displays a warning message, following the topic search window.

If the character string contains the pattern-matching wildcard character $, HELP passes the string to the help driver, up to the first $ character, as a keyword prefix. Keywords that match the prefix are displayed in a topic search window for selection.

If the help topic is specified as a number (any numeric data type), HELP passes the number to the help driver as a topic identifier. If the identifier is invalid, the help driver displays a warning message, followed by the topic search window.

If no help file can be found, the software raises an error.

Hypertext help files

The hypertext help viewer accepts only strings as topic names and they must match the html files that were used to build the . chm file.

PROCEDURE

Starts and defines a procedure.

Syntax

PROCEDURE procname ([IN|OUT|INOUT] parm) [LOCAL (var)]

Parameters

procname	A valid object name. Procname must be the name of the existing application document that contains this procedure and must not conflict with a system keyword.
IN, OUT, or INOUT	Designates the direction in which the associated parm passes a value: Into the procedure (IN), out of the procedure (OUT), or both (INOUT). If omitted, IN is assumed.
parm	The name of a parameter (a type of variable used only to carry values into and out of procedures). When more than one parameter is specified, they are separated from one another by commas. If no parameters are defined, the enclosing parentheses must still appear. A corresponding expression for each parameter is provided in the call to the procedure.
var	The name of the local variable whose use is restricted to within the local procedure. Local variables must be separated from one another by commas.

Comments

PROCEDURE declares the start of a procedure program. (A procedure program can have many local procedures, but only one main procedure.)

The call to the procedure must contain a corresponding expression for each parameter. The order of the expressions in the call must match the order of the parameters in the procedure declaration. If the number of expressions in the call differs from the number of declared parameters, then the call is ignored. Within the procedure, formal parameters are treated as if they were variables.

A PROCEDURE command must always have a corresponding ENDPROCEDURE command that marks the end of the procedure.

The number of formal parameters, plus the number of local variables, must not exceed the maximum parameters entry in the configuration file. The parameter size entry in the configuration file determines the maximum size of each formal parameter and local variable.

Example

procedure MyProc (item1, in item2, out item3, inout item 4)

Item1 and item2 are formal IN parameters, item3 is a formal OUT parameter, and item4 is a formal INOUT parameter.

procedure Summarize (DeptName, out AvgSalary) local (WorkVar)

WorkVar is a local variable (known only to procedure Summarize).

Syntax

LOCALPROCEDURE procname> ([IN|OUT|INOUT] parm)[LOCAL(var)]

Parameters

procname

A valid object name. The name of the local procedure cannot conflict with a software keyword. When a local procedure name conflicts with a pre-defined object name, the local procedure name takes precedence, provided the software is currently operating within the program that contains the local procedure.

IN, OUT, or INOUT

Designates the direction in which the associated parm passes a value: into the procedure (IN), out of the procedure (OUT), or both (INOUT).
If omitted, IN is assumed.

parm

The name of a parameter (a type of variable used only to carry values into and out of procedures). When more than one parameter is specified, they are separated from one another by commas.
If no parameters are defined, the enclosing parentheses must still appear.
A corresponding expression for each parameter is provided in the call to the local procedure.

var

The name of the local variable whose use is restricted to within the local procedure. Local variables must be separated from one another by commas.

Comments

The body of a local procedure is a sequence of commands. A LOCALPROCEDURE must always end with a corresponding ENDPROCEDURE command.

Local procedure declarations must appear at the beginning of their application program document, before the main procedure or before the commands of a macro program. A local procedure cannot be nested within the body of another procedure or local procedure. Local procedures obey all the same call/return rules as standard procedures, and possess the same capabilities as a standard procedure.

A local procedure can call other procedures in the same application program document or in other program documents. However, a local procedure can be called only by other procedures defined in the same program document.

Example

localprocedure LocalProc1 ()

transform LocalProc2 ()

endprocedure

%——————————————-

localprocedure LocalProc2 ()

output “Hi from LocalProc2”

endprocedure

%——————————————-

procedure MainProc (Param1, Param2)

LocalProc1 ()

LocalProc2 ()

endprocedure

The main procedure calls two local procedures. The first local procedure transfers control to the second through a TRANSFORM command.

COLUMN BREAK

Breaks the body of column-oriented reports into summary groups.

Syntax

COLUMN BREAK level [HEADING reportitem [:format:]]

[FOOTING reportitem [:format:]]

Parameters

level	The break level number (an integer greater than or equal to zero). In the hierarchy of breaks, the higher the level number, the more minor the break. (For example, a level 1 break also triggers breaks at level 2, level 3, and so on.)
HEADING	Introduces the “heading clause” for the break level, which can consist of a break orientation statement, a number of report items and their format instructions, or both. The footing displays each time the break level is triggered.
FOOTING	Introduces the “footing clause” for the break level, which can consist of a break orientation statement, a number of report items and their format instructions, or both. The heading displays each time the break level is triggered.
reportitem	Any valid expression that yields a value for display in the break heading or break footing. The heading and footing can each display a series of reportitems. Each item has its own associated format.
format	A set of instructions defining the format for the associated reportitem. Format is enclosed in : (colons) and can consist of any valid combination of format options.

Comments

The COLUMN BREAK command breaks the body of a column-oriented report into summary groupings.

Each time a BREAK command triggers a break at a specified level, the COLUMN BREAK for that level and all levels lower in the hierarchy are triggered.

Report items in the COLUMN BREAK heading can include individual values from the first member of the current group. Report items in the COLUMN BREAK footing can include individual 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.

If both the heading and footing clauses are omitted, a column break at the indicated level causes report formatting to recommence at the left-hand side of the page, beneath any previously formatted columns.

Syntax

Comments

Syntax

Parameters

Comments

See Also

Syntax

Return Value

Comments

Example

Set Specification

Syntax

Parameters

Comments

Example

See Also

Dynamic Rename (->)

Overview

Syntax

Detailed Explanation

Examples

Example 1: Renaming Employees to Managers

Example 2: Loop Example

Comments

Practical Applications

Why Use Dynamic Renaming?

1. Flexibility in Data Manipulation

2. Simplifying Complex Queries

3. Enhanced Data Analysis

4. Efficient Resource Management

5. Improved Algorithm Implementation

Conclusion

Syntax

Parameters

Return Value

Comments

Example

See Also

Syntax

Parameters

Comments

Winhelp help files

Hypertext help files

See Also

Syntax

Parameters

Comments

Example

See Also

Syntax

Parameters

Comments

Example

See Also

Syntax

Parameters

Comments