7 Functions
Functions are the interface to the used programming language. The keyword is function followed by the function type and the function identifier. As to function prototypes the data types of the parameters have to be specified instead of the function arguments. In this definition the functions have to be distinguished according to their later use.
Basically, several different kinds of functions can be distinguished here:
-
This function type can have up to 16 arbitrary parameters, which have to be specified correspondingly in the function declaration.
-
Function connected to an object (callback function):
This function, which is specified directly in the object definition by .function, has to be defined as a callback function. The IDM defines which parameters this function will get. This is why they must not be specified in the declaration. In addition, the definition of this function specifies the user events for which the function is to be called.
-
Function connected to a "canvas" object (canvas function):
Since this object is a significant exception in the IDM, and has to be treated differently by the application, there is a special function type canvasfunc for it. Its function parameters are also predefined by the IDM and must not be given in the declaration.
-
This function can be specified in the .datamodel attribute of all objects that also support user-defined attributes. A data function can serve as a Data Model (Model component) to provide the presentation objects with data values. The parameters of a data function are predefined by the ISA Dialog Manager and cannot be changed by the user.
-
This function is indicated when defining format resources as well as at editable texts and tablefields (attribute .formatfunc). The function parameters are predefined by the IDM and must not be defined in the declaration.
-
Reloading function for tablefields:
This function is indicated in the attribute .contentfunc when defining tablefields. The function parameters are predefined by the IDM and must not be defined in the declaration.
Permitted languages are:
If no language is defined, C is chosen as default language.
| Data Type |
Value Range |
|---|---|
|
Arbitrary, undefined data type; will be defined only by actual occupation. |
|
|
Attribute data type in the IDM. |
|
|
Boolean value (true | false). |
|
|
Class of an object, e.g. "window". |
|
|
IDM data type. |
|
|
Symbolic constant; enumeration type for special attributes, e.g. "sel_row". |
|
|
Type of event, e.g. "select". |
|
|
Index value for 2-dimensional attributes [I,J]. |
|
|
Integral number ("long integer"), e.g. 42. |
|
|
Method, e.g. "delete". |
|
|
Object in the sense of the IDM (actual objects, resources, functions, rules,…). |
|
|
Pointer from the application. |
|
|
Character string which can be arbitrarily long (zero terminated), e.g. "hello". |
|
|
Data type without value. |
Note for IDM on Microsoft Windows
The IDM data type integer corresponds to the data type long in the C Interface.
The ISA Dialog Manager uses the Pascal Calling Convention as default. It is advisable to have the IDM write and integrate the function prototypes.
7.1 Function Called in Rules
These functions can be explicitly called up from the rules. They must have one of the permitted function types and are parametrizable with a maximum of 16 arguments. The data type of any argument can be indicated in the function braces. If there is more than one argument, they have to be separated with a comma.
Syntax
{ export | reexport } function { <language> } <data type> <function name>
( { <parameter> { , <parameter> } } ) ;language ::= c | cobol
parameter ::= <data type> { [ <size> ] } { <parameter name> { := <default value> } } { input } { output }
Within this declaration of the function parameters, the parameter values can be defined. There are three possibilities:
-
If a parameter shall serve only as input value in a function, the keyword input is optional after the definition of the data type, because this type is the default. This parameter can only be read in the function by this declaration.
-
If a parameter shall serve only as output value of a function, the keyword output has to be added after the definition of the data type. This means that the parameter has to be set in the application and can afterward be processed in the IDM.
-
Input value as well as output value (input output)
If a parameter shall serve as input value in a function and simultaneously as output value of this function, the keywords input and output have to be added after the definition of the data type. With this declaration, you have the possibility to specify an attribute value in a function as input parameter, to manipulate the value there, and to display the result of this manipulation in the relevant attribute.
Parameter of functions can also be defined by names, e.g. to be able to see for what the individual parameters are used.
Example
function c boolean ReadData(string Filename,
integer Index,
string Value output);
It is also possible to define default values for arguments of type input. These arguments are optional and need not be stated when calling the function.
Note
Arguments with default values must be at the end of the parameter list.
The length of a parameter can also be indicated to the system. This is especially important if a character string shall be passed to an application, e.g. with COBOL. The size has to be given in brackets ( [<size>]).
7.1.1 Alias Name with Optional Code Page Definition
Availability
When defining application functions, the keyword alias followed by a string can be specified after the function parameters.
Syntax
{ export | reexport } function <language> <return_data_type>
<function_identifier> ( { parameter [ , parameter ] } )
alias <alias_string> ; | <code_block>alias_string ::=
"<alias-name>{ ;<code_page> } | <code_page>"
code_page ::=
[CP=]<code_page_identifier>
The alias specification is used to provide a correct function name for dynamic binding (i. e. without the restrictions that apply to function identifiers).
In the alias string a function-specific code page for string processing can be specified as well. This has to begin with CP=
, immediately followed by the code page identifier ( analog to the CP defines from IDMuser.h, but without the prefix CP_
).
If an alias name is defined in addition, the code page specification must follow it, separated by a semicolon (;
).
Examples
function integer Atoi (string S) "myatoi;CP=utf8"; function string CurTime() "CP=utf16b";
7.1.2 Calling Parameters of a Function during Runtime
It is possible to query the parameters of a function also during runtime. For this purpose the attributes .type for the data type and .input for the input value or .output for an output value have to be specified each with the index of the parameter to be queried. If the relevant parameter is of the type string, you can query the size of the parameter with the attribute .size.
The following attributes are valid for a function:
|
Attribute |
Description |
|---|---|
|
.count |
Number of parameters. |
|
.language |
Programming language in which function is to be written. |
|
.type |
Data type of the return value of function. |
|
.input[I] |
Parameter I is input value. |
|
.output[I] |
Parameter I is output value. |
|
.size[I] |
Size of string parameters (only relevant for COBOL). |
|
.type[I] |
Data type of I-th parameter. |
Example
dialog Test
{
}
function void MyTestFunc(integer A input output,
string[20] B output, boolean C input,
pointer D input output);
on dialog start
{
variable integer I;
print MyTestFunc.count;
print MyTestFunc.type;
print MyTestFunc.language;
for I := 1 to MyTestFunc.count do
print MyTestFunc.input[I];
print MyTestFunc.output[I];
print MyTestFunc.size[I];
print MyTestFunc.type[I];
endfor
}
results in the following tracefile output
[XR] rule on dialog start (this=dialog Test)
4
void
"default"
true
true
0
integer
false
true
20
string
true
false
0
boolean
true
true
0
pointer
[XD] rule on dialog start
7.2 Callback Function
A callback function is called when an object to which the function is attached receives an event which was specified when defining this callback function. The callback function is called before the event rule processing. The corresponding event rules are only processed if the callback function returns the value true.
Syntax
{ export | reexport } function { <language> } callback <function name> ( )
for <event> [ , <event> ] ;
Callback functions are later linked to an object in the object definition with the attribute .function. The definition of the function specifies which user events trigger calls of this function, e.g. select, activate, deselect or charinput.
The parameters of the function are predefined by the IDM and cannot be changed.
Example
function callback ObjectCall () for close, move, activate;
window TestWindow
{
.function ObjectCall;
.xleft 17;
}
This function is called when the user is closing, moving or activating the window.
See Also
Chapter “Object Callback Functions” in manual “C Interface - Basics”
7.3 Canvas Function
Canvas functions serve for processing of special canvas events and allow the display of graphics within a canvas. The canvas events and how the graphics are displayed in the canvas are window system-dependent.
Syntax
{ export | reexport } function { c } canvasfunc <function name> ( ) ;
These functions can be indicated when defining canvas objects with the attribute .canvasfunc.
The parameters of the function are predefined by the IDM and cannot be changed.
Example
function canvasfunc HandleCanvas ();
window CanvasWindow
{
.xleft 17;
child canvas Dynamic
{
.canvasfunc HandleCanvas;
.width 100;
}
}
See Also
Chapter “Canvas Functions” in manual “C Interface - Basics”
7.4 Data Function
A data function can serve as a Data Model (Model component) to provide the presentation objects with data values. The function is called when data values shall be synchronized, i.e. either to retrieve data values from the Data Model or to assign them.
Syntax
{ export | reexport } function { <language> } datafunc <function name> ( ) ;
These functions can be specified in the .datamodel attribute of all objects that also support user-defined attributes.
The data function can be implemented in C/C++, as of IDM version A.06.01.d COBOL is also supported as application language with the COBOL interface for Micro Focus Visual COBOL.
The data function may be implemented on the DDM server side.
The parameters of the function are predefined by the IDM and cannot be changed.
See also
Chapter “Data Functions” in manual “C Interface - Basics”
Chapter “Data Functions” in manual “COBOL Interface”
Chapter “Datamodel” in manual “Programming Techniques”
Attributes .dataget[attribute], .datamodel[attribute], .dataoptions[enum], .dataset[attribute]
7.5 Format Function
Format functions serve the formatting of edittext and tablefield contents.
Syntax
{ export | reexport } function formatfunc <function name> ( ) ;
These functions can be specified when defining format resources. When defining edittexts and tablefields they can be specified with the attribute .formatfunc.
The parameters of the function are predefined by the IDM and cannot be changed.
See Also
Chapter “Format Functions” in manual “C Interface - Basics”
7.6 Reloading Function
Reloading functions can be used for dynamic reloading of tablefield contents and are called by the IDM when a user is scrolling in a tablefield in such a way that the area visible after the scroll action contains rows and columns without contents. The reloading function can then load the missing contents into the tablefield and, if necessary, delete contents which are not in the visible area and which are not needed anymore.
Syntax
{ export | reexport } function { <language> } contentfunc <function name> ( ) ;
These functions can be given when defining tablefields with the attribute .contentfunc.
The parameters of the function are predefined by the IDM and cannot be changed.
See Also
Chapter “Reloading Functions” in manual “C Interface - Basics”
7.7 Simulation of Functions
Functions which are not linked to the ISA Dialog Manager can be simulated by rules. When large applications are developed the programmer of the graphic user interface often cannot dispose of all functions he needs for the process or simulation of his surface. He can only test parts of his application. To make the dialogs independent of the missing functions, these functions can be simulated by rules. Functions which are bound to the Dialog Manager are called as usual.
The following functions can be simulated:
On defining the function you usually also indicate the rule. Instead of concluding the definition with a semicolon, you type an opening brace to define the simulation rule. The simulation rule has the same attributes like a named rule.
Example of a function definition without simulation rule
function c boolean CheckOnline();
Example of the same function with simulation rule
function c boolean CheckOnline()
{
return( true ); // always online simulation
}
The simulation rules can be used similarly to the named rules. They have the same parameters as the simulated function.
Example
function c void ConvertDate(boolean CurrentDate input,
string Date input output)
{
// Date will be in format YYYYMMDD and we are to lazy to do
// this here, it will be sufficient for us to do this with
// two different dates
if ( CurrentDate ) then
Date := "11.11.2011"; // simulate always with this
// date as current
else
Date := "1.4.2010"; // no conversion supplied,
// this is sufficient
endif
}
function cobol boolean GetExchangeRate( string From input,
string To input, string ExchangeRate output)
{
case From
in "EUR":
case To
in "EUR": ExchangeRate := "1.000";
in "USD": ExchangeRate := "1.3249";
in "GBP": ExchangeRate := "0.8550";
... // many more currencies
endcase
in "USD":
case To
in "USD": ExchangeRate := "1.000";
in "EUR": ExchangeRate := "0.7548";
...
...
endcase
return (true);
}
record Currency
{
string Which;
string EUR;
string USD;
string CHF;
...
}
function cobol boolean GetCurrencyRates(record Currency
input output)
{
case Currency.Which
in "EUR":
Currency.EUR := "1.000";
Currency.USD := "1.3249";
...
in "USD":
...
}
This simulation should suffice most of the applications. In most cases, a complete substitution of the function is not necessary, since it is enough to control the dialog process usefully.
The ISA Dialog Manager enables the developer to specify directly the functions for events. These are called directly on occurrence of the specified event. For these callback functions you can also indicate simulation functions. In doing so, you can program a useful function simulation for the dialog simulation and the testing procedures. The simulated callback function has the same attributes as an event rule. The accompanying event rules, if there are any, are always executed after the simulated callback function.
function callback PushbuttonSelect() for select, focus
{
if ( thisevent.event[select] ) then
// the simulation code for select
endif
if ( thisevent.event[focus] ) then
// the simulation code for focus
endif
}
default pushbutton
{
.function PushbuttonSelect;
}
on PUSHBUTTON select
{
// is also executed
}
The developer can control the dialog and react to the events without having to implement additional event rules.
7.8 Functions in modularized dialogs
In order to use functions in modularized dialogs the attributes .application on the import object and .masterapplication on the module or dialog object are available. Thus all functions of a module can be assigned from "outside" to a special application. The procedures for both variants - for import and for use - are described in chapter “Programming Techniques” / “Modularization” / “Object Application”.
Support