Copyright: © 1998 Baan Development B.V. All rights reserved.          Wednesday, December 10, 2003 12:15:20
Citation: © 1998 Baan Development B.V. All rights reserved


3GL programming language features: overview

This section describes the features of the Baan 3GL programming language. You can use the 3GL language in both 3GL scripts and 4GL scripts.

•	Vocabulary

•	Constants

•	Variables

•	Expressions and operators

•	Transfer of control

•	Iterations

•	Functions

•	Preprocessor

•	Compiler


Vocabulary

Character set

You can include the following characters in a 3GL language statement:

•	the full alphabet – a-z and A-Z

•	the digits 0-9

•	the characters # $ ^ & * ( ) - _ + = { } [ ] | \ ; : " , . / < >

This document uses uppercase characters to indicate keywords. However, this is not necessary in your programs.

Continuation symbol

If a statement does not fit on one line, you can split it across two or more lines. There is no limit to the number of lines that you can use for one statement. Wherever you can include a space, you can also make a new line.

There are two exceptions: a string constant and a macro definition. If these do not fit on one line, you must place a caret symbol [^] at the beginning of the second and subsequent lines. You can use the caret symbol in other statements also, but this is not necessary.

Comment

The pipe symbol [|] indicates that the text from the symbol to the end of the line must be handled as a comment. The compiler ignores this text. Good comments help the reader of a program source to understand the program better.

Separators

You can use tabs, newlines, and spaces as separators in your program.

Reserved words

The Baan 3GL programming language includes a number of words with defined meanings. These are reserved words that you cannot use other than in the context for which they were designed. Not all these words are described in this document; some are for internal use or for compatibility with older releases.

The following is a list of these reserved words:

AND	END	IN	SELECTBIND
AT	ENDCASE	INPUT	SELECTDO
BASE	ENDFOR	LE	SELECTEMPTY
BASED	ENDIF	LONG	SELECTEOS
BREAK	ENDWHILE	LT	SELECTERROR
BSET	ENDSELECT	MB	STATIC
CALL	ENDDLLUSAGE	MULTIBYTE	STEP
CASE	EQ	NE	STOP
COMMON	EXTERN	NOT	STRING
CONST	FALSE	ON	TABLE
CONTINUE	FIXED	OR	THEN
DEFAULT	FOR	PRINT	TO
DIM	FUNCTION	PROMPT	TRUE
DLLUSAGE	GE	REF	UNTIL
DOMAIN	GLOBAL	REFERENCE	VOID
DOUBLE	GOTO	REPEAT	WHEREBIND
ELSE	GT	RETURN	WHEREUSED
EMPTY	IF	SELECT	WHILE
Related topics

•	3GL programming language: overview


Constants

A constant is a value of a special type that you can assign to a variable. The Baan 3GL programming language supports the following types of constants:

•	Numeric constants

•	String constants

•	Symbolic constants

•	Enumerate / set constants

Related topics

•	3GL programming language: overview


Numeric constants

The Baan 3GL programming language supports long and floating point constants. Both types can be preceded by a '+' or a '-' sign.

Long constants

A long constant consists of the digits 0-9 only. For example:

12345

-530

0xFFF	(hexadecimal)

Floating point constants

Floating point constants consist of the digits 0-9 and a decimal point. You cannot end a constant with a decimal point. An exponential part can be added to a constant by including the letter 'e' followed by a long constant (maximum 307). You can have up to six digits after the decimal point in a constant. For example:

123.56

0.8743

.8743

123.5e-5

-2.34e10

Related topics

•	3GL programming language: overview

•	Constants


String constants

A string constant is a number of displayable single-byte or multibyte characters enclosed by double quotation marks. A string constant with length zero (that is, an empty string) is indicated by two adjacent quotation marks. To include a double quotation mark within a string constant, you must include two adjacent double quotes.

For example:

"This is a string constant"

""

"A quote "" within a string constant"

"This is a very long string constant whic

^h does not fit on one line"

Related topics

•	3GL programming language: overview

•	Constants


Symbolic constants

A symbolic constant is used in your program as a symbolic name, but at runtime it has a fixed value. The defined constants are:

FALSE   	   	   	| The actual value is 0
TRUE	| The actual value is 1
PI	| The actual value is 3.141592653589793

Note that if FALSE and TRUE are used as boolean values (for example, as a result of expressions), they mean zero and not zero respectively.

Related topics

•	3GL programming language: overview

•	Constants


Enumerate and set constants

In the data dictionary you can define database table fields and domains of type enumerate or set.

An enumerate or set domain consists of a number of constants. In the program script (and other places in the data dictionary), a symbolic name is used. The symbolic name is the domain name, followed by a period [.] followed by the name of the constant. Variables of type set can also consist of a combination of set values.

Examples of enumerate constants

DOMAIN color	box_color	| color is an enumerate domain

| with two constants, green and red

box_color = color.green

box_color = color.red

Examples of set constants

DOMAIN feature cf	| feature is a domain of type set with

| the constants bold, reverse, underlined

cf = feature.bold

cf = cf + feature.reverse	| add constant, cf contains

| bold and reverse

cf = cf - feature.bold	| subtract constant

etol( cf )	| returns the combined number of the

| current value, here reverse.

For working with sets, see also the bit functions.

A special constant of type enumerate or set is EMPTY. This indicates an empty set or an enumerate which is not defined. Internally, it has the value 0.

Related topics

•	3GL programming language: overview

•	Constants


Variables

The name of a variable is used to indicate the memory location where data (characters, numbers, and so on) is stored. The name of the variable refers to the associated data.

The value of a variable can change during execution of the program. A variable belongs to a data type and must be declared before its use. This is usually done at the start of the program. In some cases initialization of the declared variables is necessary. The default initial value is always zero for longs and doubles, and an empty string for strings.

The name of a variable can consist of any number of letters, digits, underscores [_], and periods [.]. It must begin with an alphabetic character.

You should keep the following in mind when naming a variable:

•	The name of a variable must not be the same as a reserved word or a previously declared variable.

•	The name of the variable must give an indication of its contents. It is good practice to indicate the purpose of a variable beside its declaration, in the form of comments.

•	A variable must not be used for a purpose other than the one for which it was originally intended.

For further information, see the following sections:

•	Data types

•	Declarations

•	Tables

•	Domains

•	Arrays

•	Fixed and based variables

•	Multibyte strings

•	Bidirectional strings

•	Common variables

•	NULL characters in strings

Related topics

•	3GL programming language: overview


Data types

There are five types of variables: long, double, string, table, and domain variables.

•	Long variables can contain any whole number from -2147483648 to 2147483647. For numbers beyond this range, use double variables instead. Physically, four bytes are reserved for each long variable.

•	Double variables are used for any number containing a decimal point, with a maximum of 15 significant digits (8 bytes).

•	A string variable contains a string constant. The maximum length of a string is 1024 characters.

•	A table variable is used for database tables in your program. The table must be defined in the data dictionary.

•	A domain variable is a variable of a certain type that is defined in the data dictionary. Each of the following types are possible: long, byte, integer, date, enumerate, set, float, double, string, text. Each domain defined in the data dictionary can be used in a declaration of your program. See also Domains.

Related topics

•	3GL programming language: overview

•	Variables


Declarations

You can declare variables either within a function block or at the start of the program. Variables declared in a function block can be used within that function block only. Variables declared at the start of the program can be used in each function described below the declaration.

General syntax

You declare variables with the following syntax (parts between [ ] are optional):

[ special ] <type> <variable> [ option ] [, <variable> [ option ], ...]

The following are the possible values for the various parts of a variable declaration:

special	EXTERN | Not in function blocks STATIC | Only in function block; see Functions
type	LONG DOUBLE STRING TABLE DOMAIN <domain name>   | domain name is a domain  | defined in the data dictionary
variable	The syntax for <variable> is: <name>[(<expression>,...)]
option	BASED | (only for arrays) FIXED MB | (multibyte)
You can declare several variables of the same type in the same statement. To do so, simply include commas between the variable names.

If a variable is to be accessed by its symbolic name from outside the program, it must be declared with the keyword EXTERN, so that the variable name is stored in the symbol table of the object.

You must declare a variable with the keyword EXTERN if that variable is used within other programs, within forms (field names and variables within expressions), or within the function expr.compile(). If the functions get.var() and put.var() are used within the program, the variables in the other program must be declared as EXTERN.

Related topics

•	3GL programming language: overview

•	Variables


Tables

If you use database tables and records in your program, you must declare the tables as follows:

TABLE <table name>	| table name must start with a 't'.

This declaration creates a pointer to the table. Declaration of a table implies declaration of all its fields and its record buffer. It is not necessary to declare these separately.

For a further details see Database handling.

Related topics

•	3GL programming language: overview

•	Variables


Domains

When declaring temporary variables for storing values of database fields, you can use normal variables of type long, double, or string. But this can cause problems if the length or type of the table field has been changed in the data dictionary. It is preferable to use domain declarations for storing the value of a database table field. When you use a domain declaration, the type and length for the declared variable are read from the data dictionary.

Variables of type enumerate or set must always be declared with a domain declaration.

It is also possible to declare an array by using a domain. In that case the number of elements must be set between the brackets, the length of the elements is embedded in the data dictionary.

Examples

The following examples illustrate various domain declarations, and the declaration of the same variables without domains.

DOMAIN declarations

DOMAIN tst_str10	tmp_str,  	| String of length 10

tmp_str_arr(100)	| 100 strings of length 10

DOMAIN tst_long 	tmp_lng1, 	| A long number

tmp_lng2, 	| Another long number

tmp_lng_matr(5,2)	| A matrix 5 x 2

DOMAIN tst_double	tmp_dbl,  	| A floating point

tmp_dbl_arr(100)	| 100 floating points

STRING declarations

#define	LENG	10

STRING	tmp_str(LENG),	| String of length 10

tmp_str_arr(LENG*10,10)	| 10 strings of length 100

LONG declarations

LONG	tmp_lng1,	| A long number

tmp_lng2,	| Another long number

tmp_lng_matr(5,2)	| A matrix 5 x 2

DOUBLE declarations

#define	MAXLEN=1000

DOUBLE	tmp_dbl,  	| A floating point

tmp_dbl_array(MAXLEN/10)	| MAXLEN/10 floating points

Related topics

•	3GL programming language: overview

•	Variables


Arrays

You use arrays to store multiple variables of the same type within one data item. Each variable can be referred to with the construction array_name(index). For example, the first element in a one-dimensional array is array_name(1).

An array can have up to four dimensions. The dimension (and, in case of a string, also the length) of an array must be stated in the declaration.

There are three types of arrays: long, double, and string.

Long arrays

You declare one-dimensional long arrays as follows:

LONG lng_array(5)	| 1-dimensional array for 5 longs

The number in parentheses after the array name specifies the number of longs that can be stored in the array.

You declare two-dimensional long arrays as follows:

LONG lng_array(2,4)

The first number after the array name indicates the number of dimensions in the array. The second number indicates the number of longs that can be stored in each dimension. The following diagram illustrates a two-dimensional array as a matrix:

	lng_array(1,1) = 3     lng_array(2,1) = 100 lng_array(1,2) = 4    lng_array(2,2) = 98 lng_array(1,3) = 56    lng_array(2,3) = 55 lng_array(1,4) = 78    lng_array(2,4) = 77
Double arrays

A double array differs from a long array only in that it is prefixed by the keyword DOUBLE and the array elements must be filled with double values. You declare a double array as follows:

DOUBLE dbl_array(5)

String arrays

The declaration of string arrays differs from that for other array type in that the first dimension contains the length of the strings to be stored in the array. For example:

STRING str_arr(10,5)	| 5 strings of length 10

STRING str_arr(10,5,5,5)	| A 5 x 5 x 5 matrix of strings of length 10

When referencing a string array, the first dimension indicates the start position in the string. The particular string to be accessed is indicated by the other dimensions. It is possible to specify a length for the string to be retrieved by using a semicolon [;] followed by the required length. If you omit the length, the total length of the string is taken.

Example 1 (two-dimensional string array)

STRING str_arr(6,2)	Space reserved for 2 strings of 6 characters each. For example, the first string contains "abcdef" and the second "ABCDEF".
str_arr(1,1) = "abcdef"	This references the first string starting at position 1.
str_arr(2,1;1) = "b"	This references the first string starting at position 2 with length 1.
str_arr(3,2) = "CDEF"	This references the second string beginning at position 3.
Example 2 (filling string variables)

Consider a string declared as:

STRING strg(26)

The statements listed below will have the indicated results:

strg = "good morning"	The words "good morning" are stored from the first position of strg: "good morning"
strg(1) = "good morning"	The same result but filled with spaces:  "good morning              "
strg(9) = "good morning"	The string is stored from position 9 onwards and filled with spaces: "        good morning      "
strg(2;3) = "Hello"	The letters "Hel" (3 characters) are stored from position 2 onwards:  " Hel    good morning      "
Example 3 (accessing string variables)

Suppose the string declared in the previous example has the value "ABCDEFGHIJKLMNOPQRSTUVWXYZ". The results of the statements below will be as indicated:

print strg	"ABCDEFGHIJKLMNOPQRSTUVWXYZ"

print strg(13)	"MNOPQRSTUVWXYZ"

print strg(2;3)  	  	  	"BCD"

In these examples, strg(n) refers to the entire array from position n onwards and strg(n;x) refers to x positions starting at position n.

Example 4 (two-dimensional string array)

Consider a 2-dimensional string array declared as:

STRING twice(6,2)

The statements below will have the indicated results.

twice(1,1) = "ABCDEF"	The first string is filled from position 1 onwards.
twice(1,2) = "123456"	The second string is filled from position 1 onwards.
print twice(3,1)	"CDEF" is printed.
print twice(4,1;2)	Two characters are printed starting at position 4 in string 1 – that is,  "DE" is printed.
String lengths

There are two lengths associated with a string: the maximum and the current length. The maximum length is defined at declaration of the string and the current length can vary, depending on the contents of the string.

If a string is declared as STRING strg(100), the maximum length of strg is 100. If strg is filled as strg = "hello", the current length is 5. If strg is filled as strg(1) = "hello", the current length is also is 100, as the remaining positions are filled with spaces. When you specify a start position, the string is always filled out with spaces.

If a string is declared as FIXED, the current length is always equal to the maximum length, because the string is always filled up with spaces. Also, in the case of multi-dimensional strings, the current length is always equal to the maximum length.

Related topics

•	3GL programming language: overview

•	Variables


Fixed and based variables

Fixed variables

A string variable can be declared as fixed so that its current length always equals the maximum length. For example:

STRING name(10)  FIXED

name = "andrew"	| the string is always filled up with spaces

The keyword FIXED is applicable to one-dimensional strings only. Multi-dimensional string arrays are always fixed and do not need to be declared with the keyword FIXED.

Based variables

The BASED mechanism is applicable to strings or arrays of all possible types. It determines that a variable will be based on another variable. For based variables, no memory space is reserved when they are declared. At runtime they use the same memory space as the variable on which they are based. So by using this mechanism, the same section of memory can be accessed via different names.

You use the following construction to base one variable on another:

BASE var_1 AT var_2

In the case of a string, the based variable is always fixed. You must ensure that the based variable always fits in the variable on which it is based. So it will be safe to declare the basic variable as FIXED.

 Example

STRING a(10)	FIXED

STRING b(5)	BASED

BASE b AT a(3)	| This indicates that the space occupied

| by b is the same as the space for a(3;5)

b(2;3) = "yes"	| a(4;3) now also contains "yes"

a(1;8) = "12345678"	| b now contains "34567"

Variable and fixed length strings

The following points summarize the rules for variable and fixed length strings:

•	Strings with variable length are 1-dimensional strings not declared as based or fixed. All other strings are fixed– that is, database table fields, string arrays, and variables declared as FIXED or BASED.

•	Normally, variable length strings are not filled up with spaces except when a start position is specified in the assignment.

•	Fixed length strings are always filled up with spaces, except when a length is specified. In the latter case, the remaining positions are not overwritten by spaces.

•	If a string (of variable or fixed length) is filled from a certain start position, the part of that string preceding the start position is filled up with spaces if it was not filled before.

Related topics

•	3GL programming language: overview

•	Variables


Multibyte strings

A string variable can be declared as a multibyte string, in order to handle multibyte or bidirectional characters. For example:

STRING mb_str(10,5)	MB	| 5 multibyte strings of 10 characters

In a single-byte string, each byte contains a single character. But in a multibyte string, characters can occupy from one to four bytes.

Example

This multibyte string contains six characters. The fourth character is a TSS (that is, multibyte) character containing 4 bytes. Note that all TSS characters are prefixed with hex 9b.

Notes

•	In program scripts, it is not possible to assign a multibyte character (for example, Chinese) to a multibyte string.

•	The string declared as:

str(x)	MB	| x is the number of characters

requires a space of x * mb.factor (where mb.factor has been defined in the user file). A Japanese character for example has a multiplication factor of about 2.

•	The string str(x;1) contains one character, and a size of one or four bytes. If the character has a size of 4 bytes, it is a TSS character.

•	It is not advisable to assign a multibyte string to a normal string, as this can cause problems regarding storage space and special manipulations like indexing.

•	You cannot use multibyte strings in combination with the BASED mechanism.

Related topics

•	3GL programming language: overview

•	Variables


Bidirectional strings

Bidirectional functionality is necessary to support languages that read and write from right to left– for example, Arabic and Hebrew. Bidirectional input is supported only on fields of type multibyte string. A string is bidirectional when it contains at least one bidirectional character. You can check whether a string includes bidirectional characters by calling  mb.hasbidi(). All strings, including bidirectional, are stored in logic order – that is, the first typed character is the leftmost one in the string. This means that all regular string handling functions like pos(), and constructors like the semicolon [;], work correctly.

Special attention must be paid when concatenating or splitting strings. When bidirectional and non-bidirectional strings are concatenated, one part must be reversed.

Related topics

•	3GL programming language: overview

•	Variables


Common variables

Unlike other variables, which can be used only within the program in which they are declared, common variables can be used in more than one program. Only string variables can be declared as COMMON.

Common variables are automatically based on a common memory part that can be used by several programs. For this reason they must be declared as BASED. The fact that they are common must be indicated with the reserved word COMMON.

Declaration of common variables must be located outside every function. So they must be declared as global variables.

Example

In program 1 and program 2, the same memory space is used for variables com_1 and com_2.

Within program 1:

STRING	com_1(10) BASED, com_2(15) BASED

COMMON	com_1, com_2

<functions which use com_1 and com_2>

Within program 2:

STRING	com_1(10) BASED, com_2(15) BASED

COMMON	com_1, com_2

<functions which use com_1 and com_2>

As an alternative to using common variables, you can use import(), export(), get.var() and put.var() to transport the values of variables between processes.

Related topics

•	3GL programming language: overview

•	Variables


NULL characters in strings

Technically, a string is an array of characters. The internal representation of a string has a NULL character [\0] at the end. The NULL character represents the character with the value zero.

Null characters can occur within strings after use of the following functions:

seq.read()

copy.mem()

store.byte()

store.short()

store.long()

store.double()

store.float()

When a normal string is copied into another string, it is always copied up to the first NULL character. If the target string is a fixed string, then it is filled up with spaces from the NULL character to the end of the string. The copy action can result from a normal assignment, from passing a string as a call by value parameter to a function, or from the use of the import() and export() functions.

There is one exception to this rule. When the left or right side in an assignment is a record buffer (rcd.<table name>), all bytes in the buffer will be copied. For example:

table	tttadv999

strbuf = rcd.ttadv999	| NULL characters are copied

rcd.ttadv999 = strbuf	| NULL characters are copied

strbuf2 = strbuf	| NULL characters are NOT copied

In all other cases, if NULL characters are meaningful, use copy.mem(). This copies NULL characters as well as ordinary characters.

Related topics

•	3GL programming language: overview

•	Variables


Expressions and operators

An expression is a combination of variables, constants, and operators, built up in accordance with certain rules. There are two main kinds of operators: unary and binary. All operators, except the negation operators, are binary. Expressions with unary operators have the general form:

operator operand

Expressions with binary operators have the following form, where each operand can be another expression, variable, or constant:

operand_1 operator operand_2

The available operators can be divided into four categories: arithmetic, relational, logical, and control operators.

Class	Operator	Description
Arithmetic	- * / + - \ &	negation multiply/divide/add/subtract remainder after division string concatenation
Relational	= r EQ <>or NE > or GT < or LT >= or GE <= or LE	is equal to is not equal to is greater than is less than is equal to or greater than is equal to or less than
Logical	AND, OR, NOT	logical ‘and’, ‘or’ and negation
Control	? :	question mark expression
The question mark expression is a special type of expression. The syntax is:

<condition> ? <expr_1> : <expr_2>

If the condition is TRUE, expr_1 is executed. If the condition is FALSE, expr_2 is executed. For example:

lng_1 = (a >= b) ? a : b

| if condition a >= b is TRUE lng_1 gets the value of a,

| else lng_1 gets the value of b.

For further information on the different operator types, see the following sections:

•	Arithmetic operators

•	Relational operators

•	Logical operators

•	Operator Precedences

•	Assignment operator

Related topics

•	3GL programming language: overview


Arithmetic operators

Arithmetic operators perform arithmetic operations on the operands. All arithmetic operators, except string concatenation, must have operands of numerical type. If one of the two operands is a double, the other is also converted to double, and the result is also of double type. For example:

45/30	is equal to 1

| 45 and 30 are both LONG so the result is LONG

45/30.0 	is equal to 1.5

| 30.0 is a DOUBLE so the result is a DOUBLE

The concatenation operator concatenates expressions, variables, or constants of string type.

Examples

LONG	lng_1, lng_2

DOUBLE	doub

STRING strg_1(16), strg_2(50), strg_3(10), strg_4(20)

expression	result
lng_2 = 8\3	The variable lng_2 contains 2, which is the remainder after dividing 8 by 3..
lng_1 = lng_2 + 3	The variable lng_1 now contains 5.
doub = lng_1 * 2.0	The variable lng_1 is multiplied by 2.0; the result (10.0) is stored in doub.
doub = 45 / 30	The variable doub now equals 1.0. Note that 45 and 30 are both longs, so the result of the expression is 1. Converted to double for storing in the result, this becomes 1.0.
doub = 45 / 30.0	The variable doub now contains 1.5.
strg_1 = "hel" & "lo"	The variable strg_1 now contains the value "hello".
strg_2 = strg_3 & strg_4	The contents of strg_3 and strg_4 are concatenated and placed in strg_2.
Related topics

•	3GL programming language: overview

•	Expressions and operators


Relational operators

Relational operators compare two operands. If the condition (equal, greater than, less than, and so on) is satisfied, the result becomes TRUE. If not, it becomes FALSE.

Relational operators can be performed on values of every available type, but the operands of one expression must be of the same type. One exception to that rule is that longs can be compared to doubles.

In the case of strings, the ASCII values of the strings are compared on the basis of the following rules:

•	The comparison is made on the basis of the ASCII value of the strings, starting at the leftmost character of each string.

•	If two characters are not equal, the string with the lower character value is considered to be smaller and the comparison is terminated.

•	If both strings contain the same number of characters and the characters agree in all cases, the strings are equal. If one string is shorter than the other, and the corresponding characters are equal, the shorter string is considered to be smaller than the other.

Related topics

•	3GL programming language: overview

•	Expressions and operators


Logical operators

Logical operators perform logical operations on their operands. The operator NOT is unary, so it has only one operand. The operands of logical operators can be logical expressions, relational expressions, variables, or constants.

The following table illustrates the results of logical expressions:

A	B	NOT A	A AND B	A OR B
FALSE	FALSE	TRUE	FALSE	FALSE
FALSE	TRUE	TRUE	FALSE	TRUE
TRUE	FALSE	FALSE	FALSE	TRUE
TRUE	TRUE	FALSE	TRUE	TRUE
Variables or expressions of type LONG can be used as boolean. If a long expression results in the value zero, it is evaluated as FALSE. If the result is not equal to zero, it is evaluated as TRUE

Related topics

•	3GL programming language: overview

•	Expressions and operators


Operator precedence

An expression can include a number of operators, variables, and constants. The overall result is calculated in accordance with the rules of precedence described here. For example, because multiplication has precedence over addition, the result of the expression (3 + 4 * 5) is 23 and not 35.

The following table lists all operators in order of decreasing precedence. Operators with high precedence are evaluated before operators with lower precedence. Operators on the same line in the table have the same precedence. If they occur in one expression, they are evaluated from left to right.

Operator	Associativity
- (negation)	right to left
* / \	left to right
&	left to right
+ - (minus)	left to right
= > < <> <= >=	none
NOT	right to left
AND	left to right
OR	left to right
?:	right to left
You can use parentheses to force a specific precedence. For example:

The result of the expression 3+4*5	is 23

The result of the expression (3+4)*5	is 35

The result of the expression 10/2*5	is 25

The result of the expression 10/(2*5)	is 1

In case of doubt, always use parentheses. This makes the program easier to read.

Notes

•	The operators NOT and - (negation) are unary, the others are binary.

•	The relational operators are non-associative. This means that A <= B <= C is not available. This should be A <= B AND B <= C.

Related topics

•	3GL programming language: overview

•	Expressions and operators


Assignment Operator

You use the assignment operator [=] to store variables, constants, and the results of expressions in a variable.

Examples (general)

LONG	I, J, K(100), L(100)

STRING	S(50), A, B(10)

DOUBLE	AMOUNT

J	= 4

AMOUNT	= 123.45 * J

L(20)	= 1001

S	= "This is an example"

I	= J	| The contents of J are stored in variable I

L(2)	= L(20)	| Now L(2) is equal to L(20)

A	= S(3;1)  	  	| The character 'i' is placed in A

B(1;2)	= S(6;2)   	| The word 'is' is placed in the first two

| positions of B

K	= L	| The entire content of array L is copied to K

Except in the case of doubles and longs, both operators must be of the same type. For doubles and longs, the following rules apply:

Left operator	Right operator and conversion
long	Can be integer or double. The result is converted to integer. In case of double, the digits after the decimal point are truncated. After truncation the value must be between -2147483648 and 2147483647.
double	Result converted to double.
Examples (longs and doubles)

LONG      A

DOUBLE    C

A = 3.14	| A is set to 3

C = A	| C now contains 3.0

C = 45 / 30	| C now equals 1.0, because this division

| results a long

Related topics

•	3GL programming language: overview

•	Expressions and operators


Transfer of control

The Baan 3GL programming language supports several statements that change the flow of control in a program. These enable control to be transferred either conditionally or unconditionally to a specified point in the program.

You use the GOTO statement to transfer control unconditionally to a specified point. You use the IF...THEN...ELSE statement or the ON CASE statement for conditional transfer. These latter statements evaluate a specified condition and transfer control if the condition is TRUE.

Related topics

•	3GL programming language: overview


The GOTO statement

The GOTO statement transfers control unconditionally to a specified point in the program. You use a label to indicate a position to which the statement can transfer control. The label name can consist of letters, digits, underscores [_], and periods [.]. It must begin with an alphabetic character.

Examples of labels:

LABEL_1:

START_OF_PROCESS_A:

Examples of GOTO statements:

GOTO LABEL_1

GOTO START_OF_PROCESS_A

Both the GOTO statement and the label to which it refers must be within the same function. You cannot transfer control to a label in another function.

Related topics

•	3GL programming language: overview

•	Transfer of control


The IF-THEN-ELSE statement
The IF ...  THEN ...  ELSE statement

The IF statement enables conditional transfer of control. The statement tests a condition, and executes the succeeding statements only if the condition is true. The condition can consist of an expression, or it can be a long variable or a function that returns a long. When the condition is a long variable or a function that returns a long, the value zero is evaluated as FALSE and all other values are evaluated as TRUE.

IF...THEN

This tests a condition. If the condition evaluates to TRUE, the statements following the IF...THEN statement are executed. For example:

IF condition THEN

statement(s)

ENDIF

IF...THEN...ELSE

This tests a condition. If the condition evaluates to TRUE, the statements following the IF...THEN statement are executed. If the condition evaluates to FALSE, the statements following the ELSE statement are executed. For example:

IF condition THEN

statement(s)_1

ELSE

statement(s)_2

ENDIF

Examples

IF a >	b THEN

b = b + 1

ENDIF

IF present AND found THEN

count = count + 1

do_something()

ENDIF

IF isspace(str1) THEN

message("String is empty")

ENDIF

IF a > b THEN

max_val = a

ELSE

max_val = b

ENDIF

Related topics

•	3GL programming language: overview

•	Transfer of control


The ON-CASE statement
The ON CASE statement

This statement has the following syntax:

ON CASE expression

CASE expr_1:

statements_1

break

CASE expr_2:

statements_2

break

CASE expr_3:

statements_3

break

DEFAULT:	| optional

statements

ENDCASE

The ON CASE statement is a multiple-way decision table. It evaluates an expression and compares the result with the expressions of each specified CASE. When a match is found, control transfers to that branch and the code for that particular CASE is executed. If no match is found, the DEFAULT code is executed. If there is no DEFAULT label, the program continues with the first statement after ENDCASE. CASES and the DEFAULT label can occur in any order.

The CASE statements serve as labels. This means that after execution of the statements related to a particular CASE, the remaining CASES continue to be evaluated. However, if two CASE expressions give the same result, only the first is executed.

You can use the BREAK command to skip evaluation of other CASES after the code for the matching CASE has been executed. You include this command at the end of the code for each CASE. When the command is executed, execution of the ON CASE statement ends. In the case of nested CASES, the BREAK command cancels execution of the CASE statements at the same level only.

The ON CASE expression must be either a long expression or a string expression.

Related topics

•	3GL programming language: overview

•	Transfer of control


Long expressions (ON CASE)

The expression after ON CASE is evaluated and compared with the various CASE expressions that follow. All expressions in the case labels must be of type LONG or STRING. When string expressions are used, the ASCII value of the string is compared with the ON CASE expression. For example:

ON CASE weekday

CASE 1:

day = "Sunday"

BREAK

CASE 2:

day = "Monday"

BREAK

CASE 3:

day = "Tuesday"

BREAK

DEFAULT:

day = "other day"

ENDCASE

It is also possible to execute a statement for multiple labels. For example:

ON CASE weekday

CASE 1:

CASE 2:

CASE 3:

CASE 4:

beginweek()

BREAK

CASE 5:

CASE 6:

CASE 7:

endweek()

BREAK

ENDCASE

Related topics

•	3GL programming language: overview

•	Transfer of control


String expressions (ON CASE)

The expression after ON CASE is evaluated and compared with the various CASE expressions that follow. Normally, when the ON CASE expression is a string expression, the CASE expressions are also strings. However, if the ON CASE expression evaluates to a non-printable character – for example, ESC (=27), this cannot be tested against a string constant. In this situation, the CASE expressions can be integer constants that represent ASCII values. The ASCII value of the ON CASE expression is then compared with the numeric values of the CASE labels. For example:

ON CASE choice_char

CASE "A":

CASE "E":

abort()

CASE "N":

next_screen()

BREAK

CASE "P":

last_screen()

BREAK

CASE 27:

escape()

BREAK

DEFAULT:

message("unknown choice")

ENDCASE

Related topics

•	3GL programming language: overview

•	Transfer of control


Iterations

Iterative statements repeat the associated statements until a specified condition becomes FALSE.

WHILE statement

This statement has the following form:

WHILE expression

statement(s)

ENDWHILE

The expression is evaluated. If the result is TRUE (that is, non-zero), the statements between WHILE and ENDWHILE are executed. The process is then repeated until the expression is FALSE (that is, zero). When the expression evaluates to FALSE, control passes to the statement after ENDWHILE. For example:

LONG counter

counter = 1

WHILE counter <= 10000

counter = counter + 1

ENDWHILE

FOR statement

This statement has the following form:

FOR num_var = num_expr_1 TO num_expr_2 [STEP num_expr_3]

statement(s)

ENDFOR

The num_var variable is referred to as the loop variable. Num_expr_1 specifies the initialization of the loop variable. Num_expr_2 specifies the end value of the loop variable. Num_expr_3 specifies the step size for each iteration. The latter variable is optional; the default step size is 1. It is possible to use a negative step size.

After execution of the statements within the loop, num_expr_3 is added to the loop variable. The num_expr_2 expression is then evaluated. If the loop variable does not exceed num_expr_2, the statements are executed again. This process continues until the loop variable exceeds its end value. For example:

LONG total, i

FOR i = 1 TO 100 STEP 2

total = total + i

ENDFOR

REPEAT ... UNTIL statement

The REPEAT ... UNTIL differs from the WHILE statement, in that the REPEAT ... UNTIL statement tests the condition after execution of the loop statements instead of before execution of the loop statements. Consequently the statement(s) within a REPEAT ... UNTIL statements are executed at least once.

The syntax of this statement is:

REPEAT

statement(s)

UNTIL expression

The loop iterates as long as the result of the expression is non-zero.

Using BREAK and CONTINUE (iterations)

You can use the BREAK command in an iterative statement in order to cancel the loop, regardless of the value of the loop condition. After a BREAK, control passes to the statement following the terminated loop. It is important to note that with nested loops the BREAK statement cancels the innermost loop only.

The CONTINUE command also interrupts an iteration loop. But, in this case, the expression is immediately evaluated again for the next iteration. For example:

LONG numbers(100), i

FOR i = 1 TO 100

IF numbers(i) <= 0 THEN

CONTINUE	| Next iteration

ENDIF

IF NOT process(numbers(i)) THEN

BREAK	| Exit FOR statement

ENDIF

ENDFOR

The BREAK and CONTINUE commands can be very useful in a program, but you should be take great care when using them.

Related topics

•	3GL programming language: overview

•	Transfer of control


Functions

In a program, a function performs a particular task that can be executed many times, with different values. The syntax of a function is as follows (parts between brackets [] are optional):

FUNCTION [ function_type ] function_name( [ arglist ] )

{

declaration of local variables

statement(s)

RETURN[( return_value )]

}

where arglist consists of one or more argument declarations with the following syntax:

 [REFERENCE / CONST] argument_type argument_name

When including more than one argument declaration, use commas [,] to separate the declarations. Note that the key word REFERENCE can be replaced by REF.

For further information about functions, see the following topics:

•	Function type and return value

•	Local variables

•	Static variables

•	Global variables

•	External variables

•	Function arguments

•	Function prototypes

•	Function calls

Related topics

•	3GL programming language: overview


Function type and return value

The type declaration in a function declaration indicates the type of the function. This must be the same as the type of the return value. Functions can be of the following types:

•	long

•	double

•	string

•	domain

•	void (this means that no value is returned)

If you do not specify a type, the function is of type void by default. In functions of type void, the return statement cannot have any argument. For example:

FUNCTION add_one()	| this function is of type void

{

count = count + 1	| count is a global variable

RETURN

}

Related topics

•	3GL programming language: overview

•	Functions


Local variables

Variables declared within a function block are local variables. They are accessible only within the function in which they are declared.

Declaration, initialization, and scope

Point of declaration	In the function between the brackets { }.
Syntax of declaration	<type> name
Initialization	The value of local variables is undefined with each function call. Local variables must always be initialized in the function.
Scope (validity and time)	Only within and during function execution.
 Example

function void test()

{

long I	| Local variable

for i =1 to 100	| Always to be initialized by user

....

endfor

return

}

Related topics

•	3GL programming language: overview

•	Functions


Static variables

You can declare local variables as static variables. The value of a static variable is saved at the end of the function and is used again the next time the function is called. A static variable is automatically initialized at the start of the program. Normal local variables are undefined at each function call, and are not initialized at first call.

Declaration, initialization, and scope

Point of declaration	In the function between the brackets { }.
Syntax of declaration	static <type> name
Initialization	At program start: numeric set to 0 strings ""
Scope (validity and time)	Can be used only within the function but they maintain their values throughout program execution.
Example 1

function test()

{

static long	started

if (not started) then

started = true

| Actions to be performed only first time around.

endif

....

return

}

Example 2

function void spool( long id, ref string line() )

{

static long   save_id

static long   lfn

if ( save_id <> id ) then      | Optimalization

lfn = read_new_lfn( id )

save_id = id

endif

seq.puts( line, lfn )

}

Related topics

•	3GL programming language: overview

•	Functions


Global variables

Variables declared outside any function block are global variables. You can use them in all functions that occur after the variable declaration.

Declaration, initialization, and scope

Point of declaration	Outside the functions.
Syntax of declaration	<type> name
Initialization	At program start: numeric set to 0 strings ""
Scope (validity and time)	Valid anywhere in the source, throughout the execution. If any arguments or variables within a function are declared with the same name as a global variable, the global variable cannot then be accessed within that function.
Example 1

function test()

{

return

}

long glob_var

function long dupl()

{

return( glob_var * 2 )

}

In this example, glob_var is a global variable. It is not accessible in the test() function as it was declared after that function block. On the other hand, glob_var is accessible in function dupl().

Example 2

long i

function void test()

{

long i

i = 10	| This is the local variable

| Nothing happens to the global variable 'i'

}

Related topics

•	3GL programming language: overview

•	Functions


External variables

An external variable is declared outside the function blocks. You can use them in all functions that occur after the variable declaration, and also in other programs (for example, forms, reports, and runtime expressions). It is possible to declare external variables within a function block but this is not recommended.

If a local variable has the same name as an external variable, the local variable is used within the function. The external variable is not affected.

Declaration, initialization, and scope

Point of declaration	Outside the functions. (Or within a function, but this is not recommended.)
Syntax of declaration	extern <type> name
Initialization	At program start: numeric set to 0 strings ""
Scope (validity and time)	Valid anywhere in the source, throughout the execution. Also valid outside the program – for example, on forms/reports, in runtime expressions, and by way of import() and export().
Example

extern long   i

function void test()

{

i = 10        | This is the external variable

}

Related topics

•	3GL programming language: overview

•	Functions


Function arguments

The arguments of a function are the variables declared in the function header. Arguments can be accessed only within the function.

Declaration, initialization, and scope

Point of declaration	In the function between the brackets { }.
Syntax of declaration	[ref|reference] <type> name Note that  array subscripts must be empty for reference arguments.
Initialization	At function call. For value arguments (see below), the values of the function call are copied. For reference arguments, the same variable (or the same memory area) is used as occupied by the variable submitted to the function call.
Scope (validity and time)	Only during function execution.
Value arguments

A value argument gets its value at the time of the function call and has its own memory space. For example:

FUNCTION long dupl(long val)	| val is a value argument

{

RETURN( val * 2 )

}

FUNCTION MAIN()

{

message("%d", dupl(10))

| the argument val gets value 10

}

Reference arguments

Reference arguments must be declared in the function header with the keyword REFERENCE or REF.

A reference argument has the same memory space as the variable used in the function call. Consequently, all changes made to a reference argument within the function block are also accessible after the function call in the variable used in the function call. If a reference argument has array subscripts, these must be empty in the declaration as the contents and size of the call variable is used. If strings or large arrays are used, it is preferable to use reference arguments instead of  returning them with the return statement. This avoids copy actions.

Example 1

Note that in this example, the reference argument is empty in the declaration.

FUNCTION LONG read_line( REF STRING buffer() )

{

IF ( . . . . ) THEN

buffer = . . . . . . . . . . .

RETURN( 1 )

ELSE

buffer = ""

RETURN( 0 )

ENDIF

}

FUNCTION MAIN()

{

STRING line(100)

IF read_line(line) THEN

. . . .

ELSE

message("No present line")

ENDIF

. . . .

}

Example 2

This example uses a multi-dimensional array:

FUNCTION VOID fill_array ( REF LONG array(,) )

{

array(1,1) = 10

array(1,2) = 20

....

}

FUNCTION MAIN()

{

STRING      a(5,10)

fill_array(a)

}

Constant arguments

Constant arguments must be declared with the keyword CONST in the function header. These are similar to reference arguments in that the same memory space is used for the constant argument and the variable used in the function call. However, with constant arguments, it is possible to use a string constant within the function call. Consequently, the value of the argument after the function call is not returned in the calling function.

You cannot change a constant argument within the function. Nor can you use a constant argument as reference in another function call. Only strings with one dimension can be used as constant arguments. The array subscript of the constant argument must be empty in the declaration because the size of the constant is used. For example:

FUNCTION print_mess( CONST STRING mesg() )

{

IF NOT isspace(mesg) THEN

message("Message: " & mesg)

ENDIF

}

FUNCTION MAIN()

{

.....

print_mess("This is a message")

.....

}

Varying number of arguments

It is possible to pass an (as yet) unspecified number of arguments to a function definition by replacing the actual arguments with '...'. The function call must contain the actual arguments required to execute the function. This enables you to use different arguments (from 0 to approximately 250) each time you call the function. This feature is useful, for example, if you wish to change some (not all) of the flags of a process, and you do not know beforehand precisely which flags you are going to change. See the arg() functions for information on using this feature.

Related topics

•	3GL programming language: overview

•	Functions


Function prototypes

A function consists of three parts:

•	Function prototype

•	Function definition (function block)

•	Function call

The function prototype must be exactly the same as the function header in the function definition. The prototype of a function is not always necessary. For example, it is not necessary in the following situations:

•	if the function is of type void and has no arguments

•	if the definition of the function occurs before any call of that function

In all other situations the prototype of the function must occur before the function call. For example:

prototype

FUNCTION LONG compnr_check( LONG new_compnr )

function call

IF compnr_check( 999 ) THEN

. . . .

ELSE

mess("pcgen00016", 999)

| Comp. number %d not present

ENDIF

definition

FUNCTION LONG compnr_check( LONG new_compnr )

{

TABLE tpctst999

SELECT pctst999.*

FROM pctst999

WHERE pctst999.compnr = :new_compnr

ORDER BY pctst999.compnr

SELECTDO

compnr = pctst999.compnr

SELECTEMPTY

RETURN(FALSE)

ENDSELECT

RETURN(TRUE)

}

From compiler version bic6.1 onwards, it is not necessary to use function prototypes within the same source as the function definition.

Related topics

•	3GL programming language: overview

•	Functions


Function calls

The call of a function must have the same number of arguments as declared in the function header. Value arguments can be called using a constant or a variable; reference arguments can only be called using a variable. If the called function is not of type void, the function call must be assigned to a variable or used as value argument in another function call.

It is possible to use recursive function calls. This means that in a function block a call to the same function is used. However, this is currently implemented only for functions without local variables and arguments. In other situations, the following runtime message is generated: "Recursion not yet implemented".

Related topics

•	3GL programming language: overview

•	Functions


Preprocessor

The bic6.2 compiler for 3GL program scripts has a built in preprocessor with the following functions:

•	include files

•	macro definition

•	object identifications

•	pragma codes

•	conditional compiling

All preprocessor directives starts with a '#'. A preprocessor directive must be the first word on a source line, possibly with leading spaces or tabs.

Related topics

•	3GL programming language: overview


Include files
Include files (preprocessor)

To include files, use one of the following statements:

#include "filename"

#include <filename>

Files included between '<' and '>' are searched for in the directory '$BSE/include<rel.number>'. This directory is reserved for system headers and cannot be used for applications. Normally a file specified between quotes is searched for using the standard file redirection method.

Note that the preprocessor works only during compilation of a 3GL source, as the standard generator std_gen6.2 does not have a preprocessor pass. So it is not possible to use 4GL events in an included file.

Example

Suppose the following entry occurs in $BSE/lib/fd.6.2<package_comb>:

ippmmm:/usr/bse/standard6.2

and there is an include statement as follows:

#include "ippmmmheader"

The file "/usr/bse/standard6.21/ippmmm/immmheader0" is included. If a '/' occurs in the filename, the file is searched using the specified path name. When a file is included twice, the second include is ignored.

Related topics

•	3GL programming language: overview

•	Preprocessor


Macro definition
Macro definition (preprocessor)

Use the following statement to define a macro:

#define macroname[(arguments)]

Use the folowing statement to undefine a macro:

#undef macroname[(arguments)]

Defining macros

The macro names in the source are expanded to the macro definition. If a macro definition does not fit on one line, it is possible to continue the definition on the next line(s) by using the caret symbol '^' at the beginning of each line. It is possible to use arguments in the macro. For example:

#define a(x, y, z)	for i = x to y

^	z()

^	endfor	     	| The definition

a(1, 100, func)  	  	  	  	  	  	    	     	| The invocation

Macro definitions with the same name but with different numbers of arguments are regarded as different. For example:

#define  x	definition without arguments

#define  x()	definition with 0 arguments

#define  x(arg1)	definition with 1 argument

#define  x(arg1,arg2)	definition with 2 arguments

#define  x(...)  	  	  	definition with undefined number of arguments

Note that there is a difference between a macro without arguments and a macro with zero arguments. In the first case, you must use 'x' in the program script to call the macro. In the second case, you must use 'x()' to call the macro.

Undefining macros

The '#undef' statement causes the macro definition to be ignored. The number of arguments in the '#undef' call must match the number of arguments in the definition. For example:

#define MAXLENGTH	1000

#define INCR	1

#define INCR(i)	i=i+INCR

.....

#undef  MAXLENGTH

#define INCR	2	| Redefines INCR

.....

#undef	INCR(i)

An error occurs if you apply #undef to an unknown macro. To be sure that the macro was defined, use the following construction:

#ifdef INCR	| without arguments

#undef INCR(i)

#endif

See Conditional Compiling for a detailed description of #ifdef and #endif calls.

Variable macro arguments

You can use the ellipsis notation ( , ... ) to define the macro with a varying number of arguments. For example:

#define fillbuf(buf1, format, ...)  buf1 = sprintf$(format,...)

| macro call

string buffer(100)

long l_val

double d_val

fillbuf(buffer, "%d. %s = %d %5.2f", 1, "Value", l_val, d_val)

The macro definition can contain a number of arguments, but the ellipsis notation must be the last argument.

Related topics

•	3GL programming language: overview

•	Preprocessor


Token pasting
Token pasting (preprocessor)

In the macro, you can enter a part of a variable as a macro argument. The symbol '##' is used to distinguish macro arguments and the rest of the macro. This is omitted in the macro call. You can paste more macro arguments together as one identifier. This principle is called token pasting. It is used to reuse parts of the source code, where using functions is impossible or difficult.

Example 1

#define p(x)	message("%d", var##x)

#define q(x,y)	message("%d", x##y)

#define r(x,y,z)	message("%d", x##y##z)

long var1a, var1b

p(1a)	| becomes: message("%d", var1a)

p(1b)	| becomes: message("%d", var1b)

q(var, 1a)	| becomes: message("%d", var1a)

q(var, 1b)	| becomes: message("%d", var1b)

r(var, 1, a)	| becomes: message("%d", var1a)

r(var, 1, b)	| becomes: message("%d", var1b)

Example 2

#define VRC(table,v,r,c)

^	tt##table##.vers = v

^	tt##table##.rele = r

^	tt##table##.cust = c

VRC(adv100, "6.2", "a", "")

VRC(adv200, "6.2", "a", "")

VRC(adv300, "6.2", "a", "")

Related topics

•	3GL programming language: overview

•	Preprocessor


Object identifications
Object identifications (preprocessor)

The compiler always places a default identification in an object, but you can include you own if you wish. You can use the UNIX command what to write all object lines that begin with '@(#)' on standard output.

The default identification has the following content:

#ident "@(#)<source name>, YY/MM/DD, [HH/MM], From ${logname}"

To set you own identification use the following statement:

#ident "@(#)Identification of object"

 For example:

#ident "@(#)<progname>, YY/MM/DD [HH/MM], version, author"

Related topics

•	3GL programming language: overview

•	Preprocessor


Pragma codes
Pragma codes (preprocessor)

Pragma codes represent compiler options. The following pragma codes are available:

#pragma nodebug	Do not show the source while debugging.
#pragma debug	Show the source while debugging.
#pragma nowarnings	Do not give warnings about the source.
#pragma warnings	Give warnings about the source.
#pragma notransactions	The source contains only read actions; there are no transactions. So, it is sufficient to start one database server.
#pragma warning <text>	The programmer generates his own warning. (Warning level 15). See example.
#pragma fatal <text>	The programmer generates his own error.
#pragma sticky	Do not remove the object out of memory when the process ends.
#pragma used <component> <code>	See below.
Example

#pragma warning This is not a fine solution !

| After compilation the following warning appears:

| <Source(line)>: Warning(15): This is not a fine solution !

Where-used list

In some cases the where-used list is not updated automatically. For example, when a session code is entered but not expected:

 	message("ttadv2130m000")

or

bms.send("command", event, "ttaad3100m000", pr.id)

To put this session code into the where-used list, enter the following command line:

#pragma used session	ttadv2130m000

The following example illustrates the pragma codes to update the where-used list:

#pragma used include    <file>

#pragma used table      <table code>

#pragma used field      <field code>

#pragma used domain     <domain code>

#pragma used message    <message code>

#pragma used question   <question code>

#pragma used session    <session code>

#pragma used menu       <menu code>

#pragma used dll        <dll objectname>

#pragma used chart      <chart code>

Usually the where-used list is updated. In the case of functions, the where-used list is updated if the function call contains the string value. For example:

mess("ttadvs0000", 1)	| Where-used list will be updated

str = "ttadvs0000"

mess(str, 1)	| Where-used list will not be updated

#pragma used message ttadvs0000

Location of pragma codes

You can place pragma codes anywhere in the source. For example, if you set the following pragma at the start of the source:

#pragma nowarnings

you can enter the following pragma after a number of lines:

#pragma warnings

Related topics

•	3GL programming language: overview

•	Preprocessor


Conditional compiling
Conditional compiling (preprocessor)

Directives

The preprocessor provides the following directives to enable you to compile parts of the source depending on certain conditions:

#ifdef <macro>	The source after #ifdef up to #else/#elif/#endif is compiled if <macro> is defined. Otherwise this source is ignored.
#ifndef <macro>	The source after #ifndef up to #else/#elif/#endif is compiled if <macro> is not defined. Otherwise this source is ignored.
#if <constant expression>	The source after #if up to #else/#elif/#endif is compiled if <constant expression> is TRUE. Otherwise this source is ignored.
#else	If the condition belonging to #if/#ifdef/#ifndef/#elif is FALSE, the source after #else up to #endif is compiled. If the condition belonging to #if/#ifdef/#ifndef/#elif is TRUE, the source after #else up to #endif is ignored.
#elif <constant expression>	'#elif' is a combination of #else and #if. For example: #if <constant expression> ... #else #if <constant expression> ... #else ... #endif #endif This is equivalent to the following: #if <constant expression> ... #elif <constant expression> ... #else ... #endif
#endif	To finish a part of the source started with #ifdef/#ifndef/#if.
#undef <macro>	To delete a macro definition. The macro is not known on the next #ifdef call.
Notes on using the directives

•	The <constant expression> in #if and #elif is a numeric expression in which you can use only macros of type long and operators such as +, -, *, /, =, <, >, <=, >=, <>, and, or, not, ?:, ().

•	It is possible to use nested #if structures.

•	It is possible to define a macro when starting the compiler. You use the D option to do this. For example:

bic6.2 -D<macro>	| no value means default 1
bic6.2 -D<macro>=<value>
bic6.2 -D<macro>='any token string'

These macros can also be used in the #if conditions. For example:

bic6.2 -DDEBUG -DMYTEST <source>

|source

#if DEBUG and MYTEST

message("Some debug information")

...

#endif

bic6.2 -DCUSTOMER_X -DCUSTOMER_Y <source>

bic6.2 -DSTANDARD <source>

#if STANDARD

....

#elif ( CUSTOMER_X and (not CUSTOMER_Y) )

....

#endif

•	You can use #ifdef  to make a part of the file inactive. For example: Example:

#ifdef OLD

....

....

....

#endif

•	The preprocessor works only during compilation of a 3GL source, as the standard generator std_gen6.2 does not have a preprocessor pass. So it is not possible to use 4GL events in #if, #ifdef or #ifndef.

•	It is not possible to use a #ifdef statement within an embedded SQL query. So, the following construction is not allowed:

select *

#ifdef STANDARD

...

from x

#else

...

from y

#endif

where ...

selectdo

...

endselect

But the following construction is possible:

#ifdef STANDARD

select * from x where ...

selectdo

...

endselect

#else

select * from y where ...

selectdo

...

endselect

#endif

•	The following keywords provide debug information in 3GL sources:

 __FILE__	: contains the name of the current source

__LINE__	: contains the line number of the current source

For example:

message("This is at line %d in the source %s", __LINE__, __FILE__)

Related topics

•	3GL programming language: overview

•	Preprocessor


Compiler

You compile program scripts with the bic6.2 compiler. The compiler is automatically activated after you have edited your program or report script and after the use of std_gen6.2 and repgen6.2 at the option 'Compile' in the data dictionary. You can also use the compiler to compile 3GL programs

The syntax for the compiler is:

bic6.2 [-ilpsV] [-wW[level]] [-o <object>] [-d dll[:dll...]]

             [-D <macro>] [-I <dir>] source

-I	Assembler output is stored in <source>.i. Do not specify an object file.
-l	Object will run in debug mode.
-p	Object will run in profiling mode for time analysis (see function times.on()).
-s	Generate symbol table to stdout; for more information use 'bic_info6.2 -s'.
-V	Print release information.
-w	Suppress all warnings.
-wn	Suppress warnings of level n.
-Wn	Give warnings of level n.
-o <obj>	Specifies the object name; when not specified, only a syntax check is performed.
-d	Specifies the DLL(s), separated by a colon (':'). These are the objects of dynamic-link libraries necessary to compile the source program.
-D<macro>	Specifies a condition <macro>, see also Preprocessor.
-I<dir>	Specifies a directory where included files are located.
The warnings associated with the various level numbers are as follows:

Level	Warning
1	Declared but never used For example, remove the declaration of the non-used variables. Warnings related to an include file can be prevented by entering "#pragma nowarnings" at the beginning of the include file. All warnings caused by the include file will then be ignored.
2	Function never used A function is found but never called. For instance remove the function. This warning related to an include file can be prevented by entering "#pragma nowarnings".
3	Return value of function ignored When a function yields a value, that value must be checked. The reason is that many functions return TRUE or FALSE, depending on whether the action has been completed successfully or not. If the return value is of no importance, a dummy value must be assigned to the function. For example: dummy = ittadv0037.search.label(....)
4	A long divided by a long gives also a long A long divided by a long will result in a long. For example: long a long b a = 1 b = 3 a / b = 0 and not 0.33
5	Statement/Label not reached Occurs if a statement cannot be reached. For example: function test.a() { if a = 0 then ... return() else ... return() endif a = 1 } The statement a = 1 will never be reached, so this warning indicates a programming error or logical error.
6	Comparison of two float types may yield unpredictable results This warning is given when two double types are compared for equivalence. Please use the function double.cmp() to compare double variables, double domains, and double functions. Note that for double functions the warning appears only if the function has been prototyped before its actual use. For example: function double d() function main() { domain tttst.db62   dbldom double              a, b if a = b then ... endif if d() > a then ... endif if a <= dbldom then ... endif } All the above expressions may yield unpredictable results, as no tolerances have been specified.
9	External variable '%s' passed as reference to function '%s' When an external variable is given as a call by reference to a function, the value of this variable within the function is not equal to the local value. Just after the return, the value of the external variable will be changed. For example: extern long a function main() { a = 5 make.ten(a) message("a = %d", a)   | results in a = 10 } function make.ten( ref long x ) { message("a = %d", a)   | results in a = 5 x = 10 .... message("a = %d", a)   | results in a = 5 } When within the function make.ten() another function is called using the external variable a, the variable a still has the value 5.
10	Passing fixed variable to non-fixed call by reference argument (or non-fixed to fixed) When a global variable is declared as fixed, the variable within a function is still regarded as fixed, although the reference declaration is not fixed. For example: string a(20)   fixed function process.variable( ref string b ) { } If the function is invoked using the argument "a", "b" is considered fixed.
12	External variable '%s' added in external symbol table An external variable is declared within a function. For example: function test() { extern long a .... }
13	System library <bic_stdlib> NOT included !
15	Warning given by #pragma <text> This is a warning of your own format, see Pragma Codes.
16	Missing selectdo; automatic break or Missing selectdo; loop until selecteos When a selectdo is missing in the select statement, an automatic break is generated to prevent unnecessary use of cpu time. When a selectdo is missing, while a selecteos section exists, the select statement should be executed. Probably this is a non optimal select statement.
18	Macro '%s' redefined A macro is defined, which was already defined with the same arguments.
19	Function '%s' in DLL '%s' ignored taken from '%s' A duplicate function occurs in a DLL or program script. A function is searched for in the script first and next in the libraries that are linked to the script in the specified order. If a function is found twice, this warning appears.
You can specify the options for automatic compilation in the session Maintain Development Parameters (tadv0110m000).

When an error is found in the program, all warnings after that error are suppressed.

Related topics

•	3GL programming language: overview


4GL programming features: overview

This section describes the 4GL features of the BAAN programming language.

When you create a session, the session generator generates a standard source. This standard source provides default session functionality. If the required functionality of the session is not fully implemented by the standard source, you can program the additional functionality in a 4GL program script.

In previous versions of the software, changes or additions to the default functionality for a session were programmed in a single script that was associated with the session. Both user interface actions and database actions were programmed in this script.

In BaanERP, user interface actions and database actions have been separated. The Data Access Layer (DAL) now handles database interaction. Programmers create a user interface (UI) script to change the default behavior of a session. They create a DAL script to program all the logical integrity rules for a particular table. This section discusses UI scripts.

4GL script types

There are four types of 4GL program scripts:

•	type 1 (with main  table): single-occurrence (details) session

•	type 2 (with main table): multi-occurrence (overview) session, with group fields

•	type 3 (with main table): multi-occurrence (overview) session, without group fields

•	type 4 (without main table): print/processing sessions

Event-driven programming

4GL scripts are event oriented. They consist of one or more event sections in which you program actions to be performed at particular states of execution of the standard program – for example, when a session is started, before a form is activated, before input to a field, after input to a field, and so on. It is not necessary to program all sections, only those for which the standard program does not provide the required functionality.

The statements programmed in a section can be a combination of 3GL/4GL functions and 3GL statements. For information about the 3GL programming language, see 3GL programming language features.

Related topics

•	4GL event sections

•	Flow of standard program

•	Automatic import of variables


4GL event sections

A 4GL script can contain one or more of the following types of sections:

•	Program sections

•	Form sections

•	Group sections

•	Choice sections

•	Field sections

•	Zoom sections

•	Main table sections

With the exception of program sections, each section consists of a main section and one or more subsections. A main section indicates the object for which the programmed actions must be executed. A subsection specifies when the actions must be executed. Program sections consist of a main section only.

If you do not include a main section immediately before a subsection, the subsection is assigned to the previous main section in the script. For example:

form.1:	| main section

init.form:	| subsection executed for form 1

...

...

before.form:	| subsection executed for form 1

...

...

after.form:	| subsection executed for form 1

...

The following rules apply to the ordering of sections within a script:

•	The declaration section must be the first section in the script.

•	The functions section must be the last section in the script.

•	Other sections can occur in any order, but the preferred order is: program sections, form sections, group sections, choice sections, field sections, zoom sections, main table sections.

•	Do not mix sections of different types. For example, do not define a choice section, followed by a field section, and then a choice section again. Exceptions are the declaration and functions sections, which must be the first and last sections respectively in the script.

Variables declared in the declaration section are global variables that you can use in other sections. Variables declared within any other section are local variables that you can use in that section only.

Related help topics

•	4GL programming features (overview)

•	Flow of standard program

•	Automatic import of variables


4GL program sections

You use program sections to define functions, and to declare tables and global variables, that you want to use in the other sections in the script. You also use program sections to program actions that you want to be executed when the session starts or ends.

The following program sections are available. They are all main sections. There are no subsections associated with program sections.

Main sections

declaration:

Use this section to declare tables and global variables that you want to use in other sections in the script. See Variable declarations and Table declarations for details of the declaration syntax. You also use this section to define function prototypes.

before.program:

Use this section to program actions that must be executed when the session starts. For example, you can use this section to initialize or import variables or to read a special record. Note that the default values or imported values overwrite the fields of the main table.

on.error:

Use this section to program actions that must be executed at the end of the session, before the after.program section. If the session is canceled, the actions in this section are not executed. If an error is detected, you can check the predefined variable e for the error code.

after.program:

Use this section to program actions that must be executed at the end of the session, after the on.error section. If the session is canceled (with the command ABORT.PROGRAM), the actions in this section are not executed.

after.update.db.commit:

Use this section to program actions that must be executed immediately after a commit.transaction() call, if the database is updated.

before.display.object:

Use this section to program actions that must be executed each time the entire record is displayed.

before.new.object:

Use this section to program actions that must be executed once before the input of the first field of the new created record. It is used for setting the default values of the record fields.

functions:

Use this section to define the functions used in the other sections. This must be the last section in the script. The function syntax is the same as for 3GL functions.

Example

declaration:

table	tpctst999

long	var01, ret

before.program:

if read_parameter() then

mess("pctsts0001", 1) | Parameter not present

stop()

endif

on.error:

mess("........", 1)

functions:

function long read_parameter()

{

select pctst999.*

from pctst999

order by pctst999._index1

as set with 1 rows

selectdo

return(0)

selectempty

return(1)

endselect

}

Related help topics

•	4GL programming features (overview)

•	4GL event sections

•	Flow of standard program

•	Automatic import of variables


4GL form sections

You use form sections to program actions that you want to be executed when forms are activated or ended. Form sections consist of a main section and a subsection. The main section specifies the particular form(s) for which the actions are to be executed. The subsections specify when the actions must be executed – for example, when the form is activated or when the form is ended.

Main sections

form.<form number>:

The subsections associated with this section are executed for the specified form. The <form number> is the sequence number of the form, as defined in the Maintain Sessions by Package VRC session (ttadv2100m000).

form.all:

The subsections associated with this section are executed for all forms of the session.

form.other:

A subsection associated with this section is executed for all forms for which the particular subsection has not been programmed in a form.<form number> section.

Subsections

init.form:

The actions programmed in this subsection are executed the first time the specified form becomes current, immediately before the subsection before.form. You use this subsection to program the first action to be performed by the system – a first.set or first.view, for example.

before.form:

The actions programmed in this subsection are executed each time the specified form becomes current.

after.form:

The actions programmed in this subsection are executed each time the specified form is ended.

 Example:

form.1:

init.form:

execute(first.set)

form.other:

init.form:

display("disp3")

form.all:

before.form:

display("disp")

Note:

Only the form.all section is relevant to dynamic forms. For dynamic forms, use the group sections instead.

Related help topics

•	4GL programming features (overview)

•	4GL event sections

•	Flow of standard program

•	Automatic import of variables


4GL group sections

With dynamic forms, the mapping of groups to forms is not fixed. Consequently, the only form section that is relevant to dynamic forms is the form.all section. When dealing with dynamic forms, you use group sections instead of form sections

You use group sections to program actions that you want to be executed when particular groups are activated or ended. Group sections consist of a main section and a subsection. The main section specifies the particular group(s) for which the actions are to be executed. The subsections specify when the actions must be executed – for example, when the group is activated or when the group is ended.

Note that a group becomes active when the form on which it occurs becomes current.

Main section

group.<group number>:

This section defines the group for which the actions programmed in the group subsections are executed. The group number is automatically generated when the group is created.

Subsections

init.group:

The actions programmed in this subsection are executed only the first time the group becomes active, immediately before the before.group subsection. You use this subsection to program the first action to be performed by the system when the group becomes active. When the group is split across two or more forms (because not all the group fits on one form or because it is a repeating group), this subsection is executed the first time that the first form on which the group occurs becomes current.

Note: the init.group section for group.1 is the former init.form section for form.1. Group number 1 is not one of the groups in the form-definition.

before.group:

The actions programmed in this subsection are executed each time the specified group becomes active. When the group is split across more than one form, this subsection is executed whenever any form on which it occurs becomes current.

after.group:

The actions programmed in this subsection are executed each time the form on which the group occurs is ended. When the group is split across more than one form, this section is executed whenever any form on which the group occurs is ended.

Related help topics

•	4GL programming features (overview)

•	4GL event sections

•	Flow of standard program

•	Automatic import of variables


4GL choice sections

You use choice sections to program actions that you want to be executed when standard commands are activated or ended. Choice sections consist of a main section and a subsection. The main section specifies the standard command for which the actions must be executed. The subsections specify when the actions must be executed.

Main section

choice.<standard command>:

The subsections associated with this main section are executed for the specified standard command. You use the Maintain Forms by Package VRC session to select the standard commands (ttadv3100m000) for each form. A list of standard commands appears at the end of this help topic.

Subsections

before.choice:

The actions programmed in this subsection are executed immediately before the specified command is executed. You can use this subsection, for example, to test data before the command process continues. You can use the choice.again() function to stop the command.

on.choice:

The actions programmed in this subsection are executed when the specified command is activated. These actions are executed instead of the standard action associated with the command. This subsection is available for the following commands only:

•	print.data

•	run.job

•	global.delete

•	global.copy

•	bms

•	all commands in type 4 programs (except modify.set, restart.input, end.program, abort.program)

after.choice:

The actions programmed in this subsection are executed immediately after the specified command has been executed. This subsection is not available for the end.program and abort.program commands.

 Example

choice.first.view:

after.choice:

execute(first.set)

Standard commands

The following table lists the available standard commands and the types of program in which the various choice subsections can be programmed for each command.

No	Choice_option	Description	Before	On	After
01	start.set	Add/start a new group in main table	1234	---4	1234
02	first.view	View first group of main table	1234	---4	1234
03	next.view	View next group of main table	1234	---4	1234
04	prev.view	View previous group of main table	1234	---4	1234
05	last.view	View last group of main table	1234	---4	1234
06	def.find	Find a specific record on key	1234	---4	1234
07	find.data	Start the set from the current data in the program script. Use: after import of data in a zoom process. (refresh)	1234	---4	1234
08	first.set	View first set of main table	1234	---4	1234
09	next.set	First execute an update.db and then view next set of main table	1234	---4	1234
10	display.set	Open read-only details	1234	---4	1234
11	prev.set	First execute an update.db and then view previous set of main table	1234	---4	1234
12	rotate.curr	Show amounts in other currency (on.choice subsections are available for this command only if no currencies are set)	1234	1234	1234
13	last.set	View last set of main table	1234	---4	1234
14	add.set	Insert a new record	1234	---4	1234
15	update.db	First test consistency of data and then (re)write record or set (save)	1234	---4	1234
16	dupl.occur	Copy the record to a new one	1234	---4	1234
17	recover.set	Undo modifications which are not yet written to the database	1234	---4	1234
18	mark.delete	Delete selected records	1234	---4	1234
19	mark.occur	Select a record on the screen	1234	---4	1234
20	change.order	Change the search key	1234	---4	1234
21	modify.set	Change a record stored in the database	1234	----	1234
23	print.data	Make a report with the current data on the form	1234	1234	1234
24	create.job	Add session in job	1234	----	1234
25	form.tab.change	Go to another form in session	1234	----	1234
26	first.frm	Go to first form	1234	----	1234
27	next.frm	Go to next form	1234	----	1234
28	prev.frm	Go to previous form	1234	----	1234
29	last.frm	Go to last form	1234	----	1234
31	resize.frm	Resize the current form	1234	1234	1234
33	cmd.options	Show available form options	----	----	----
34	zoom	Zoom to another session/menu	1234	----	1234
35	interrupt	Do an action each time interval	1234	1234	1234
36	end.program	End execution of the session; the main table will be updated	1234	----	----
37	abort.program	Cancel execution of the session. The main table is not updated	1234	----	----
39	text.manager	Start the text manager	1234	----	1234
40	run.job	Run job of session	1234	1234	1234
41	global.delete	Delete range of records	1234	1234	1234
42	global.copy	Copy range of records	1234	1234	1234
43	save.defaults	Save values as defaults	1234	----	1234
44	get.defaults	Get previous stored defaults	1234	----	1234
45	start.chart	Chart Manager is started	1234	---4	1234
46	start.query	Start query by form	1234	---4	1234
60	ask.helpinfo	Asks for session help	----	----	----
62	calculator	Calculator will be started	----	----	----
63	calendar	Calendar will be started	----	----	----
64	bms	A broadcast message is received	1234	1234	1234
71	cmd.whats.this	Asks for field help	----	----	----
72	help.index	Asks for the help index	----	----	----
The following commands are supported for backward compatibility only. Support is not guaranteed in future versions of the software.

22	restart.input	Restart the input after giving <Esc> during input mode	1234	----	1234
38	cont.process	Start user defined process	1234	1234	1234
48	user.0	User option 0	1234	1234	1234
49	user.1	User option 1	1234	1234	1234
50	user.2	User option 2	1234	1234	1234
51	user.3	User option 3	1234	1234	1234
52	user.4	User option 4	1234	1234	1234
53	user.5	User option 5	1234	1234	1234
54	user.6	User option 6	1234	1234	1234
55	user.7	User option 7	1234	1234	1234
56	user.8	User option 8	1234	1234	1234
57	user.9	User option 9	1234	1234	1234
Related help topics

•	4GL programming features (overview)

•	4GL event sections

•	Flow of standard program

•	Automatic import of variables


4GL field sections

You use field sections to program actions that you want to be executed for a variety of field events. Field sections consist of a main section and a subsection. The main section specifies the field(s) for which the actions must be executed. The subsections specify when the actions must be executed.

Main sections

field.<field name>:

The subsections associated with this main section are executed for the specified field. The field name you specify must correspond with the name on the form.

field.all:

The subsections associated with this main section are executed for all fields on the form

field.other:

A subsection associated with this section is executed for all fields for which the particular subsection has not been programmed in a field.<field name> section.

Subsections

init.field:

The actions programmed in this subsection are executed the first time that the form on which the field occurs becomes current. The subsection is executed immediately before the init.form section of the form. You can use this section to change field attributes.

before.field:

The actions programmed in this subsection are executed each time the focus moves to the specified field. The subsection is executed immediately before the before.input or before.display subsections.

before.input:

The actions programmed in this subsection are executed immediately before input to an input field commences. This section is supported for backward compatibility only. In BaanERP programs, use enable.fields() and disable.fields() to enable and disable fields.

before.display:

The actions programmed in this subsection are executed each time that the specified field is displayed. You can use this subsection, for example, to set the value of a display field or to change the output format of currencies and dates (by using attr.oformat$).

before.zoom:

When a zoom process is started on the specified field, the actions programmed in this subsection are executed immediately before the zoom process is executed. You can use this subsection to change the zoom attributes. For example, in the field definition in the form manager, a default zoom code can be specified. You can then use this subsection to change the zoom code (by setting the predefined variable attr.zoomcode).

before.checks:

The actions programmed in this subsection are executed after input to the field has been completed and the TAB key has been pressed. The subsection is executed immediately before the domain and references are checked. You can use this section, for example, to change the value of the field before the domain and reference checks.

domain.error:

The actions programmed in this subsection are executed if the domain check causes an error after data has been entered in the field. You can use this section to provide your own error message instead of the standard message.

ref.input:

The actions programmed in this subsection are executed if a reference error occurs. If you program this section, the standard program does not display a message.

ref.display:

The actions programmed in this subsection are executed if there is an error in the reference display.

check.input:

The actions programmed in this subsection are executed immediately after the domain and reference checks. You can use this section to test for errors that are not detected automatically. If the standard program detects an error, input is automatically restarted. In a script, you can use set.input.error() to display an error message and start input again.

This section is replaced by DAL functionality (if a DAL exists for the table).

on.input:

The actions programmed in this subsection are executed immediately after the check.input subsection. You can use this section, for example, to perform some appropriate action when the user enters a special character or to display a warning message in certain cases.

when.field.changes:

The actions programmed in this subsection are executed when the new value entered in the specified field differs from the old value.

after.zoom:

The actions programmed in this subsection are executed when the zoom process on a specified field ends. You can use this subsection, for example, to redisplay any field that has changed as a result of the zoom process.

after.input:

The actions programmed in this subsection are executed after all checks have been performed on input to the specified field and after the when.field.changes subsection has been executed. In this subsection, you can use the to.field() function if the sequence deviates from the default.

after.display:

The actions programmed in this subsection are executed just after display of the specified field. You can use this subsection, for example, to read reference tables.

after.field:

This is the last subsection for a field. The actions programmed in this subsection are executed after input to or display of the specified field. This section is always executed, even if the user left the field by pressing ESC, one of the arrow keys, or a mouse button. You can use this subsection to perform special actions before leaving the field.

Example

field.pctst099.item:

check.input:

select pctst001.*

from pctst001

where pctst001.item = :pctst099.item

as set with 1 rows

selectdo

....

selectempty

pctst001.dsca = "*****"

set.input.error(".....")

endselect

before.input:

if ..... then

attr.input = false

endif

after.display:

select pctst001.*

from pctst001

where pctst001.item = :pctst099.item

as set with 1 rows

selectempty

pctst001.dsca = "*****"

endselect

field.pctst099.date:

before.input:

attr.oformat$ = "%D002,2"

Related help topics

•	4GL programming features (overview)

•	4GL event sections

•	Flow of standard program

•	Automatic import of variables


4GL zoom.from sections

You use zoom.from sections to program actions that you want to be executed when the current session is activated as a zoom process. A zoom process can be activated by a form-specific command of type session, by zooming on an input field, by pressing CTRL+B, or by calling zoom.to$() in the program script. Zoom.from sections consist of a main section and a subsection. The main section specifies the process for which the actions must be executed. The subsections specify when the actions must be executed.

Main sections

zoom.from.<zoom name>:

Each field has a name that can be used as a zoom name. You can specify the zoom name in this main section. The zoom name indicates which field the current session was zoomed from (when the subprocess is started from a form command, the zoom name is "choice"). The subsections associated with this main section are executed when the current process was zoomed to from the specified process.

zoom.from.all:

The subsections associated with this main section are executed for all processes from which the current session can be zoomed to.

zoom.from.other:

A subsection associated with this section is executed for all processes for which the particular subsection has not been programmed in a zoom.from.<zoom name> section.

Subsections

on.entry:

The actions programmed in this subsection are executed each time the current process is started from the specified process(es). You can use this subsection to import variables.

on.exit:

The actions programmed in this subsection are executed at the end of the current process, if the current process was started from the process(es) specified in the main section. You can use this subsection to export variables.

 Example

zoom.from.all:

on.entry:

import("globvar", localvar)

on.exit:

export("globvar", localvar)

Related help topics

•	4GL programming features (overview)

•	4GL event sections

•	Flow of standard program

•	Automatic import of variables


4GL main table i/o sections

You use main table i/o sections to program actions that you want to be executed when read or write actions occur on the main table. These sections are not relevant to type 4 programs, as such programs do not have a main table. Main table i/o sections consist of a main section and a subsection. The main section is always main.table.io. The subsection indicates when the actions must be executed.

Note that main.table.io sections (except the read.view subsection) are ignored when the corresponding DAL hooks are programmed in a DAL script.

Main section

main.table.io:

The subsections associated with this main section are executed either before or after input to or output from the main table. The main table for the current session is defined in the data dictionary.

Subsections

before.read:

The actions programmed in this subsection are executed immediately before each read action on the main table.

after.read:

The actions programmed in this subsection are executed after each read action on the main table. You can use this subsection to call skip.io() in order to skip the record just read and to read the next record (if necessary).

before.write:

The actions programmed in this subsection are executed before each write action on the main table. A write action occurs when a record is inserted. You can use this subsection to call skip.io() in order to undo the write action.

after.write:

The actions programmed in this subsection are executed after each write action on the main table. A write action occurs when a record is inserted. You can use this subsection, for example, to write data to tables other than the main table.

after.skip.write:

The actions programmed in this subsection are executed if a write action on the main table has been skipped as a result of actions programmed in the before.write subsection. The actions are executed immediately after the skip action.

before.rewrite:

The actions programmed in this subsection are executed immediately before each rewrite of a record in the main table. A rewrite action occurs when a record is changed. You can use this subsection to call skip.io() in order to skip the rewrite action.

after.rewrite:

The actions programmed in this subsection are executed after each rewrite action on the main table. A rewrite action occurs when a record is changed.

after.skip.rewrite:

The actions programmed in this subsection are executed if a rewrite action on the main table has been skipped as a result of actions programmed in the before.rewrite subsection. The actions are executed immediately after the skip action.

before.delete:

The actions programmed in this subsection are executed immediately before each delete action on the main table. You can use this section to call skip.io() in order to skip the delete action.

after.delete:

The actions programmed in this subsection are executed immediately after each delete action on the main table. You can use this subsection, for example, for deleting references, if this is not done automatically.

after.skip.delete:

The actions programmed in this subsection are executed if a delete action on the main table has been skipped as a result of actions programmed in the before.delete subsection. The actions are executed immediately after the skip action.

read.view:

The actions programmed in this subsection are executed immediately after a view action on the main table (start.set, first.view, next.view, prev.view or last.view). You can use this subsection to call skip.io() in order to skip an entire set of records with the same value in the view fields.

Example

main.table.io:

before.delete:

if (not pctst099.del) then

skip.io("pctsts0001")

| cannot be deleted

endif

read.view:

if strip$(pctst099.cprj) = "" then

skip.io("")

endif

Related help topics

•	4GL programming features (overview)

•	4GL event sections

•	Flow of standard program

•	Automatic import of variables


Flow of standard program

This section presents the general flow of the standard program.  It is not complete, but the most important actions are included. The flow is similar for programs of types 1, 2, 3, and 4. Any differences are indicated by comments.

Main routine

The main routine displays the first form on the screen and waits for a command.

function main()

{

before.program

read.form()

init.references

create.sql.queries

if background then

get.ref.var(parent)

read record

endif

db.bind(tmain)                | Not in type 4

if job.process then           | Only type 4

 	before.choice.run.job

execute(cont.process) or on.choice.run.job

after.choice.run.job

execute(end.program)

endif

zoom.from.on.entry

for each field on form

init.field

put.attributes()

endfor

change to start index	| Not in type 4

init.form

execute start event

before.form

while true

input.choice()

if update.status and choice <> ... then	| Not in type 4

on.update.db()

| See "update database" section

endif

on case choice

case <choice.option>

before.<choice.option>

on.<choice.option>

after.<choice.option>

break

case ...

....

endcase

endwhile

Choice sections

The choice sections above are given as before.choice.option and after.choice.option. In a 4GL program, a choice section consists of the main section choice.choice.option and one of the subsections before.choice, on.choice, or after.choice.

Form sections

When changing from form X to form Y, the form sections are executed in the following sequence:

after.form 	for X

init.form	for Y      (only the first time)

before.form	for Y

The above subsections can be defined, as follows:

for all forms	: form.all

for a specific form	: form.<form name>

for forms not specifically defined	: form.other

At init.form the sequence is:

form.all: init.form

form.<form name>: init.form or form.other: init.form

At before.form the sequence is:

form.all: before.form

form.<form name>: before.form or form.other: before.form

At after.form the sequence is:

form.<form name>: after.form or form.other: after.form

form.all: after.form

Field sections

There are two groups of field sections:

•	sections for which the field.all section is executed first:

init.field

before.field

before.input

before.display

before.checks

before.zoom

check.input	| if not in DAL

on.input

•	sections for which field.all is executed after field.<field name> or field.other:

after.input

after.display

after.zoom

ref.input

ref.display

domain.error

when.field.changes

after.field

The general flow of input fields is as follows:

Field.input:

before.field

if not input.field then

read.reference

if error.reference then

ref.display

else

before.display

display.field()

after.display

endif

return

endif

before.input

if input disabled then

read.reference

if error.reference then

ref.display

else

before.display

display.field()

after.display

endif

return

endif

zoom.ret:

do.input.field()

if in.ret = ZOOM then

before.zoom

zoom.to ...

after.zoom

goto zoom.ret

endif

if choice = f.to.choice or

in.ret = arrow.up/down/left/right/tab then

goto after.field

endif

before.checks

check.domain()

if domain.error then

domain.error

error.message

goto field.input

endif

check.reference

if reference.error then

ref.input

error.message

goto field.input

endif

check.input

if check.input.error then

error.message

goto field.input

endif

on.input

....

....

when.field.changes

after.input

after.field

End of program

The flow of the end of the program is as follows. The function end.of.program() is called when executing the standard command END.PROGRAM.

function end.of.program()

{

before.end.program

if e then

on.error

endif

after.form

after.program

if zoomfield <> "" then

fill.zoomreturn

zoom.from.on.exit

if record.marked then

commit.transaction()   | Not in type 4

exit(exit.val)

endif

endif

commit.transaction()          | Not in type 4

exit()

 }

Zoom sections

The zoom.from.on.entry and zoom.from.on.exit sections are used In the main routine and in the end.of.program() function. In a 4GL program, a zoom section consists of a main section (zoom.from.all, zoom.from.<zoomname>, or zoom.from.other) and a subsection (on.entry or on.exit).

The sequences in which the sections are executed differ for on.entry and on.exit. For on.entry, zoom.from.all is executed first and then zoom.from.<zoomname> or zoom.from.other. For on exit, it is the other way around.

Update database

An update of the database is necessary if a record is added, changed or deleted. The actual update is executed if one of the following actions is activated after a record has been added, changed or deleted: start.set, def.find, find.data, first.set, next.set, prev.set, last.set, next.help, prev.halfset, change.order, cont.process.

All these actions first call on.update.db() if a record is added, changed or deleted. The general flow of the on.update.db() is as follows. Note that this function is not relevant to programs of type 4.

on.update.db()

{

if update.status = add.set or modify.set then

for all occurrences

check.domains()

if domain.error then

domain.error

error.message

return

endif

check.references

if reference.error then

ref.input

error.message

return

endif

for each field of occurrence

check.input

if check.input.error then

error.message

return

endif

endfor

endfor

endif

before.update.db

db.retry.point()

for all occurrences

before.write / before.rewrite / before.delete

if not skip then

write / rewrite / delete record

after.write / after.rewrite / after.delete

else

after.skip.write / after.skip.rewrite / after.skip.delete

endif

endfor

back.to.old.key

after.update.db

commit.transaction()

after.update.db.commit

 }

Main table i/o section

Most of the main table i/o are mentioned above. They are not available in programs of type 4.

The read.view section is executed immediately after any view action on the main table (only in type 3 programs). The function skip.io("messcode") can be used in this section. This implies that the next or previous view is read.

Related help topics

•	4GL programming features (overview)

•	4GL event sections

•	Automatic import of variables


Automatic import of variables

When you zoom from a main process to a subprocess, in some cases variables are imported automatically.

Case 1

From the main process with main table X you have zoomed to the subprocess with main table Y. Table X has a foreign (cross-reference) key to table Y. For example,  X = customer table, Y = currency table. The currency field in the customer table refers to the currency table.

The standard program imports the field(s) from table X and stores them in the primary key fields of table Y.

Consequences for programming in script

In the script of the subsession, only the following needs to be programmed:

if background then

execute(find.data)

(or, sometimes, for type 3 screens: execute(first.set))

else

....

endif

There is no need to adjust the main session in order to import the variables into the subsession.

Case 2

From the main process with main table X, you have zoomed to the subprocess with main table Y. A field in table Y refers to table X. (In most cases, there is an identifying relationship between table X and table Y – for example, order header (table X) and order lines (table Y).) The standard program imports the primary key values from table X and stores them in the corresponding fields of table Y.

Example

Primary key of table X is Order number; primary key of table Y is Order number, position number.

The standard program imports the order number from table X to the corresponding field in table Y. The position number in table Y remains, of course, empty.

Consequences for programming in script

See Case 1 above.

Case 3

From the main process with main table X, you have zoomed to the subprocess with the same main table. (For example, a zoom from 'Maintain Item Data' (type 1) to 'Display Item Data' (type 2 or 3).)

The standard program imports the primary key value from table X for the main process and stores it in the primary key fields of table X for the subprocess.

Consequences for programming in script

See Case 1 above.

Case 4

From the main process with main table X you have zoomed to a subprocess without a main table (for example, a print program). The standard program imports the primary key values of main table X for the main process and stores them in the primary key fields of table X (if available) for the subprocess.

Example

A zoom from 'Maintain Item Data' to 'Print Item Data'. The main table for the main process is tstpi100. The subprocess imports values of tstpi100.cuno and tstpi100.item from the main process and stores them in the fields of the subprocess.

Consequences for programming in script

In many cases, you must reprogram the main process in such a way that the primary key fields of the main table for the subprocess are filled.

Case 5

From the main process without a main table you have zoomed to a subprocess with main table X. The standard program imports the primary key values of table X (if available) for the main process and stores them in the primary key fields of the subprocess's main table.

Example

A zoom from 'Print Item Data' to 'Display Item Data'. The main table for the subprocess is ttstpi100. The standard program tries to import tstpi100.cuno and tstpi100.item from the main process and stores them in the fields of the main table for the subprocess.

Consequences for programming in script

See Case 1 above.

In many cases you must reprogram the main process in such a way that the primary key fields of the main table for the subprocess are filled.

Example

field.item.t:

before.zoom:

tstpi100.cuno = cuno.f

tstpi100.item = item.f

Case 6

From the main process with table X you have zoomed to a subprocess with table Y. There is no relationship between table X and table Y (none has been defined in the data dictionary). The standard program imports the primary key values of table Y for the main process (if available) and stores them in the primary key fields of table Y for the subprocess.

Consequences for programming in script

See Case 1 above.

Often you will have to reprogram the main process in such a way that the primary key fields of the main table for the subprocess are filled.

Example

field.tswoc150.item:

before.zoom:

tstpi100.cuno = tswoc100.cuno

tstpi100.item = tswoc150.item

Related help topics

•	4GL programming features (overview)

•	4GL event sections

•	Flow of standard program


Guideline on field initializing and field enabling/disabling

Baan software was originally written in the “ASCII terminal” era. Since then mouse driven GUI’s, Dynamic Forms (implemented in BaanERP 5.1 and beyond),  and user environments like “Page Mode” (implemented in BaanERP 5.1 and beyond) were introduced.

This means that some sections in the 4GL scripts are not always executed, because fields can be skipped (Mouse) or have been removed by the user (Dynamic Forms)

In Page Mode another problem arises, only fields that are changed will be synchronized when passing a synchronization point. This means that even entering and leaving a field will not ensure that, for example, before.field, before.input, after.input and after.field will be invoked.

For the above mentioned points, some guidelines are developed that, if followed, will ensure your code works as expected.

Guidelines

If actions must be performed:

•	On record level, use the section before.new.object.
Do not use the section before.input of the first field on the form.

•	On a group of fields, use the sections before.new.object and init.group.
Do not use the section before.input of the first field on the form.

•	On field level, use the section when.field.changes and display the resulting fields.
Do not use the sections, before.input, after.input, before.field, after.field, before.display, after.display, after.zoom.

Variables must be initialized directly after performing an action, depending on the type of form:

•	Type 1-3
Initialize variables in sections, add.set, before.new.object and when.field.changes

•	Type 4 (no records only selections)
Initialize variables in sections: init.group, before.display.object and when.field.changes

Always use set.enum.values.for.field() in section when.field.changes instead of set.enum.values() in the section before.input which is forbidden.

Creating/Duplicating an ‘object’

Action that may be executed when initializing fields and controls	Event section where the action should be executed
Initializing values of fields	before.new.object
Initializing statuses of fields	before.new.object
Initializing list box masks of fields	before.new.object
Initializing statuses of controls (menu items, buttons)	before.new.object
Initializing status bar message	before.new.object
Entering fields

Action that may be executed when entering a field	Event section where the action should be executed
Enabling menu-items that relate to the field.	Before.input: if the action only must be performed in case the field has the input status.
Presenting a status bar message. (only relevant on overview windows)	Use: Before.field: if the message must be presented in case the field has either the input or display status Before.input: if the message only must be performed in case the field has the input status Before.display: if the message only must be presented in case the field has the display status
Changing the format of the information, for example, currencies. (if the Standard Program does not do this)	Use: Before.input: if the action only must be performed in case the field has the input status Before.field: if the action must be performed in case the field has either the input or display status (to be avoided) Before.display: if the action only must be performed in case the field has the display status (to be avoided)
Leaving fields

Action that may be executed when leaving a field	Event section where the action should be executed
Disabling menu-items that relate to the field.	After.input, after.display or after.field In general the action should be executed in the opposite subsection of the before.x subsection.
Changing the format of the information, for example, currencies. (if the Standard Program does not do this)	After.input, after.display or after.field In general the action should be executed in the opposite before.x subsection.
Presenting a status bar message. (In case a message is presented in a before.x subsection, that message should be removed or replaced by a (default) message in the opposite after.x subsection in general)	Use: After.input: if the message only must be performed in case the field has the input status After.display: if the action only must be performed in case the field has the display status After.field: if the message must be presented in case the field has either the input or display status
Changing values and statuses

The following actions may not be executed in before.field, before.input, before.display, after.display, after.input and after.field:

•	Changing the value of the field

•	Changing the status of the field

•	Changing the value of other fields

•	Changing the status of other fields

•	Changing an enum mask

Consequences of changing values

If the user changes the value of a field, this may have consequences on the values or statuses of other controls.

Action that may be executed when the value of a field is changed and accepted	Event subsection where the action should be executed
Changing the value of other fields	When.field.changes
Changing the status of other controls	When.field.changes
Enabling/disabling menu items and buttons that depend on the value of the field or another field that is modified	When.field.changes
Determining list box (enum) mask	When.field.changes
Example (not correct

)

field.tisfc001.plan:

after.input:

|* date/time 0 means undefined

if tisfc001.plan = tcplcd.forward and tisfc001.strt = 0 then

tisfc001.strt = get.default.date()

display("tisfc001.strt.date")

display("tisfc001.strt.time")

endif

if tisfc001.plan = tcplcd.backward and tisfc001.endd = 0 then

tisfc001.endd = get.default.date()

display("tisfc001.endd.date")

display("tisfc001.endd.time")

endif

Example (correct)

add.set:

before.new.object:

|* date/time 0 means undefined

|* forward planning is the default

tisfc001.plan = tcplcd.forward

tisfc001.strt = get.default.date()

tisfc001.endd = 0

field.tisfc001.plan:

when.field.changes:

if tisfc001.plan = tcplcd.forward and tisfc001.strt = 0 then

tisfc001.strt = get.default.date()

display("tisfc001.strt.date")

display("tisfc001.strt.time")

disable.fields(“tisfc001.strt”)

endif

if tisfc001.plan = tcplcd.backward and tisfc001.endd = 0 then

tisfc001.endd = get.default.date()

display("tisfc001.endd.date")

display("tisfc001.endd.time")

disable.fields(“tisfc001.endd”)

endif

Page Mode

In Page Mode checks, for instance with the database, are performed when the complete record is saved. However for usability synchronization points can be defined per field. In page mode a window is updated after the user passes a sync-point. There are several standard sync-points (e.g. using the scroll bar, moving to another tab). Furthermore the software engineer can set ‘extra’ sync-points in the form editor. The number of ‘extra’ sync-points however should be limited, because otherwise the network performance profits of page mode will be neutralized.

Synchronization points can be set for difficult calculations and defaults. In fact the question is what is the penalty for not giving a default, will the user be lost, does he/she have to redo a lot of actions.

An example, is for instance, a startdate and a calculated enddate based on the leadtime. If the leadtime in the business is in minutes, the user will not be interested immediately in the enddate. However if the leadtime is some months, the user is very interested in the enddate, since he may stop the entering, since the customer may find it unacceptable. In fact during package implementation with page mode it is important to think about synchronization points.

Synchronization guidelines

•	Synchronize after the user modifies a field that results in a change of value of another field on the same form

•	Do not place more than three synchronization points in one form in a details window

•	Do not place more than two synchronization points in the group fields of an overview window

•	In an editable overview window, synchronize after each record


Report scripts: overview

BaanERP reports are used to output data from the database to a variety of devices (for example, printers, displays, and files).

The contents and layouts of reports are defined in the data dictionary. In addition, you can link a report script to a report. In a report script, you can program actions that you want to be performed at particular stages of the report execution. For example, you can create a script to perform calculations on the report data or to read records from related tables that are not automatically available to the report. You program report scripts in the same way as you program 4GL program scripts, except that report scripts use different event sections and some special functions.

Related help topics

•	Report script sections

•	Predefined variables

•	Report script functions

•	Expanding text variables


Report script sections

A report script consists of one or more event sections in which you program actions to be performed at particular states of execution of the report to which the report script is linked. The statements programmed in a report script section consist of a combination of 3GL language statements and report script functions.

Report scripts support the following event sections:

•	program sections

•	report sections

•	text field sections


Program sections (report scripts)

You use program sections to define functions, and to declare tables and global variables, that you want to use in the other sections in the script. You also use program sections to program actions that you want executed at the start and end of the report and after the report writer receives a record.

The following program sections are available. They are all main sections. There are no subsections associated with program sections.

declaration:

Use this section to declare tables and global variables that you want to use in other sections in the report script. See Variable declarations and Table declarations for details of the declaration syntax. Note that there is no need to declare a table if a field of that table is defined in the report writer as an input field. The report writer declares such tables automatically.

before.program:

Use this section to program actions that must be executed when the report is started. For example, you can use this section to initialize or import variables.

after.program:

Use this section to program actions that must be executed at the end of the report. For example, you can use this section to close files that were opened during execution of the report.

after.receive.data:

Use this section to program actions that must be executed whenever the report writer receives a record. For example, you can use this section to read or modify a variable.

functions:

Use this section to define functions that you want to use in other sections in the report script. The syntax of functions used in a report script is the same as for 3GL functions.

When included, this section must be the last section in the report script.

Related help topics

•	Report scripts: overview

•	Report script sections

•	Predefined variables

•	Report script functions

•	Expanding text variables


Report sections (report scripts)

A report consists of a number of layouts, which define the content and organization of the various parts of a report (for example, the header, footer, and body of the report). There are a number of possible layout types, as follows:

•	before.report – printed once at beginning of the report (a title page, for example)

•	after.report – printed once at the end of the report

•	header – printed at the top of each page

•	footer – printed at the bottom of each page

•	before.field – printed before each group of records in reports of type 3; if a group of records spans more than one page, the before.field layout is repeated at the top of the new page

•	after.field – printed immediately after each group of records in reports of type 3

•	detail – used for the individual records included in the body of the report

The content and arrangement of these layouts are defined in the data dictionary.

In the report sections in a report script, you can program actions to be performed before and/or after execution of individual layouts of these types. Report sections consist of a main section and a subsection. You use a main section to specify the particular layout for which the programmed actions are to be executed. You must follow a main section with either a before.layout or an after.layout subsection. These latter specify whether the actions are to be executed before or after the particular layout is printed.

Main sections

before.report.<layout_number>:

Actions programmed in this section are executed for a specified layout of type before.report.

after.report.<layout_number>:

Actions programmed in this section are executed for a specified layout of type after.report.

header.<layout_number>:

Actions programmed in this section are executed for a specified layout of type header.

detail.<layout_number>:

Actions programmed in this section are executed for a specified layout of type detail.

before.<field name>.<layout_number>:

Actions programmed in this section are executed for a specified layout of type before.field.

after.<field name>.<layout_number>:

Actions programmed in this section are executed for a specified layout of type after.field.

footer.<layout_number>:

Actions programmed in this section are executed for a specified layout of type footer.

Subsections

before.layout:

Actions programmed in this subsection are executed before the specified layout is printed.

When lattr.print is set to false, the layout is not printed and the before.layout and after.layout sections are not executed. If you set lattr.print to false in the before.layout section itself, the layout is not printed and the after.layout section is not executed.

after.layout:

Actions programmed in this subsection are executed after the specified layout is printed.

Related help topics

•	Report scripts: overview

•	Report script sections

•	Predefined variables

•	Report script functions

•	Expanding text variables


Text field sections (report scripts)

You use a text field section to apply certain actions to all instances of a particular text field that are included in the report. A text field section consists of a main section and a subsection. The main section specifies the particular text field to which the actions must be applied. The subsection specifies that the actions are to be performed before the text field is printed.

For example, you could include the page(), need(), and skip() functions in a text field section to enforce a page break or to skip a specified number of lines before the text field is printed. Or you could set lattr.print in the section in order to skip one text line before printing the text field.

Main field

field.<text_field>:

Actions programmed in this section are executed for all instances of the specified text field that are included in the report. The text field must have been defined as a report input field in the data dictionary.

Subsection

before.print:

Actions programmed in this section are executed before the specified text field is printed.

Related help topics

•	Report scripts: overview

•	Report script sections

•	Predefined variables

•	Report script functions

•	Expanding text variables


Report scripts: predefined variables

You can use the following predefined variables in a report script.

R = read-only     R/W = read and write

lattr.autobefores	R/W	A boolean indicating whether or not before.field layouts are automatically repeated at the top of a page if the page break does not correspond with a sort break. The default value is true.
lattr.autoreset	R/W	A boolean indicating whether or not reset.suppress() is automatically performed in the case of breaks of layouts in sorting fields. The default value is true.
lattr.break	R	A boolean that is set to true during printing of before.field layouts when the layout is printed as the result of a sort field change. It is set to false when a before.field layout is printed because of a page break.
lattr.enddata	R	A boolean indicating whether or not the end of the data has been reached.
lattr.header	R	A boolean that is set to true during printing of header layouts and during printing of before.field layouts at the top of a page.
lattr.language$	R	The language code of the report.
lattr.lineno	R	The current line number.
lattr.multicol	R/W	Indicates whether or not multiple columns are used when more than one layout fits on a line. Possible values are: MULTICOL_NONE Normal output; no columns are used. MULTICOL_ORDER_HORIZONTAL   Output is arranged in multiple columns, ordered horizontally. For example: rec_1    rec_2    rec_3 rec_4    rec_5    rec_6 MULTICOL_ORDER_VERTICAL  Output is arranged in multiple columns, ordered vertically (per page). For example: rec_1    rec_3    rec_5 rec_2    rec_4    rec_6
lattr.multicol.count	R/W	Specifies the number of columns to use when multiple columns are specified (see lattr.multicol). The default value is 0. In this case, the report manager calculates the number of columns based of the report width and the layout width.
lattr.multicol.repeat	R/W	A boolean indicating whether headers and footers are automatically repeated for each column. The default value is true. The width of the header and footer layouts width must be equal to or less than the width of the detail layout.
lattr.pageno	R/W	Current page number.
lattr.print	R/W	Indicates whether or not a layout is to be printed.
lattr.prline	R/W	After expansion of a variable in a report, this is filled with the text line that is printed.
lattr.recordtimes	R/W	Indicates the number of times the layout will be printed.
lattr.textexpand	R/W	A boolean indicating whether or not variables included in text fields can be expanded. The default is false.
lattr.textlang$	R/W	The language code for printing text. The default is the language code of the report.
lattr.textline	R	A string containing the source text line from the text manager.
lattr.textlineno	R	The number of the line that must be printed.
lattr.textlines.max	R/W	The maximum number of lines in the layout.
lattr.textlines.min	R/W	The minimum number of lines in the layout.
Related help topics

•	Report scripts: overview

•	Report script sections

•	Report script functions

•	Expanding text variables


Report script functions

The statements programmed in a report script section consist of a combination of 3GL language statements and the following 4GL report functions:

layout.again()	Evaluate and print layout again.
need( expr )	Force a page break if the number of free lines is less than expr.
page()	Start a new page.
reset.suppress()	It is possible to suppress printing a value when it is the same as the previous value. You can use this function to suppress the value once (that is, for one value).
skip( expr )	Skip expr number of lines before printing the next layout.
skip.to( expr )	Skip to the line number indicated by expr. Intervening lines are left blank. If the specified line number is less than the current page number, a new page is started.
to.page( expr )	Start a new page with number expr.
You cannot use need(), page(), skip(), skip.to(), or to.page() in header and footer layouts.

Related help topics

•	Report scripts: overview

•	Report script sections

•	Predefined variables

•	Expanding text variables


Expanding text variables

Variables or expressions that are included in text lines can be expanded or substituted for report purposes. You must set the variable lattr.textexpand=TRUE if you want this to happen. Expressions are internally evaluated by the function expr.compile().

Customers can use variables in texts. For example, "address", "city", "salary" and so on. Customers must be informed about these variables so that they can use them.

Syntax

The following is the syntax for variables and expressions included in text lines:

$variable	or    #variable

${expression}	or	 #{expression}

When the $ symbol if used, the text moves over to accommodate the expanded variable or expression. When the # symbol is used, the expanded variable or expression overwrites existing text.

Example

The following is an example of text created by using the text manager. The text includes both variables and expressions that can be expanded/substituted for report purposes.

To:	$surname $christian name	#date	, Ede

  	$address

$ZIP code  $city

Dear $christian name:

We have the pleasure of informing you that, as of $date, your salary 	has been raised by 5%. For you this implies a gross amount of

${edit( salary + ( salary * 0.05 ), "ZZZZ9,ZZ" )} per month.

Kind regards,  $Mgr.

Related help topics

•	Report scripts: overview

•	Report script sections

•	Predefined variables

•	Report script functions


Database handling: overview

BaanERP data is stored in a relational database, which is managed by a Relational Database Management System (RDBMS). The RDBMS acts as the database server for BaanERP applications. BaanERP supports the following RDBMS products:

•	Informix

•	Oracle

•	Sybase

•	DB2

•	Microsoft SQL Server

The BaanERP architecture includes a database driver. This provides the application server (that is, the bshell) with a common interface to the database server, regardless of which RDBMS product is used. This enables the application server to be database independent. The database driver is responsible for translating database commands received from the application server into RDBMS-specific commands. Although, the database driver's interface with the application server is the same for all RDBMS products, Its interface with the RDBMS is RDBMS-specific. Therefore, there is a separate database driver for each of the supported RDBMS products.

Database tables

A relational database presents information to the user in the form of tables. In a table, data is organized in columns and rows. Each column (also referred to as a field) represents a category of data. Each row (also referred to as a record) represents a unique instance of data for the categories defined by the columns.

   Table illustration

A field always refers to a domain, which defines a set of values from which one or more fields can draw their actual values. For example, the 'tcweek' domain is the set of all integers greater than zero and less than or equal to 53.

Primary keys

Every database table has a field, or a combination of fields, which uniquely identify each record in the table. This unique identifier is referred to as the primary key. Primary keys are fundamental to database operations, as they provide the only record-level addressing mechanism in the relational model. Primary keys act as references to the records in a table.

Relationships/references

With a relational database, you can store data across multiple tables and you can define relationships between the tables. This means that individual tables can be kept small and data redundancy can be minimized. A relationship exists between two tables when they have one or more fields in common. So, for example, a Customer Details table can be linked to an Orders table by including a Customer ID field in both tables. In the Customer Details table, the Customer ID field is the primary key. In the Orders table, it is referred to as a foreign key. By linking the two tables in this way, there is no need for the Orders table to include customer details such as name and address. Note that references from one table to another must always use the primary key.

Combined fields

A combined field is a field that consists of two or more child fields. You can use combined fields as primary keys, and you can also use them for references and indexes.

Indexes

Indexes facilitate speedy searching and sorting of database tables. An index is a special kind of file (or part of a file) in which each entry consists of two values, a data value and a pointer. The data value is a value for some field in the indexed table. The pointer identifies the record that contains this value in the particular field. This is analogous to a conventional book index, where the index consists of entries with pointers (the page numbers) that facilitate the retrieval of information from the body of the book.

Note that it is also possible to construct an index based on the values of a combination of two or more fields.

Every table must have at least one index, which is an index on the primary key field(s). This is referred to as the primary index. An index on any other field(s) is referred to as a secondary index.

   Index illustration

Structured Query Language (SQL)

Baan SQL is the database query language that you use to access data in the database tables. Using Baan SQL, you can construct queries to retrieve specific data from the database. The syntax and usage of Baan SQL is discussed fully in the section Baan SQL.

Naming conventions

The naming syntax for tables, record buffers, and table fields is as follows:

tppmmmxxx	| table

rcd.tppmmmxxx	| record buffer of table

ppmmmxxx.ffffffff  	| logical field of table

where t stands for table, pp is the package code, mmm is the module code, xxx is the table number (range 000 to 999), and ffffffff  is a field name (maximum 8 alphanumeric characters, starting with an alphabetic character).

Using tables in program scripts

If a table is used in a script it must be declared with the following statement:

table	tppmmmxxx

Declaration of a table implies declaration of all its fields and its record buffer. It is not necessary to declare these separately.

There are no special functions for opening and closing tables. A table is automatically opened at the first database call on that table and it is automatically closed at the end of the program.

You can use the record buffer of a table to save the contents of a record in a temporary string. And you can subsequently restore the record from the buffer. If a record contains numeric fields, you can only save and restore records. You cannot perform any other actions on the temporary string, as the presence of NULL characters will cause loss of data.

Data types

The data type is the internal representation of table field and domain data. The following data types are available:

DB.BITSET	DB.INTEGER

DB.BYTE	DB.LONG

DB.COMBINED	DB.MAIL

DB.DATE	DB.MULTIBYTE

DB.DOUBLE	DB.STRING

DB.ENUM	DB.TEXT

DB.FLOAT	DB.TIME

Related help topics

•	Transaction handling

•	Locking

•	Retry points

•	BAAN SQL

•	Error handling

•	Hints for using SQL

•	Hints for using db.retry.point()


Transaction handling

With respect to database actions, a transaction is a sequence of related actions that are treated as a unit. The actions that make up a transaction are processed in their entirety, or not at all.

A transaction ends with the function commit.transaction() (all changes made during the transaction are stored in the database) or with the function abort.transaction() (no changes are stored in the database). A transaction starts either at the beginning of a process, with the function set.transaction.readonly(), with the function db.lock.table(), or after the preceding transaction has ended.

A transaction is automatically rolled back (that is, it is undone) when a process is canceled and if a program ends without a commit.transaction() or abort.transaction() after the last database call. Undoing a transaction is only possible if the underlying database system supports this.

Certain database actions cannot be placed within a transaction, because they cannot be rolled back. These actions are: db.create.table(), db.drop.table(), and set.transaction.readonly(). These functions can be called only at the start of a program or after the end of the preceding transaction.

You can set a retry point immediately before a transaction. In case of an error, the system returns to this point and re-executes the transaction from there.

A read-only transaction is a transaction in which you are permitted only to read records (without lock) from the database. You retain read consistency during the entire transaction. This means that during the transaction your view of the database does not change, even if other users update the records. A read-only transaction starts with the function set.transaction.readonly() (this must be called after ending the preceding transaction or at the beginning of the program) and ends with a commit.transaction() or abort.transaction(). A consistent view consumes a large amount of memory, so a read-only transaction must be as short as possible; user interaction during the transaction is not recommended.

Related help topics

•	Database handling: overview

•	Locking

•	Retry points

•	BAAN SQL

•	Error handling

•	Hints for using SQL

•	Hints for using db.retry.point()


Locking

Database inconsistencies can arise when two or more processes attempt to update or delete the same record or table. Read inconsistencies can arise when changes made during a transaction are visible to other processes before the transaction has been completed – for example, the transaction might subsequently be abandoned. To avoid such inconsistencies, BaanERP supports the following locking mechanisms:

•	Record/page locking

•	Table locking

•	Application locking

Record/page locking

To ensure that only one process at a time can modify a record, the database driver locks the record when the first process attempts to modify it. Other processes cannot then update or delete the record until the lock has been released. However, they can still read the record.

While one process is updating a table, it is important that other processes retain read consistency on the table. Read consistency means that a process does not see uncommitted changes. Updates become visible to other processes only when the transaction has been closed. Some database systems do not support read consistency, and so a dirty read is possible. A dirty read occurs when one process updates a record and another process views the record before the modifications have been committed. If the modifications are rolled back, the information read by the second process becomes invalid.

Some databases, such as SYBASE, use page locking instead of record locking. That is, they lock an entire page in a table instead of an individual record. A page is a predefined block size (that is, number of bytes). The number of records locked partly depends on the record size.

Supported features

	INFORMIX	ORACLE	SYBASE	DB2	SQL Server
locking	row	row	page	row	page
dirty read	yes	no	*
consistent read	no	yes	*
transactions	yes	yes	yes	yes	yes
* SYBASE will block when there is a read action (locked or not) on a record in a page that has been locked.

Delayed locks

Locking a record for longer than required can result in unnecessarily long waiting times. The use of delayed locks solves this problem to a great extent.

A delayed lock is applied to a record immediately before changes are committed to the database and not earlier. When the record is initially read, it is temporarily stored. Immediately before updating the database, the system reads the value of the record again, this time placing a lock on it. If the record is already locked, the system goes back to the retry point and retries the transaction. If the record is not locked, the system compares the content of the record from the first read with the content from the second read. If changes have been made to the record by another process since the first read, the error EROWCHANGED is returned and the transaction is undone. If no changes have occurred, the update is committed to the database.

You place a delayed lock by adding the keyword FOR UPDATE to the SELECT statement (see BAAN SQL). For example:

table   tpctst999

db.retry.point()

SELECT pctst999.*

FROM pctst999 FOR UPDATE

SELECTDO

pctst999.dsca = "...."

....

db.update(tpctst999, DB.RETRY)

ENDSELECT

Table locks

BaanERP provides a table locking mechanism, which enables you to lock all the records in a specified table. A table lock prevents other processes from modifying or locking records in the table but not from reading them. This is useful when a particular transaction would otherwise require a large number of record locks. You use the db.lock.table() function to apply a table lock.

Application locks

An application lock prevents other applications and users from reading and/or modifying an application’s data during critical operations. It is not part of a transaction and so is not automatically removed when a transaction is committed. Instead, an application lock is removed when the application ends or when appl.detete() is called.

Related help topics

•	Database handling: overview

•	Transaction handling

•	Retry points

•	BAAN SQL

•	Error handling

•	Hints for using SQL

•	Hints for using db.retry.point()


Retry points

A retry point is a position in a program script to which the program returns if an error occurs within a transaction. The transaction is then retried.  There are a number of situations where retry points are useful:

•	During the time that a delayed lock is applied to a record/page, an error can occur that causes the system to execute an abort.transaction(). In such cases, all that BaanERP can do is inform the program that the transaction has been aborted. However, if retry points are used, the system can automatically retry the transaction without the user being aware of this.

•	Some database systems generate an abort.transaction() when a dirty record is read (that is, a record that has been changed but not yet committed). An abort.transaction() may also be generated when two or more processes simultaneously attempt to change, delete, or add the same record. In all these situations, BaanERP Tools can conceal the problem from the user by using retry points. It simply retries the transaction. If there is no retry point, the transaction is aborted and the session is terminated.

•	In BaanERP, updates are buffered, so the success or failure of an update is not known until commit.transaction() is called. If an update fails, the commit of the transaction also fails, and the entire transaction must be repeated. If retry points are used, the system automatically retries the transaction.

•	Retry points can also resolve potential deadlock problems. If, for example, the system is unable to lock a record, it rolls the transaction back and tries again.

It is vital that retry points are included in all update programs.

Coding retry points

The retry point for a transaction must be placed at the start of a transaction. The following example illustrates how you program retry points:

db.retry.point()	| set retry point

if db.retry.hit() then

......	| code to execute when the system

| goes back to retry point

else

......	| initialization of retry point

endif

The function db.retry.hit() returns 0 when the retry point is generated – that is, the first time the code is executed. It returns a value unequal to 0 when the system returns to the retry point through the database layer.

When the system goes back to a retry point, it clears the internal stack of functions, local variables, and so on that were called during the transaction. The program continues from where the retry point was generated. The value of global variables is NOT reset.

When a commit fails, the database automatically returns to its state at the start of the transaction; the program is set back to the last retry point. It is vital, therefore, that the retry point is situated at the start of the transaction. The db.retry.hit() call must follow the db.retry.point() call. Do not place it in the SQL loop itself as this makes the code very untransparent. When a retry point is placed within a transaction, the system produces a message and terminates the session.

Testing retry points

The following shell variables enable you to test the operation of retry points:

TEST_RETRY=X	This variable indicates how often the system must go back to a retry point at the moment of committing. This cannot be used when testing different sessions with retry points parallel.
MAX_RETRY=X	This variable indicates how often the system may return to a retry point as a result of an abort in an update action. Default: 10
Related help topics

•	Database handling: overview

•	Transaction handling

•	Locking

•	BAAN SQL

•	Error handling

•	Hints for using SQL

•	Hints for using db.retry.point()


Baan SQL

You use Baan SQL (Structured Query Language) to retrieve information from the database. With Baan SQL's SELECT statement, you can retrieve any selection of data from the database, regardless of the number of tables in which the data is stored. The system does search through all records sequentially. It bases its search on a number of conditions defined in the SELECT statement.

The SELECT statement does not modify the data in the database. It is used simply to query the data. Whereas only one user at a time can modify data, any number of users can query or select the data concurrently.

The SELECT statement works at the table level; the output is also a table consisting of 0, 1, or more records. If the query is very specific, the output may consist of only one record. The structure of a SELECT statement is directly derived from the table structure. It takes the following general form:

SELECT columns ...

FROM table(s) ...

WHERE each row fulfills the condition(s) ...

The following sections provide information on SQL syntax and using SQL:

•	SQL syntax

•	Using program variables

•	References

•	Company numbers

•	SQL and combined fields

•	SQL subqueries

•	SQL programming

•	SQL and delayed locks

•	SQL trace options


SQL syntax

The general structure of an SQL query is as follows:

SELECT <select list>

[ FROM <from list> ]

[ WHERE <where condition> ]

[ GROUP BY <group list>

[ HAVING <having condition> ] ]

[ ORDER BY <order by list> [ WITH RETRY [REPEAT LAST ROW] ]]

[ SET SPECIFICATION ]

For full details of any of the above clauses of the SELECT statement, simply click on the relevant clause.

Related help topics

•	BAAN SQL


SELECT <select list>

The SELECT clause specifies the table fields that must be represented in the output and the functions (if any) that must be executed on the selected fields. You can use the wildcard character [*] to specify all fields of all tables. You can specify all fields of a particular table by suffixing the table name by the wildcard character [*].

You can use the following functions in the SELECT clause:

•	 min(<field name>) – for the minimum value of the field

•	max(<field name>) – for the maximum value of the field

•	sum(<field name>) – for the sum of the values of the field

•	count(<field name>) – for the number of fields selected

•	count(*) – for the number of records selected

•	avg(<field name>) – for the average value of the field.

These functions consider all selected records as one group and are executed on that group. So they produce a single result – for example, the average value of a specified table field. You usually use these functions in combination with the GROUP BY clause. With this clause, you can group the results into a number of subsets. The function is then performed on each subset.

Related help topics

•	BAAN SQL


FROM <from list>

The FROM clause specifies the names of the tables from which fields must be selected. The names of fields specified in the SELECT clause include the table name. It is not necessary to include these tables in the FROM clause as well.

In the FROM clause, you can define aliases for table names. Aliases are necessary, for example, for double references and for references to the main table. You define an alias as follows:

<table name> <alias name>

Include the keyword FOR UPDATE after a table name to indicate that the table must be read with delayed lock. If you include FOR UPDATE after the keyword SELECT in the SELECT clause, this indicates that all tables must be read with delayed lock.

Related help topics

•	BAAN SQL


WHERE <where condition>

The WHERE clause specifies one or more conditions which the selected records must meet. It has the following format:

WHERE <operand1> <operator> <operand2> [<operand3>]

Operands

Operands 1 and 2 can consist of any of the following:

•	numeric constant (for example, 10, 3.1415927)

•	string constant (for example, "John", "mod")

•	combined constant (for example, { 10 , "xyz" })

•	table field, optionally followed by array indication

•	pseudo field – for example, for indexes (<table>._index1, see combined fields)

•	4GL variable or pseudo variable (see Using program variables)

•	numeric expression (in which the operators +, -, *, /, \ are possible)

•	string expression (in which the operator & and a substring are possible)

•	special field –  enum constants, date constants (using the function date.to.num(Y,M,D) and date.num())

Operand 2 can also consist of the following:

•	subqueries

•	set definition (as subquery or a list of constants)

Operators

The following operators are possible:

•	comparison operators

=, <, <=, >, >=, <>, !=
#>, #>=, #<, #<=  (for combined fields)

•	IN operator

Here, operand2 contains a set of values (or subquery). The system tests if the value of operand1 is present in operand2. This operator replaces a number of expressions separated by the OR operator. For example, both of the following statements define the same condition:

WHERE ttadv200.cpac = "tc" OR ttadv200.cpac = "tt"

WHERE ttadv200.cpac IN ( "tc", "tt" )

•	LIKE operator

The LIKE operator compares operand1 with operand2. Operand2 can contain wild cards. For example:

WHERE name LIKE "[Tt]riton.*"

In this example, "Triton2.1" and "triton" are legal values. In this case, operand2 is a regular expression. See the expr.compile() function for a list of the possible features that the expression can contain.

•	BETWEEN / INRANGE operator

These operators check whether operand1 falls within a specified range of values. Operand2 and operand3 specify the lower and upper values of the range. For example, both of the following statements define the same condition – that is, they define a range from "tc" through "ts":

WHERE ttadv200.cpac >= "tc" AND ttadv200.cpac <= "ts"

WHERE ttadv200.cpac INRANGE "tc" AND "ts"

The operators BETWEEN and INRANGE are identical, except when you use combined fields (see SQL and combined fields).

•	EXISTS operator

This operator tests whether certain records do or do not occur. It is used in conjunction with subqueries. The following example selects only those items on the order list with an order quantity greater than 100:

select tiitm001.item, tiitm001.dsca

from tiitm001

where exists

( select timps052.*

  	from timps052

where timps052.item = tiitm001.item and

timps052.qana > 100 )

•	REFERS TO operator

See References.

Related help topics

•	BAAN SQL


GROUP BY <group condition>

The GROUP BY groups the records of the output table, based on the fields specified in the clause. It combines similar records, producing a single result record for each group of records with the same values for each table field listed in the SELECT clause. All elements of the <group condition> must be specified in the <select list> of the SELECT clause.

The power of the GROUP BY clause is most apparent when it is used with the functions min, max, count, avg, and sum. In these cases, it produces summary values for each group. For example:

SELECT ttadv200.cpac, ttadv200.cmod, ttadv200.cses

FROM ttadv200

GROUP BY ttadv200.cpac, ttadv200.cmod, ttadv200.cses

| Sessions with the same session code and different VRCs are

| selected only once

SELECT ttadv200.cpac, ttadv200.cmod, ttadv200.cses, count(*)

FROM ttadv200

GROUP BY ttadv200.cpac, ttadv200.cmod, ttadv200.cses

| The program counts the sessions with the same

| names but different VRCs.

Related help topics

•	BAAN SQL


HAVING <having condition>

The HAVING clause sets conditions on groups defined by the GROUP BY clause (that is, HAVING does for groups what WHERE does for records). If you use a HAVING clause, you must specify a GROUP BY clause also. The elements in the <having condition> can be either elements from the <select list> in the SELECT clause or functions on fields from the <select list>. The <having condition> can contain arithmetical and string expressions. For example:

SELECT ttadv200.cpac, ttadv200.cmod, ttadv200.cses, count(*)

FROM ttadv200

GROUP BY ttadv200.cpac, ttadv200.cmod, ttadv200.cses

HAVING count(*) > 1

Related help topics

•	BAAN SQL


ORDER BY<order by condition>

The ORDER BY clause has the following syntax:

ORDER BY <order by condition> [ WITH RETRY [REPEAT LAST ROW] ]

This clause determines the order of the records in the output table. In the <order by condition>, you list one or more fields from the <select list> in the SELECT clause. The field listed first in the ORDER BY clause takes precedence. You can list the fields by name or you can specify an index to their position in the SELECT clause. For each field in the <order by condition>, you can indicate if the order is to be ascending (default) or descending – for example, ORDER BY 1 asc, 2 desc.

If retry points are included, you must use ORDER BY to ensure that the sequence after return to the retry point is identical to the one used the first time. After a jump to a retry point, it is important that the query continues at its position in the selected set at the time that the retry occurred. By using the WITH RETRY addition this is easy to realize. By performing a commit.transaction(), the values for the retry conditions are saved. In case of a jump to a retry point, the query continues, starting from the values saved during the commit.transaction(). In the case of WITH RETRY the new set starts after the saved values. In the case of WITH RETRY REPEAT LAST ROW, the set starts at the saved value; so the last record is read again. In the case of WITH RETRY REPEAT LAST ROW, enter a commit.transaction() in the SELECTEOS part of the select statement to prevent a new build-up of the query in some cases.

Example (embedded SQL)

SELECT	tisfc001.*

FROM	tisfc001 FOR UPDATE

WHERE	tisfc001.pdno < 100

ORDER BY	tisfc001.pdno WITH RETRY

SELECTDO

tisfc001.proc = tcyesno.yes

db.update(tisfc001, DB.RETRY)

commit.transaction()

ENDSELECT

| In this case we do not use REPEAT LAST ROW, because the

| moment retry takes place, the value present at the stage of

| commit.transaction() has certainly been saved.

Related help topics

•	BAAN SQL


Set specification

Baan SQL supports the following options in relation to sets:

•	Maximum set size.

With this option you can indicate the maximum number of records the query can produce. The syntax is:

SELECT .... [from][where] AS SET WITH <number> ROWS

•	Prepared set.

With this option, the entire set is retrieved before the first record is returned. The set is temporarily stored. This option is useful when a process simultaneously selects and maintains (or deletes or adds) records. In this case, changes must not be visible in the selected records. The prepared set option forces a consistent read. The syntax is as follows:

SELECT ... [from][where] AS PREPARED SET

•	Maximum set size and prepared set.

You can combine both options as follows:

SELECT ... [from][where] AS PREPARED SET WITH <number> ROWS

Related help topics

•	BAAN SQL


Using program variables

As a 4GL query is handled via the bshell, you can directly relate program variables to it. Linking program variables is required for both the SELECT clause and the WHERE clause.

SELECT clause

In the <select list> of the SELECT clause, program variables are used to indicate the elements in which the query results must be stored. You can do this by explicitly specifying a program variable. The general syntax is:

<select part>:<program variable>

For example:

SELECT ppmod123.field1:my_val1

Or you can directly use a program variable (a table or field name) from the calling program in the <select list>. For example:

SELECT ppmod123.field1

In the first example, the program places the result in the <program variable>. In the second example, the name in the query and the name of the program variable are identical.

FROM clause

You can also use program variables in the WHERE clause. When evaluating the query, the program loads the values of the program variables into the query and includes them in the evaluation. This link can be realized by incorporating a program variable in the query, preceded by a colon [:]. For example:

WHERE ppmod123.field1 = :myval1

Note

A table field can be a program variable as well as a query variable. Note that the following query:

select tccom010.*

where tccom010.cuno = tccom010.cuno

has a different result from:

select tccom010.*

where tccom010.cuno = :tccom010.cuno

The latter selects one record; the former selects all records from the table tccom010, as tccom010.cuno by definition equals tccom010.cuno for each row.

Related help topics

•	BAAN SQL


References

Retrieving references to a record

In the standard SQL interface, you can retrieve references to a record as follows:

| Suppose that tiitm001 has a reference to tccom010 (field 'cuno'),
| and to tccom011 (field 'suno')

table	ttiitm001

table	ttccom010

table	ttccom011

SELECT tiitm001.*, tccom010.*, tccom011.*

FROM tiitm001, tccom010, tccom011

WHERE tiitm001.cuno = tccom010.cuno AND

tiitm001.suno = tccom011.suno

Retrieving references using REFERS TO

To simplify the retrieval of references, you can specify references (using the keyword REFERS TO) in the WHERE clause. Apart from simplifying the query, this also optimizes query handling. As references always refer to a primary key, they can be found immediately. Moreover, the program fills a field with reference characters if it does not find a reference. The following implements the previous example by using REFERS TO:

table	ttiitm001

table	ttccom010

table	ttccom011

SELECT tiitm001.*, tccom010.*, tccom011.*

WHERE tiitm001.cuno REFERS TO tccom010 AND

tiitm001.suno REFERS TO tccom011

| OR

SELECT tiitm001.*, tccom010.*, tccom011.*

WHERE tiitm001 REFERS TO tccom010 AND

tiitm001 REFERS TO tccom011

REFERS TO syntax

A REFERS TO statement has the following form:

<from> REFERS TO <to> [PATH <path> [,<path>...]] [UNREF<mode>]

The following table explains the various parts of the statement:

<from>	The referring table field or table.
<to>	The table referred to.
<path>	The path via which reference is reached (always table fields). If PATH is specified, specifying a table field for <from> is mandatory. For example: WHERE table1.field REFERS TO table4.field PATH table2.field, table3.field
<mode>	A mode indicating system action if reference does not exist; possible values are: SKIP If a reference cannot be found, the record is skipped. CLEAR If a reference is empty or absent, the referring  record is filled with spaces or 0 (numeric). SETUNREF The value of an undefined reference is filled with  an 'undefined reference' sign, defined in the data  dictionary, or with 0 (numeric). CLEARUNREF The referred record is filled with spaces or 0  (zero) when reference fields are empty. When  the reference is undefined the referred record  is filled with an 'undefined reference' sign. Depending on the reference definition in the data dictionary, the default reference mode is: reference mode in DD UNREF mode mandatory SETUNREF mandatory unless empty CLEARUNREF not mandatory CLEAR
Example

SELECT	ttadv100.*

FROM	ttadv100, ttadv101

WHERE	ttadv101.cmod BETWEEN "aaa" and "azz"

AND	ttadv101 REFERS TO ttadv100 UNREF <UNREF_mode>

AND	ttadv100.cpac BETWEEN "  " and "zz"

The evaluation order of this query is as follows:

1	Find all rows / records in ttadv101 that match the BETWEEN "aaa" and "azz" condition.

2	Find all references from each row from step 1 in table ttadv100.

3	Find all rows selected in step 2 which match the BETWEEN "  " and "zz" condition

When some reference does not exist in ttadv100 (step 2 fails), because of the condition on the referenced table, the whole row is rejected.

Using aliases with REFERS TO

You can use aliases to refer from one table to another with two references. In the following example, there are two references from ttadv300 to ttaad110, via ttadv300.lanl and via ttadv300.clan. Both are searched for in the following construction:

string desc.clan(20), desc.lanl(20)

table  tttadv300

SELECT ttadv300.desi, ttadv300.cfrm, ttadv300.clan,

tclan.dsca:desc.clan, ttadv300.lanl, tlanl.dsca:desc.lanl

FROM	ttadv300, ttaad110 tlanl, ttaad110 tclan

WHERE	ttadv300.desi = :designer AND

ttadv300.clan REFERS TO tclan UNREF SETUNREF AND

ttadv300.lanl REFERS TO tlanl UNREF SETUNREF

Using program variables or constants with REFERS TO

You can also retrieve references by using a program variable or a constant. This avoids the program first reading the <from> table. In the following example tiitm001 has a reference to tccom010 (field 'cuno'), and a reference to tccom011 (field 'suno') and the value of tiitm001 is known:

Table	ttccom010

Table	ttccom011

SELECT tccom010.*, tccom011.*

FROM tccom010, tccom011

WHERE	:tiitm001.cuno = tccom010.cuno AND

:tiitm001.suno = tccom011.suno

In the following example, the REFERS TO clause is used to achieve the same result. If the program does not find the reference, it fills the field with reference characters.

Table	ttccom010

Table	ttccom011

SELECT tccom010.*, tccom011.*

WHERE	:tiitm001.cuno REFERS TO tccom010 AND

:tiitm001.suno REFERS TO tccom011

In this case the REFERS TO statement has the following from:

<from> REFERS TO <to> [UNREF <mode>]

The following table explains the various parts of the statement:

<from>	The referring program variable or constant. If a combined constant is used, all fields must be filled.
<to>	The table referred to (refers to primary key of the table). This can also be a field provided that a unique index to this field exists.
<mode>	A mode indicating system action if reference does not exist; possible values are: SKIP If a reference cannot be found, the record is skipped. CLEAR If a reference is empty or absent, the referring  record is filled with spaces or 0 (numeric). SETUNREF The value of an undefined reference is filled with  an 'undefined reference' sign, defined in the data  dictionary, or with 0 (numeric). CLEARUNREF The referred record is filled with spaces or 0  (zero) when reference fields are empty. When  the reference is undefined the referred record  is filled with an 'undefined reference' sign. As no dictionary default is available, SETUNREF has been defined as the default action.
Example

SELECT	tccom010.*

FROM	tccom010, tiitm001

WHERE	tiitm001.cuno = :tiitm001.cuno AND

tiitm001.cuno REFERS TO tccom010

This is equal to the following:

SELECT	tccom010.*

WHERE	:tiitm001.cuno REFERS TO tccom010

Restrictions to the use of the REFERS TO:

The following "refers to" expressions are illegal:

1. A "refers to" expression is not allowed in an OR branch.

   For example, the following query is not allowed:

select a.respemp, b.empno

from   dbtst160 a, dbtst120 b

where  a.respemp refers to b or a.respemp = 0

2. A table cannot be refered to by more than one table.

   For example, the following queries are not allowed:

   select a.respemp, a.projno, b.hiredate, c._index1

   from   dbtst160 a, dbtst120 b, dbtst180 c

   where  { a.respemp, a.projno, b.hiredate, b.hiredate } refers to c._index1

   select a.respemp, b.empno, c.empno

   from   dbtst160 a, dbtst180 b, dbtst120 c

   where  a.respemp refers to c

   and    b.empno refers to c

3. If a table is referred to with more than one key element  these key elements

   must all be columns of the same table or must all be constants.

   For example, the following query is not allowed:

   select a.hiredate, b._index1

   from   dbtst120 a, dbtst180 b

   where  { 10, 'OP2013', a.hiredate, a.hiredate } refers to b._index1

   select  * from dbtst120 a, dbtst100 b, dbtst100 c

   where a.workdept refers to c

   and '123' refers to c

4. A refers to expression is not allowed in an OR condition.

   select a.respemp, b.empno

   from   dbtst160 a, dbtst120 b

   where  a.respemp refers to b or a.respemp = 0

Related help topics

•	BAAN SQL


Company numbers

The company number used during execution of a BAAN 4GL query is the current company number. The current company number is:

•	the default company number ( defined in the session "Maintain User Data" )

•	a company number specified by the compnr.check() function

The <table._compnr field

The <table>._compnr field enables the use of different company numbers. This field specifies the actual company number of the table. When this field is undefined, the current company number is taken as the default. 'Undefined' is denoted by the value -1.

When a record is selected with 'select <table>.*', the field <table>._compnr in the record contains the company number of the table. When inserting a record in a table with a specific company number, you must fill <table>._compnr with the corresponding company number. The function db.insert() takes care of this and writes the record in the correct (physical) table. No special file pointers are necessary (for example, by using db.bind()).

Example

The record where the field ttadv100._compnr = 000 belongs to the

(physical) table ttadv100000

The record where the field ttadv100._compnr = 200 belongs to the

(physical) table ttadv100200

Using <table>._compnr in the WHERE clause

You can also use <table>._compnr in the WHERE clause of a Baan SQL statement. In this case it is used as a search condition. For example:

SELECT  ttadv100.*

FROM    ttadv100

WHERE   ttadv100._compnr = 200 AND ttadv100.cpac = 'tt'

This query lists all records from table ttadv100200 where ttadv100.cpac has the value 'tt'.

You can use <table>._compnr in the following ways:

•	<table>._compnr = <number> or <number> = <table>._compnr where <number> specifies an integer number. The value of <number> is taken as the company number. It must be a 3-digit number.

•	<table>._compnr = <string> where <string> specifies a list of company numbers, separated by commas [,]. This construction can be used to check a condition for a range of company numbers. The string can contain only digits and commas. (So, you specify company numbers 0 and 23 by <table>._compnr = "000,023"). For example:

SELECT ttadv100.*

WHERE ttadv100._compnr = "200,300" AND <condition>

This query results in a list of the records from the table ttadv100 (with company numbers 200 and 300) that match <condition>.

•	<table>._compnr IN <set specification> where <set specification> is a set of constants or a subquery.

Sets must not contain duplicate values. See IN operator.

Combining <table>._compnr conditions

•	A list of AND conditions can contain only one condition that includes <table>._compnr. So, the following construction is possible:

WHERE <table>._compnr = 100 AND <condition>

but the following is not possible:

WHERE <table>._compnr = 100 AND <table>._compnr = 200

•	In a list of OR conditions, each condition must have a condition on <table>._compnr, or none of them. So, the following construction is possible:

WHERE (<table>._compnr = 100 OR <table>._compnr = 200)

AND <condition>

but the following is not possible:

WHERE (<table>._compnr = 100 OR <other_field> = <value>)

AND <condition>

Related help topics

•	BAAN SQL


SQL and combined fields

Defining a query that can be handled efficiently by the query handler is a complex task. This is especially true if there are combined fields (which consist of a number of child fields), as each field must be specified separately.

Specifying a combined field

As the designer can usually judge best which index should be used for an optimum result, the following construction enables the designer to specify a combined field:

WHERE ppmod001.comb1 = {"adv", "099", "123"}

A child field can be an expression, a BAAN 4GL variable, or a pseudo variable. A comparison operator (=, >, >=, etc.) for a combined field applies to the combination of all child fields. For example:

| suppose the combined field ppmod001.comb1 consists of the
| fields ppmod001.modu, ppmod001.tblno and ppmod001.compno:

WHERE ppmod001.comb1 >= {"adv", "000", "100"}

| The above statement is equal to the following statement

WHERE	( ppmod001.modu > "adv" ) OR

( ppmod001.modu = "adv" AND ppmod001.tblno > "000" ) OR

( ppmod001.modu = "adv" AND ppmod001.tblno = "000" AND

ppmod001.compno >= "100" )

Comparison operators for combined fields

The comparison operators #>, #>=, #<, #<= for a combined field apply to each child field separately. For example:

WHERE	( ppmod001.comb1 #>= {"adv", "000", "100"} AND

ppmod001.comb1 #<= {"zzz", "999", "200"} )

This represents the following:

WHERE	ppmod001.modu >= "adv" AND ppmod001.modu <= "zzz" AND

ppmod001.tblno >= "000" AND ppmod001.tblno <= "999" AND

ppmod001.compno >= "100" AND ppmod001.compno <= "200"

If a child field of a combined field is not specified, the value of this field is free and is not included in the condition. For example:

WHERE	ppmod001.comb1 #>= {"adv", "000", "100"} AND

ppmod001.comb1 #<= {"zzz", "999"}

This represents the following:

WHERE	ppmod001.modu >= "adv" AND ppmod001.modu <= "zzz" AND

ppmod001.tblno >= "000" AND ppmod001.tblno <= "999" AND

ppmod001.compno >= "100"

As the field ppmod001.compno has no upper limit, all values greater than or equal to 100 are fetched.

Indexes as combined fields

You can specify an index as a combined field even if a combined field is not present in the data dictionary. The index name is table._indexY where:

table	is the name of the table or alias of a table
_index	is a prefix to indicate that an index field is involved (a condition for this syntax is that there are no field names having this format)
Y	is the sequence number of the index defined in the data dictionary
As a combined field is being used, the value must always be enclosed by '{' and '}'. For example:

WHERE tiitm001._index1 = { :item }

As with other combined fields, children of index fields for which no value is specified are not included in the condition. However, you can leave fields unspecified only at the end of the index, not in the middle.

An index's pseudo field cannot be used in the query preceded by ':'.

Meanings of upper and lower limits

In connection with combined fields, the combination of upper/lower limit can have two meanings (compare '>' and '#>').

•	Firstly, it can mean that each field of a record that meets the conditions lies between the boundaries specified. For example:

WHERE	( ppmod001.comb1 #>= {"adv", "000", "100"} AND

ppmod001.comb1 #<= {"zzz", "999", "200"} )

Here, {"adv", "050" "123"} meet the conditions, but the combination {"uvw", "123", "300"} does not, because of the last child field.

For this construction we define the INRANGE statement. With INRANGE, the preceding example becomes:

WHERE	ppmod001.comb1

INRANGE {"adv", "000", "100"} AND {"zzz", "999", "200"}

With INRANGE, the boundaries indicated apply to each separate field (usual in print sessions).

•	Secondly, it can mean that all records are selected for which the combined field (regarded as one single field) lies between the boundaries indicated. For example:

WHERE	( ppmod001.comb1 >= {"adv", "000", "100"} AND

ppmod001.comb1 <= {"zzz", "999", "200"} )

Here, {"uvw", "123", "300"} meets the condition as "uvw"&"123"&"300" lies between "adv"&"000"&"100" and "zzz"&"999"&"200" ('&' means concatenation).

For this purpose we use a BETWEEN statement. With BETWEEN, the preceding example becomes:

WHERE	ppmod001.comb1

BETWEEN {"adv", "000", "100"} AND {"zzz", "999", "200"}

With BETWEEN, the fields in the combined are regarded as one field; the boundaries apply to the combined field as a whole.

If the field consists of one single element, INRANGE and BETWEEN are equivalent.

Related help topics

•	BAAN SQL


SQL subqueries

Baan SQL permits the use of subqueries. These are SELECT statements in the WHERE clause of another SELECT statement.

Defining nested queries can be very difficult. It is best to define the subquery of the lowest level first and the main question last.

Example 1

Select those prices from the item file that are above average. When calculating the average, the system should not take prices less than or equal to zero into account.

SELECT	tiitm001.copr	| cost price

FROM	tiitm001

WHERE	tiitm001.copr >

( SELECT	avg(tiitm001.copr)

WHERE	tiitm001.copr > 0 )

ORDER BY tiitm001.copr

In this case, the subquery should only produce one result (here the average cost price). If the subquery produces more than one result, use the operators IN and EXISTS.

Example 2

Select the numbers and names of all suppliers who have yet to deliver.

SELECT	tccom020.suno, tccom020.nama

FROM	tccom020	| Suppliers

WHERE	EXISTS

( SELECT *

FROM   timps053	| Purchase orders

WHERE  timps053.suno = tccom020.suno )

SELECT	tccom020.suno, tccom020.nama

FROM	tccom020

WHERE	tccom020.suno IN

( SELECT   timps053.suno

FROM     timps053

GROUP BY timps053.suno )

Related help topics

•	BAAN SQL


SQL programming

There are two ways to use Baan SQL in a Baan 4GL program. You can embed it in the language (embedded SQL), or you can using Baan 4GL functions (dynamic SQL).

Related help topics

•	BAAN SQL


Embedded SQL

Syntax

The following loop structure enables the use of SQL as part of the language:

SELECT < set definition (= actual query, see syntax description) >

[ SELECTBIND ( number, var) ] ...

[ WHEREBIND (number, expression) ] ...

[ SELECTDO

< operation(s) on all selected records > ]

[ SELECTEOS

< operation(s) after last selected record > ]

[ SELECTEMPTY

< operation(s) if nothing has been selected > ]

[ SELECTERROR

< operation(s) in case of an error condition > ]

ENDSELECT

Description

Data is selected on the basis of the condition specified in the SELECT statement. The operations between SELECTDO and ENDSELECT are performed on each record from the selected set. The loop ends either when the program has handled the entire set or the program encounters a BREAK command.

In the case of an error, the program executes the SELECTERROR part. A CONTINUE statement in the SELECTERROR part causes the next record to be processed. If there is no SELECTERROR section, the program generates a BREAK as the default action. Note that errors are returned only if the shell variable ERROR.BYPASS = 1.

The SELECTEOS part is executed after the SELECTDO of the last selected record. The intention of the SELECTEOS part is that before the program encounters a 'break' from the loop you can give a commit.transaction(), while a commit.transaction() may cause a retry. If a commit.transaction(), given after the ENDSELECT part, causes a retry, then the whole query must be regenerated.

If the SELECTDO part is suppressed, the program encounters a 'break' from the loop after the first selected record. If the SELECTDO part is suppressed but the SELECTEOS part occurs, the program will select the whole set of records.

In order to bind pseudo variables, the functions SELECTBIND and WHEREBIND have been added. Pseudo variables have the form ':<number>'. A special bind function is then used to link a program variable to the pseudo variable. For example:

SELECT ppmod123.field1:5, ppmod123.field2:6

SELECTBIND(5, my_val1)

SELECTBIND(6, my_val2)

SELECTDO

....

ENDSELECT

This is equal to 'SELECT ppmod123.field1:my_val1', but using a bind function.

It is also possible to use a pseudo variable in the WHERE clause. The WHEREBIND function is then used to link a value to the pseudo variable. For example:

SELECT ....

WHERE ppmod123.field1 = :1

WHEREBIND(1, 10 + sqrt(a+b))

SELECTDO

....

ENDSELECT

Used BAAN 4GL variables (with ':') are 'bound' automatically.

Example

table   tppmod090

long    total, m_val

m_val = 25

SELECT ppmod090.fld1, count(*):1

FROM ppmod090, ppmod091	| this line is optional

WHERE ppmod090.fld2 = ppmod091.fld5 AND

ppmod091.fld3 > :m_val

GROUP BY ppmod090.fld1

ORDER BY 2

SELECTBIND(1,total)

SELECTDO

print_info(ppmod090.fld1, total)

SELECTERROR

message("Error %d occurred", db.error)

break

ENDSELECT

See Dynamic SQL for an example of the same query executed using dynamic SQL.

Related help topics

•	BAAN SQL


Dynamic SQL

Dynamic SQL enables a program to form an SQL statement during execution, so that the contents of the statement can be determined, for example, by user input.

Functions

To use Dynamic SQL, the following functions are available:

Functions	Description
sql.parse()	Query definition.
sql.set.rds.full()	This sets the size of the RDBMS buffer.
sql.select.bind() sql.where.bind()	These functions link program variables to the query's pseudo variable. In Dynamic SQL, all non-external program variables used in the query must be linked to a pseudo variable with these functions.
sql.exec()	This function initializes the query. It gives the variables their proper values.
sql.fetch()	This function executes the query. It reads one result on which operations can be performed. This function must be invoked for each separate record from the selected set.
sql.break()	Stops execution of the query. Any interim results are cleared.
sql.close()	Deletes (all) internal information belonging to this query.
See the Dynamic SQL functions for more information and a description of the syntax of these functions.

Sequence of actions

By using these functions a query, once defined, can be reused optimally. The sequence of the actions is then:

sql.parse, sql.bind, sql.exec, sql.fetch, sql.fetch, ..., sql.break

sql.bind, sql.exec, sql.fetch, sql.fetch, ..., sql.break

sql.close

In this way you can prevent expensive sql.parse() calls, while still working with new arguments.

This flow is automatically generated from an embedded SQL program by bic6.2. Usually, the programmer will therefore opt for embedded SQL, the more so, since it automatically binds 4GL variables.

Example

Table	tppmod090

Long	sql

Long	total, m_val

m_val = 25

if ( not sql ) then

sql = sql.parse(

"select ppmod090.fld1, count(*):1 " &

"from ppmod090, ppmod091 " &

"where ppmod090.fld2 = ppmod091.fld5 AND " &

"ppmod091.fld3 > :2 " &

"group by ppmod090.fld1 " &

"order by 2")

endif

sql.select.bind(sql, 1, total)

sql.where.bind(sql, 2, m_val)

sql.exec(sql)

while ( true )

on case ( sql.fetch(sql) )

case eendfile:

break

case 0:

print_info(ppmod090.fld1, total)

continue

default:	| error

message("Error %d occurred", db.error)

endcase

break

endwhile

sql.break(sql)

sql.close(sql)	| After sql.close, a new sql.parse must be

sql  = 0	| executed to give sql a correct value. If the

| last two lines are skipped, sql retains a

| correct value.

See Embedded SQL for an example of the same query executed using embedded SQL.

Related help topics

•	BAAN SQL


SQL and delayed locks

The purpose of delayed locking is to postpone the physical lock of a record as long as possible. The program places the physical lock immediately before updating. During updating, the value of the record at the moment of selection must be known, as this is compared to the value at the moment of updating. During comparison, the relationships between fields are taken into account.

For a record to be delayed-locked when selected, the keyword FOR UPDATE must be included in the SELECT statement. In SQL, 'normal' record locking is not possible.

When placing a delayed lock on a record, the program fills the field <table>._dlock with an identification number linked to the record. This field identifies the original record. This guarantees a fast search procedure. This field will be overwritten when changing the record buffer.

Updates in combination with SELECT FOR UPDATE are executed with the following functions:

db.insert(table, DB.RETRY [, eflag])

db.update(table, DB.RETRY [, eflag])

db.delete(table, DB.RETRY [, eflag])

The DB.RETRY flag indicates that we are dealing here with updates with SELECT FOR UPDATE and retry points. This flag ensures that the actual update action is postponed until the commit. The db.update() and db.delete() functions with the DB.RETRY flag can be invoked only in combination with SELECT FOR UPDATE. The use of db.insert() with the DB.RETRY flag, on the other hand, is not linked to the use of SELECT FOR UPDATE.

Related help topics

•	BAAN SQL


SQL trace options

It is possible to monitor whether the SQL compiler and optimizer are taking the right decisions. If the results indicate that the design is incorrect, the query must be changed. The optimizer can never emulate the programmer. The Baan programming language therefore enables the programmer to instruct the computer what it has to do to a considerable degree of detail. You can define which index to use; also, a number of special (non-standard SQL) functions have been built in.

You can use the environment variable TT_SQL_TRACE to trace what happens inside the SQL processor. TT_SQL_TRACE is used to trace SQL processing in the client (that is, bshell6.2), as well as in the server process (that is, bisam_srv6.2). The methods involved are different for client and server.

Client tracing

When TT_SQL_TRACE is set, the output from the client process is written to stderr. To keep this information, you must call the bshell with the options "-keeplog" and "-logfile <log file name>". For example:

bx6.1 -- -keeplog -logfile mylogfile -set TT_SQL_TRACE=02000

This enables TT_SQL_TRACE with value 02000. The output is written to the file "mylogfile" in the current working directory.

Server tracing

When TT_SQL_TRACE is set, the output is written to a file named "dbs.log". This file is located in the current working directory when the Database Server runs locally (on same host as Display Server). When the database is remote, it is written in the login directory of the corresponding user on that remote system. To enable logging of TT_SQL_TRACE in the file "dbs.log", you must also set the environment variable DBSLOG, as follows:

DBSLOG=02000

The "02000" is an octal value, and can be OR-ed with other variables. The meaning of the other values is described in a separate document (Logging Database Information (DBSLOG)).

Query identification

A QueryIdentifier (QID) identifies each query. This makes it easy to find out which output in the Client log file is related to the output of the Server log file.

Trace options

The following values for TT_SQL_TRACE are available (C indicates that an option can be used for the client; S indicates that it can be used for the server):

1. TT_SQL_TRACE=040 (C)   	  	Show queries with their QID

2. TT_SQL_TRACE=02000 (C)	Show calls of internal SQL functions.

3. TT_SQL_TRACE=0200 (C)	Show query execution times

4. TT_SQL_TRACE=04000 (C+S)	Show query evaluation plan.

5. TT_SQL_TRACE=020000 (S)	Show FullTableScan

6. TT_SQL_TRACE=010000 (S)	Show Query Evaluation Plan

You can combine trace options by assigning several different flags to TT_SQL_TRACE at the same time. For example:

TT_SQL_TRACE=010200 export TT_SQL_TRACE

bshell6.2 2>sql.dbg

In sql.dbg, this produces the results of both options 010000 and 0200.

TT_SQL_TRACE=040

Shows all queries (query text) which are evaluated. For example:

Evaluated Query (QID : 4)

select  	ttadv450.vers, ttadv450.rele, ttadv450.cust, ttadv450.expi,

ttadv450.mess

where ttadv450._index1 = {:clan, :1, :2}

TT_SQL_TRACE=02000

Shows calls of internal SQL functions, including their arguments. For example:

[SqlParse: before parse] SqlId : 200db008 - QID : 4 - Status : 0

Trans 1 Mode 0 Query:

select  ttadv450.vers, ttadv450.rele, ttadv450.cust, ttadv450.expi,

ttadv450.mess

where ttadv450._index1 = {:clan, :1, :2}

[SqlParse: after parse (e = 0)]

SqlId : 200db008 - QID : 4 - Status : 2

[SqlWhereBind for clan] SqlId : 200db008 - QID : 4 - Status : 2

Value(str): '2'

[SqlWhereBind for 1] SqlId : 200db008 - QID : 4 - Status : 2

Value(str): 'tt'

[SqlWhereBind for 2] SqlId : 200db008 - QID : 4 - Status : 2

Value(str): 'gfdmnucal   '

[SqlExec (CompNr 000)] SqlId : 200db008 - QID : 4 - Status : 2

[SqlFetch] SqlId : 200db008 - QID : 4 - Status : 3

[SqlFetch returns 0 errno 0 msg ]

SqlId : 200db008 - QID : 4 - Status : 4

'6.1 ' 'b ' '    ' 2 'Calendar

'

[SqlBreak] SqlId : 200db008 - QID : 4 - Status : 4

Warning: The line following the message "SqlFetch returns .." shows the result of the fetch. The order of the fields is not always the order as mentioned in the SELECT clause.

TT_SQL_TRACE=0200

Shows query execution times. For example:

================================================

Fetch times of Query (QID : 12) in SqlBreak :

select  ttdsk360.*

where

(ttdsk360.user = :logname$ or ttdsk360.user = :1)

order by ttdsk360.user desc, ttdsk360.cpac desc,

ttdsk360.rsst desc, ttdsk360.rsid desc

------------------------------------------------

Nr Rows Fetched    	  	  	  	  	:	39

Fetch Time for 1st Row	:	0.060 sec

Max Fetch Time	:	0.060 sec

Average Fetch Time	:	0.000 sec

Average Fetch Time (except Max)	:	0.000 sec

================================================

A value 0.000 means that the time to fetch was too small to be measured. This can happen when the result is already available in the client. In that case, fetching is (globally seen) only copying from one memory location to another.

TT_SQL_TRACE=04000

Show the query evaluation tree. There is different output for client and server. The client shows how the query is distributed over different databases (normally there is one database). The server shows how the query is evaluated. This can be different for different databases. The example shows the evaluation in a non-SQL database driver. In the examples, the same query is used as in the example of TT_SQL_TRACE=040.

Client Side:

Expression Tree (QID : 4):

[11] flag 011 cost 0 next_eval 12 next 12

cost 0 0 nr 0

Operand1:

Database View Id 0 - Drivers:

Database View - Tables:

ttadv450 (dd: ttadv450) flag 1000 cost 0

Database View - Expression:

[10] flag 031 cost 0 next_eval -1 next -1

cost 0 0 nr 0

Operand1: CombColumn: ttadv450._index1

Combined {

(1) ttadv450.clan

(2) ttadv450.cpac

(3) ttadv450.cmes

(4) ttadv450.vers

(5) ttadv450.rele

(6) ttadv450.cust

}

Operator: =

Operand2:                Combined {

(1) Host var: 'clan' = '2'

(2) Host var: '1' = 'tt'

(3) Host var: '2' = 'gfdmnucal   '

}

Database View - Host Variables:

Host var: 'clan' = '2'

Host var: '1' = 'tt'

Host var: '2' = 'gfdmnucal   '

Database View - Output Columns:

ttadv450.vers

ttadv450.rele

ttadv450.cust

ttadv450.expi

ttadv450.mess

Database View - RDS Out:

Dump Info on RDS:   MalId 15 - Size 143 164 - Flag 2

[ 1] type   6 dept   1 size   4 offset   0

[ 2] type   6 dept   1 size   2 offset   4

[ 3] type   6 dept   1 size   4 offset   6

[ 4] type   1 dept   1 size   1 offset  10

[ 5] type   7 dept   1 size 132 offset  11

Operator: DBView

Operand2:  --

AND (011)

[12] flag 011 cost 0 next_eval -1 next -1

[1] End of Query

-End of Tree --

Server:

Generated Query Execution Tree:

Sql id 6 company 000 sid 1 flag 1 (QID : 4)

Output Columns (total 5)

[ 0] vers idx  0 type  6 size  4 depth  1

[ 1] rele idx  1 type  6 size  2 depth  1

[ 2] cust idx  2 type  6 size  4 depth  1

[ 3] expi idx  3 type  1 size  1 depth  1

[ 4] mess idx  4 type  7 size 132 depth  1

Rds Out:

Dump Info on RDS:   MalId 6 - Size 143 164 - Flag 2

[ 1] type   6 dept   1 size   4 offset   0

[ 2] type   6 dept   1 size   2 offset   4

[ 3] type   6 dept   1 size   4 offset   6

[ 4] type   1 dept   1 size   1 offset  10

[ 5] type   7 dept   1 size 132 offset  11

All tables

ttadv450 flag 12

Query 200a207c flag 00

Tables

ttadv450 (a) dep 1 flag 012

ttadv450(a).cmes

ttadv450(a).cpac

ttadv450(a).clan

ttadv450(a).mess

ttadv450(a).expi

ttadv450(a).cust

ttadv450(a).rele

ttadv450(a).vers

Output Columns (total 5)

ttadv450.vers idx  0 type  6 size  4 depth  1

ttadv450.rele idx  1 type  6 size  2 depth  1

ttadv450.cust idx  2 type  6 size  4 depth  1

ttadv450.expi idx  3 type  1 size  1 depth  1

ttadv450.mess idx  4 type  7 size 132 depth  1

View bind

vers : type 6 size 4 flag 9

rele : type 6 size 2 flag 9

cust : type 6 size 4 flag 9

expi : type 1 size 1 flag 9

mess : type 6 size 132 flag 9

View expression

[15] flag 011 cost 0 next_eval 17 next 17

Table View on 'ttadv450'

Expression:

[14] flag 011 cost 3 next_eval 16 next 16

SrchOper for ttadv450 compnr 000 index 1 (mode 0)

Field clan:

Equal: [=] Bind (Col clan) Value: '2'

Field cpac:

Equal: [=] Bind (Col cpac) Value: 'tt'

Field cmes:

Equal: [=] Bind (Col cmes) Value: 'gfdmnucal   '

Field vers:

Field rele:

Field cust:

AND (011)

[16] flag 011 cost 0 next_eval -1 next -1

cost 0 0 nr 0

Operand1:

Operator: QpsPermOper

Operand2: '-1'

AND (011)

[17] flag 011 cost 0 next_eval -1 next -1

[1] End of Query

There are a lot of numbers/state values in this tree. Most of them are for internal use only.

TT_SQL_TRACE=020000

Shows all tables for which FullTableScan is performed. This can depend on which database is used. For example:

FullTableScan for table ttdsk355 (QID : 2)

The QID refers to the query. This can be found in the client trace file.

TT_SQL_TRACE=010000

Shows Query Evaluation Plan (QEP). This also depends on which database is used. For example:

Query Evaluation Plan (QID : 30)

------------------------------------------------

Table tccom000 (alias: a): IndexSearch with condition(s):

SrchOper for tccom000 compnr 000 index 1 (mode 0)

Field ncmp:

Equal: [=] Bind (Col ncmp) Value: '812'

Forced Order: Ascending (index 1)

Table tcmcs046 (alias: b): IndexSearch with condition(s):

SrchOper for tcmcs046 compnr 000 index 1 (mode 6)

Field clan:

Equal: [REF (clear)] Index Col key 1 mode 5 equal 0

tccom000(a).clan

Table tcmcs002 (alias: c): IndexSearch with condition(s):

SrchOper for tcmcs002 compnr 000 index 1 (mode 6)

Field ccur:

Equal: [REF (clear)] Index Col key 1 mode 5 equal 0

tccom000(a).ccur

================================================

The query which belongs to this QEP is shown in the client log file (TT_SQL_TRACE=040) as follows:

Evaluated Query (QID : 30)

Select	tccom000.*, tcmcs002.*, tcmcs046.*

From	tccom000, tcmcs002, tcmcs046

Where	tccom000.ncmp = :company.nr

And	tccom000.ccur refers to tcmcs002 unref clear

And	tccom000.clan refers to tcmcs046 unref clear

order by tccom000.ncmp

From the QEP, the following information can be retrieved:

1	There are three tables: tccom000 (alias: a), tcmcs046 (alias: b), tcmcs002 (alias: c). The alias name is used in case of SQL databases. This alias name is only one or two characters in order to keep the SQL statement for the SQL database as short as possible.

2	The order of evaluation of the tables is from top-to-bottom in the QEP, so first tccom000, then tcmcs046, then tcmcs002.

3	Searching in tccom000 is done on the primary index (index 1). The field 'ncmp' has value '812' and has been specified by some '=' operation. In the query above, this comes from the line containing
"where  tccom000.ncmp = :company.nr".

4	The query has an ORDER BY part. The ORDER BY can be eliminated by reading tccom000 on index 1, in ascending order. This is denoted by: "Forced Order: Ascending (index 1)".

5	Next table to be read is tcmcs046. Here also index 1 is used for reading. The key is specified by some "unref clear" operation. The field 'clan' is filled to search in the table. This field specifies the whole primary key (index 1).

6	Last evaluated table is tcmcs002, in the same way as tcmcs046. Here, the field 'ccur' is used.

Related help topics

•	BAAN SQL


Error handling

There are two broad categories of errors. Errors generated by the operating system (numbers 1 - 99) and errors generated by the database system (numbers 100 - 900). See Errors.

To keep the messages to be sent over the network to a minimum, database actions and messages must be buffered as much as possible. Buffering updates means that as few updates as possible return error codes. These, after all, cause a rollback and a return to a retry point. It is therefore possible to allocate flags to updates indicating the action to be taken by the system when a database action fails. The database server will then no longer execute a rollback, but a follow-up action.

Fatal and non-fatal errors

There are fatal and non-fatal errors. Fatal errors terminate the session. Non-fatal errors are those that are temporary (for example, elocked), or that are caused by a multi-user situation (for example, a record is deleted by two processes, one process receiving enorec). Non-fatal errors cause the program to go back to the last retry point. If this is missing, the session is terminated. Fatal errors are errors caused by:

•	Errors in the (logical) database (for example, enotable, eddcorrupt, enoserver)

•	Errors in the underlying (R)DBMS (for example, ebadkey)

•	Program errors (for example, enotinrange)

The following error codes result in a return to the retry point:

elocked	(107)	record is locked

eflocked	(113)	file (table) is locked

emlocked	(210)	record in mirroring is locked

ereflocked	(601)	reference record is locked

edupl	(100)	duplicate record

enorec	(111)	record not present

erowchanged	(201)	record modified since last read

eabort	(850)	rollback in (R)DBMS

The eflag

For a number of errors it is possible to indicate which action the system must carry out when the error occurs. You can add these to a database action with the <eflag>. For example:

db.insert(table, DB.RETRY [, eflag])

db.update(table, DB.RETRY [, eflag])

db.delete(table, DB.RETRY [, eflag])

The following flags are available for eflag:

db.exit.on.norec	stop session if no record was found
db.skip.norec	skip update/delete action if no record was found
db.exit.on.dupl	stop session if duplicates occur
db.skip.dupl	skip update/insert action if duplicates occur
db.exit.on.rowchanged	stop session if record has been changed after delayed lock
db.skip.rowchanged	skip action if record has been changed after delayed lock
db.return.error *	return error code
db.return.norec *	return error code if no record was  found
db.return.dupl *	return error code if duplicates occur
db.return.ref.exists *	return error code if reference exists
db.return.ref.not.exists *	return error code if reference does not exist
db.return.rowchanged *	return error code if record has been changed after delayed lock
* These flags store the contents of the buffer to the database if an error occurs. The program does not return to the retry point.

Note that you can combine flags by using the '+' sign.

Example

table   ttiitm001

db.retry.point()

SELECT tiitm001.*

FROM tiitm001 FOR UPDATE

WHERE tiitm001.item between :item.f and :item.t

SELECTDO

......

db.insert(ttiitm001, DB.RETRY, db.skip.dupl)

ENDSELECT

In this case, the flag 'db.skip.dupl' causes the system neither to go back to the retry point nor return an error code when adding an already existing record.

Related help topics

•	Database handling: overview


Hints using SQL
Hints for using SQL

1	In the WHERE clause:

- use as few conditions as possible:

- use as many conditions with indexes as possible

- use as many conditions with combined fields as possible

- use BETWEEN/INRANGE when an upper and lower boundary are specified for a field.

2	Use REFERS TO if references have been defined in the data dictionary.

3	Use as few overlapping OR conditions as possible. For the following:

cpac&cmod >= 'ttadv' (only if there is no index to cpac&cmod)

do not use the following construction:

WHERE ttadv200.cpac > 'tt' OR

ttadv200.cpac >= 'tt' AND ttadv200.cmod >= 'adv'

instead use the following construction:

WHERE ttadv200.cpac > 'tt' OR

ttadv200.cpac = 'tt' AND ttadv200.cmod >= 'adv'

Use BETWEEN or INRANGE if there is an index to cpac&cmod. For example:

WHERE ttadv200._index1 BETWEEN {'tt', 'adv'} and { }

4	Only select fields of tables necessary in the flow of the program.

5	It is not necessary to bind external variables and database fields used in the query as substitution variables. In embedded SQL local variables are bound automatically.

6	The program executes the query the first time the function sql.fetch() is called. If reading in the entire set is unnecessary (so no order by, group by, and so on), the program only physically retrieves records at each sql.fetch(). This avoids an entire set being retrieved when only part of it is used. When the set is no longer necessary call sql.break() to clear the remaining records.

7	Use ORDER BY to ensure that the records are retrieved in the correct sequence. If an index can be used for the ORDER BY, no sort action will take place beforehand.

8	The program will execute a Full Table Scan (FTS) if the operators NOT INRANGE, IN, LIKE are used or if no index (or part of an index) is used. This means that the system checks beforehand whether all records in the table meet the conditions of the query. This precludes optimization. If only the first part of an index (combined or normal field) is used, the system uses that index to search the table.

When GROUP BY is used, the system first determines the entire set (prepared set), before producing the first record. The same thing happens if the operator is preceded by an expression –for example, WHERE <table.field1> & <table.field2> = "...........". Note that the various subexpressions separated by AND or OR cannot be combined for optimization.

9	It is possible to have the program carry out commits at certain points in the select loop. If retry points are included, use of ORDER BY is required to ensure that the sequence after return to the retry point is identical to the one used the first time. See also the practical examples.

10	If a transaction adds or processes records, it depends on the database if the same transaction can also process new records without a select being carried out again. To ensure that new records are processed in any case, a commit and a new select are required. To ensure that new records are not processed, define the set at the point of the select (prepared set).

11	When using transactions, the first priority should be that the actions within the transaction constitute a logical unit. For reasons of performance, update, insert, and delete actions can be combined up to a number of 256 (this is an average, not a limit) per transaction. For example, programs processing orders should execute one commit.transaction() for each order.

12	It may be necessary to know how far the program had advanced before it moved back to the retry point. If the key consists of more than one field, it is probably possible to have the program execute a commit.transaction() when a particular key field changes. If a key consists of order number and order line, for instance, a commit by order number would be preferable to a commit by order line. Care should be taken in programs that print and process data in one run. An abort transaction restores the database but not the output to the printer. In such cases a commit must be executed for each print line to prevent lines being printed twice.

For example:

save.orno = start

select for update order line.orno order line.pono

from order line

where order line.orno >= :save.orno

selectdo

if ( save.orno <> order line.orno ) then

commit.transaction()

save.orno = order line.orno

endif

update actions()

         endselect

         commit.transaction()

13	A DB.RETRY.POINT() must be included in each update program.

Related help topics

•	Database handling: overview


Hints for using db.retry.point

For programs of type 1, 2 or 3, this is generally the retry.point of the standard program which has a retry just after 'before choice' of update.db and in the read section where also the references are read.

To have clearly structured sources, never use more than one level db.retry.point(). Only one above the first level of select. Use retry in the following situations:

Situation for Select	Commit per fetch	Commit over multiple fetch
db.update/db.insert/db.delete	1	2
Collecting	3	3
Combination	4	5
A skip back to a retry point can be indicated by a problem in:

•	db.update(), db.delete() or db.insert() with argument db.retry

•	commit.transaction()

Situation 1: Only update actions, commit per fetch

The function 'with retry' can be used here. For example:

db.retry.point()

select  tisfc001.*

from    tisfc001 for update

where   tisfc001.pdno inrange :pdno.f and :pdno.t

order by tisfc001._index1 with retry

selectdo

tisfc001.proc = tcyesno.yes

db.update(ttisfc001,db.retry)

commit.transaction()

endselect

In this case REPEAT LAST ROW is not used, because when retry is done, the value which was present at the stage of commit.transaction() has certainly been saved.

Situation 2: Only update actions, commits over fetches

In this case we can also use the 'with retry' option. For example:(commit per order and not per fetch !):

save.pdno = 0

db.retry.point()

select  ticst001.*

from    ticst001 for update

where   ticst001.pdno inrange :pdno.f and :pdno.t

order by ticst001._index1 with retry repeat last row

selectdo

if ticst001.pdno <> save.pdno then

if save.pdno <> 0 then

commit.transaction()

endif

save.pdno = ticst001.pdno

endif

ticst001.proc = tcyesno.yes

db.update(ticst001,db.retry)

selecteos

commit.transaction()

endselect

Both db.update() and commit.transaction() can result in a retry. So selecteos is used. Notice that REPEAT LAST ROW is used because the present value at the time of doing the save is already the value of the next order.

Situation 3: only print / collect actions (no commit)

There is no transaction or dependency between records / fetches. For example:

total.quant = 0

select	ticst001.*

from	ticst001

where	ticst001.pdno inrange :pdno.f and :pdno.t

order by ticst001._index1

selectdo

total.quant = total.quant + ticst001.quan

print.row(1)

endselect

Situation 4: Update actions plus print/collect with commit per fetch

For example, update of print status plus print and collect:

total.quant = 0

db.retry.point()

select  ticst001.*

from    ticst001 for update

where   ticst001.pdno inrange :pdno.f and :pdno.t

order by ticst001._index1 with retry

selectdo

ticst001.proc = tcyesno.yes

db.update(ticst001,db.retry)

commit.transaction()

total.quant = total.quant + ticst001.quan

print.row()

endselect

Notice that this works only when the db.update() and commit.transaction() are done before the print and the collect statement. An alternative to this solution is described in situation 5.

Situation 5: Update actions plus print/collect with commit over fetches

For example, update of print status plus print and collect per order:

save.pdno = 0

save.pono = 0

total.select.quan = 0

db.retry.point()

total.order.quan = 0

select  ticst001.*

from    ticst001 for update

where   ticst001.pdno inrange :pdno.f and :pdno.t

order by ticst001._index1 with retry repeat last row

selectdo

if ticst001.pdno <> save.pdno then

if save.pdno <> 0 then

total.order.quan = 0

commit.transaction()

endif

save.pdno = ticst001.pdno

endif

if ticst001.pdno > lsp.pdno or

(ticst001.pdno = lsp.pdno and

ticst001.pono > lsp.pono ) then

print.row()

total.select.quan = total.select.quan + ticst001.quan

lsp.pdno = ticst001.pdno

lsp.pono = ticst001.pono

endif

total.order.quan = total.order.quan + ticst001.quan

ticst001.proc = tcyesno.yes

db.update(ticst001,db.retry)

selecteos

commit.transaction()

endselect

lsp stands for last processed. pdno and pono are together the index of cst001. The 'lsp.' variables should always be used for this kind of saving within selects. These variables save which record has already been printed/collected. The total.order.quan can always be added because setting to zero is done for each retry again.

Related help topics

•	Database handling: overview


Table


Index


Data Access Layer: overview
Data Access Layer

Overview

In BAAN applications, the standard program (STP) provides much of the default functionality for a session. In previous versions of the software, changes or additions to the default functionality for a session were programmed in a single script that was associated with the session. Both user interface actions and database actions were programmed in this script.

In BaanERP, user interface actions and database actions have been separated. The Data Access Layer (DAL) now handles database interaction. Programmers create a user interface (UI) script to change the default behavior of a session. They create a DAL script to program all the logical integrity rules for a particular table. So the DAL ensures the logical integrity of the database. As in previous versions of the software, the database server ensures the referential integrity of the database.

The DAL script for a particular table has the same name as that table. It is implemented as a DLL that can be accessed by user interface scripts (via the standard program), by other DALs, and by external programs (via the Common Data Access Server (CDAS). The following diagram illustrates the overall relationship of these components.

Database integrity checks

The following are examples of some logical integrity rules that could be programmed in a DAL script:

•	When customers have reached their credit limit, they cannot order further items.

•	If the invoice for an order has been printed, the order cannot be changed.

•	If the current VRC of a user is not equal to the package VRC of the program script, the script cannot be compiled.

Programming database integrity checks in a separate DAL script has two main advantages:

•	Code reuse: The integrity rules do not have to be replicated in each session that uses a particular table.

•	External access: External applications can access the database via the CDAS and the DAL.

For an overview of the interaction between the user interface, the standard program, and the DAL, see DAL, UI, and STP interaction.

Business methods

In addition to performing data integrity checks, the DAL provides business methods for handling non-interactive database modifications such as printing sales orders or posting all orders to history.

A business method is a function that performs a task that involves manipulating and/or checking one or more tables in the database. The function is programmed in a DAL script and can be called directly from a UI script. It must be programmed in the DAL script of the most relevant table.

Users can activate a business method with a single command. There is then no further user interaction. The UI script calls the relevant function in the DAL script. The function performs all operations to complete the required task. The user must wait until the business method finishes before continuing with other tasks. However, if a progress window is provided, the user can cancel the business method by clicking on the Cancel button.

The UI script starts a business method by calling the dal.start.business.method() function.

Related topics

•	DAL terminology

•	DAL, UI, and STP interaction

•	DAL hooks

•	Data Access Methods (DAM)

•	Property methods

•	Query extensions

•	Communication with STP and CDAS

•	Transition issues (BAAN IV to BaanERP)


DAL terminology

Class	A description of a group of objects with similar properties, common behavior, common relationships, and common semantics. A DAL class corresponds to a BAAN table definition.
Object	An instance of a class. It consists of data and the methods (code) to manipulate the data. The data of a DAL object corresponds to a record in a BAAN table.
Object set	All objects of a class, as stored in the database. A DAL object set corresponds to a BAAN table.
Property	An attribute of an object. A DAL property corresponds to a field in a record in a BAAN table.
Method	The implementation of an operation for a particular class. It provides a means of retrieving and manipulating data (properties) in objects. Method is another name for an operation or function.
Hook	A logic integrity rule. Hooks are implemented in the DAL as functions.
Related topics

•	Data Access Layer: overview


DAL, UI, and STP interaction
UI, DAL, and STP interaction

Overview

A DAL script contains all the logic integrity rules for a particular object set. These rules are referred to as hooks and they can be programmed for every possible manipulation of an object in the object set. For each session with a main table, the standard program ensures that the integrity rules for the table are checked each time an update, delete, insert, or read operation is performed on an object of the table.

If there is no DAL script for the particular object set being accessed, no logic integrity checks are performed (unless they are programmed in the UI script itself).

A DAL script can contain hooks that prevent access to the database and hooks that prevent data being passed back to the user interface. The former are executed before the database action. The latter are performed after the database action.

Example

If a user changes the address of a customer on a form, the standard program changes the address for that customer in the database via the DAL. If you want certain restrictions to apply to the update action, you can program a property hook in the DAL of the session’s main table to impose these restrictions. For example:

when the address changes:

if changed into something valid then

accept
else

reject

endif

UI function calls

The UI script can use either the db.* functions or the DAL Data Access Methods (DAM) to manipulate the database. The db.* functions are direct database calls. They do not use the DAL. In this case, any logic integrity checks required must be programmed in the UI script itself. This means that they cannot be reused by other sessions. In preference, use the DAL Data Access Methods. These access the database via the DAL, so all necessary checks are automatically performed.

Function flow

When the DAL is used to manipulate the database, the main steps involved are as follows:

1	The user issues a command through the user interface to access a record in the database.

2	The standard program loads the appropriate DAL and calls the hooks in the DAL to check the integrity rules for the object.

3	If the particular database action is permitted, the standard program issues the appropriate database call.

4	After the database has been updated, the DAL can perform further checks to determine whether or not data is passed back to the user interface.

5	The standard program passes data back to the user interface (provided that the integrity rules permit this).

The following diagram illustrates this flow:

One-way interaction

Note that because the DAL can be used in situations where there is no user interface, the DAL cannot call functions in the UI.

Related topics

•	Data Access Layer: overview

•	DAL terminology

•	DAL hooks

•	Data Access Methods (DAM)

•	Property methods

•	Query extensions

•	Communication with STP and CDAS

•	Transition issues (BAAN IV to BaanERP)


DAL hooks

A hook is a function, with a predefined name, that the DAL programmer programs in a DAL script. The function is used to program logic integrity rules for database access. The DAL script is compiled into a DLL.

When a user issues a command to access the database, the standard program loads the DAL DLL for the object being accessed and calls the hooks to perform the integrity checks. Provided that a DAL script exists for an object set being accessed, the standard program always ensures that the hooks in the DAL are called at the appropriate times.

A DAL script can contain two types of hooks:

•	property hooks

•	object hooks

Related topics

•	Data Access Layer: overview

•	DAL terminology


Property hooks

Property hooks are hooks that relate to a specific property (that is, a table field).

Property hooks replace the check.input event sections for fields of the main table. If there is a DAL for an object set, the property hooks are called to perform the necessary field checks. Any check.input sections in the UI script are ignored. So, if a UI script contains check.input sections for fields of the main table, you must replace these by property hooks in the DAL. In the UI script, check.input sections are retained for non-database form fields. Such sections are executed even if a DAL exists.

There are two property hooks:

•	Property hook fieldname.check() is called by the standard program when inserting or updating an object

•	Property hook fieldname.set.defaults() is called by the B3 through a BOI in case of a DAL_NEW or DAL_UPDATE

fieldname.check()

Syntax

function extern long ppmmmvss.bbbb.check( long has_changed [, long element] )

Description

Use this hook to program logical integrity rules for a specified field. The function name is ppmmmvss.bbbb.check(), where pp is the package code, mmm is the module code, vss is the table number, and bbbb is the field name.

Arguments

has_changed	This indicates whether the value of the field has changed. It is set by the standard program and can be tested in the hook. Possible values are: 0 not changed DAL_NEW change caused by inserting a new object DAL_UPDATE change caused by updating an existing object
element	This is set for array fields only. It indicates the index of the array element that must be checked.
Return values

This hook returns 0 if the value of the field is accepted. It returns a negative value (DALHOOKERROR) if the value is not accepted.

Example

A property hook programmed in DLL tdsls040:

function extern long tdsls040.oqua.check(long has_changed)

{

if tdsls040.stat = tdsls.stat.invoiced and

   	has_changed then

dal.set.error.message("tdsls44041")

| Order is already invoiced, cannot change

| quantity

return(DALHOOKERROR)

endif

...

return(0)

}

fieldname.set.defaults()

Syntax

function extern long ppmmmvss.bbbb.set.defaults(long	has_changed)

Description

Use this hook to set defaults based on a specified field. The function name is ppmmmvss.bbbb.check(), where pp is the package code, mmm is the module code, vss is the table number, and bbbb is the field name.

If this hook exists, it is executed only by B3 through a BOI in case of DAL_NEW or DAL_UPDATE.

A record will be created or modified in a specific order. This order should be defined in the table definition in the section default sequence.

default mandatory	Possible values are: • Always this field should be passed by the BOI (insert) • Conditionally this field can be set by defaults; otherwise mandatory • Not this field is not really required; but can be passed
sequence	This indicates the number in the sequence. The lowest number will be executed first (0 does not count). First the sequence for default mandatory Always will be executed, followed by Conditionally and Not.
Arguments

has_changed	This indicates whether the value of the field has changed. It is set by the standard program and can be tested in the hook. Possible values are: • DAL_NEW change caused by inserting a new object • DAL_UPDATE change caused by updating an existing object
Return values

This hook returns 0 if the value of the field is accepted. It returns a negative value (DALHOOKERROR) if the value is not accepted.

Points of Attention

•	The field order is very important and is hierarchically structured.
The first element of the default mandatory Always is the most important. After all elements of that category have been checked the first element of the default mandatory Conditionally is most important. After all elements of that category have been checked the first element of the default mandatory Not is most important.
If an element (table field) in one of the categories have been managed this field should not be updated (by defaults generated from other fields lower in the hierarchy).

•	Mandatory fields cannot always automatically be derived from the table definitions. Check for instance tisfc001.pdno (Production Order). One should check both UI and DAL script in order to see which fields belong to what category (Always / Conditionally / Not).

•	Hint: Use ttaad4100 with DAL for checking the quality of the DAL.

•	Default mandatory Always fields should be controlled via domain or table field check.

•	Default mandatory Conditionally fields should be checked via the DAL.

Example

function extern long tisfc001.pdno.set.defaults(long has_changed)

{

domain tclngt length.of.group	|* Length of Order Series Group

domain tcbool defaults.found	|* Defaults by Order Series Found

if has_changed = DAL_NEW then

tisfc001.rswc = tisfc000.rswc

get.and.fill.defaults.of.order.serie(tisfc000.ngpd,

get.sfc.serie.out.of.pdno(tisfc001.pdno,

length.of.group), defaults.found)

endif

return(0)

}

See also

Property methods

Related topics

•	Data Access Layer: overview

•	DAL terminology

•	DAL hooks


Object hooks

Object hooks are used for checking the logic integrity of objects (that is, records in a table).

Object hooks replace the before.read, after.read, before.write, after.write, before.rewrite, after.rewrite, before.delete, and after.delete subsections in the main.table.io section of the UI script.

If there is a DAL for an object set, the standard program calls the object hooks in the DAL every time that a DAM is executed for that object set. The object hooks perform the necessary checks to ensure the logical integrity of the objects being accessed. Any of the above mentioned sections in the UI script are ignored. So, if a UI script contains any of these sections, you must replace these by object hooks in the DAL.

Available object hooks

Open object set hook

before.open.object.set()

Get object hooks

before.get.object()

after.get.object()

Destroy object hooks

before.destroy.object()

after.destroy.object

Save object hooks

before.save.object()

after.save.object()

After commit transaction hook

after.commit.transaction()

Method is allowed hook

method.is.allowed()

Default object set hook

set.object.defaults()

Return values and errors

Only the before hooks can prevent a database action. The after.get.object() hook can prevent a record from being sent to the UI. Both these types of hook block continuation of the calling method if the return value is set to DALHOOKERROR (a negative constant). If the return value is zero, the method continues.

The following table indicates how return values and error messages are handled. The STP column indicates how the standard program reacts if a hook returns a DALHOOKERROR. The Messages column indicates what happens to messages when an error occurs. The Warnings column indicates what happens to messages when no error is returned. The DAM column indicates how Data Access Methods react when an error occurs.

Hook	STP	Messages	Warnings	DAM
before.open.object.set()	exit	display	display	return
before.get.object()	ignore	ignore	ignore	return
after.get.object()	skip	ignore	ignore	return
before.destroy.object()	return	display	display	return
after.destroy.object()	ignore	ignore	ignore	return
before.save.object()	return	display	display	return
after.save.object()	ignore	ignore	ignore	return
Related topics

•	Data Access Layer: overview

•	DAL terminology

•	DAL hooks


before.open.object.set()

Syntax

function extern long before.open.object.set()

Description

Use this to program checks that determine whether opening of the object set is permitted.

If this hook exists, it is executed after the before.program event section for the main table. It is also called for every first access to a DAL by business methods or Data Access Methods.

You can also use this section to program query extensions.

Return values

The hook returns 0 if opening of the object set is permitted. If the hook returns a negative value (DALHOOKERROR), the session is aborted (if the hook is called by the STP) or the method returns an error (if the hook is called by a DAM or a business method).

Related topics

•	DAL object hooks


before.get.object()

Syntax

function extern long before.get.object( long dir )

Description

Use this to program checks that determine whether reading a record is permitted. The dir argument is set by the STP or CDAS and specifies the object being read. The possible values are:

DAL_GET_FIRST	DAL_GET_NEXT	DAL_GET_PREV
DAL_GET_LAST	DAL_GET_FIND	DAL_GET_CURR

This object hook replaces the before.read subsection of the main.table.io event section in a UI script. If there is a DAL for an object set, this hook is called to perform the necessary checks. Any before.read sections in the UI script are ignored. So, if a UI script contains before.read sections for the main table, you must replace these by before.get.object() hooks in the DAL.

Return value

The hook returns 0 if reading of the record is permitted. Negative return values (DALHOOKERROR) are ignored by the calling program.

Example

function extern long before.get.object( long dir )

{

return(0)

}

Related topics

•	DAL object hooks


after.get.object()

Syntax

function extern long after.get.object( long dir )

Description

Use this to program checks that determine whether reading a record is permitted. The checks are performed after the record has been retrieved from the database. The dir argument is set by the STP or CDAS and specifies the object being read. The possible values are:

DAL_GET_FIRST	DAL_GET_NEXT	DAL_GET_PREV
DAL_GET_LAST	DAL_GET_FIND	DAL_GET_CURR

This object hook replaces the after.read subsection of the main.table.io event section in a UI script. If there is a DAL for an object set, this hook is called to perform the necessary checks. Any after.read sections in the UI script are ignored. So, if a UI script contains after.read sections for the main table, you must replace these by after.get.object() hooks in the DAL.

Notes

It is preferable to use a query extension in the before.program section of the UI script instead of this hook. So, only use this hook if a query extension is not possible.

The standard program ignores messages set in this hook.

Return value

The hook returns 0 if reading of the record is permitted. If the hook returns a negative value (DALHOOKERROR), the object is skipped.

Example

| after.get.object hook

function extern long after.get.object(long dir)

{

on case dir

case DAL_GET_FIRST:

…

break

case DAL_GET_NEXT:

…

break

case DAL_GET_PREV:

…

break

case DAL_GET_LAST:

…

break

case DAL_GET_FIND:

…

break

case DAL_GET_CURR:

…

break

default:

…

break

endcase

if ttadv100.cpac = "tt"

return(DALHOOKERROR)

| Error messages from after.get.object are

| ignored by the standard program

endif

return(0)

}

| Query extension with the same result

| Use this in preference

before.program:

query.extend.where("ttadv100.cpac <> ""tt"" ")

Related topics

•	DAL object hooks


before.destroy.object()

Syntax

function extern long before.destroy.object()

Description

Use this to program checks that determine whether deleting a record is permitted.

This object hook replaces the before.delete subsection of the main.table.io event section in a UI script. If there is a DAL for an object set, this hook is called to perform the necessary checks. Any before.delete sections in the UI script are ignored. So, if a UI script contains before.delete sections for the main table, you must replace these by before.destroy.object() hooks in the DAL.

Return value

The hook returns 0 if deleting the record is permitted. If the hook returns a negative value (DALHOOKERROR), the transaction is aborted.

Example

function extern long before.destroy.object()

{

if tdsls040.stat = tdsls.stat.invoiced then

dal.set.error.message("tdsls44041")

| You cannot delete an invoiced transaction

return(DALHOOKERROR)

endif

...

return(0)

}

Related topics

•	DAL object hooks


after.destroy.object()

Syntax

function extern long after.destroy.object()

Description

Use this to update referenced tables after the current object has been deleted.

This object hook replaces the after.delete subsection of the main.table.io event section in a UI script. If there is a DAL for an object set, this hook is called to perform the necessary actions. Any after.delete sections in the UI script are ignored. So, if a UI script contains after.delete sections for the main table, you must replace these by after.destroy.object() hooks in the DAL.

Return value

The hook returns 0 if successful. Negative return values (DALHOOKERROR) are ignored by the calling program.

Example

function extern long after.destroy.object

{

return(0)

}

Related topics

•	DAL object hooks


before.save.object()

Syntax

function extern long before.save.object( mode )

Description

Use this to program checks that determine whether saving a record is permitted. The mode argument is set by the standard program. The possible values are:

DAL_NEW 	indicates a new record
DAL_UPDATE 	indicates a record being updated

This object hook replaces the before.write and before.rewrite subsections of the main.table.io event section in a UI script. If there is a DAL for an object set, this hook is called to perform the necessary checks. Any before.write and before.rewrite sections in the UI script are ignored. So, if a UI script contains before.write and before.rewrite sections for the main table, you must replace these by before.save.object() hooks in the DAL.

Return value

The hook returns 0 if saving the record is permitted. If the hook returns a negative value (DALHOOKERROR), the transaction should be canceled.

If the hook was called directly by the standard program, the transaction is canceled automatically. If the hook was not called by the standard program, the transaction must be canceled by calling abort.transaction() or abort.io(), typically in the UI script.

Example

function extern long before.save.object(long mode)

{

if mode = DAL_NEW then

| this is code from before.write subsection

else

| this is code from before.rewrite subsection

endif

return(0)

}

Related topics

•	DAL object hooks


after.save.object()

Syntax

function extern long after.save.object( mode )

Description

Use this to update referenced tables after a record has been added or updated. The mode argument is set by the standard program. The possible values are:

DAL_NEW 	indicates a new record
DAL_UPDATE 	indicates a record being updated

This object hook replaces the after.write and after.rewrite subsections of the main.table.io event section in a UI script. If there is a DAL for an object set, this hook is called to perform the necessary actions. Any after.write and before.rewrite sections in the UI script are ignored. So, if a UI script contains after.write and after.rewrite sections for the main table, you must replace these by after.save.object() hooks in the DAL.

Return values

The hook returns 0 if successful. Negative return values (DALHOOKERROR) are ignored by the calling program.

Example

function extern long after.save.object( long mode )

{

if mode = DAL_NEW then

| this is code from after.write subsection

else

| this is code from after.rewrite subsection

endif

}

Related topics

•	DAL object hooks


after.commit.transaction()

Syntax

function extern void after.commit.transaction()

Description

Use this to update other database tables after an update of the current table has been committed to the database.

This object hook replaces the after.update.db.commit event section in a UI script. If there is a DAL for an object set, this hook is called to perform the required actions. Any after.update.db.commit sections in the UI script are ignored. So, if a UI script contains a after.update.db.commit section for the main table, you must replace it by an after.commit.transaction() hooks in the DAL.

This hook is called only by the STP and CDAS. It is not called by Data Access Methods or commit.transaction().

Related topics

•	DAL object hooks


method.is.allowed()

Syntax

function extern long method.is.allowed( long method )

Description

This is a special hook for handling centralized authorizations. Use it to perform checks that determine whether certain Data Access Methods are permitted for an object. The method argument specifies the method to check.

The hook can be called from the UI script, but it is also called from the standard program to check if certain operations are allowed.

Return values

TRUE	the method is permitted
FALSE   	the method is not permitted

Example

function extern long method.is.allowed( long meth )

{

on case meth

case DAL_NEW:

if .... then

dal.set.error.message("error message")

return(false)

endif

break

case DAL_UPDATE:

...

break

case DAL_DESTROY:

...

break

endcase

return(true)

}

Related topics

•	DAL object hooks


Data Access Methods (DAM)

You use Data Access Methods (DAM) to update the database via the DAL. In a UI script, you can use the methods to update any object set. In a DAL script, you can use the methods to update objects in an object set other than the one with which the script itself is associated.

There are three Data Access Methods:

•	dal.update()

•	dal.new()

•	dal.destroy()

These functions encapsulate the db.update(), db.insert() and db.delete() functions respectively, together with the DAL hooks of the object set.

Related topics

•	Data Access Layer: overview

•	DAL terminology

•	Transition issues (BAAN IV to BaanERP)


Property methods

Setting properties

In order to notify the DAL about a change in the value of a property, you must use the dal.set.property() function to change the value. Using this function ensures that the relevant property hooks are executed when the value is changed. If you use an assignment or the db.* functions to change a property value, the DAL is not notified of the change. Consequently, the property checks in the DAL are not executed.

You can call this function from both UI and DAL scripts.

Retrieving properties

You can retrieve the value of the has_changed flag (see property hooks) for any property by calling dal.get.property.flag(). The property must have been changed by the dal.set.property() function.

You can call this function from both UI and DAL scripts.

Related topics

•	Data Access Layer: overview

•	DAL terminology

•	DAL hooks

•	Transition issues (BAAN IV to BaanERP)


Query extensions

Query extensions define conditions that the standard program adds to the SELECT, FROM, and/or WHERE clauses of a database query in order to minimize the number of fields read from the main table and in order to retrieve all reference table fields required by the UI and/or DAL scripts.

BaanERP provides the following  functions for constructing query extensions:

•	query.extend.select()

•	query.extend.select.in.zoom()

•	query.extend.from()

•	query.extend.from.in.zoom()

•	query.extend.where()

•	query.extend.where.in.zoom()

You can program query extensions in the UI script and/or the DAL script. In the UI script, you program the extensions in the before.program or before.zoom sections. In the DAL script, you program the extensions in the before.open.object.set() hook.

 For a full discussion of query extensions, see SQL Query extensions.

Related topics

•	Data Access Layer: overview


Communication with STP and CDAS

BaanERP provides the following functions to enable the standard program and external applications to retrieve and display DAL error messages:

•	dal.count.error.messages()

•	dal.get.error.message()

•	dal.get.first.error.message()

•	dal.reset.error.messages()

•	dal.set.error.message()

You use dal.set.error.message() to specify a message to be displayed when the DAL returns an error (that is, a negative value). This function is called in the DAL script and not in the UI script.

UI scripts can call dal.get.first.error.message() to retrieve DAL messages. External applications use dal.get.error.message() to retrieve DAL messages.

The following example illustrates the use of these functions in a UI script:

db.retry.point()

nr.of.errors = dal.count.error.messages()

if db.retry.hit()  then

| Remove the error messages since the last commit

dal.reset.error.messages( nr.of.errors )

endif

…

…

commit.transaction()

nr.of.errors = dal.count.error.messages()

…

commit.transaction()

while dal.get.error.message( message ) >= 0

report.message( message )

Related topics

•	Data Access Layer: overview

•	DAL terminology

•	DAL, UI, and STP interaction

•	Transition issues (BAAN IV to BaanERP)


Transition issues (BAAN IV to BaanERP)

4GL event sections

This table lists the 4GL event sections that have been moved to the DAL in BaanERP. It also lists the DAL methods that replace these sections.

If a DAL script exists for a particular table, the standard program calls the methods in the DAL to perform the relevant integrity checks. Any corresponding 4GL event sections in the UI script are ignored. If there is no DAL for the table, the 4GL event sections are executed.

4GL event sections	DAL methods
field.<x>: check.input:	function extern long <x>.check()
main.table.io: before.read:	function extern long before.get.object()
main.table.io: after.read:	function extern long after.get.object()
main.table.io: before.write:	function extern long before.save.object()
main.table.io: after.write:	function extern long after.save.object()
main.table.io: before.rewrite:	function extern long before.save.object()
main.table.io: after.rewrite:	function extern long after.save.object()
main.table.io: before.delete:	function extern long before.destroy.object()
main.table.io: after.delete:	function extern long after.destroy.object()
4GL functions

This table lists those 4GL UI functions that have DAL equivalents. If a DAL exists for a particular table, it is preferable to use the DAL functions instead of the 4GL UI functions.

4GL function	DAL function
on.main.table()	with.object.set.do()
on.old.occ()	with.old.object.values.do()
set.input.error()	dal.set.error.message() return(DALHOOKERROR)
skip.io()	dal.set.error.message() return(DALHOOKERROR)
abort.io()	dal.set.error.message() return(DALHOOKERROR)
db.update()	dal.update()
db.delete()	dal.destroy()
db.insert()	dal.new()
If a function is used only in the DAL, you should move it to the DAL. If a function is used in both the DAL and the UI, you can move it to the DAL (the UI can call functions in the DAL but not vice versa). Alternately, you can store the function in a separate DLL that is linked to both the UI and the DAL.

Session codes

The DAL does not recognize session codes (prog.name$) and so cannot evaluate them. However, in the case where integrity checks must be session dependent, a solution is to evaluate properties instead of session codes. For example, you could identify a field or a combination of fields whose value(s) uniquely identify the session. Or you could add a property to the object set and give this property a value that is unique to the session.

Predefined variables

The predefined variable previous.choice is not supported in the DAL, as the DAL does not recognize standard commands. Instead, the first argument in the before.save.object() and after.save.object() hooks indicates if an insert or update operation caused the save operation. Note that for the DAL, the copy command is an insert operation.

The predefined variable before.update.check is not supported in the DAL. In BaanERP, field checks are executed both after field input and before the database operation. The programmer cannot influence when these checks are performed. Note that in the CDAS, checking is programmed in the dal.set.property() hook and not in the dal.after.save.object() hook.

Questions

It is not possible to ask for user input during the execution of DAL hooks. If hooks contain conditions that depend on user input, set the condition before the hook is called. Alternately, handle the user input and check the conditions after completion of the database operations.

Messages

The DAL cannot display error messages directly. However, you can set an error message in the DAL with the dal.set.error.message() method. The DAL can notify the calling process of an error by returning the value DALHOOKERROR. The process can then display the error message. Messages can be stacked before they are retrieved by the UI.

Non-table fields

Only table fields are checked in the DAL. Checks for non-database fields must still be programmed in the UI script.

Include files

When writing a Data Access Layer, you must include bic_dal. To use progress indicators and Data Access Methods in your UI, you must include bic_dam.

Related topics

•	Data Access Layer: overview


set.object.defaults()

Syntax

function extern long set.object.defaults()

Description

Use this hook to fill a new record with defaults.

If this hook exists, it is executed only by B3 through a BOI in case of DAL_NEW. Before this hook will be called a db.set.to.default() has been executed; therefore it is not necessary to assign values that are already present in the table definition.

Note: This hook only contains assignments.

Return Values

The hook returns 0 if the hook has been executed successfully.

Example

function extern long set.object.defaults()

{

tisfc001.efdt = utc.num()	|* reference date

tisfc001.prdt = utc.num()	|* production start date

tisfc001.prcd = 999	|* priority

return(0)

}


Dynamic-link libraries

BaanERP Tools supports the use of dynamic-link libraries (DLLs). A DLL consists of a library of functions that are compiled, linked, and stored separately from the processes that use them. The functions are resources that can be shared by multiple programs that are running concurrently. Only one copy of the DLL needs to be present in memory. Each program that uses the DLL links to it at runtime, at the time it calls one of the DLL’s functions.

For example, consider the sprintf$() function. This is a very common function, used by many programs. Instead of including a copy of the function in each program that uses it, you can program the function in a separate DLL. Multiple programs can then share this one copy of the function, by linking to the DLL at runtime.

The following are some of the benefits of using DLLs:

•	Instead of programming common functions in each program that uses them, you can program the functions in one or more DLLs. The code can then be shared by all the programs that use it. By implementing DLLs in BaanERP applications, you can reduce the size of objects to a minimum, as the standard program is not merged with each 4GL program script.

•	You can upgrade a function within a DLL without recompiling all the applications that use it.

•	You can upgrade an application without recompiling all the DLLs it uses.

•	A DLL is loaded only when required. It is also loaded only once, though multiple programs can share its code.

The following sections describe how you handle DLLs:

•	Function declarations

•	Scope of variables across DLLs

•	Sharing DLL object code

•	Dynamic linking

•	Function overloading

•	Object information tool

•	DLL compilation and runtime errors


Function declarations

For functions programmed within a DLL to be accessible to other programs, they must be declared as external functions – that is, they must be declared with the keyword EXTERN. For example:

function extern long funct_a( long arg )

{

.....

}

Functions declared without the EXTERN keyword are local functions. They are accessible only within the program in which they are declared. A DLL usually contains both local and external functions.

Related help topics

    Dynamic-link libraries


Scope of variables across DLLs

Global variables

Global variables are declared outside the functions in a script, without the EXTERN keyword. They are only known within the DLL in which they are declared. For example:

long var_1

External variables

External variables are declared outside the functions in a script, with the EXTERN keyword. They are known within all DLLs in the process in which they are declared. For example:

extern long var_2

Database fields

Database tables are declared as follows:

table  t<table_name>

Declaration of a table implies declaration of all its fields also. Though a table declaration does not include the EXTERN keyword, tables fields are known within all DLLs in the process in which they are declared. When one DLL in a process reads a record, the values of the record fields are shared by all DLLs in the same process.

Related help topics

    Dynamic-link libraries


Sharing DLL object code

DLL objects contain both a program code part and a data part. The program code of a DLL object is loaded into memory when one of the DLL’s functions is called. The data part defines the memory part available for variables. Memory is allocated for a variable the first time that variable is used.

The program code part of a DLL can be loaded into a common virtual memory address space. This enables two or more sessions, within one or more bshells on the same system, to share the program code. The data part is not loaded into shared memory and so cannot be shared.

By default, the program code of BaanERP DLLs can be shared only within the same bshell. Once the DLL has been loaded, it is shared by all process within the bshell.

For process within all bshells on the same system to be able to share the program code, you must specify the object name in the file $BSE/lib/srdd_tabx.x (where x.x is the bshell version). The object will be loaded automatically and its code will be shared by sessions within all bshells on the same system. It is advisable to use this method for all DLLs that are frequently used by several users. For more details, consult the Shared memory manager section in the BaanERP Tools Technical Manual.

Related help topics

    Dynamic-link libraries


Dynamic linking

DLLs can be linked to a program script either at compile time or at runtime.

Dynamic linking at compile time

For dynamic linking at compile time, you must specify the libraries that belong to a program script when you create or update that script. Which libraries belong to a program script depends on which external functions the program uses. It is necessary to specify the libraries at compile time because the compiler locates the functions and checks the types of arguments and return values with the function prototypes. Note that a DLL object is loaded into memory and linked to the executable program at runtime, at the time a DLL function is called.

You must compile the libraries before you compile the program script that uses those libraries. However, since loading and linking take place at runtime, when a library is changed, you need only compile the library and restart the program.

The are two ways to compile the libraries and program script:

•	Use the BaanERP Tools. Choose the Compile option in the sessions "Maintain Libraries" and "Maintain Program Scripts".

•	Use the bicx.x compiler (where x.x is the bhsell version). For example:

$ bic6.2 dll1 -o odll1

$ bic6.2 dll2 -o odll2

$ bic6.2 dll3 -o odll3

$ bic6.2 <program> -o<object> -d odll1:odll2:odll3

Note that, at runtime, external functions are searched for in the order in which the DLLs were supplied during compilation. In above example, dll1 is first.

Dynamic linking at runtime

This is used in cases where the DLL(s) that must be linked to a program are known only at runtime.

For example, consider a programmer’s interface that receives a string containing the library or external function to be called. The return value of the function call (if any) is sent back to the calling process. In this case dynamic linking at runtime must be used, because only at runtime is it known which external function must be called.

A number of functions are available for handling dynamic linking at runtime. Using these functions, you can load a specific DLL and execute one or more of its functions. See DLL functions (executing).

Related help topics

    Dynamic-link libraries


Function overloading

When DLLs are dynamically linked at runtime, instead of at compile time, function overloading is possible. This means that an external function contained in a loaded DLL can be replaced by overloading another DLL that contains a function with the same name and arguments.

You use the load_dll() function to load DLLs dynamically. When you call this function, you can specify whether the DLL is to be overloaded or not. When searching for an external function called by a program, the bshell always searches in overloaded DLLs first.

Specifying which DLLs belong to an object

There are three methods for specifying which DLLs belong to an object.

•	Specify the DLL dynamically, with overload, in the source code. For example:

load_dll( <dll_object>, DLL_OVERLOAD )

•	Specify the DLL statically at compile time. There are three ways to do this:

-	use the option "Define Libraries" in the session "Maintain Program Scripts"

-	use the following syntax when starting the bicx.x compiler (where x.x is the bshell version)

  bicx.x script -o object -d dll_object

-	use the following pragma code in the script

 #pragma used dll <dll_object>

•	Specify the DLL dynamically, without overload, in the source code. For example:

load_dll( <dll_object>, 0 ) or
load_dll( <dll_object> )     | 0 is default

Function search algorithm

When a DLL function is called for the first time, the function address is unresolved. The bshell attempts to resolve the function address by searching for the function using the search method described below. After a function address is resolved, that address is used for all subsequent function calls with the same function name and arguments. So once a function address is resolved, the function cannot be replaced by overloading a different DLL containing a function of the same name and arguments.

The bshell searches DLLs in the following order:

1	All dynamically overloaded DLLs – that is, DLLs loaded by calling load_dll() with the overload flag set to DLL_OVERLOAD. For example:

load_dll(dll_object, DLL_OVERLOAD)

The bshell searches the overloaded DLLs in reverse order. So, the DLL that was overloaded last is searched first.

2	The first DLL where the function was found during compilation.

3	All statically specified DLLs.

First the bshell searches in the DLLs specified in the compilation command with the –d option. The DLLs are searched in the order they are specified in the command. For example:

bic6.2 script -o object -d odll1:odll2:odll3

Next the bshell searches in DLLs specified using the following pragma statement:

#pragma used dll <dll_object>

4	All dynamically loaded DLLs – that is, DLLs loaded by calling load_dll() without the overload flag or with the overload flag set to 0. For example:

load_dll(dll_object, 0

The bshell searches the loaded DLLs in the order in which they were loaded. So, the DLL that was loaded first is searched first.

Note that you can change the search order of dynamically loaded DLLs by calling load.dll() for a loaded DLL and changing the value of the overload flag.

Function overloading – example

Compile

bic6.2 dll -o odll

bic6.2 dll_new -o odll_new

bic6.2 script -o object -d odll –DDEBUG

Script code

function main()

{

#ifdef DEBUG

if ( debug flag ) then

| Load dynamically DLL 'dll_new' to

| overload the DLL 'dll'

load_dll("odll_new", 1)

| Argument '1' means overload

endif

#endif

dll_function()

}

dll code

function extern dll_function()

{

...

}

dll_new code

function extern dll_function()

{

...

}

Related help topics

    Dynamic-link libraries


Object information tool

To display information about an object, use the object information tool bic_infox.x (where x.x is the bshell version). Note that maximum information is displayed when the object has been compiled with the debug option.

Syntax

bic_infox.x [-aidshwcV] [-eu] [-f[flags]] object

Options

-a	Show all available object information (default).
-I	Show instructions in object (Disassembler). This is only possible when the object is compiled with the debug option.
-d	Show used DLLs and where the external functions used are defined.
-s	Show list of used variables, (global) functions, string constants, and double constants.
-h	Show Object header.
-w	Show #ident <strings>.
-c	Check checksum. exit(0) ok  exit(1) corrupted
-V	Show version/release and portings information of bic_infox.x.
-e	Show prototypes of all external functions defined in the object.
-u	Show the general usage of the library (see below).
-f	Show flags.
-f<flag>	Check flags. When this options is used, all other options are ignored. <flag> can be a combination of the following: 1    NOTRANSACTION  2    DEBUG  4    PROFILE  8    DLL exit(0) flag(combination) is in object exit(1) flag(combination) is not in object
Combining -e and -u displays the description of the object and the descriptions and prototypes of all external functions within the object (see below).

Object and function descriptions

You specify an object’s description between the keywords DLLUSAGE and ENDDLLUSAGE in the program script. You place the information outside all functions so that it is global for the entire program. The description should explain the general usage of the object. The description is added to the object and you can retrieve it with the command bic_infox.x -u <object>.

You also specify a function’s description between the keywords DLLUSAGE and ENDDLLUSAGE in the program script. However, you place the information within the body of the function, between the { and } characters. The description should explain the general usage of the object, its arguments, and its return value, for example. You can retrieve function descriptions and prototypes with the command bic_infox.x –eu <object>.

Example

dllusage

This is the object description.

enddllusage

function extern long abs( long arg )

{

dllusage

This function returns the absolute value of the specified argument.

Input:

ARG	The value for which the absolute value is to be returned.

Output:

Return the positive value of ARG.

enddllusage

return ( arg >= 0 ? arg : -arg )

}

Related help topics

    Dynamic-link libraries


DLL compilation and runtime errors

Compilation errors

A compilation error occurs when a function is not found in the specified DLLs or if there is an argument mismatch.

Runtime errors

The following runtime error message is displayed when a script calls a function that has been removed from the DLL and only the DLL has been recompiled:

Dynamic Link Failure function %s

The following runtime error messages are displayed when a function’s arguments are changed within a DLL without recompilation of programs that call the changed function:

Arg error <function name>(<argument name>) type ... expected ...

or

Illegal number of args (%d) for function %s expected %d

To avoid runtime errors, it is advisable to recompile programs whenever you change the programmer’s interface of a DLL that is linked to those programs.

Related help topics

    Dynamic-link libraries


Multitasking and the GUI

The BAAN bshell provides the execution environment for BAAN applications. Whenever a user logs on to the BAAN system, a separate bshell process is activated for that user. So, when multiple users log on to the same BAAN system, or when the same user logs on multiple times, multiple bshell processes are activated on the execution platform.

The BAAN bshell provides a multitasking execution environment for BAAN applications. Each bshell can execute and schedule multiple parallel processes. So, it blocks individual processes only while they are waiting for user input, and not while other processes are waiting for user input.

This section provides an overview of how processes and user interface interaction are managed by the bshell.

•	Bshell scheduler

•	Context switches

•	Events

•	Requests, inquiries, and replies

•	Processes, process groups, and main windows

•	Synchronizing processes with the wait() function

The following diagram provides a schematic overview of the relationships between the scheduler, process queues, and the display server.

Note

The bshell is a single-threaded process. The complete bshell blocks when a database action is performed by the database driver.


Bshell scheduler

The bshell scheduler is responsible for managing and scheduling processes. It maintains four process queues, as follows:

•	running queue

•	blocking queue

•	sleeping queue

•	terminating queue

The scheduler keeps all processes in one or other of the above process queues, depending on their current state.

Running queue

The scheduler schedules processor time only for those processes in the running queue. It schedules each process in the running queue in turn, in order of priority. Each scheduled process receives a number of ticks, and the execution of each instruction costs the process a certain number of ticks. When the process has used up all its ticks, the bshell schedules another process.

The scheduler always schedules the process with the highest priority.

When a process is started, it gets a default priority (this depends on its nice value). While it is in the running queue, the process's priority is incremented each time that another process is scheduled. In this way, the process's priority increases until it has the highest priority in the running queue. It is then scheduled. When a process has been scheduled, its priority returns to its default value.

Blocking queue

When a process is waiting for input, the scheduler moves it from the running queue to the blocking queue. So, the running queue contains only processes that can be run. When a blocked process receives an event, it is moved back from the blocking queue to the running queue.

Sleeping queue

Processes in the sleeping queue are suspended until some external action wakes them again. Processes can be put in a sleeping state (and so in the sleeping queue) only by the functions sleep(), suspend(), receive.bucket$(), and related functions.

Terminating queue

When a process ends, it is stripped of almost all allocated data and moved to the terminating queue. When the scheduler has scheduled another process to run, it then 'cleans up' the terminating queue. That is, it removes all processes except zombie processes. A zombie process is a process that has ended but whose parent process has not yet caught its exit signal.

Related topics

•	Multitasking and the GUI


Context switches

Each running process receives a number of ticks when it is scheduled. This is the equivalent of a UNIX time slice. The execution of each instruction costs the process a number of ticks. When the process has used up all its ticks, the bshell schedules another process. The switch to another process is referred to as a context switch.

Forcing a context switch

Normally, the bshell executes context switches automatically. Functions such as bms.send(), appl.set(), and start.session() also cause a context switch. And programmers can force a context switch by calling suspend(0).This is useful when the immediate response of another process is required.

Allocating bonus ticks

The database locking mechanism prevents two or more processes from updating or deleting the same record or table simultaneously. When a process is modifying the database, the relevant record or table is locked. Other processes cannot modify that record or table until the lock is released.

Some database management systems use a page locking mechanism instead of a record locking mechanism. That is, they lock a predefined block size that can include several records. This can result in a deadlock when two processes within the same bshell attempt to lock records that are positioned very close to each other in the database. To prevent this happening, you can boost the number of ticks assigned to a process by using the bonus tick mechanism. When this mechanism is enabled, the bshell assigns bonus ticks to a process when it locks a database record (note that a lock is applied when the first update, insert, or delete is performed by a database transaction) . This means that the process is not scheduled out before the lock is released (the lock is released when the transaction is committed or aborted).

You can configure the bonus tick mechanism by means of environment variables or user resources.

User resource	Environment variable	Value
bonus_enable	BSE_BONUS_ENABLE	0      bonus ticks off (default) 1      bonus ticks on
bonus_timeslice	BSE_BONUS_TIMESLICE	The number of bonus ticks to assign to a process. The default is 1073741824.
bonus_timeout_warning	BSE_BONUS_TIMEOUT_ WARNING	0 1 2 3	Warning mechanism off.  Warning mechanism on. A warning message is displayed when a process is about to loose its time slice. The message is also displayed when a context switch is forced. This is similar to 1, except that when the object is in debug mode, the process stops and the debugger points to the next instruction. This is similar to 2, except that the process is aborted.
Related topics

•	Multitasking and the GUI


Events

BaanERP programs are designed to respond to events. Usually, they consist of a main loop that waits for events to occur. When an event occurs, the program performs the appropriate actions to process the event. It then returns to its waiting state.

Event types

There are four broad categories of events, as listed below. For a full list of event types, see Event types.

•	User action events.

Most of the events that occur in a BAAN application relate to user interaction. When a user performs an action in the user interface (for example, clicking the mouse or pressing a keyboard key), this generates an event.

•	Timer events.

A process can start a timer that sends an event to the calling process at specified intervals. See Timers.

•	Client events.

A process can send client events to another process by using the send.event() function. The sending and receiving processes can determine their own protocol.

•	Bucket message events.

A process can broadcast bucket message events to other processes by using the bms.send() function.

Note that functions such as keyin$() and data.input() are based internally on events.

Event flow

When a UI object generates an event, the display server sends that event to the bshell. The bshell distributes received events to the event queues of the appropriate process groups; note that events are sent to process groups and not individual processes. The bshell never requests events; the display server always acts independently.

When one of the processes in the bshell requires input, the bshell checks whether any event is present in the event queue of the process group to which the process belongs. If there are no events in the event queue, it checks the connection between the bshell and the display server. If it finds events there, it distributes them to the appropriate process groups.

Event masks

A process can set the event mask of a UI object in order to specify the types of events in which it is interested; the object then generates only events of these types (see select.event.input()). Normally, event masks are automatically set for keyboard and mouse events. However, programmers should not assume any default settings for an event mask. Note that the following event types are always selected and cannot be masked: client events, timer events, bucket message events.

Event functions

BAAN Tools provides the following functions for handling events:

•	next.event( event )

•	peek.event( event )

•	pending.events( )

•	send.event( event )

•	select.event.input( object_id, mask )

Event arrays

The event argument included in the next.event(), peek.event(), and send.event() functions consists of an array of longs (of size EVTMAXSIZE) that contains details of the incoming or outgoing event. You retrieve the contents of an event array by using the set of parameters defined for the particular event type. See Event array parameters.

Sample code

The following example illustrates the basic principle of event handling that is used by almost every event driven program.

#include <bic_event>

function main_event_loop()

{

long event( EVTMAXSIZE )

while next.event( event )

on case evt.type( event )

case EVTBUTTONPRESS:

case EVTBUTTONRELEASE:

x = evt.button.x( event )

y = evt.button.y( event )

button = evt.button.button( event )

if button = EVTBUTTON1 then

print "left button pressed"

refresh()

endif

break

default:

print "not a button press/release"

refresh()

return

endcase

endwhile

}

Related topics

•	Multitasking and the GUI


Requests, inquiries, and replies

A request is a message sent by the bshell to the display server requesting some action – for example, the creation of a window or some other UI object. It consists of a package of information that tells the display server what action to perform and the parameters to use for that action. Requests are asynchronous, so the bshell does not wait for a reply from the display server. Consequently, if an error occurs, the bshell does not detect it. The display server, however, may generate an error message on screen and/or in a log file.

An inquiry is a request for which a result is returned in the form of a reply. Normally, inquiries are used to retrieve information about existing UI objects. When a process sends an inquiry to the display server, it waits for the server to process the inquiry and send a reply. Consequently, inquiries are more time-consuming than asynchronous requests. When response time is important, avoid using the inquiry/reply mechanism. For example, when retrieving information that does not change, you can store the data in variables and retrieve it from those variables instead of sending queries to the display server.

The following example illustrates the use of requests, inquiries, and replies:

#include <bic_gpart>

gpart_id = first.gpart( window_id )           	| Inquiry-reply

while gpart_id

get.gpart( window_id, part_id, type, x, y )| Inquiry-reply

if type = GPLINE then

destroy.gpart( window_id, gpart_id )	| Request

endif

gpart_id = next.gpart( window_id, gpart_id )| Inquiry-reply

endwhile

Related topics

•	Multitasking and the GUI


Processes, process groups, and main windows

Processes

A process consists of a program object, a date, and a state. A process that has been started can be in any one of the following states:

•	Running.

The process is in the running queue. It has been scheduled to run, or is ready to be scheduled.

•	Blocking.

The process is in the blocking queue. It is waiting for input.

•	Sleeping.

The process is in the sleeping queue. It has been suspended and requires an external action to wake it up again.

•	Terminating.

The process is in the terminating queue. It has ended but not all its resources have yet been removed.

Each process stores information about the current main window, the current menu, and current character window. Other information about display objects is not directly available to it.

Process groups

A process group is a group of related, interdependent processes. One process is the group leader. Child processes are started by the leader or by one of its children. All processes belong to a process group.

The following are some of the characteristics of process groups:

•	Each process group has its own event queue. Events are sent to the process group, not to individual processes.

•	When one process within a group starts a child process, the child process is automatically placed in the same process group as its parent. However, you can use the function set.pgrp() to place the process in a different process group.

•	When a process is killed or ended, its parent is automatically awakened, unless the parent and child are in different groups.

•	You use the grab.mwindow() function to set the process group to which a main window sends its events. After calling this function, all events that occur in the main window are sent to the specified process group.

Main windows

A main window acts as the frame window for both sessions and 3GL applications. It is used for starting processes and for creating graphical and character windows. It is not used directly for handling user input or displaying program output. Usually, a main window consists of a border, title bar, menu bar, status area, control menu box, sizing controls, and a work area. The objects used by an application for user interaction are created within the work area of a main window and are managed by that main window.

Each process can have zero, one, or more main windows.

Process groups and main windows

Process groups and main windows are used:

•	to ensure unambiguity of input focus

•	to keep related processes dependent

•	to enable parent and child processes to be independent of each other

Unambiguity of input focus

To ensure that there is never any ambiguity as to where the events generated by a particular window are sent, when you create a main window, you define a single process group to which that main window sends its events. You do this with the grab.mwindow() function. After calling this function for a main window, all events that occur in that window are sent to the specified process group. In principle, there is only one running process in a process group at any time; so the events are sent to that process.

In principle, each process could have its own event queue. However, there are a number of situations where this would cause problems. For example:

•	When the input focus is on an input field and the user zooms to another process to select a value. In this case, the parent process is moved to the sleeping queue and will be awakened when the child process ends.

However, if the user types in the input field after the zoom process has started but before the zoom process has created its own windows, the characters typed are sent to the sleeping process and not to the zoom process for which they were intended. When the windows of the zoom process appear, the user must then restart the selection. However, when the zoom process exits, the characters sent to the parent process are displayed in the input field and not those entered in the zoom process. This is because, when awakened, the parent process finds those characters in its process queue.

•	A similar problem can arise when a uses ends a number of nested processes by repeatedly pressing the EXIT key and also when processes are synchronized by using bucket functions.

These problems are avoided by enabling related, interdependent processes to share the same process group (and so the same event queue).

Keeping related processes dependent

When a process is started by the functions activate(), act.and.sleep(), or wait.and.activate(), by default the new process inherits the process group and main window of its parent. The parent process is moved to the sleeping queue will be awakened automatically when the child process ends.

The following diagram illustrates this.

A process with the same ID as its process group is referred to as the group leader. For the group leader, the predefined variable background is set to FALSE, For child processes, this variable is set to TRUE.

A process group keeps track of the number of processes that belong to it. When no processes remain in the group, the group is automatically destroyed. You can destroy all processes in a particular group simultaneously by calling kill.pgrp().

Making related processes independent

When a process starts a child process, by default the child process inherits the process group and main window of its parent, and the parent is suspended until the child exits. However, it is possible to create a new process group and main window for the child process and so keep the parent and child processes independent. The following diagram illustrates this.

The code for disconnecting a child process from its parent can be included either in the parent process or in the child process. In the following example, it is included in the parent process.

old.mwindow = current.mwindow()

new.mwindow = create.mwindow( title, mode, flags)

change.mwindow( new.mwindow )

child.pid = act.and.sleep( program.name, arglist )

if child.pid then

set.pgrp( child.pid, child.pid )

grab.mwidow( new.mwindow, child.pid )

reactivate( child.pid )

endif

change.mwindow ( old.mwindow )

destroy.mwindow( new.mwindow )

In this example, the parent process first creates a new main window for the child process. It then starts the child process and calls set.pgrp() to place the child process in a different process group. By specifying the same ID for the process and the process group in the set.pgrp() call, a new process group is automatically created with the same ID as the process. The process becomes the leader of the new process group. The parent process then calls grab.mwindow() to link the new process group to the new main window.

In this example, it is important to start the child process with act.and.sleep() and to reactivate the process only after it has been placed in the new process group. If the process is started with activate(), and a context switch occurs immediately after the child process is started, then the process would be scheduled with the incorrect process group.

Note that if a process is moved to another process group, it will be impossible to switch it back to the original group if that group is destroyed in the meantime.

Related topics

•	Multitasking and the GUI


Waiting on child exits
Synchronizing processes with the wait() function

The wait() function enables synchronization of parent and child processes. It causes the parent process to wait for one or all of its children to exit before continuing. Each child process sends an exit signal to the parent process when it ends.

The parent can choose to ignore child signals or not. If it wants to ignore child signals, the parent process calls:

signal(SIGCHLD, SIGIGN)

If it does not want to ignore child signals, it calls:

signal(SIGCHLD, SIGNOIGN)

When a parent process issues a wait() call but is ignoring child signals, child processes exit without any action by the parent. They exit, send an exit signal to the parent, and are removed. The parent process blocks until it receives an exit signal from the last process. The exit value and process ID of the last child are returned in the return value and prodess_id argument respectively of the wait() function. The following diagram illustrates this situation.

When a parent process issues a wait() call and is not ignoring child signals, the exit signal of every child process is caught by the wait() function (including exit signals from children in other process groups). So, each child waits after exiting until its parent process calls the wait() function. While it is waiting for the parent process to catch its exit value, the child process becomes a zombie process. It is placed in the terminating process queue, but is not removed until the parent catches its exit signal. The following diagram illustrates this situation.

Note that if a parent ends while some of its children are zombie process, those children are removed automatically.

Related topics

•	Multitasking and the GUI


The BAAN debugger

The BAAN debugger is an interactive statement interpreter that enables you to control and test the execution of a program. Its principal features include:

•	simultaneous program execution and display of debug information

•	source instructions and debug information are displayed in their own windows, separate from the application

•	source instructions are displayed in a window that you can move and resize

•	on non-graphical displays, debug information is displayed in screen columns 81 to 132

•	the debugger supports variable tracing during program execution (that is, all changes to the values of specified variables are displayed during program execution)

•	the debugger is fully symbolic – machine addresses are not used

•	the debugger is fully integrated with the bshell.

The debugger works only with source programs that have been compiled with the debug option (-l in the case of the BAAN Compiler). When you start such a program, two additional windows are displayed. One displays the source code being executed (the line currently being processed is highlighted). The other is a command window where you input debugger commands and where command results and error messages are displayed.

For information about other debug facilities, see the Logic Server section in the BaanERP Tools Technical Manual.

Click here [image] for information on debugger commands.

Click here [image] for information on debugger mouse actions.


Debugger commands

Debugger commands consist of from one to three words; the words can be separated from each other by one or more spaces. The assignment command is an exception. Here the variable and the value to be assigned are separated by a ':=' sign. Most commands require a line number and/or a source name. If no source name is specified, the default is the current source.

When you start the debugger for an object, the source used by the debugger is first searched for by using the directions in the file fdx.x.<pack.comb.> (where x.x is the bshell version), then it is searched for in the $BSE/tmp directory, and finally in the current directory.

Command	Action
b [[source] line_number]	Set a break point on the current or specified line of the current or specified source. The line is highlighted.  Note that you cannot set break points in included parts in a source. Instead the break point must be set in the included file.
B [source]	Display all set break points in the current or specified source.
c [number]	Continue (execute the source) up to the next break point. If you specify a number, the debugger skips that number of break points. The executed source lines are not displayed.
C [number]	Same as 'c', except that the executed source lines are displayed.
cc	Change the size of the command window. This is valid only when application and debugger are in the same window.
cs	Change the size of the source window. This is valid only when the application and debugger are in the same window.
d [source line_number]	Delete the break point on the specified line number in the source. If you do not specify a line number, the debugger provides the opportunity to interactively delete any break point in the current source file.
D [source]	Delete all set break points in the specified or current source.
delete all	Delete all traces and stop instructions.
delete number	Delete a specified trace or stop instruction.
ds	Delete the source window.
dd	Generate a dump of the data dictionary.
<expression>	Execute the specified expression.
f [noarg|noname][number]	Display stack trace (present nesting of functions), with the arguments of the functions. If you specify a number, only that number of nestings is displayed. noarg only the names of functions are displayed noname arguments are displayed but not their names
fdebug	Show the open tables on the command window.
Fdebug	Print the open tables to the spooler.
g [source] line_number	Continue program execution at the specified line number (goto).
help (or ?)	Start the Help Viewer for debugger options.
instr	Generate a symbolic dump of the object.
l	Display the full list of program variables.
L	Display the list of program variables that have a value, and display their current values. To stop displaying the contents of an array, enter 'n' at the question 'More ?'.
lp	Print the output of the 'l' command.
Lp	Print the output of the 'L' command.
mem	Generate a dump including information about the memory allocated.
p	Go to the source line currently being processed (this is useful after the view or seek command). The line is indicated by a greater than (>) sign before the line number.
q	Exit the debugger (quit).
return	Continue execution until the end of the current function.
s [number]	Execute the program step by step, the specified number of instructions at a time (default is 1). During execution, the intermediate source lines are not displayed.
S [number]	Similar to 's', except that a function call is executed as a single statement.
slow [number]	Reduce the rate of running source code. The maximum number is 100; the minimum (and default) number is 0.
split number	Split the command and source window. The specified number is the last line of the command window. This is often used after resizing the Debugger window.
status [trace|stop|number]	Display traced variables and/or stop instructions. If you specify a number, only that traced variable or stop instruction is displayed.
stop if <expression>	Stop execution when expression is True.
stop in <function>	Stop execution when function is entered.
sym	Generate a dump of the symbol table.
trap off	Disables ‘trap on’. This command is available only when the bshell was started with the -dbgcpu flag.
trap on	The debugger stops after execution of every function call. This command is available only when the bshell was started with the -dbgcpu flag.
t variable	Trace the specified variable during program execution. The execution of the program stops every time the value of the variable is changed. You cannot trace array variables or common variables.
T variable [value]	Same as 't', except that program execution is not stopped when the variable changes. If you specify a value, execution stops when the variable gets that value.
u [variable]	Stop tracing the specified variable. If no variable is specified, you can stop tracing each variable interactively.
U	Stop tracing all variables currently being traced.
v [source] line_number	Display a specified source line in the source window (view). If line_number is greater than the total number of lines, the last line is displayed.
v {+-} number	Shift the display to the source line that is number lines before or after the current source line.
/pattern	Seek a matching text pattern in the current source and display that line.
[function.]variable [/option]	Display the value of a specified variable. If you specify a function, the value of the local variable of that function is displayed. Otherwise, the value of the variable of the current function or the global variable is displayed. If a variable has no value (empty string or zero number), the value is not displayed. /option can have the following values:
	/  /d /D /x /X /b	Use to display the value of a variable that has the same name as a Debugger command. For example, ‘b/’ displays the value of variable b.  Print the flags of the variable and the dimension for arrays. Display the number of bytes allocated in a long or double variable. Display the number of bytes for one element in a string array. The following options are useful for record buffers and binary data. They display the value of a string variable with its full declared length, regardless of NUL characters. NUL characters are displayed as ‘^@’. Characters with values 0 to 31 are displayed as ‘\x<value in hex>’. All characters are displayed as ‘\x<value in hex>’.
variable := value	Assign a value to a variable. The value can be: a string constant or expression a numeric constant or expression a variable name
vi	Activate the vi editor for the current source at the current source line. Changing the source has no influence on the source displayed by the debugger in the source window.
width value	Change the width of command and source window. You can specify any value in the range 80 to 132.
<Ctrl>D/<Ctrl>U	Page down or up in source.
<Esc>	Toggle between normal and history mode.
<Arrow up>/ <Arrow down>	In history mode, these display previously executed commands on the command line. In normal mode, these move the cursor through the source.
Related help topics

    The BAAN Debugger
    Debugger mouse actions


Debugger mouse actions

The Debugger supports the following mouse actions in the source window:

•	Click on a line number to set a break point on that line.

•	Click on a source line to move the cursor to that line.

•	Click on a variable to display its value.

Related help topics

    The BAAN debugger
    Debugger commands


Errors

There are three categories of errors:

•	Error numbers 1-99 are operating system errors

•	Error numbers 100-899 are database errors

•	Error numbers 900-999 are network errors

Notes

To retrieve errors with error codes greater than 1000, subtract 1000 from the error number. The result is the database error code. For example, the error code 1510 represents the database error code 510 (that is, 1510 – 1000).

When a fatal error occurs, information about the error is stored in the log files in the directory $BSE/log. For example, if bdbpost6.2 causes an error, this is reported in the file log.bdbpost6.2.

 UNIX errors

1	EPERM	Not owner This indicates an attempt to modify a file that cannot be modified, except by its owner or by a super user. This is also generated when ordinary users attempt an action that only a super user is permitted to carry out.
2	ENOENT	No such file or directory This occurs when a specified file name should exist but does not, or when one of the directories in a path name does not exist.
3	ESRCH	No such process This occurs when a specified process cannot be found.
4	EINTR	Interrupted system call This indicates that an asynchronous signal (such as interrupt or quit), which the user has elected to catch, occurred during a system call. If the system resumes execution after processing the signal, it will appear as if the interrupted system call returned this error code.
5	EIO	I/O error This indicates some physical I/O error. In some cases, this error can point to the call following the one to which it actually applies.
6	ENXIO	No such device or address This occurs when I/O on a special file refers to a subdevice that either does not exist, or is beyond the limits of the device. It may also occur when, for example, a tape drive is not online or no disk pack is loaded on a drive.
7	E2BIG	Arg list too long This occurs when an argument list longer than 5120 bytes is presented to a member of the exec family system calls.
8	ENOEXEC	Exec format error This indicates that a request has been made to execute a file which, although it has the appropriate permissions, does not start with a valid magic number. See a.out(5).
9	EBADF	Bad file number This indicates either that a file descriptor does not refer to an open file, or that a write request has been made to a file that is opened only for reading, or that a read request has been made to a file that is opened only for writing.
10	ECHILD	No child processes This occurs when a wait is executed by a process that has no existing or unwaited-for child processes.
11	EAGAIN	No more processes This indicates that a fork has failed, either because the system's process table is full or because the user is not allowed to create any more processes.
12	ENOMEM	Not enough space This occurs during an exec or sbrk, when a program asks for more space than the system is able to supply. This is not a temporary condition. The maximum space size is a system parameter.  This error can also occur when the arrangement of text, data, and stack segments requires too many segmentation registers, or if there is not enough swap space during a fork.
13	EACCES	Permission denied This occurs when an attempt is made to access a file in a manner forbidden by the protection system.
14	EFAULT	Bad address This occurs if the system encounters a hardware fault when it attempts to use an argument of a system call.
15	ENOTBLK	Block device required This occurs when a nonblock file is specified where a block device is required – for example, in mount.
16	EBUSY	Device busy This indicates an attempt to mount a device that was already mounted, or an attempt to dismount a device on which there is an active file (open file, current directory, mounted-on file, active text segment). This error also occurs when an attempt is made to enable accounting when it is already enabled.
17	EEXIST	File exists This occurs when an existing file is specified in an inappropriate context (for example, as a new link name in the link function).
18	EXDEV	Cross-device link This occurs when an attempt is made to link to a file on another device.
19	ENODEV	No such device This occurs when an attempt is made to apply an inappropriate system call to a device – for example, when an attempt is made to read from a write-only device.
20	ENOTDIR	Not a directory This indicates that a nondirectory was specified where a directory is required – for example, in a path prefix or as an argument to chdir(S).
21	EISDIR	Is a directory This indicates an attempt to write to a directory.
22	EINVAL	Invalid argument This indicates an invalid argument. For example, dismounting a nonmounted device, specifying an undefined signal in signal or kill, reading or writing a file for which lseek has generated a negative pointer. This error is also used by the math functions described in the (S) entries of the UNIX manual.
23	ENFILE	File table overflow This indicates that the system's table of open files is full, and that temporarily no more open commands can be accepted.
24	EMFILE	Too many open files This occurs when an attempt is made to open more than the maximum number of files. No process can have more than 20 file descriptors open at a time.
25	ENOTTY	Not a typewriter This indicates that the specified device does not have the properties of a terminal.
26	ETXTBSY	Text file bus This occurs when an attempt is made either to execute a pure-procedure program that is currently open for writing or reading, or to open for writing a pure-procedure program that is being executed.
27	EFBIG	File too large This indicates that the size of a file exceeded the maximum file size (1,082,201,088 bytes) or ULIMIT. See ulimit(S).
28	ENOSPC	No space left on device This occurs during a write to an ordinary file when there is no free space left on the device.
29	ESPIPE	Illegal seek This occurs when an lseek is issued to a pipe.
30	EROFS	Read-only file system This occurs when an attempt is made to modify a file or directory on a read-only device.
31	EMLINK	Too many links This indicates an attempt to make more than the maximum number of links (1000) to a file.
32	EPIPE	Broken pipe This indicates an attempt to write on a pipe for which there is no process to read the data. This condition normally generates a signal; the error is returned if the signal is ignored.
33	EDOM	Math arg out of domain of func This indicates that an argument of a math function is outside the defined domain of the function.
34	ERANGE	Math result not representable This indicates that the value of a function in the math package cannot be represented within machine precision.
Database errors

100	EDUPL	This indicates that a duplicate value exists.
101	ENOTOPEN	This indicates that the specified table is not open.
102	EBADARG	This indicates that an illegal argument has been specified.
103	EBADKEY	This indicates that an Illegal key description has been specified. Use the bdbpre and bdbpost tools to resolve.
107	ELOCKED	This indicates that the specified record is locked. You can either wait until the lock is released or you can remove the lock yourself.
108	EKEXISTS	This indicates that the specified key already exists.
110	EENDFILE	This indicates that the end of file has been reached.
111	ENOREC	This indicates that no record was found that matches the query criteria.
112	ENOCURR	This indicates that there is no current record.
113	EFLOCKED	This indicates that the table is locked. You can either wait until the lock is released or you can remove the lock yourself.
201	EROWCHANGED	This indicates that the record was changed after a delayed lock.
202	EDBLOCKED	This indicates that the database is locked. You can either wait until the lock is released or you can remove the lock yourself.
203	ETRANSACTIONON	This occurs when you attempt an action that is not allowed within the transaction.
204	EISREADONLY	This indicates that the transaction is read only.
205	ENOTINRANGE	This indicates that the field value is out of range and does not agree with the domain definition.
206	ENOTLOCKED	This indicates that the record is not locked.
207	EAUDIT	This indicates an audit trailer error.
208	EPERMISSION	This occurs when you attempt an action that is not allowed at this time.
209	EMIRROR	This indicates an error in the mirroring of the database. The tables are inconsistent. You can use the bdbpre and bdbpost tools to copy the tables correctly.
210	EMLOCKED	This indicates either that the record is locked in the mirrored database, or that the tables are inconsistent, or that the mirroring definition in tabledef6.2 is not compatible.
213	ETRANSACTIONOPEN	This indicates that the transaction was started, but not updated. This is an internal bshell error.
214	EUNALLOWEDCOMPNR	This indicates that the operation for mapping company numbers is not allowed. If the logical company is not equal to the physical number, then you are not allowed to perform a drop or clear table operation.
251	EAUDSETUP	This occurs when the audit server setup is not correct. See the log.audit file for more information.
252	EAUDCORRUPT	This indicates that an audit file is corrupt. See the log.audit file for more information.
253	EAUDLOCKED	This indicates that the audit file is locked by another user. See the log.audit file for more information.
254	EAUDABORT	This indicates that a commit transaction has failed in the audit server. See the log.audit file for more information.
301	ESQLQUERY	This indicates a general SQL error. It occurs when the SQL query is syntactically incorrect.
302	ESQLSYNTAX	This indicates that the SQL syntax is not correct.
303	ESQLREFER	This indicates that a reference in the query cannot be found.
305	ESQLWRONGROW	This occurs when a wrong record was returned. It probably means either that the table index is corrupt or that the RDBMS has a different sorting order than the BaanERP software.
501	EMEMORY	This indicates an internal memory error.
502	EBDBON	This indicates that the user is already logged on.
503	EBADADRS	This occurs when an illegal address is used.
504	EBADFLD	This indicates an undefined column.
505	ENOSERVER	This indicates either that there is no server specified in  tabledef6.2 or that the server cannot be started. See the log file for more information.
506	ENOTABLE	This indicates that the table does not exist.
507	ETABLEEXIST	This indicates that the table you are trying to create already exists.
508	EBDBNOTON	This indicates that you are not logged on to a database.
509	EBADCURSOR	This indicates that you have a bad memory cursor or that a bad table pointer has been specified.
510	EDBNOTON	This indicates that the database has not been started. Start the database to correct the problem.
511	EWRONGVERSION	This indicates that client and server versions are incompatible.
512	EDDCORRUPT	This indicates a corrupt data dictionary. You can use the bdbpre and bdbpost tools to repair it.
513	ENODD	This indicates that the data dictionary was not found.
514	ESECURITY	(ORACLE) This indicates a security error. It probably means that you do not have the correct user or group permission.
515	ELICENSEERROR	This indicates a license error; probably an unpatched binary.
516	EUPDSEGM	This occurs during the making or filling of rollback segments. It probably means that the disk is full.
517	EDELAYED	This indicates a general delayed locking error.
518	ENOSESSION	This occurs when an invalid session code is specified.
519	ENOCOMPNR	This occurs when no company number is specified or when an illegal company number is specified. A valid company number is a number between 0 and 999.
520	EBUFUPD	This occurs when flushing of buffered updates fails. The flushing can fails due to a lock or to a referential integrity constraint.
521	ENOSHM	This indicates that shared memory has not been loaded. Load shared memory to correct the problem (see BaanERP Tools Technical Manual for more information).
600	EREFERENCE	This indicates a general reference error. See the log file for more information.
601	EREFLOCKED	This indicates that the reference table is locked. You can either wait until the lock is released or remove the lock yourself.
602	EUNDEFREF	This indicates an undefined reference. This probably means that there is a problem in the runtime data dictionary. See the log file for more information.
604	EREFUPDATE	This indicates that a reference could not be updated.
605	EREFEXISTS	This indicates that the record cannot be deleted while a reference exists. See the log file for more information.
606	EREFNOTEXISTS	This indicates that the reference does not exist.
607	ENOREFTBL	This indicates that the reference table could not be found. This may mean that the data dictionary is not correct. See the log file for more information.
608	ENOREFCNT	This indicates that no reference counter fields are present.
609	EUPDREFCNT	This indicates an error during updating of the reference counter.
700	ESETLOCALE	This indicates an error during setting of the locale. See the log file for more information.
850	EABORTONLOCK	Automatic rollback on lock error. The database driver aborts the transaction.


Known limits

Reports

•	sorting doubles correct to 6 decimal places

•	maximum 253 fields on a report (including array elements)

Bshell

•	maximum string buffer size is 4K – be careful when concatenating strings with '&' sign

•	maximum function stack depth is 75

Bic

•	maximum 255 arguments per function

•	maximum 32K variables per compilation

•	maximum BRANCH of 32K (BRANCH refers to the amount of generated code per function, including macros etc.)

SQL

•	maximum of 50 AND conditions within WHERE clause – otherwise the following error message appears:

"Stack overflow [QueryId = XX]"

Tables

•	maximum record length is 3072 bytes

•	maximum number of fields is 1024

•	maximum field length is 3072 bytes

Indexes

•	maximum index length is 120 bytes

•	maximum number of fields is 32 (no combined fields)

•	maximum number of index parts is 8


ASCII table
ASCII table (ISO 8859-1)

Character	Decimal	Hexadecimal	Character	Decimal	Hexadecimal
	0	00		128	80
^A	1	01		129	81
^B	2	02		130	82
^C	3	03		131	83
^D	4	04		132	84
^E	5	05		133	85
^F	6	06		134	86
^G	7	07		135	87
^H	8	08		136	88
^I	9	09		137	89
^J	10	0A		138	8A
^K	11	0B	cf$(0)	139	8B
^L	12	0C	cf$(1)	140	8C
^M	13	0D	cf$(2)	141	8D
^N	14	0E	cf$(3)	142	8E
^O	15	0F	cf$(4)	143	8F
^P	16	10	cf$(5)	144	90
^Q	17	11	cf$(6)	145	91
^R	18	12	cf$(7)	146	92
^S	19	13	cf$(8)	147	93
^T	20	14	cf$(9)	148	94
^U	21	15	cf$(10)	149	95
^V	22	16	cf$(11)	150	96
^W	23	17	cf$(12)	151	97
^X	24	18	cf$(13)	152	98
^Y	25	19	cf$(14)	153	99
^Z	26	1A	cf$(15)	154	9A
ESC	27	1B		155	9B
^\	28	1C		156	9C
^]	29	1D		157	9D
^^	30	1E		158	9E
^_	31	1F		159	9F
SP	32	20	NBSP	160	A0
!	33	21	¡	161	A1
"	34	22	¢	162	A2
#	35	23	£	163	A3
$	36	24	¤	164	A4
%	37	25	¥	165	A5
&	38	26	¦	166	A6
'	39	27	§	167	A7
(	40	28	¨	168	A8
)	41	29	©	169	A9
*	42	2A	ª	170	AA
+	43	2B	«	171	AB
,	44	2C	¬	172	AC
-	45	2D	SHY	173	AD
.	46	2E	®	174	AE
/	47	2F	¯	175	AF
0	48	30	°	176	B0
1	49	31	±	177	B1
2	50	32	²	178	B2
3	51	33	³	179	B3
4	52	34	´	180	B4
5	53	35	µ	181	B5
6	54	36	¶	182	B6
7	55	37	·	183	B7
8	56	38	¸	184	B8
9	57	39	¹	185	B9
:	58	3A	º	186	BA
;	59	3B	»	187	BB
<	60	3C	¼	188	BC
=	61	3D	½	189	BD
>	62	3E	¾	190	BE
?	63	3F	¿	191	BF
@	64	40	À	192	C0
A	65	41	Á	193	C1
B	66	42	Â	194	C2
C	67	43	Ã	195	C3
D	68	44	Ä	196	C4
E	69	45	Å	197	C5
F	70	46	Æ	198	C6
G	71	47	Ç	199	C7
H	72	48	È	200	C8
I	73	49	É	201	C9
J	74	4A	Ê	202	CA
K	75	4B	Ë	203	CB
L	76	4C	Ì	204	CC
M	77	4D	Í	205	CD
N	78	4E	Î	206	CE
O	79	4F	Ï	207	CF
P	80	50	Ð	208	D0
Q	81	51	Ñ	209	D1
R	82	52	Ò	210	D2
S	83	53	Ó	211	D3
T	84	54	Ô	212	D4
U	85	55	Õ	213	D5
V	86	56	Ö	214	D6
W	87	57	×	215	D7
X	88	58	Ø	216	D8
Y	89	59	Ù	217	D9
Z	90	5A	Ú	218	DA
[	91	5B	Û	219	DB
\	92	5C	Ü	220	DC
]	93	5D	Ý	221	DD
^	94	5E	Þ	222	DE
_	95	5F	ß	223	DF
`	96	60	à	224	E0
a	97	61	á	225	E1
b	98	62	â	226	E2
c	99	63	ã	227	E3
d	100	64	ä	228	E4
e	101	65	å	229	E5
f	102	66	æ	230	E6
g	103	67	ç	231	E7
h	104	68	è	232	E8
i	105	69	é	233	E9
j	106	6A	ê	234	EA
k	107	6B	ë	235	EB
l	108	6C	ì	236	EC
m	109	6D	í	237	ED
n	110	6E	î	238	EE
o	111	6F	ï	239	EF
p	112	70	ð	240	F0
q	113	71	ñ	241	F1
r	114	72	ò	242	F2
s	115	73	ó	243	F3
t	116	74	ô	244	F4
u	117	75	õ	245	F5
v	118	76	ö	246	F6
w	119	77	÷	247	F7
x	120	78	ø	248	F8
y	121	79	ù	249	F9
z	122	7A	ú	250	FA
{	123	7B	û	251	FB
|	124	7C	ü	252	FC
}	125	7D	ý	253	FD
~	126	7E	þ	254	FE
DEL	127	7F	ÿ	255	FF


Application locks: overview

Use these functions to handle application locks for 4GL processes.

You use application locks to prevent other applications and users from reading and/or modifying an application’s data during critical operations. For example, to prevent access to data when it is being updated.

You can set an application lock only for the current 4GL process. You can test for or delete an application lock only within the application to which it applies.

Application lock features

•	Each application lock has an owner, which is automatically assigned.  The owner consists of a combination of the login ID of the application user, and the process ID of the application.

•	Each application lock has a unique name, which you define when you create the lock.

•	An application lock is automatically removed when the application ends. You can also remove it with the appl.delete() function.

•	An application lock applies only to an application and that application’s data. It is not part of the RDBMS and is not linked to a table or a particular database transaction. To set table locks, use db.lock.table().

Application lock types

There are three main types of application locks:

•	Read locks

When you set a read lock, the owner of that lock has only read access to the application’s data. Other applications can read and modify the data. Other users of the application can set read and write locks on it. But they cannot set an exclusive application lock.

Each application can have several read-type application locks.

•	Write locks

When you set a write lock, the owner of that lock has both read and write access to the application’s data. Other applications can read the data but not modify it. Other users of the application can set read locks on it, but not a write lock or an exclusive lock.

Each application can have only one write-type application lock. So you cannot set this type of lock when there is a write-type or exclusive-type lock already present.

•	Exclusive locks

When you set an exclusive lock, the owner of that lock has exclusive access to the application’s data. Other applications and users can neither read nor modify the data, nor can they set any application locks on it.

You can set an exclusive lock only when there are no other locks (of any type) already present.

There is one additional lock type, which you can combine with any of the other types:

•	Application-wide locks

Normally, an application lock is set for the current company only. By using this additional lock mode, you can apply the lock globally to all companies. This means that the application lock is valid in all companies.

Related help topics

    Application locks:  synopsis


Application locks: synopsis

long	appl.delete	( string name(.), long mode )
long	appl.get.user	( string name(.), ref string user(12) )
long	appl.modify	( string name(.), long old.owner, long new.owner )
long	appl.set	( string name(.), long mode )
Related help topics

    Application locks:  overview


appl.delete()

Syntax

long appl.delete( string name(.) )

Description

This removes a specified application lock. Only the owner of the lock can delete it. And a lock can be deleted only from within the same process in which it was set.

Return values

 0	success; lock removed
-1	error; lock not found
-3	internal error

Context

3GL library function.

Related help topics

    Application locks:  overview
    Application locks:  synopsis


appl.get.user()

Syntax

long appl.get.user( string name(.), ref string user(12) )

Description

This retrieves the BAAN login name of the user who created the specified application lock.

Return values

 0	success
-1	lock not found

Context

3GL library function.

Related help topics

    Application locks:  overview
    Application locks:  synopsis


appl.modify()

Syntax

long appl.modify( string name(.), long old.owner, long new.owner )

Description

This changes the owner of a specified application lock. That is, it links the application lock to another 4GL process in the same bshell.

Arguments

name	The name of the application lock.
old.owner	The process ID of the current owner.
new.owner	The process ID of the new owner.
Return values

 0	success
-1	lock not found
-2	new.owner not found
-3	internal error

Context

3GL library function.

Related help topics

    Application locks:  overview
    Application locks:  synopsis


appl.set()

Syntax

long appl.set( string name(.), long mode )

Description

This creates an application lock for the current application.

Arguments

name	The name of the application lock. This must be unique.
mode	The type of application lock to set: APPL.READ APPL.WRITE APPL.EXCL APPL.WIDE You can combine APPL.WIDE with any one of the other lock types.
Return values

  0	success
 -1	application-wide lock present
 -3	internal error
>0	application lock already present; mode is returned

Context

3GL function library.

Examples

This example sets a write-type application lock for all companies. Only the owner can modify the application's data in all companies.

appl.set("00112334455", APPL.WRITE + APPL.WIDE)

This example sets an exclusive-type application lock on a production order and subsequently deletes it.

if appl.set( "tisfc001" & tisfc001.pdno, APPL.EXCL ) <>0 then

| Lock is already present, give message

        return

endif

. . . .

appl.delete( "tisfc001" & tisfc001.pdno )

Related help topics

    Application locks:  overview
    Application locks:  synopsis


ASCII conversion:  overview and synopsis

Overview

Use these functions to convert characters to their corresponding ASCII or multibyte codes, and vice versa.

Synopsis

long	asc	( string characters )
long	chr$	( long code )


asc()

Syntax

long asc( string characters )

Description

This returns the code of a specified ASCII or multibyte character. If characters contains more than one character, asc() returns the sum of their codes.

Note

Multibyte characters with very high values can cause the returned long to overflow and loose its meaning. No check is made on the legality of the value.

Context

Bshell function.

Example

string  select(10)

asc_b = asc("B")	| asc_b is set to 66

asc("abc")	| Returns 294 (that is, 97 + 98+ 99)

asc(select)	| Returns the sum of the ASCII codes for each character

  	  in the string variable select

Related help topics

    ASCII conversion: overview and synopsis


chr$()

Syntax

string chr$( long code )

Description

This returns the ASCII or multibyte character that corresponds to the specified code.

Note

If code is greater than 255, the returned string is of type multibyte. No check is made on the legality of the value.

Context

Bshell function.

Example

chr$(65)	| Returns "A"

chr$(asc("A"))	| Returns "A"

chr$(27)	| Returns the escape character

Related help topics

    ASCII conversion: overview and synopsis


Audit information: overview

Before you read the rest of this topic, know that there is a new set of functions that you can use for retrieval of audit information. These functions are available in BaanERP 5.1 onwards. Refer to BaanERP Audit Management: overview.

The functions in this topic can still be used but you need more knowledge of the underlying architecture to use them in comparison to the above Audit Management functions.

Audit files

For each table associated with a particular company number, the audit server stores audit information in a set of sequence files. You use the audit functions and macros to access this information.

For each table in each company number, there is also an info file. This stores information about all sequence files for the table/company number combination, and control information for creating and maintaining the sequence files for that table/company number combination.

The following diagram illustrates the overall organization of the audit files for a particular company number.

The following diagram illustrates the overall organization of the audit files for a particular table.

The audit server uses sequence files in rotation. When the last file is full, it starts writing to the first file again. So, if the current sequence file is 200, then sequence file 201 (if it exists) is the oldest sequence file and all sequence files >200 are older than sequence files <= 200.

For full details of audit file structure and management, consult the BaanERP Tools Technical Reference Manual.

Location of audit files

The file ‘$BSE/lib/auditdefx.x’ specifies the path to BAAN audit files. All 4GL audit routines use this file to retrieve the path to the audit files.

You can override the default audit path by using the AUDIT_FILE_PATH environment variable.

For example, take the case where directory ‘/usr1/audit_data’ contains the audit data for modules ‘adv’ and ‘aad’ in the subdirectories ‘attadv’ and ‘attaad’. These audit files can be referred to by setting:

AUDIT_FILE_PATH=/usr1/audit_data

Do not specify the final directory (‘attadv’ or ‘attaad’) in the audit path.

If the host name is not included in the pathname, use aud_select_host() to select the required host.

Audit file locking

Before reading information from an audit file, the audit server locks the relevant portion of the file. Other processes can read the information, but no process can write to the locked portion of the file while the read lock is in place. The read lock is released as soon as reading is completed.

Before updating an audit file, the audit server locks the relevant portion of the file with an exclusive type lock. This prevents other processes both reading and writing to the locked portion of the file. The exclusive lock is released as soon as the update is completed.

When the info header is read from the info file, only the info header part of the file is locked. When a sequence header is read from the info file, the sequence header, and the field specifying the header size, are locked.

When the header part of a sequence file is being updated, the sequence header in the sequence file, and the corresponding sequence header in the info file, are locked. In the sequence file, the table name, company number, and sequence header length fields are also locked.

Related help topics

    Audit information:  synopsis
    Audit information:  macros (info header)
    Audit information:  macros (sequence header)
    Audit information:  macros (transaction header)
    Audit information:  macros (transaction record)
    Audit information:  macros (transaction dates and times)
    Audit information:  macros (dates and times)
    Audit information:  sample program


Audit information: synopsis

Include files

#include <bic_audlib>

#include <bic_audhdr.h>

Functions

long	aud_close_audit	( long seqid )
void	aud_get_audit_dd	( const string seqhdr(), ref string    colnames(,), ref long colinfo(,) )
void	aud_get_col_info	( const string seqhdr(), long col_no,    ref string col_name(), ref long    col_type, ref long col_dep,    ref long col_len )
long	aud_get_fld_values	( long colno, const long colinfo(,),    const string rec_buff(),    ref string values(,) )
long	aud_get_hdr_size	( long seqid )
long	aud_get_info_seq_hdr_size	( long seqid, long seqno )
long	aud_open_audit	( const string host_name(), const string    table_name(), long compno, long seqno )
long	aud_read_audit_rec	( long seqid, long rec_no, ref string    rec_buff() )
long	aud_read_info_hdr	( const string host_name(), const string    table_name(), long compno, ref string    info_hdr() )
long	aud_read_info_seq_hdr	( long seqid, long seqno, ref string    seqhdr() )
long	aud_read_next_audit_rec	( long seqid, ref string rec_buff() )
long	aud_read_next_tran	( long seqid, ref string tran_hdr() )
long	aud_read_seq_hdr	( long seqid, ref string seqhdr() )
long	aud_read_tran	( long seqid, long tran_no, ref string    tran_hdr() )
long	aud_select_host	( const string table_name(), long compno,    long user_interaction, ref string    host_name() )
long	aud_update_infofile	( long seqid, const string seqhdr )
long	aud_write_info_hdr	( const string host_name(), const string    table_name(), long compno, const string    info_hdr )
long	aud_write_seq_hdr	( long seqid, const string seqhdr() )
Related help topics

    Audit information:  overview
    Audit information:  macros (info header)
    Audit information:  macros (sequence header)
    Audit information:  macros (transaction header)
    Audit information:  macros (transaction record)
    Audit information:  macros (transaction dates and times
    Audit information:  macros (dates and times)
    Audit information:  sample program


aud_close_audit()

Syntax

long aud_close_audit( long seqid )

Description

Discards the specified sequence identifier. seqid is the identifier returned by aud_open_audit() when the particular sequence file was opened. When the last sequence file associated with an info file is closed, the info file is also closed.

Return values

 0	success
-1	error (for example, could not close the sequence file or info file).

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


aud_get_audit_dd()

Syntax

void aud_get_audit_dd( const string seqhdr(), ref string colnames(,), ref long colinfo(,) )

Description

This retrieves the audit data dictionary information from the sequence header of a particular sequence file.

Arguments

seqhdr	The buffer containing the sequence header. You fill this by calling aud_read_seq_hdr() or aud_read_info_seq_hdr.
colnames	An array containing the names of the audited fields. This array must be allocated dynamically.
colinfo	An array containing the data dictionary information for the audited fields. For example, the information for the first audited field can be interpreted as follows: colinfo(AUD_FLD_TYPE,1) contains the field type – for example,  DB.LONG, DB.FLOAT colinfo(AUD_FLD_DEPT,1) contains the field depth – this is always 1  for non-array fields colinfo(AUD_FLD_LEN,1) contains the field length  This array must be allocated dynamically.
Context

3GL library function.

Example

long    audit_flds

string  colnames(1,1) based

long    colinfo(1,1) based

audit_flds = aud_get_no_audit_flds(seqhdr)   | get number of audited fields

alloc.mem(colnames, AUD_COL_NAME_LEN, audit_flds)

alloc.mem(colinfo, 3, aud_flds)

aud_get_audit_dd( seqhdr, colnames, colinfo )

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


aud_get_col_info()

Syntax

void aud_get_col_info( const string seqhdr(), long col_no, ref string col_name(), ref long col_type, ref long col_dep, ref long col_len )

Description

This retrieves information about a specified field from the sequence header of a particular sequence file. It retrieves the same information as aud_get_audit_dd(), but for a single field only.

Arguments

seqhdr	The buffer containing the sequence header. You fill this by calling aud_read_seq_hdr() or aud_read_info_seq_hdr.
col_no	The column number.
colname	The field name.
coltype	The field type – for example, DB.LONG, DB.STRING.
col_dep	The field depth. This is always 1 for non-array fields.
col_len	The field length.
Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


aud_get_fld_values()

Syntax

long aud_get_fld_values( long colno, const long colinfo(,), const string rec_buff(), ref string values(,) )

Description

This retrieves the values of a specified field from an audit record. You can use this for records of type insert, delete, and update only. For records of type insert and delete, you can retrieve the values of any field. For records of type update, you can retrieve the values of changed fields and primary key fields only.

Arguments

colno	The column number.
colinfo	An array containing the audit DD of the sequence file that contains the audit record. You fill this by calling aud_get_audit_dd().
rec_buff	The buffer containing the audit record. You fill this by calling aud_read_audit_rec() or aud_read_next_audit_rec().
values	An array containing the field values in string format. There are two string elements, the first containing the old value of the field, the second containing the new value. For example: values(1,1) old value values(2,1) new value The size of the both elements is determined by the predefined constant AUD_MAX_FLD_SIZE.
Return values

 0	Record of type insert or delete. In these cases, there is no new value. Only values(1,1) is relevant.
 1	Record of type update. Both old and new values are relevant.
-1	Error. Possibly invalid column number or record not of type insert, delete, or update.

Context

3GL library function.

Example

| For a column of type DB.FLOAT

long    colno, coltype, coldept

string  rec_buff(AUD_MAX_REC_SIZE)

string  values(AUD_MAX_FLD_SIZE,2)

float   new_value, old_value

if ( aud_get_fld_values(colno, colinfo, rec_buff, values) = 1 ) then

new_value = load.float( values(1,1) )

old_value = load.float( values(2,1) )

endif

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


aud_get_hdr_size()

Syntax

long aud_get_hdr_size( long seqid )

Description

Because the audit DD of a table can differ in different sequence files, the size of the sequence header can also differ from sequence file to sequence file.

This function returns the size (in bytes) of the header of a specified sequence file. You can use the return value to allocate space for the sequence header before retrieving it with aud_read_info_seq_hdr() or aud_read_seq_hdr(). seqid is the sequence identifier returned by aud_open_audit() when the particular sequence file was opened.

Note

You can also use aud_get_info_seq_hdr_size() to retrieve the size of the sequence header. The value returned by both functions is normally the same.

Return values

>0	sequence header size (in bytes)
 -1	error; probably invalid seqid

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


aud_get_info_seq_hdr_size()

Syntax

long aud_get_info_seq_hdr_size( long seqid, long seqno )

Description

Because the audit DD of a table can differ in different sequence files, the size of the sequence header can also differ from sequence file to sequence file.

This function returns the size (in bytes) of the header of a specified sequence file, as stored in the associated info file. You can use the return value to allocate space for the sequence header before retrieving it with aud_read_info_seq_hdr() or aud_read_seq_hdr().

Arguments

seqid	The sequence identifier returned by aud_open_audit() when the sequence file was opened.
seqno	The sequence number of the sequence file.
Note

You can also use aud_get_hdr_size() to retrieve the size of the sequence header. The value returned by both functions is normally the same.

Return values

>0	length of the sequence file header
 -1	error – possible reasons are:
– error occurred while opening sequence file
– open file limit reached

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


aud_open_audit()

Syntax

long aud_open_audit( const string host_name(), const string table_name(), long compno, long seqno )

Description

This opens a specified sequence file. You identify the file to open by the table/company combination with which it is associated, the host on which it is located, and the sequence file number. The function returns a unique identifier for the file. Other audit functions use this identifier (referred to as the sequence identifier) to refer to this particular sequence file.

When you open a sequence file, the associated info file is automatically opened also (unless it is already open).

Arguments

host_name	The name of the host on which the sequence file is to be accessed. You can use aud_select_host() to select the host to be used.  If this argument is an empty string, aud_select_host() is called automatically to select a host name.
table_name	The name of the table with which the sequence file is associated. This takes the form ppmmfff, where pp is the package code, mmm is the module code, and fff is the file number.
compno	The company number.
seqno	The number of the particular sequence file to open.
Return values

>0	sequence id for file
 -1	error – possible reasons are:
– table or sequence file does not exist
– error occurred while opening sequence file
– open file limit reached

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


aud_read_audit_rec()

Syntax

long aud_read_audit_rec( long seqid, long rec_no, ref string rec_buff() )

Description

This retrieves a specified audit record from the current transaction. You can use aud_read_next_audit_rec() to retrieve the next and subsequent records from the transaction. You can access information in the audit record using the transaction record  macros.

Arguments

seqid	The sequence identifier returned by aud_open_audit() when the sequence file was opened.
rec_no	The number of the audit record within the transaction. Specify 1 to retrieve the first audit record, 2 to retrieve the second, and so on.
rec_buff	A buffer containing the actual audited record. The predefined constant AUD_MAX_REC_SIZE holds the size of this buffer.
Return values

 0	success
-1	error – possible reasons are:
– seqid does not exist
– rec_no does not exist

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  macros (transaction record)
    Audit information:  macros (transaction dates and times)
    Audit information:  sample program


aud_read_info_hdr()

Syntax

long aud_read_info_hdr( const string host_name(), const string table_name(), long compno, ref string info_hdr() )

Description

This retrieves the header of the info file associated with a specified table and company number combination. You can access information in the info header using the info header macros.

Arguments

host_name	The name of the host on which the info file is to be accessed. You can use aud_select_host() to select the host to be used.  If this argument is an empty string, aud_select_host() is called automatically to select a host name.
table_name	The name of the table with which the info file is associated. This takes the form ppmmfff, where pp is the package code, mmm is the module code, and fff is the file number.
compno	The company number.
info_hdr	The buffer in which the info header is stored. The info header size is fixed. The predefined constant AUD_INFO_HDR_SIZE holds the size of the buffer.
Return values

>0	success
 -1	error – possible reasons are:
– host not found
– info file not found
– error opening info file
– info file locked
– unable to unlock file after read action
– unable to close info file

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  macros (info header)
    Audit information:  sample program


aud_read_info_seq_hdr()

Syntax

long aud_read_info_seq_hdr( long seqid, long seqno, ref string seqhdr() )

Description

This reads the header information for a particular sequence file from the associated info file. You can access information in the sequence header using the sequence header macros.

Use aud_read_seq_hdr() to read the sequence header from the sequence file itself. The information retrieved by both functions is normally the same.

Arguments

seqid	The sequence identifier returned by aud_open_audit() when the sequence file was opened.
seqno	The sequence number of the sequence file.
seqhdr	The buffer in which the sequence header information is stored. Use aud_get_hdr_size() or aud_get_info_seq_hdr_size() to retrieve the size of this buffer.
Return values

 0	success
-1	error; probably invalid seqid

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  macros (sequence header)
    Audit information:  sample program


aud_read_next_audit_rec()

Syntax

long aud_read_next_audit_rec( long seqid, ref string rec_buff() )

Description

This reads the next audited record from the current transaction. You can use aud_read_audit_rec() to read a specific audit record and then use aud_read_next_audit_rec() to read the next and subsequent records. You can access information in the audited record using the transaction record macros.

Arguments

seqid	The sequence identifier returned by aud_open_audit() when the sequence file was opened.
rec_buff	A buffer containing the actual audited record. The predefined constant AUD_MAX_REC_SIZE holds the size of the buffer.
Return values

 0	success
-1	error – possible reasons are:
– seqid does not exist
– no more records in the current transaction of the specified sequence file

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  macros (transaction record)
    Audit information:  macros (transaction dates and times)
    Audit information:  sample program


aud_read_next_tran()

Syntax

long aud_read_next_tran( long seqid, ref string tran_hdr() )

Description

This reads the next transaction header in the specified sequence file. You can use aud_read_tran() to read a specific transaction header and then use aud_read_next_tran() to read the next and subsequent transaction headers. You can access information in the transaction header using the transaction header macros.

Arguments

seqid	The sequence identifier returned by aud_open_audit() when the sequence file was opened.
tran_hdr	A buffer containing the transaction header information. The predefined constant AUD_TRAN_HDR_SIZE holds the size of this buffer.
Return values

 0	success
-1	error – possible reasons are:
 	– seqid does not exist
– no more transactions in the sequence file

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  macros (transaction header)
    Audit information:  sample program


aud_read_seq_hdr()

Syntax

long aud_read_seq_hdr( long seqid, ref string seqhdr() )

Description

This retrieves the header information from a specified sequence file. You can access information in the sequence header with the sequence header macros.

Use aud_read_info_seq_hdr() to read the sequence header from the info file instead of the sequence file. The information retrieved by both functions is normally the same.

Arguments

seqid	The sequence identifier returned by aud_open_audit() when the sequence file was opened.
seqhdr	The buffer in which the sequence header information is stored. Use aud_get_hdr_size() or aud_get_info_seq_hdr_size() to retrieve the size of this buffer.
Return values

 0	success
-1	error; probably invalid seqid

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  macros (sequence header)
    Audit information:  sample program


aud_read_tran()

Syntax

long aud_read_tran( long seqid, long tran_no, ref string tran_hdr() )

Description

This reads a specified transaction header from a specified sequence file. You can use aud_read_tran() to read a specific transaction header and then use aud_read_next_tran() to read the next and subsequent transaction headers. You can access information in the transaction header with the transaction header macros.

Arguments

seqid	The sequence identifier returned by aud_open_audit() when the sequence file was opened.
tran_no	The number of the required transaction within the sequence file. Specify 1 to read the header for the first transaction in the sequence file, specify 2 to read the header for the second transaction, and so on.
tran_hdr	A buffer containing the transaction header information. The predefined constant AUD_TRAN_HDR_SIZE holds the size of this buffer.
Return values

 0	success
-1	error – possible reasons are:
– sequence id does not exist
– transaction does not exist

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  macros (transaction header)
    Audit information:  sample program


aud_select_host()

Syntax

long aud_select_host( const string table_name(), long compno, long user_interaction, ref string host_name() )

Description

Audit files can be located on more than one host (for example, on the local host and a remote host, or on two or more remote hosts). The system maintains a list of hosts where audit files for particular table and company number combinations are located. When accessing audit files, this host list is used to select the particular host on which the files are to be accessed.

aud_select_host() selects and returns the name of the host on which the audit files for a specified table and company are to be accessed. You can use this host name as input to aud_open_audit(), aud_read_info_hdr(), and aud_write_info_hdr().

Arguments

table_name	The name of the table for which audit files are to be accessed. This takes the form ppmmfff, where pp is the package code, mmm is the module code, and fff is the file number.
compno	The company number.
user_interaction	Specifies whether or not user interaction is required. Possible values are:
	USR_INTACTION_YES USR_INTACTION_NO	If there is more than one host in the host list for the specified table and company number, the user is prompted to select the host to be used. The function then returns the name of that host. If there is only one host in the list, that host is returned automatically, without user interaction. No user interaction. The 4GL library automatically selects the host. It returns the name of the first host in the host list. If there is only one host in the list, it returns the name of that host.
host_name	This returns the name of the selected host.
Notes

If the AUD_HOST_NAME environment variable is set, aud_select_host() always returns the host name stored in this variable, regardless of the user_interaction setting specified by the function. For example, the application will use the audit file on the remote host ‘ed5c21’, if the environment variable has been set as follows:

AUD_HOST_NAME=ed5c21

Note that this environment variable applies to all tables. If it is set, it is used for accessing the audit files of all tables.

Return values

>=0	success
   -1	error; possibly unable to find host list or auditing not enabled for the specified table and company

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


aud_update_infofile()

Syntax

long aud_update_infofile( long seqid, const string seqhdr )

Description

This writes sequence header information to the info file associated with the specified sequence file. You can set the information for the sequence header with the sequence header macros.

Note that the sequence header information is not automatically copied to the sequence header in the sequence file itself. To ensure that there is no mismatch between the sequence headers in the info file and in the sequence file, use aud_write_seq_hdr() instead to update a sequence header.

Arguments

seqid	The sequence identifier returned by aud_open_audit() when the sequence file was opened.
seqhdr	The buffer that contains the sequence header information.
Return values

 0	success
-1	error – possible values are:
– error occurred while opening the information file
– open file limit reached
– incorrect sequence identifier

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


aud_write_info_hdr()

Syntax

long aud_write_info_hdr( const string host_name(), const string table_name(), long compno, const string info_hdr )

Description

This writes info header information to a specified info file. You can set the information for the info header with the info header macros.

Arguments

host_name	The name of the host on which the info file is to be accessed. You can use aud_select_host() to select the host to be used.  If this argument is an empty string, aud_select_host() is called automatically to select a host name.
table_name	The name of the table with which the info file is associated. This takes the form ppmmfff, where pp is the package code, mmm is the module code, and fff is the file number.
compno	The company number.
info_hdr	The buffer that contains the header information to be written to the info file.
Return values

>0	success
 -1	error – possible reasons are:
– host not found
– table or information file does not exist
– error occurred while opening information file
– open file limit reached

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  macros (info header)
    Audit information:  sample program


aud_write_seq_hdr()

Syntax

long aud_write_seq_hdr( long seqid, const string seqhdr() )

Description

This writes header information to a specified sequence file. You can set the information for the sequence header with the sequence header macros.

The function writes the header information to the sequence file and to the associated info file.

Arguments

seqid	The sequence identifier returned by aud_open_audit() when the sequence file was opened.
seqhdr	The buffer that contains the header information to be written to the sequence file.
Return values

 0	success
-1	error; probably incorrect seqid

Context

3GL library function.

Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  macros (sequence header)
    Audit information:  sample program


Macros (info header)

Use these macros for mapping info header information. The ‘get’ macros take info_hdr as their input. This is filled by calling aud_read_info_hdr(). The 'set' macros update the info_hdr buffer. Use aud_write_info_hdr() to update the information file header itself.

aud_get_version()	string aud_get_version( string info_hdr() ) This returns the current version of the info file and related sequence files.
aud_get_tablename()	string aud_get_tablename( string info_hdr() ) This returns the name of the table to which the specified info file relates.
aud_get_compno()	long aud_get_compno( string info_hdr() ) This returns the company number of the table to which the info file relates.
aud_get_status()	long aud_get_status( string info_hdr() ) This returns the value of the status field in the info header. The status field indicates whether the sequence file reuse feature is enabled or disabled.
aud_get_from_seqno()	long aud_get_from_seqno( string info_hdr() ) This returns the starting number for sequence files related to the info file.
aud_get_to_seqno()	long aud_get_to_seqno( string info_hdr() ) This returns the maximum sequence number for sequence files related to the info file.
aud_get_curr_seqno()	long aud_get_curr_seqno( string info_hdr() ) This returns the sequence number of the current sequence file. This is the sequence file to which new audit information will be written.
aud_get_curr_security()	long aud_get_curr_security( string info_hdr() ) This returns the security permissions for the info file and associated sequence files. The return value can be a combination of the following values: AUD_SECU_NONE no permissions AUD_SECU_ALL        all permissions AUD_SECU_PRINT print permissions AUD_SECU_CLEAN      purge permissions AUD_SECU_MAINTAIN maintain permissions AUD_SECU_APPL_DEF application-defined permissions For example: long security security = aud_get_curr_security( info_hdr ) if (bit.and (security, AUD_SECU_NONE)) then | No permissions on info file else if (bit.and (security, AUD_SECU_ALL)) then | All permissions on info file else if (bit.and (security, AUD_SECU_PRINT)) then | Print permissions on info file endif if (bit.and (security, AUD_SECU_CLEAN)) then | Purge permissions on info file endif if (bit.and (security, AUD_SECU_MAINTAIN)) then | Maintain permissions on info file endif if (bit.and (security, AUD_SECU_APPL_DEF)) then | Application-defined permissions on file  endif endif endif
aud_get_max_audit_file_ size()	long aud_get_max_audit_file_size( string info_hdr() ) This returns the maximum size (in bytes) of sequence files related to the info file.
aud_set_status()	void aud_set_status( long status, string info_hdr() ) This stores the value of status in the status field of the info header.
aud_set_to_seqno()	void aud_set_to_seqno( long to_seq, string info_hdr() ) This stores the value of to_seq in the maximum sequence number field of the info header.
aud_set_curr_seqno()	void aud_set_curr_seqno( long c_seq, string info_hdr() ) This stores the value of the c_seq in the current sequence number field of the info header.
aud_set_max_audit_file_ size()	void aud_set_max_audit_file_size( long m_size, string info_hdr() ) This stores the value of m_size in the maximum file size field of the info header.
aud_set_security()	void aud_set_security( long c_sec, string info_hdr() ) This stores the value of c_sec in the security field of the info header. For a list of valid values, see aud_get_curr_security().
Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


Macros (sequence header)

Use these macros for mapping sequence header information. The ‘get’ macros take seq_hdr as their input. This is filled by calling aud_read_seq_hdr() or aud_read_info_seq_hdr( ). The 'set' macros update the seq_hdr buffer. Use aud_write_seq_hdr() or aud_update_infofile() to update the sequence header itself in the sequence file and info file respectively.

Dates are returned as UTC in the form YYYYMMDD. Times are returned as UTC in the form HHMMSS.

aud_get_app_info1() to aud_get_app_info4()	void aud_get_app_info1( string seq_hdr(),string app1(4) ) void aud_get_app_info2( string seq_hdr(),string app2(4) ) void aud_get_app_info3( string seq_hdr(),string app3(4) ) void aud_get_app_info4( string seq_hdr(),string app4(4) ) These fill their second argument with the application-specific information from the sequence header.
aud_get_creat_date()	string aud_get_creat_date( string seq_hdr() ) This returns the creation date (in UTC) of the sequence file. Use utc.to.local() to convert the UTC date to a local date.
aud_get_creat_time()	string aud_get_creat_time( string seq_hdr() ) This returns the creation time (in UTC) of the sequence file. Use utc.to.local() to convert the UTC time to local time.
aud_get_no_audit_flds()	long aud_get_no_audit_flds( string seq_hdr() ) This returns the number of audited fields in the sequence file.
aud_get_no_prim_flds()	long aud_get_no_prim_flds( string seq_hdr() ) This returns the number of primary key fields among the audited fields in the sequence file.
aud_get_no_trans()	long aud_get_no_trans( string seq_hdr() ) This returns the number of transactions in the sequence file.
aud_get_seqno()	long aud_get_seqno( string seq_hdr() ) This returns the sequence number of the sequence file.
aud_get_seq_status()	long aud_get_seq_status( string seq_hdr() ) This returns a value indicating the termination status of the sequence file. Possible values are: AUD_TERM_MAX_SIZE file terminated because it reached its maximum  size AUD_TERM_DD_CHGD file terminated because table definitions in data  dictionary have been changed AUD_TERM_USER_FRCD file forcibly terminated by user AUD_TERM_CORRUPT file terminated because of mismatch between  sequence headers in info file and sequence file AUD_SEQ_REMOVED sequence file removed using session  "ttaad4161m000" (Purge Audit Files) AUD_TERMINATE_VERSION file terminated because a new audit server  has been activated This value can be bitwise anded with predefined constants to determine the reason for termination of a particular sequence file. For example: long term_status term_status = aud_get_seq_status(seq_hdr) if ( bit.and (term_status,AUD_TERM_MAX_SIZE) ) then | Termination because of reaching max size. endif if ( bit.and (term_status,AUD_TERM_DD_CHGD) ) then | Termination because of dd change. endif if ( bit.and (term_status,AUD_TERM_USER_FRCD) ) then | Termination forced by user. endif
aud_get_seq_full_status()	long aud_get_seq_full_status( string seq_hdr() ) This returns the value of the status field in the sequence header. Note that you cannot use this value because the version information is included in the status. Use aud_get_seq_status() instead.
aud_get_seq_version()	long aud_get_seq_version( string seq_hdr() ) This returns the version of the sequence file as stored in the sequence header.
aud_get_term_date()	string aud_get_term_date( string seq_hdr() ) This returns the termination date (in UTC) of the sequence file (if the file is terminated). Use utc.to.local() to convert the UTC date to a local date.
aud_get_term_time()	string aud_get_term_time( string seq_hdr() ) This returns the termination time (in UTC) of the sequence file (if the file is terminated). Use utc.to.local() to convert the UTC time to local time.
aud_set_app_info1() to aud_set_app_info4()	void aud_set_app_info1( string app1(4), string seq_hdr() ) void aud_set_app_info2( string app2(4), string seq_hdr() ) void aud_set_app_info3( string app3(4), string seq_hdr() ) void aud_set_app_info4( string app4(4), string seq_hdr() ) These write application-specific information to seq_hdr.
aud_set_term_date()	void aud_set_term_date( string t_date(), string seq_hdr()) This stores the content of t_date in the termination date field of the sequence header.
aud_set_term_time()	void aud_set_term_time( string t_time(), string seq_hdr()) This stores the content t_time in the termination time field of the sequence header.
aud_set_seq_status()	void aud_set_seq_status( long st, string seq_hdr() ) This stores the content of st in the status field of the sequence header.
Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


Macros (transaction header)

Use these macros for mapping transaction header information. All the macros take tran_hdr as their input. This is filled by calling aud_read_tran() or aud_read_next_tran().

aud_get_tran_bytes()	long aud_get_tran_bytes( string tran_hdr() ) This returns the total size in bytes of the transaction data.
aud_get_tran_commit_date()	string aud_get_tran_commit_date( string tran_hdr() ) This returns the UTC commit date from the transaction header.
aud_get_tran_commit_time()	string aud_get_tran_commit_time( string tran_hdr() ) This returns the UTC commit time from the transaction header.
aud_get_tran_entries()	long aud_get_tran_entries( string tran_hdr() ) This returns the number of audited actions in the transaction.
aud_get_tran_id()	long aud_get_tran_id( string tran_hdr(), long g1, long g2) This reads the transaction id from the transaction header. The transaction id consists of two longs which together form a unique identification.
aud_get_tran_sess()	string aud_get_tran_sess( string tran_hdr() ) This returns the name of the session that committed the transaction.
aud_get_tran_status()	long aud_get_tran_status( string tran_hdr() ) This returns the commit status of the transaction. Possible values are: AUD_COMMITTED transaction committed AUD_ABORTED transaction canceled AUD_PREPARED it is not certain whether the transaction has been  committed or aborted
aud_get_tran_tuname()	string aud_get_tran_tuname( string tran_hdr() ) This returns the BAAN user name of the user who performed the transaction.
aud_get_tran_uuid()	long aud_get_tran_uuid( string tran_hdr() ) This returns the UNIX user id of the user who performed the transaction.
Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


Macros (transaction record)

Use these macros for mapping transaction records. All the macros take rec_buff as their input. This is filled by calling aud_read_audit_rec() or aud_read_next_audit_rec().

aud_get_rec_app_info()	void aud_get_rec_app_info( string appinfo(4), string rec_buff() ) This reads the application-specific information of the record into appinfo.
aud_get_rec_op_type()	string aud_get_rec_op_type( string rec_buff() ) This returns the type of action of the record. Possible values are: "I" insert record "D" delete record "U" update record "L" clear table "R" drop table "C" create table
aud_get_rec_seqno()	long aud_get_rec_seqno( string rec_buff() ) This retrieves the sequence number of the record within the transaction.
Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


Macros (transaction dates and times)

Use these macros to retrieve transaction dates and times. All the macros take tran_hdr as their input. This is filled by calling aud_read_tran() or aud_read_next_tran().

aud_get_tran_date_yyyy()	long aud_get_tran_date_yyyy( string tran_hdr() ) This retrieves the year value from transaction commit date. The year is represented by four digits.
aud_get_tran_date_mm()	long aud_get_tran_date_mm( string tran_hdr() ) This retrieves the month value from the transaction commit date.
aud_get_tran_date_dd()	long aud_get_tran_date_dd( string tran_hdr() ) This retrieves the day value from the transaction commit date.
aud_get_tran_time_hh()	long aud_get_tran_time_hh( string tran_hdr() ) This retrieves the hours value from the transaction commit time.
aud_get_tran_time_mm()	long aud_get_tran_time_mm( string tran_hdr() ) This retrieves the minutes value from the transaction commit time.
aud_get_tran_time_ss()	long aud_get_tran_time_ss( string tran_hdr() ) This retrieves the seconds value from the transaction commit time.
Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


Macros (dates and times)

The input to these macros is a date string in the form YYYYMMDD or a time string in the form HHMMSS.

aud_get_date_yyyy()	long aud_get_date_yyyy( string s_dat() ) This retrieves the year value from the date string s_dat. The year is represented by four digits.
aud_get_date_mm()	long aud_get_date_mm( string s_dat() ) This retrieves the month value from the date string s_dat.
aud_get_date_dd()	long aud_get_date_dd( string s_dat() ) This retrieves the day value from the date string s_dat.
aud_get_time_hh()	long aud_get_time_hh( string s_tim() ) This retrieves the hours value from the time string s_tim.
aud_get_time_mm()	long aud_get_time_mm( string s_tim() ) This retrieves the minutes value from the time string s_tim.
Related help topics

    Audit information:  overview
    Audit information:  synopsis
    Audit information:  sample program


Audit information: sample program

This sample program illustrates the general sequence of reading audit records in a sequence file and displaying audit field information. It also shows how to write application information to a sequence header.

Assume that the table has the following DD:

Field 1 : integer (2 bytes)
Field 2 : float   (4 bytes)

#include <bic_audlib>

#include <bic_audhdr.h>

long    seqid

long    seq_hdr_size

string  seq_hdr(1)  	  based

string  colnames(1,1)	  based

long    colinfo(1,1)  	  based

string  tran_hdr(AUD_TRAN_HDR_SIZE)

string  rec_buff(AUD_MAX_REC_SIZE)

long    no_recs

long    no_trans

long    audit_flds

string  appinfo(4)

string  values(AUD_MAX_FLD_SIZE,2)

long    type

| open a seqid to table aabdb000, company 0, sequence file 0

seqid = aud_open_audit( "", "aabdb000", 0, 0 )

if ( seqid = -1 ) then

error

endif

| get the size of the sequence file header

seq_hdr_size = aud_get_hdr_size( seqid )

alloc.mem( seq_hdr, seq_hdr_size )

| read the sequence file header

if ( aud_read_seq_hdr( seqid, seq_hdr ) = -1 ) then

error

endif

audit_flds = aud_get_no_audit_flds( seq_hdr )

no_trans = aud_get_no_trans( seq_hdr )

| write 16 bytes of application-specific information to seqhdr

appinfo(1) = "aaaa"

aud_set_app_info1(appinfo, seqhdr)

appinfo(1) = "aaaa"

aud_set_app_info2(appinfo, seqhdr)

appinfo(1) = "aaaa"

aud_set_app_info3(appinfo, seqhdr)

appinfo(1) = "aaaa"

aud_set_app_info4(appinfo, seqhdr)

alloc.mem( colnames, AUD_COL_NAME_LEN, audit_flds )

alloc.mem( colinfo, 3, audit_flds )

aud_get_audit_dd( seq_hdr, colnames, colinfo )

for i = 1 to no_trans

if ( aud_read_tran(seqid, i, tran_hdr) = -1 ) then

error

endif

| get number of records

no_recs = aud_get_tran_entries(tran_hdr)

for j = 1 to no_recs

| read audit records

if (aud_read_audit_rec(seqid,j,rec_buff) = -1) then

error

endif

for k = 1 to audit_flds

ind = aud_get_fld_values(k, colinfo, rec_buff, values)

if ( ind = 1 ) then

| both new and old values exist

type = colinfo(1,k)

print_value(type, values(1,1)) | print old value

print_value(type, values(2,1)) | print new value

endif

if ( ind = 0 ) then

| only one value exists

type = colinfo(1,k)

print_value(type, values(1,1)) | print unchanged value

endif

endfor

endfor

endfor

| write sequence header

if ( aud_write_seq_hdr(seqid, seq_hdr) = -1 ) then

error

endif

| close seqid

if ( aud_close_audit(seqid) = -1 ) then

error

endif

| Function to format and print the values

print_value( long type, const string values() )

{

float   fval

long    sval

on case type

DB.FLOAT:

fval = load.float( values(1) )

| print fval

DB.INTEGER:

sval = load.short( values(1) )

| print sval

...

endcase

}

Related help topics

    Audit information:  overview
    Audit information:  synopsis


Bit operations: overview and synopsis

Overview

Use these functions to compute binary bit operations on bit patterns. The bit patterns can be of type long or they can be hexadecimal constants. When using hexadecimal constants, these must begin with '0x'.

Synopsis

long	bit.and	( long pattern1, long pattern2 )
long	bit.exor	( long pattern1, long pattern2 )
long	bit.in	( long pattern1, long pattern2 )
long	bit.inv	( long pattern1 )
long	bit.or	( long pattern1, long pattern2 )
long	bit.shiftl	( long bitpattern, long no_of_bits )
long	bit.shiftr	( long bitpattern, long no_of_bits )


bit.and(), bit.exor(), bit.in(), bit.inv(), bit.or()

Syntax

long	bit.and( long pattern1, long pattern2 )

long	bit.exor( long pattern1, long pattern2 )

long	bit.in( long pattern1, long pattern2 )

long	bit.inv( long pattern1 )

long	bit.or( long pattern1, long pattern2 )

Description

These functions compute binary bit operations on one or two bit patterns. Both patterns must be of type long; a long is 32 bits.

Return value

The return value is the result of the operation. It is always a long value.

Examples

The following examples illustrate how these functions work.

Function	long bit.and(5, 6)	long bit.exor(5, 6)	long bit.or(5, 6)
Computation and result	0101 0110 0100	0101 0110 0011	0101 0110 0111
Function	long bit.inv(6)	long bit.in(5, 6)	long bit.in(4, 6)
Computation and result	0110 1001	0101  0110 FALSE (0)	0100  0110 TRUE (<>0)
You can specify hexadecimal constants as parameters instead of bit patterns. These constants must start with '0x'. The following example illustrates this.

Function	result = bit.and( 0x01b8, 0x2cdf )
Computation and result	00000000000110111000 00100000110011011111 00000000000010011000  (hexadecimal 0x00098; decimal 152)
Notes

You can also use the mathematical operators +, -, and / for computing bit operations. The operands must be declared as variables of type SET. You can declare such a variable only with a domain declaration where the domain is of database type SET.

•	The operator + equates to the function bit.or().

•	The operator * equates to the function bit.and().

•	The operator / equates to the function bit.exor().

•	The operator - equates to a special form of the function bit.and(). That is, a-b for sets equates to bit.and(a, bit.inv(b)) for longs. If the SET variables are represented as longs, the following example explains the - operator:

0101
0110
0001

•	When using SET constants as operands, the keyword IN equates to the function bit.in(). The following example illustrates the use of bit operations on SET constants. Note that EMPTY is a keyword for the empty set; all bits are zero (set value 0).

domain cf a,b 	| domain declaration: cf, a, and b are of type SET

                  	| see also the function cf$()

    a = empty            | clear a

    a = cf.dim           | set a to dim

    a = a + cf.reverse   | add/enable reverse

    a = a - cf.dim       | delete/disable dim

    a = a / cf.underline | toggle underline

    a in b

    if ( a in b ) then

         message( "All elements of a are in b" )

    endif

    if ( cf.reverse * a ) then

         message( "a contains reverse" )

    endif

    if ( a ) then

         message( "a contains at least one argument" )

    endif

    if ( a=empty ) then

         message( "a is an empty set" )

    endif

The following diagrams illustrate how set operations work (a and b are sets):

Context

Bshell functions.

Related help topics

    Bit operations:  overview and synopsis


bit.shiftl(), bit.shiftr()

Syntax

long bit.shiftl( long bitpattern, long no_of_bits )

long bit.shiftr( long bitpattern, long no_of_bits )

Description

These shift a bit pattern to the left or to the right. The bit pattern can be of type long, or it can be a hexadecimal constant. When using a hexadecimal constant, it must begin with '0x'. The no_of_bits argument indicates the number of bits that the pattern must be shifted.

Return value

The result of the shift operation as a decimal value.

Context

Bshell functions.

Example

long result

result = bit.shiftr( 0x63f, 2 )

Related help topics

    Bit operations:  overview and synopsis


Business Chart Manager: overview

The Business Chart Manager is a tool that displays data graphically, in charts. The Business Chart Manager supports a variety of chart types, including, pie, line, symbol, high-low, and layer. The input can consist of data from a database, a file, or some other appropriate source.

In this document, the term graph refers to a chart drawn within a coordinate system with two or more axes. The term pie refers to a circular chart, divided into segments, which illustrates the quantitative relationship between different groups of data.

Example

This example illustrates how the Business Chart Manager builds a chart.

Source data

The following figures represent the quantity of goods sold per month by three different companies.

	Company 1	Company 2	Company 3
Jan	40	30	10
Feb	20	25	15
Mar	20	40	10
. . .	. . .	. . .	. . .
Dec	30	35	20

The Business Chart Manager organizes this data into twelve categories (one for each month) and three series (one for each company). The data value for a particular data category and data series can be represented as a data point in a chart.

Axis-oriented graph

The sample data illustrated above can be plotted on a single axis-oriented graph. In the Business Chart Manager, a graph can has up to four axes, as follows:

      category axis	 –	  x-axis
      data axis	 –	  y-axis
      series axis	 –	  z-axis
      data axis II	 –     second y-axis

The x-axis represents the data categories (in this case, the months) against which each data value is plotted. The y-axis represents the value scale against which each data value is plotted. The values for each data series (in this case, the different companies), are differentiated in a variety of ways, depending on the chart type used. In a line graph, a line joins the data values for a particular series. The various series can be differentiated by using different line types and/or colors. On a bar graph, a vertical or horizontal bar represents each data value. Bars representing the same series have the same color, pattern, and width.

The data axis II is used in combination with data axis I when two (or more) different series must be drawn on different scales in order to facilitate comparison.

Pie Chart

A pie chart can represent only a single data series. The sample data illustrated above can be represented by either twelve or three pie charts, depending on whether the data is sorted by category or series:

Sorted by category	Each pie chart illustrates the relationship between the different series (that is, the companies) for one category. This results in twelve pie charts, one for each category (that is, month).  Each diagram has three segments, representing the three data series. The size of each segment is proportional to the value of the data point in relation to the total in the category (month).  This option facilitates comparison of the three companies for each month.
Sorted by series	Each pie chart illustrates the different category values within one series (that is, a company). This results in three pie charts, one for each company.  Each diagram has twelve segments, representing the twelve categories. The size of the segments depends on the data value of each category as a percentage of the total of all data values in the series.
Related help topics

    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


Creating a Chart Manager client application

The window preferences, fonts, charts, chart types, and option sets for a particular Chart Manager session are defined in a Chart Manager application. When you start the Chart Manager from a program script, you specify the particular Chart Manager application you want to use.

To create a Chart Manager application, use the following steps.

1	Start the Chart Manager Application Data session (ttchm1500m000)).

2	Create a new application record.

3	Define the option sets (Chart-Specific Options).

4	Create a default window setting (Window Preferences).

5	Start the Chart Manager from the Chart Manager Application Data session (ttchm1500m000).

6	Create the chart types required to present the data.

By using the Business Chart Manager functions described in this document, you can create a client application that starts the Business Chart Manager and that sends data to and receives data from the Business Chart Manager. For further details on using the Chart Manager, see the session help.

The Business Chart Manager functions fall into three groups:

Input functions	These send data from the application to the Chart Manager. The function names in this group end in .in
Output functions	These functions send data from the Chart Manager to the application. The function names in this group end in .out. Within this group, there is a further subdivision:  • Functions with the extension .first retrieve the first value for a particular object from the Chart Manager. • Functions with the extension .next retrieve the next value for a particular object from the Chart Manager. Before you can call a .next function, you must already have retrieved the first value by calling the relevant .first function.
Other functions	Miscellaneous functions. For example, control functions or functions to start and end the Business Chart Manager.
Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Business Chart Manager: example
    Business Chart Manager: glossary


Business Chart Manager: synopsis

long	chm.axis.in	( long axis_name, long logarithmic,   long log_base, long divisions,   double divisionstep, double   intersection, string division_set(16) )
long	chm.axis.out	( long axis_name, ref long logarithmic,   ref long log_base, ref long divisions,   ref double divisionstep, ref double   intersection, ref string division_set() )
long	chm.chartman	( string chart_manager(80), string    title(80), string user(14),    string owner(14) [, string version(4),   string release(2), string cust(4)] )
long	chm.check	( string chart_manager(14), string    user(14), string chart_type(16) )
long	chm.data.in	( double series_value, double    category_value, long data_number,   double data_value, long footnote_no,   [ long duplicate_option ] )
long	chm.data2domain.in	( double series_value )
long	chm.delete.data	( )
long	chm.delete.data2domains	( )
long	chm.delete.footnotes	( )
long	chm.delete.projections	( )
long	chm.delete.sets	( )
long	chm.disconnect	( )
long	chm.domain.in	( long domain_name, long data_type,   string set_name(16), string title(16),   string unit_label(16), double from_value,   double to_value, double interval,   string display_format(80 )
long	chm.domain.out	( long domain_name, ref long data_type,   ref string set_name(), ref string    title(), ref string unit_label(),   ref double from_value, ref double    to_value, ref double interval,   ref string display_format() )
long	chm.draw	( [ double cat_from_value ] )
long	chm.first.data.out	( long option, ref double series_value,   ref double category_value,   ref long data_number, ref double    data_value, ref long footnote_no )
long	chm.first.data2domain.out	( ref double series_value )
long	chm.first.footnote.out	( ref long footnote_no,   ref string footnote_text() )
long	chm.first.projection.out	( ref double projection_point,   ref long footnote_no )
long	chm.first.set.out	( string set_name(16),    ref long element_number,    ref string element_name() )
long	chm.footnote.in	( long footnote_no,   string footnote_text(80) )
long	chm.get.request	( ref long chart_no,    ref double category_from_value,   ref double category_to_value )
long	chm.new	( string chart_name(16),   ref string chart_type() )
long	chm.next.data.out	( long option, ref double series_value,   ref double category_value,   ref long data_number, ref double    data_value, ref long footnote_no )
long	chm.next.data2domain.out	( ref double series_value )
long	chm.next.footnote.out	( ref long footnote_no,    ref string footnote_text() )
long	chm.next.projection.out	( ref double projection_point,   ref long footnote_no )
long	chm.next.set.out	( string set_name(16),   ref long element_number,   ref string element_name() )
long	chm.open	( string chart_name(16) )
long	chm.projection.in	( double projection_point,    long footnote_no )
long	chm.remove	( string chart_manager(80), string    owner_from(14), string owner_to(14) )
void	chm.scale.axis	( double from_value, double to_value,   long divisions, double factor,   ref double domain_from_value,   ref double domain_to_value,   ref double divisionstep )
long	chm.select	( string chart_manager(80),    string title(80), long mode,    string user(14), string owner(14),   ref string chart_name(16),   ref string chart_type(16) )
long	chm.set.in	( string set_name(16), ref long    element_number, string element_name(80) )
long	chm.set.option	( long option, long flag )
long	chm.set.timer	( long time )
long	chm.title.in	( string main_title(80),    string sub_title(80) )
long	chm.title.out	( ref string main_title(),    ref string sub_title() )
Related help topics

    Business Chart Manager: overview
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.axis.in()

Syntax

long chm.axis.in( long axis_name, long logarithmic, long log_base, long divisions, double divisionstep, double intersection, string division_set(16) )

Description

This defines an axis for an axis-oriented graph.

Arguments

axis_name	This specifies which axis is being defined. The possible values are: CHM_SERIES_AXIS CHM_CATEGORY_AXIS CHM_DATA_AXIS CHM_DATA2_AXIS
logarithmic	If logarithmic scaling is required, set this to true. For linear scaling, set it to false.
log_base	For logarithmic scaling, this indicates the log base that must be used. The argument is ignored if logarithmic is set to false.
divisions	This specifies the number of divisions into which the axis must be divided. The domain definition determines the start and end values for the axis. The Business Chart Manager calculates the scaling on the basis of the number of divisions specified here and the interval between divisions, as specified by divisionstep. If either divisions or divisionstep is set to 0, the Business Chart Manager calculates both arguments itself.
divisionstep	This specifies the interval between two divisions on the axis. You can use chm.scale.axis() to calculate the division step.
intersection	This indicates the value on the data axis where the category and data axes intersect.
division_set	Normally, the values or labels from the associated domain are displayed on the axis. You can override this by specifying the name of a different set here. You create the set with chm.set.in().
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.axis.out()

Syntax

long chm.axis.out( long axis_name, ref long logarithmic, ref long log_base, ref long divisions, ref double divisionstep, ref double intersection, ref string division_set() )

Description

This retrieves information about a specified axis from the Business Chart Manager. If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.

Arguments

axis_name	This specifies the axis about which you want to retrieve information. The possible values are: CHM_SERIES_AXIS CHM_CATEGORY_AXIS CHM_DATA_AXIS CHM_DATA2_AXIS
logarithmic	This returns true if the axis uses logarithmic scaling, or false if it uses linear scaling.
log_base	If logarithmic returns true, this argument returns the log base used.
divisions	This returns the number of divisions into which the axis is divided.
divisionstep	This returns the interval between two divisions on the axis.
intersection	This returns the value on the data axis where the category and data axes intersect.
division_set	If the labels or values displayed on the axis are provided by a set created by chm.set.in() instead of by the domain associated with the axis, this argument returns the name of the set used.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.chartman()

Syntax

long chm.chartman( string chart_manager(80), string title(80), string user(14), string owner(14), [, string version(4), string release(2), string cust(4)] )

Description

This starts the Business Chart Manager for a specified Business Chart Manager application, user, owner, and, optionally, VRC code.

Window preferences, fonts, charts, chart types, and option sets are defined by Business Chart Manager application. For a particular application, authorizations, option sets, and window preferences are defined by user (see the Chart Manager Application Data session (ttchm1500m000)). You can also assign the same option set to a group of users. The owner is the creator of the charts; the charts are stored under the owner name (for example, a login name). Users can change only those charts they have created themselves.

Arguments

chart_manager	This specifies the name of a Business Chart Manager application. This corresponds to a particular record in the Chart Manager application data session (ttchm1500m000). The name takes the following format: pp package code mmm module code xxx the name of the application
title	This specifies the window title.
user	This specifies the name of the relevant user.
owner	This specifies the name of the relevant owner.
version, release, cust	It is possible to assign a VRC code to a chart. These optional arguments specify the relevant VRC codes.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.check()

Syntax

long chm.check( string chart_manager(14), string user(14), string chart_type(16) )

Description

This checks whether a specified user can access a particular chart type within a specified Business Chart Manager application.

Arguments

chart_manager	This specifies the name of a Business Chart Manager application. This corresponds to a particular record in the Chart Manager application data session (ttchm1500m000). The name takes the following format: pp package code mmm module code xxx the name of the application
user	The user name.
chart_type	The chart type.
Return values

true	the user can select the specified chart type
false	the user cannot select the specified chart type

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.data.in()

Syntax

long chm.data.in( double series_value, double category_value, long data_number, double data_value, long footnote_no, [ long duplicate_option ] )

Description

This sends a data point to the Business Chart Manager. You must call this function for each data point that you want to send.

Arguments

series_value	This specifies the series to which the data point belongs.
category_value	This specifies the category to which the data point belongs.
data_number	If there is more than one data point per category (a high-low graph, for example), this indicates the sequence number of the data point within the category. If there is only one data point per category, the sequence number is 1.
data_value	The data value for the specified series and category. The data value must lie within the scope of the data domain.
footnote_no	If you want to include a footnote for the data point, specify the number of the footnote here. Use chm.footnote.in() to create the footnote.
duplicate_option	If the new data value has the same series_value, category_value and data_number as another data value, use this optional argument to indicate the action that must be taken. The possible values are: CHM_OVERWRITEDUPL overwrite the existing data value CHM_IGNOREDUPL  ignore this data value CHM_INSERTDUPL increase data_value by 1 CHM_ADDDUPL double the value of data_value
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.data2domain.in()

Syntax

long chm.data2domain.in( double series_value )

Description

Data domain II defines the start value, end value, and step size for the data II axis. You use the second data domain and axis when you want to draw two different series to different scales in order to facilitate comparison. You use chm.domain.in() to define a domain. You use this function to specify which series uses the second data domain. By default, the other series uses the normal data domain.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.delete.data()

Syntax

long chm.delete.data()

Description

This removes from memory the data points added by chm.data.in(). The function cannot delete data points that the application has already saved.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.delete.data2domains()

Syntax

long chm.delete.data2domains()

Description

This removes the second data domain from memory. The series that uses the second data domain will use the first data domain after this function has been called.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.delete.footnotes()

Syntax

long chm.delete.footnotes()

Description

This removes from memory the footnotes added by chm.footnote.in(). The function cannot delete values that the application has already saved.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.delete.projections()

Syntax

long chm.delete.projections()

Description

This removes from memory the projection points added by chm.projection.in(). The function cannot delete values that the application has already saved.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.delete.sets()

Syntax

long chm.delete.sets()

Description

This removes from memory the set elements added by chm.set.in(). The function cannot delete values that the application has already saved.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.disconnect()

Syntax

long chm.disconnect()

Description

This disconnects the Business Chart Manager from the application, enabling independent user interaction. The user can now work with the Chart Manager and modify data, without affecting the data in the application.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

See also

chm.get.request()

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.domain.in()

Syntax

long chm.domain.in( long domain_name, long data_type, string set_name(16), string title(16), string unit_label(16), double from_value, double to_value, double interval, string display_format(80) )

Description

This defines a domain, which specifies a start value, an end value, and a step value for a particular axis. The domain determines which values are legal for the axis.

Arguments

domain_name	This specifies the name of the domain. The possible values are: CHM_SERIES_DOMAIN CHM_CATEGORY_DOMAIN CHM_DATA_DOMAIN CHM_DATA2_DOMAIN
data_type	This specifies the domain type. The possible values are: CHM_REAL  real (the domain consists of integers and fractions) CHM_INTEGER integer (the domain consists of integers) CHM_SET   enumerated set (the domain consists of a set of labels)
set_name(16)	When the domain type is CHM_SET, this specifies the name of the relevant set. For other domain types, specify an empty string [""] here. Use chm.set.in() to define the set.
title, unit_label	These specify the axis title and the unit of measurement that must be displayed in the chart to describe the corresponding axis.
from_value, to_value	These specify the start and end values of the domain. You can calculate these values with the function chm.scale.axis().
interval	This specifies the interval between domain values.
display_format	For domains of type CHM_REAL or CHM_INTEGER, you must specify a display format. See edit().
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.domain.out()

Syntax

long chm.domain.out( long domain_name, ref long data_type, ref string set_name(), ref string title(), ref string unit_label(), ref double from_value, ref double to_value, ref double interval, ref string display_format() )

Description

This retrieves information from the Business Chart Manager about a specified domain. If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.

Arguments

domain_name	This specifies the name of the domain for which you want to retrieve information. The possible values are: CHM_SERIES_DOMAIN CHM_CATEGORY_DOMAIN CHM_DATA_DOMAIN CHM_DATA2_DOMAIN
data_type	This returns the domain type. The possible values are: CHM_REAL  real (the domain consists of integers and fractions) CHM_INTEGER integer (the domain consists of integers) CHM_SET   enumerated set (the domain consists of a set of labels)
set_name(16)	When the domain type is CHM_SET, this returns the name of the relevant set. For other domain types, this returns an empty string [""] here.
title, unit_label	These return the axis title and the unit of measurement that are displayed in the chart to describe the corresponding axis.
from_value, to_value	These return the start and end values of the domain.
interval	This returns the interval between domain values.
display_format	For domains of type CHM_REAL or CHM_INTEGER, this returns the display format. See edit().
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.draw()

Syntax

long chm.draw( [ double cat_from_value ] )

Description

This signals to the Business Chart Manager that it must start (re)drawing the chart. The optional argument enables you to specify the value of the first category for which the chart must be (re)drawn.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.first.data.out()

Syntax

long chm.first.data.out( long option, ref double series_value, ref double category_value, ref long data_number, ref double data_value, ref long footnote_no )

Description

This retrieves information from the Business Chart Manager about the first data point in the current chart. If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.

Use chm.next.data.out() to retrieve information about the next and subsequent data points.

Arguments

option	Use this argument to indicate whether the function retrieves data for the absolute first data point or for the first data point that has been modified. The possible values are: CHM_ALL_DATA CHM_CHANGED_DATA
series_value	This returns the series to which the data point belongs.
category_value	This returns the category to which the data point belongs.
data_number	If there is more than one data point per category (a high-low graph, for example), this returns the sequence number of the data point within the category. If there is only one data point per category, the sequence number is 1.
data_value	This returns the value of the data point.
footnote_no	This returns the number of the footnote (if any) associated with the data point.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.first.data2domain.out()

Syntax

long chm.first.data2domain.out( ref double series_value )

Description

Use this to check which is the first graph series that is linked to the second data domain of the current chart.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.first.footnote.out()

Syntax

long chm.first.footnote.out( ref long footnote_no, ref string footnote_text() )

Description

This returns information about the first footnote in the current chart. Use chm.next.footnote.out() to retrieve information about subsequent footnotes in the chart.

Arguments

footnote_no	This returns the footnote number.
footnore_text	This returns the footnote text.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.first.projection.out()

Syntax

long chm.first.projection.out( ref double projection_point, ref long footnote_no )

Description

This retrieves information about the first projection point in the current chart. Use chm.next.projection.out() to retrieve information about subsequent projection points in the chart.

Arguments

projection_point	This returns the position on the category axis where the projection point occurs.
footnote_no	This returns the number of the footnote associated with the projection point. It returns 0 if there is no footnote associated with the projection point.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.first.set.out()

Syntax

long chm.first.set.out( string set_name(16), ref long element_number, ref string element_name() )

Description

This retrieves information about the first element in the specified set. Use chm.next.set.out() to retrieve information about subsequent elements in the set.

Arguments

set_name	The name of the set for which you want to retrieve information.
element_no	This returns the number of the first element in the set.
element_name	This returns the name of the first element in the set.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.footnote.in()

Syntax

long chm.footnote.in( long footnote_no, string footnote_text(80) )

Description

This function defines a footnote that can be used to annotate a data point or projection point.

Arguments

footnote_no	The footnote number.
footnote_text	The footnote text.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.get.request()

Syntax

long chm.get.request( ref long chart_no, ref double category_from_value, ref double category_to_value )

Description

This retrieves a request from the Business Chart Manager. After calling the function, the application waits for a signal from the Chart Manager that a request is ready. It can then check the return value of the function to determine the nature of the request. The application must react to the request appropriately.

Arguments

chart_no	This returns the ID of the relevant chart, as returned by chm.open().
category_from_value  category_to_value	These indicate the range of data the Chart Manager is asking for. These arguments are relevant only when the return value is CHM_SOURCE_IN.
Return Values

CHM_ABORT	Quit the Business Chart Manager.
CHM_SOURCE_IN	Send data to the Chart Manager. This value is returned when the user chooses the IN command on the Chart Manager's File menu.
CHM_SOURCE_OUT	Retrieve data from the Chart Manager. This value is returned when the user chooses the OUT command on the Chart Manager's File menu.
CHM_TIMER	Execute actions after the interval set by chm.set.timer().
< value >	This is the ID of an application option defined in the Application Options session (ttchm1120s000). When this value is returned, the application must execute the specific actions related to the particular application option.
Context

3GL library function.

Example

long request

double category_from, category_to

repeat

request = chm.get.request(chartno, category_from, category_to)

on case request

case CHM_SOURCE_IN:

....

case CHM_SOURCE_OUT:

....

case CHM_TIMER:

chm.draw()

break

case 200:

start.session(MODAL, "ppmodggggmooo", "", "")

endcase

until (request = CHM_ABORT)

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.new()

Syntax

long chm.new( string chart_name(16), ref string chart_type() )

Description

This creates a new chart. The chart is not saved until the user executes the Save command.

Arguments

chart_name	The name of the new chart.
chart_type	The chart type. If you do not specify an existing chart type, the Chart Manager selects the default chart type, as defined in the Chart Manager Application session (ttchm1500m000).
Return values

 0	success
-1	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.next.data.out()

Syntax

long chm.next.data.out( long option, ref double series_value, ref double category_value, ref long data_number, ref double data_value, ref long footnote_no )

Description

You use chm.first.data.out() to retrieve information about the first data point in the current chart. You use chm.next.data.out() to retrieve information about the next data point in the same chart. To retrieve information about all subsequent data points, you can place this function in a loop that executes as long as the return value is CHM_OK.

If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.

Arguments

option	Use this argument to indicate whether the function retrieves data for the absolute next data point or for the next data point that has been modified. The possible values are: CHM_ALL_DATA CHM_CHANGED_DATA
series_value	This returns the series to which the data point belongs.
category_value	This returns the category to which the data point belongs.
data_number	If there is more than one data point per category (a high-low graph, for example), this returns the sequence number of the data point within the category. If there is only one data point per category, the sequence number is 1.
data_value	This returns the value of the data point.
footnote_no	This returns the number of the footnote (if any) associated with the data point.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.next.data2domain.out()

Syntax

long chm.next.data2domain.out( ref double series_value )

Description

You use chm.first.data2domain.out() to retrieve the sequence number of the first graph series that is linked to the second data domain of the current chart. You use chm.next.data2domain.out() to retrieve the sequence number of the next graph series that is linked to the second data domain of the same chart. To retrieve information about all subsequent graph series that are linked to the second domain, you can place this function in a loop that executes as long as the return value is CHM_OK.

If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.next.footnote.out()

Syntax

long chm.next.footnote.out( ref long footnote_no, ref string footnote_text() )

Description

Use chm.first.footnote.out to retrieve information about the first footnote in the current chart. Use chm.next.footnote.out() to retrieve information about the next footnote in the current chart. To retrieve information about all subsequent footnotes in the chart, you can place this function in a loop that executes as long as the return value is CHM_OK.

If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.

Arguments

footnote_no	This returns the footnote number.
footnore_text	This returns the footnote text.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.next.projection.out()

Syntax

long chm.next.projection.out( ref double projection point, ref long footnote_no )

Description

Use chm.first.projection.out to retrieve information about the first projection point in the current chart. Use chm.next.projection.out() to retrieve information about the next projection point in the same chart. To retrieve information about all subsequent projections in the chart, you can place this function in a loop that executes as long as the return value is CHM_OK.

If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.

Arguments

projection_point	This returns the position on the category axis where the projection point occurs
footnote_no	This returns the number of the footnote associated with the projection point. It returns 0 if there is no footnote associated with the projection point.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.next.set.out()

Syntax

long chm.next.set.out( string set_name(16), ref long element_number, ref string element_name() )

Description

Use chm.first.set.out() to retrieve information about the first element in a specified set. Use chm.next.set.out() to retrieve information about the next element in the set. To retrieve information about all subsequent elements in the set, you can place this function in a loop that executes as long as the return value is CHM_OK.

Arguments

set_name	The name of the set for which you want to retrieve information.
element_no	This returns the number of the next element in the set.
element_name	This returns the name of the next element in the set.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.open()

Syntax

long chm.open( string chart_name(16) )

Description

This opens the specified chart with its associated data.

Return values

>0	the ID of the opened chart
  0	error; the Business Chart Manager cannot find or cannot open the specified chart

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.projection.in()

Syntax

long chm.projection.in( double projection_point, long footnote_no )

Description

This defines a projection point for the current chart.

Arguments

projection_point	This specifies the position on the category axis where the projection point occurs.
footnote_no	This specifies the number of the footnote (if any) associated with the projection point. Specify 0 here, if you do not want to associate a footnote with the point. You use chm.footnote.in() to create footnotes.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.remove()

Syntax

long chm.remove( string chart_manager(80), string owner_from(14), string owner_to(14) )

Description

This removes all charts from the chart list for the specified users. It is not necessary to start the Business Chart Manager in order to use this function.

Arguments

chart_manager	This specifies the name of a relevant Business Chart Manager application. The name takes the following format: pp package code mmm module code xxx the name of the application
owner_from, owner_to	These specify the range of users for whom the charts are to be removed.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.scale.axis()

Syntax

void chm.scale.axis( double from_value, double to_value, long divisions, double factor, ref double domain_from_value, ref double domain_to_value, ref double divisionstep )

Description

This generates a scaling based on the minimum and maximum data values to be presented by the graph and on the number of divisions required. You can use the returned domain_from_value, domain_to_value, and divisionstep as inputs to chm.domain.in() and chm.axis.in().

Arguments

from_value, to_value	Use these to specify the minimum and maximum data values to be presented by the graph.
divisions	Use this to specify the number of divisions required. The axis will be divided into the specified number of divisions.
factor	This is a user-specified factor that determines the preciseness of the divisions.  The larger the factor, the more closely the domain_from_value and the domain_to_value approach the from_value and to_value, and the greater the number of figures after the decimal point in the axis labels. If the factor is small (for example, between 0 and 2), the figures in the axis labels are rounded to integers, tens, or hundreds, depending on the from_value, to_value and number of divisions.
domain_from_value domain_to_value	The function calculates and returns these values, which are the minimum and maximum values of the domain. These will be the start and end points of the axis.
divisionstep	This returns the size of the steps that separate the divisions on the axis.
Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.select()

Syntax

long chm.select( string chart_manager(80), string title(80), long mode, string user(14), string owner(14), ref string chart_name(16), ref string chart_type(16) )

Description

This starts a session in which the user can select or create another chart or chart type. It is not necessary to start the Business Chart Manager in order to use this function.

Arguments

Arguments

chart_manager	This specifies the name of a Business Chart Manager application. This corresponds to a particular record in the Chart Manager application data session (ttchm1500m000). The name takes the following format: pp package code mmm module code xxx the name of the application
title	This specifies the window title.
mode	This specifies whether the session enables selection or creation of a chart or chart type. The possible values are: CHM_SELECT_CHARTTYPE select another chart type CHM_CREATE_CHART create another chart CHM_SELECT_CHART select another chart CHM_CREATESELECT_CHART create or select another chart
user	This specifies the name of the user. The session is started with this user's option set.
owner	This specifies the name of the relevant owner. When a list of charts is called, the system displays the charts that this user owns.
chart_name	This returns the name of the selected chart.
chart_type	This returns the type of the selected chart.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.set.in()

Syntax

long chm.set.in( string set_name(16), ref long element_number, string element_name(80) )

Description

This adds an element to a specified set.

Arguments

set_name	The name of the set to which the element is to be added.
element_no	The sequence number of the element within the set.
element_name	The description of the element.
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.set.option()

Syntax

long chm.set.option( long option, long flag )

Description

Use this to switch an application option on and off. Applications options are defined in the Applications Options session (ttchm1120s000). Actions can be linked to an application option using the chm.get.request function.

Arguments

option	The option that must be switched on or off.
flag	This specifies whether the option is be switched on or off. The possible values are: true the option is enabled false the option is disabled
Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.set.timer()

Syntax

long chm.set.timer( long time )

Description

This starts a timer. The Business Chart Manager sends a CHM_TIMER signal to the application every specified number of milliseconds. When the application retrieves the signal, it can perform appropriate actions (see chm.get.request()). You can turn off the timer by calling chm.set.timer() with a time of zero.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.title.in()

Syntax

long chm.title.in( string main_title(80), string sub_title(80) )

Description

This function defines a main title and a subtitle for the current chart.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


chm.title.out()

Syntax

long chm.title.out( ref string main_title(), ref string sub_title() )

Description

This retrieves the main title and subtitle of the current chart. If the client application modifies the information and saves it to the source table or file, the new information is included the next time the chart is started.

Return values

CHM_OK	success
CHM_ERROR	error

Context

3GL library function.

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example
    Business Chart Manager: glossary


Business Chart Manager: example

#define CHART.NAME                   "RESULT"

#define CHART.APPLICATION            "ttchmtest"

#include <bic_chartman>

long     chart.data(2,4)

function main()

{

long chno

string chart_type(16)

| start Chart manager

chm.chartman(CHART.APPLICATION, "Title", "user1", "")

chno = chm.open(CHART.NAME, chart_type)

if chno > 0  then

send.chart.data()          | define data

chm.draw()                 | draw chart

get.chart.data(chno)       | store data

endif

}

| define data, send it to Chart manager

function void send.chart.data( )

{

double     series, category

long       no_1, no_2, no_3, no_4

| Chart title

chm.title.in("Financial Results", "")

| Set definitions

no_1 = 1

no_2 = 2

no_3 = 3

no_4 = 4

chm.set.in("Series", no_1, "Company 1")

chm.set.in("Series", no_2, "Company 2")

chm.set.in("Categories", no_1, "Qrtr I")

chm.set.in("Categories", no_2, "Qrtr II")

chm.set.in("Categories", no_3, "Qrtr III")

chm.set.in("Categories", no_4, "Qrtr IV")

| Domain definitions

chm.domain.in(CHM_SERIES_DOMAIN, CHM_SET,

                      "Series", "Companies", "Unit", 1.0, 2.0, 1.0, "")

chm.domain.in(CHM_CATEGORY_DOMAIN, CHM_SET,

                      "Categories", "Quarters", "1993", 1.0, 4.0,

                      1.0, "")

chm.domain.in(CHM_DATA_DOMAIN, CHM_REAL, "", "Result", "x 1000",
0.0, 100.0, 0.01, "ZZZZZ9V,99")

| Axis data

chm.axis.in(CHM_SERIES_AXIS, FALSE, 0, 2, 1.0, 0.0, "")

chm.axis.in(CHM_CATEGORY_AXIS, FALSE, 0, 4, 1.0, 0.0, "")

chm.axis.in(CHM_DATA_AXIS, FALSE, 0, 10, 10.0, 0.0, "")

get.data.from.table(chart.data())          | user defined

for series = 1 to 2

for category = 1 to 4                 | Data values

chm.data.in(series, category, 1,

chart.data(series, category), 0)

endfor

endfor

}

| get data from Chart manager

function void get.chart.data( long chart_no)

{

long      datn, footnote_no, ret, request

double    catv, data, serv, category_from, category_to

repeat

request = chm.get.request( chart_no,category_from,

                                category_to)

on case request

case CHM_SOURCE_OUT:	| OUT-command Chart manager

          	ret = chm.first.data.out(CHM_ALL_DATA,

                           serv, catv, datn, data, footnote_no)

while (ret = CHM_OK)

chart.data(serv, catv) = data

ret = chm.next.data.out(CHM_ALL_DATA,

                              serv, catv, datn, data, footnote_no)

endwhile

put.data.in.table(chart.data()) | user defined

break

endcase

until (request = CHM_ABORT)

}

Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: glossary


Business Chart Manager: glossary

axis	One of two or more reference lines, positioned at right angles to each other, against which data values are plotted. In mathematics, X, Y, and Z axes are used. The Chart Manager uses four axes:  category axis  as x axis  data axis  as y axis  series axis  as z axis  data axis II  as second y axis   You use data axis II when you want to draw two series to different scales in the same graph.
axis label	This indicates the meaning or value of a major division on the axis.
back plane	The plane behind the graph (that is, the background).
bar chart	A graph in which a vertical or horizontal bar represents each data value. Bars representing the same series have the same color, pattern, and width. The higher the bar, the higher the value at that point. The bar width and thickness (3D only) can be set per series. Bars representing different series can overlap wholly or partially.
bottom plane	The plane below the graph.
category	Measuring points are divided into categories. For example, when plotting the quarterly expenditures in a particular year, each quarter is regarded as an information category. Category values are measured on the x-axis. In pie charts, each segment can be regarded as a category, depending on the way the data is sorted.
chart	A chart is a graphical presentation of information. A chart displays a pie and/or graph including title, legend, and footnotes.
Chart Manager	A tool within the BaanERP application, which presents data in graphs and pie charts.
Chart Manager application	A collection of charts, user option sets and window preferences. The Chart Manager needs this information for its operation.
chart type	The chart type specifies the attributes of a chart – for example, the graph type, the thickness of lines and bars, colors, and fonts. These settings are data- independent.
data	The information presented in the chart – for example, the domains used, the data point values, and so on.
data label	The name or the value of a data point.
data number	The sequence number of a data point within a category.
data point	A point in the chart representing a value, and displayed, for example, as a symbol, a bar, a pie segment, or a kink in a line.
division	The axes of a graph are divided into a number of major and minor divisions. These divisions are marked by ticks. Grids and labels are assigned by major division.
division labels	Special labels at major divisions. These replace the values from the domain associated with the axis.
domain	A range with a start value, end value and step size. These indicate which values are legal. There are data, category, and series domains.
domain type	In the Chart Manager there are three domain types:  integer the domain consists of a series of integers  real the domain consists of both fractions and integers  enumerated set   the domain consists of a set of labels
exploded	A detached pie segment. You can use this option to draw attention to one of the segments. The distance from the segment to the pie center can be specified as a percentage of the pie's radius.
footnote	Information relating to a data point or projection point. Footnotes are placed in a separate box in the chart.
footnote label	The text placed in a footnote box.
footnote number	The number or the series of asterisks placed at the data point or projection point and referring to the same number or series of asterisks in the footnote box.
graph	A graphical presentation of information drawn within a set of axes.
grid	A pattern of lines at right angles to each other and the axis. They connect the values in the graph with the points on the vertical and horizontal axes. Grid lines are drawn at major divisions only.
hilo (high-low) graph	A hilo graph contains multiple data points per category, each data point having its own meaning. For each category there may, for example, be a data point representing the maximum value and one representing the minimum value. This type of graph is very suitable, for example, for monitoring stock market developments.
hilo selects	Symbols in a hilo graph indicating where in a category a particular data point is located.
histogram	A histogram consists of a set of stacked blocks, each block representing a particular data value.
intersection point	The value on the data axis where category axis and data axis intersect.
legend	An explanation of the chart. The legend contains a sample of each series (bar, line, pie, etc.) in the chart with a description of the series.
line	In a line graph, the data points for each series are connected by a line. There are four types of lines: curve, linear, stepped and wire. Line graphs are mainly used to show trends.
linear	A line graph in which data points are joined by straight lines.
logarithmic	A scaling in which the axis is divided into equal sections that do not represent equal steps in a scale of values. Instead the divisions increase by a specified factor. Logarithmic scales are useful when there is a wide range of values.
option set	A number of possibilities or limitations per user or group.
owner	The creator of the chart. Users can modify only their own charts.
percent label	The proportion of the total pie value represented by a pie segment.
pie	Circular diagram divided into segments showing the quantitative relationship between different series or categories. The pie represents the total value. Pies are the only graphs that are not axis-oriented.
pie segment	A part of the pie. Each segment represents a percentage of the total pie.
projection	A way of presenting a graph in which the graph is split up in different parts referred to as projection areas. Each projection area has its own attributes. A series can be shown by a different graphical means in each projection area. The use of several projection areas is a convenient means to distinguish between measured and expected (projected) values in a series. Projection areas are separated by a projection line, which is placed at right angles to the category axis.
projection point	The point on the category axis where the projection line and the category axis intersect.
scale	The size of the graph or pie as a percentage of the box size.
second data axis	The fourth axis of the Chart Manager's coordinate system. It has the same dimensions as the data axis (y-axis). The second data axis is always used in combination with the first data axis when two (or more) different series must be drawn to different scales in the one chart.
second data domain	The second data domain is used for the second data axis.
series	A set of related data points that are linked graphically. In a line graph, for instance, they are connected by a line. This line indicates which data points constitute one series.
set	A group of labels.
side plane	The plane beside the graph.
stepped	A line graph in which the line consists of horizontal and vertical sections. Stepped lines draw attention to changes in the level of data values.
symbol	A sign indicating where a data point is located.
ticks	Signs indicating the divisions on the axis. Ticks at major divisions are larger than those at minor divisions.
title	In the Chart Manager there are four types of titles:  • The description of the Chart Manager application. This appears at the top of the form together with the package and module codes.  • Main title (placed in the title box).  • Subtitle (placed in the title box).  • Axis title. This is the description of an axis and is the same as the domain label.
unit label	The description of the unit (measure or quantity) in which categories, data or series are expressed. The label is placed beside the relevant axis.
wire	A line graph in which the data points of different series are connected by lines, the result being a kind of mountain landscape. This is possible in 3-D graph only.
Related help topics

    Business Chart Manager: overview
    Business Chart Manager: synopsis
    Creating a Chart Manager client application
    Business Chart Manager: example


Character-based windows: overview and synopsis

Overview

This section describes functions that are relevant to character-based windows only. You do not use these functions to handle graphical windows.

Note

The functions for sending data and instructions to the screen or printer all return a string that you can print by calling the print() function or that you can use in a string expression. When you use print() with these functions, only the internal screen is updated. You must call refresh() to update the terminal screen.

Synopsis

string	bc$	( long type, long rows, string barcode(.) )
string	bg$	( long color )
void	box	( long box_x, long box_y, long box_width,    long box_height, long mode )
string	bs$	( [num_expr] )
string	cf$	( num_expr )
void	change.window	( long wind_id )
void	cl.screen	( long column, long row, long no_of_cols,    long no_of_rows )
string	cp$	( long column, long row )
string	cr$	( )
string	cs$	( [num_expr] )
long	current.window	( )
void	data.input	( string options(.), ref string result(.),    string default(.) [, ref long    event(EVTMAXSIZE), ref long char_value )
void	del.window	( long wind_id )
string	delch$	( num_expr )
string	deleteln$	( num_expr )
void	dump.window	( [long wind_id] )
string	el$	( )
string	es$	( )
string	ff$	( )
string	fg$	( long color )
void	first.window	( long wind_id )
string	fs$	( [num_expr] )
long	get.col	( )
void	get.cp	( ref long x, ref long y )
long	get.row	( )
long	get.window.attrs	( long wind_id, ref long attrs(WINMAXSIZE) )
string	insch$	( string_expr )
string	insertln$	( string_expr )
string	keyin$	( [99] )
void	last.window	( long wind_id )
string	lf$	( [num_expr] )
void	map.window	( long wind_id )
long	mark.handler	( ref long mark.table() )
void	move.window	( long col, long row )
long	new.window	( long height, long width, long row, long col )
void	no.scroll	( long wind_id )
string	pc$	( num_expr )
string	pf$	( num_expr )
void	refresh	( [long wind_id] )
void	resize.window	( long width, long height )
void	scroll	( long wind_id )
void	set.bg.color	( long wind_id, long color )
void	set.fg.color	( long wind_id, long color )
string	sf$	( num_expr )
long	sub.window	( long parent_wind, long height, long width,    long row, long col )
string	tab$	( num_expr )
void	unmap.window	( long wind_id )
void	wrebuild	( long mode )


bc$()

Syntax

string bc$( long type, long rows, string barcode(.) )

Description

Use this to create a barcode of the specified type.

Arguments

type	This points to a shell script that generates the barcode. The script is stored in the barcode directory; this is specified in the printer information file. The script names take the form ‘typexx’, where xx is a two digit number. For example ‘type02’. You specify the two digit number in this argument.
rows	The height of the barcode, as a number of lines.
barcode	The string that must be converted to a barcode and printed.
Context

Bshell function.

Example

print bc$( 02, 2, input_string )

refresh()

Related help topics

    Character-based windows: overview and synopsis


bg$()

Syntax

string bg$( long color )

Description

Use this to set the background color of the current window. The color argument can have the following values:

CW.BLACK     CW.BLUE             CW.GREEN        CW.CYAN
CW.RED         CW.MAGENTA     CW.YELLOW      CW.WHITE

Context

Bshell function.

Example

print bg$( CW.RED )

refresh()

Related help topics

    Character-based windows: overview and synopsis


box()

Syntax

void box ( long box_x, long box_y, long box_width, long box_height, long mode )

Description

This draws a rectangle on the screen. If the specified box does not fit in the current window, only the part that does fit is displayed.

Changes become visible on screen only after calling refresh().

Arguments

box_x, box_y	The screen co-ordinates for the top left corner of the box.
width, height	The width and height respectively of the box.
mode	0 only the box is drawn; no other screen modifications are made 1 the interior of the box is cleared 2 the box is drawn dimmed; no other screen modifications are made  3 the box is drawn dimmed and its interior is cleared In addition to the above values, you can specify special effects such as reversed and blinking. For a list of possible attributes, see cf$(). To use these attributes, you must multiply the attribute number by 10, and then add one of the above mode values.
Context

Bshell function.

Examples

| This draws the largest possible box
box( 1, 1, 80, 23, mode )

refresh()

| This draws a box with the reverse attribute

cf_mode = 41      | attribute 4 (* 10) + mode 1

box( 2, 2, 40, 13, cf_mode )

refresh()

Related help topics

    Character-based windows: overview and synopsis


bs$()

Syntax

string bs$( [long num_expr] )

Description

Use this to position the cursor num_expr positions to the left. If you do not specify the num_expr argument, the default number of positions is 1.

Context

Bshell function.

Example

print bs$(4)	| Move cursor 4 positions to the left

refresh()

Related help topics

    Character-based windows: overview and synopsis


cf$()

Syntax

string cf$( long attribute_code )

Description

Use this to send a control code to the current window or printer. All characters after the command are printed or displayed in the font associated with the control code. To reset the font to normal, call cf$(0).

The following codes are available:

Code	Screen	Printer
0	normal	normal
1	bold	bold
2	blinking	bold
3	bold blinking	bold
4	reverse	reverse
5	bold reverse	bold reverse
6	blinking reverse	bold reverse
7	bold blinking reverse	bold reverse
8	underscore	underscore
9	underscore bold	underscore bold
10	underscore blinking	underscore bold
11	underscore bold blinking	underscore bold
12	underscore reverse	underscore reverse
13	underscore reverse bold	underscore bold reverse
14	underscore reverse blinking	underscore bold reverse
15	underscore reverse bold blinking	underscore bold reverse
Note

If the printer is unable to print in reverse, text is printed in bold instead. Blinking is possible only on ASCII terminals.

Context

Bshell function.

Example

| To screen

print cf$(4),"This is reversed printing on the screen",cf$(0)

| To printer

spool.pr.line = cf$(4)&"Printed reverse"&cf$(0)

spool.line()

Related help topics

    Character-based windows: overview and synopsis


change.window()

Syntax

void change.window( long wind_id )

Description

This makes the specified window current. This does not affect the screen display.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


cl.screen()

Syntax

void cl.screen( long column, long row, long no_of_cols, long no_of_rows )

Description

This clears a specified area of the current window. The changes become visible on screen only after you call refresh().

Arguments

column, row	The column and row co-ordinates for the top left corner of the area to be cleared.
no_of_cols	The number of columns to be cleared.
no_of_rows	The number of rows to be cleared.
Context

Bshell function.

Example

cl.screen( 1, 5, 80, 6 )

refresh()

Related help topics

    Character-based windows: overview and synopsis


cp$()

Syntax

string cp$( long column, long row )

Description

Use this to position the cursor at the specified column and row. The cursor position is always relative to the upper left corner of the current window.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


cr$()

Syntax

string cr$()

Description

Use this to send a carriage return (without a line feed) to the screen or printer. The cursor is positioned at column 1 of the current line.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


cs$()

Syntax

string cs$( [num_expr] )

Description

Use this to change the window size and/or clear the window. The num_expr argument can have one of the the following values:

0	clear current window
1	clear current window (default value)
2	set screen to 80 columns and clear current window
3	set screen to 132 columns and clear current window
4	set screen to 80 columns without clearing current window
5	set screen to 132 columns without clearing current window
Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


current.window()

Syntax

long current.window()

Description

This returns the identification number of the current window.

A window becomes current when it is created or when you call change.window(). All actions to the screen (print() for example) are sent to the current window.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


data.input()

Syntax

void  data.input( string options(.), ref string result(.), string default(.) [, ref long event(EVTMAXSIZE), ref long char_value )

Description

This reads data from the keyboard.

If the function specifies a default value, that value is displayed on screen. The value is accepted when the user presses ENTER. However, if the user enters a character at the first position in the field, the default value is deleted.

Normally, characters typed by the user are inserted before the current cursor position. However, if option ‘C’ is included in the options argument, characters typed by the user are inserted at the current cursor position.

Users can edit the default value or make minor corrections to the string entered (before they press ENTER) by using the following keys:

→	Scroll right.
←	Scroll left.
DEL	Delete character at cursor position. Characters to the right of the deleted character are moved one position to the left. If the cursor is positioned beyond the last character, this character is deleted and the cursor moves one position to the left. Pressing DEL in an empty field redisplays the default value.
CTRL+X	Clear field.
TAB	Delete all characters from the cursor position to the end of the field.
Arguments

options	This argument must either be empty or it must contain 5 parts separated by one or more spaces.  If it is empty, the following input characteristics apply: - no fill characters are displayed - input starts at the current cursor position - all characters are permitted - the maximum number of characters that can be input is 132 If it is not empty, it must include the following five items: - the starting column - the starting row - the minimum length of the string to be read - the maximum length of the string to be read - zero or more options The following options are available. You can specify them with or without separating spaces.
	+ABIDI	Supports input of bidirectional data.
	B	Empty result not permitted.
	C	Overwrite mode.
	E	E and e permitted as input; always converted to capital letter.
	F	Effect of ‘.’ (moving cursor to previous field) is switched off.
	FILL='.'	The specified character is used as the fill character for the field. By default, the fill character defined for the user is used.
	G	A floating-point number is expected.
	K	Converts all uppercase characters to lower case.
	L='..'	Characters specified by this option are interpreted as the end of input. When the user enters one of these characters, data.input()returns immediately without waiting for the user to press ENTER. The char_value argument returns the decimal value of the character that was typed.  You can specify any combination of the following characters with this option: - ASCII characters A - Z, a - z, and others such as % & ! ?. - Octal representation of characters; these must start with ‘\0’. For example: \01 and \012. - Decimal representation of characters; these must start ‘\’. For example: \1 and \12. - Hexadecimal representation of characters; these must start with ‘\0x’. For example: \0x1and \0x12. - Control characters. For example: ^B and ^F. - Backslash (\\). - Circumflex (\^). - Escape (\E or \e). - Space (\s). - New  line,(\n). - Return (\r). - Form feed (\f). - Previous line (\v). - Backspace (\b). The following example specifies the following characters: A, B, C, octal 13, Control+N, Control+P, Esc, new line, and backslash. L='ABC\013^N^P\E\n\\'
	LEN='..'	This specifies the available space on the terminal screen. If the cursor is at the beginning or end of the available space, the field scrolls horizontally.
	N	An integer number is expected.
	P	Entered characters are suppressed. No default value or fill characters are displayed on screen.
	R	An automatic carriage return is executed when the last character is entered (that is, when the string is full).
	T='..'	A string specifying all valid input characters. All other characters are invalid.
	U	Converts all lowercase characters to uppercase.
	V='..'	A string specifying all invalid characters. All other characters are valid.
	Y	Result must be ‘Y’ or ‘N’. Lowercase characters are converted             to uppercase,  so ‘y’ and ‘n’ are also permitted. If these characters are not specified with T=’YyNn’, other characters are also permitted. But after the user presses ENTER, the message ‘Only Y/N allowed’ is displayed.
	>	After the user presses ENTER, the input string is right justified.
	<	After the user presses ENTER, the input string is left justified.
result	This returns the value typed by the user. The argument must be declared as a one-dimensional string.
default	A default string that is displayed on screen.
event	If the function is stopped as a result of an event, that event is stored in this argument. See Events.
char_value	If the function is stopped by input of a special character, the character typed is stored in this argument.
See also

keyin$()

Context

Bshell function.

Example

string result(1)

data.input("0 0 1 1 UE T='YN'", result, "")

Related help topics

    Character-based windows: overview and synopsis


del.window()

Syntax

void del.window( long wind_id )

Description

This deletes the specified window. When you delete the current window, the next window in the internal window stack becomes the current one. The screen is not refreshed automatically.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


delch$()

Syntax

string delch$( num_expr )

Description

Use this to delete num_expr characters, from the current cursor position to the right. The text following the deleted characters shifts num_expr positions to the left.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


deleteln$()

Syntax

string deleteln$( num_expr )

Description

Use this to delete num_expr lines, from the current line down. Lines below the deleted ones are moved up.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


dump.window()

Syntax

void dump.window( [long wind_id] )

Description

This sends the specified window to the printer spooler. If you do not specify a window, the ID of the current window is sent. The user must choose the required spooler.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


el$()

Syntax

string el$()

Description

Use this to erase all characters from the current character to the end of the line. The cursor position is not changed.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


es$()

Syntax

string es$( )

Description

Use this to erase all characters from the current cursor position to the end of the screen. The cursor position is not changed.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


ff$()

Syntax

string ff$( )

Description

Use this to send a form feed to the printer. The result of this function cannot be sent to the screen.

Context

Bshell function.

Example

spool.pr.line = ff$()

spool.line()

Related help topics

    Character-based windows: overview and synopsis


fg$()

Syntax

string fg$( long color )

Description

Use this to set the foreground color of text, starting at the current cursor position.

The color argument can have the following values:

CW.BLACK     CW.BLUE             CW.GREEN        CW.CYAN
CW.RED         CW.MAGENTA     CW.YELLOW      CW.WHITE

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


first.window()

Syntax

void first.window( long wind_id )

Description

This places the specified window above all other windows on the screen. The window is also placed at the first position in the internal window stack. The alterations become visible on screen only when you call refresh() or wrebuild(0).

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


fs$()

Syntax

string fs$( [num_expr] )

Description

Use this to move the cursor num_expr positions to the left. If you exclude the num_expr argument, the cursor is moved one space to the left.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


get.col()

Syntax

long get.col()

Description

This retrieves the number of the column where the cursor is currently positioned. The function uses get.cp(), so it is slower than that function.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


get.cp()

Syntax

void get.cp( ref long x, ref long y )

Description

This stores the coordinates of the current cursor position in the x and y arguments.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


get.row()

Syntax

long get.row()

Description

This retrieves the number of the row where the cursor is currently positioned. The function uses get.cp(), so it is slower than that function.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


get.window.attrs()

Syntax

long get.window.attrs( long wind_id, ref long attrs(WINMAXSIZE) )

Description

This stores attributes of the specified window in the attrs array. The maximum number of attributes that can be retrieved is indicated by the predefined constant WINMAXSIZE.

You can retrieve the attributes with the following predefined variables:

 win.parent( attrs )	window ID of parent window

 win.x( attrs )	x-position of window

 win.y( attrs )	y-position of window

 win.width( attrs )	width of window

 win.height( attrs )	height of window

 win.border.width( attrs )	border width of window (gwindow only)

 win.background( attrs )	background color of window

 win.event.mask( attrs )	mask indicating the events generated by the window

Return values

TRUE	success
FALSE	error

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


insch$()

Syntax

string insch$( string_expr )

Description

Use this to insert the result of string_expr at the current cursor position. The characters to the right of the cursor are moved string_expr positions to the right.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


insertln$()

Syntax

string insertln$( string_expr )

Description

Use this to insert the result of string_expr on a new line, above the current line. The current and succeeding lines are moved down.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


keyin$()

Syntax

string keyin$( [99] )

Description

This reads the first character from the keyboard buffer. If there is no character in the buffer, the function waits until one is entered.

If you include the optional argument, the function performs a non-blocking read. If there is no character in the buffer, the function returns immediately with an empty string. This form of the function is used for interrupting a batch process when the user presses a key.

The function converts the following function keys to ASCII characters:

Key 	ASCII

KEY_LEFT	BS	     8	   ^H

KEY_RIGHT	FF	     12	    ^L

KEY_UP	VT	     11	   ^K

KEY_DOWN	LF	     10	   ^J

KEY_INSERT	EM	     25	   ^Y

Return values

The character read from the event queue. If the returned string contains multiple bytes, the character is s multibyte character. If the character is a function that cannot be converted, the function returns an empty string.

Context

Bshell function.

See also

Events
data.input()

Example

repeat

...

until (keyin$(99)=chr$(27)) | until <Esc> is pressed

Note that the above example is very time consuming.

Related help topics

    Character-based windows: overview and synopsis


last.window()

Syntax

void last.window( long wind_id )

Description

This places the specified window below all other windows on the screen. The window is also placed at the last position in the internal window stack. The alterations become visible on screen only when you call refresh() or wrebuild(0).

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


lf$()

Syntax

string lf$( [num_expr] )

Description

Use this to send one or more line feeds to the screen or printer. The cursor is moved down num_expr lines. If you do not specify a number of lines, the cursor is moved down one line.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


map.window()

Syntax

void map.window( long wind_id )

Description

This makes the specified window visible, without changing the order of the windows.

Context

Bshell process.

Related help topics

    Character-based windows: overview and synopsis


mark.handler()

Syntax

long mark.handler( ref long mark.table() )

Description

This enables a user to mark one or more records on an ASCII form. On return, the mark.table argument indicates which records are marked. Each element in the mark.table array corresponds to a record on the form. If an array element is set to 1, the corresponding record is marked. If it set to 0, the corresponding array element is not marked.

The predefined variables marked and mark.status are not affected by this function.

Return values

0	no records marked
1	one or more records marked

Context

4GL library function.

You can use this function only in 4GL scripts, and only in choice and form sections of those scripts. You cannot use it in programs of type 4.

See also

mark.occ()

Example

| if records 3 and 8 are marked, the following is true

| mark.table(3) = 1

| mark.table(8) = 1

| other elements are 0 (false)

for i=1 to filled.occ

if mark.table(i) then

do.occ(i, some_function)

endif

endfor

Related help topics

    Character-based windows: overview and synopsis


move.window()

Syntax

void move.window( long col, long row )

Description

This moves the current window to a specified position (relative to the top left corner of the parent window). There is no need to refresh the window.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


new.window()

Syntax

long new.window( long height, long width, long row, long col )

Description

This creates a new window. The new window automatically becomes the current window.

Arguments

height, width	The height and width of the new window.
row, column	These indicate the position of the top left corner of the new window, relative to the top left corner of the parent window.
Return values

The window ID for the new window.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


no.scroll()

Syntax

void no.scroll( long wind_id )

Description

This disables scrolling for the specified window.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


pc$()

Syntax

string pc$( num_expr )

Description

Use this to set certain printer codes. The following printer codes are available:

1	paper bin 1
2	paper bin 2
3	paper bin 3
4	paper bin 4
5	landscape
6	portrait
7	usr1
8	usr2
.	.
.	.

22	usr16

You define codes 9 to 22 in the printer information file for the particular printer (for example, $BSE/lib/printinf/m/m290).

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


pf$()

Syntax

string pf$( num_expr )

Description

Use this to change the printer font settings. The following settings are available:

1	large
2	small
3	middle
4	dblwide
5	nlq
6	italic
7	superscript
8	subscript
9	font1
10	font2
.	.
.	.
24	font16

You define settings 9 to 24 in the printer information file of the particular printer (for example, $BSE/lib/printinf/m/m290).

 Context

Bshell function.

Example

spool.pr.line = pf$(2)

spool.line()             | Set printer to small font

Related help topics

    Character-based windows: overview and synopsis


refresh()

Syntax

void refresh( [long wind_id] )

Description

This copies the internal screen to the terminal screen. The internal screen is modified by any function which sends data to the screen (for example, print(), box(), map.window()). The terminal screen is updated only after you call refresh().

If you specify a window ID, the specified window is refreshed. But the window sequence is not changed. If you do not specify a window ID, the current window is refreshed and placed above all other windows on the screen.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


resize.window()

Syntax

void resize.window( long width, long height )

Description

This resizes the current window. You must specify the new width and height in pixels. There is no need to refresh the window.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


scroll()

Syntax

void scroll( long wind_id )

Description

This enables scrolling for the specified window. By default, windows do not scroll.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


set.bg.color()

Syntax

void set.bg.color( long wind_id, long color )

Description

This sets the background color of a specified ASCII window. The color argument can have the following values:

CW.BLACK     CW.BLUE             CW.GREEN        CW.CYAN      CW.GRAY
CW.RED         CW.MAGENTA     CW.YELLOW      CW.WHITE

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


set.fg.color()

Syntax

void set.fg.color( long wind_id, long color )

Description

This sets the foreground color of a specified ASCII window. The color argument can have the following values:

CW.BLACK     CW.BLUE             CW.GREEN        CW.CYAN      CW.GRAY
CW.RED         CW.MAGENTA     CW.YELLOW      CW.WHITE

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


sf$()

Syntax

string sf$( num_expr )

Description

Use this to set all text on the screen to bold. Use sf$(0) to reset the screen to normal.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


sub.window()

Syntax

long sub.window( long parent_wind, long height, long width, long row, long col )

Description

This creates a new window in the specified parent window.

Arguments

parent_window	The ID of the parent window.
height, width	The height and width of the new window.
row, col	These indicate the position of the top left corner of the new window, relative to the top left corner of the parent window.
Return values

The window ID for the new window.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


tab$()

Syntax

string tab$( num_expr )

Description

Use this to position the cursor at a specified column in the current window. If you use this function in the variable spool.pr.line for the function spool.line(), the printer is set to column num_expr.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


unmap.window()

Syntax

void unmap.window( long wind_id )

Description

This hides the specified window.

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


wrebuild()

Syntax

void wrebuild( long mode )

Description

This redraws the entire screen. The mode argument can have one of the following values:

0	all windows are refreshed
1	the screen is cleared and all windows are rebuilt

Context

Bshell function.

Related help topics

    Character-based windows: overview and synopsis


Client file access: overview

Use these functions to perform various operations on client files – for example:

•	to open, read, write to, close, and delete files on a client

•	to transfer files between client and server

•	to retrieve client file information

•	to create and delete directories on a client

•	to start an application on a client

Note

You can use these functions only with the BW interface, and not with BI.

Related help topics

    Client file access: synopsis


Client file access: synopsis

long	app_start	( string commandline, string directory,   string stdin, string stdout,    string stderr )
long	app_status	( long app.id )
long	client2server	( string source, string dest, long text.mode   [, long rm.file]    [, long progress.window] )
long	create.local.directory	( string dirent )
long	remove.local.directory	( string dirent )
void	remove.local.file	( string filename )
void	seq.close.local	( long lfn )
long	seq.fstat.local	( string filename, ref long nr.bytes )
long	seq.open.local	( string filename, string mode(2)   [, long remove.after.use] )
long	seq.read.local	( ref string buf, ref long size, long lfn )
long	seq.write.local	( string buf, long size, long lfn )
long	server2client	( string source, string dest, long text.mode   [, long progress.window] )
Related help topics

    Client file access: overview


app_start()

Syntax

long app_start( string commandline, string directory, string stdin, string stdout, string stderr )

Description

This starts the application specified in the commandline argument. It returns an ID for the started application. You can subsequently use this ID as the app.id argument in the app_status() function.

Arguments

commandline	This specifies the command that starts the application. If commandline does not include a directory path, Windows searches for the executable file in the following directories, in the order shown below: 1 The directory where BW is loaded. 2 The Windows system directory. 3 The Windows directory. 4 The directories listed in the PATH environment variable.
directory	The default working directory for the application.
stdin	The standard input file name.
stdout	The standard output file name.
stderr	The standard error file name.
Notes

If commandline specifies the name of a nonexecutable file, Windows starts the application with which the file name extension is associated. For example, if commandline is c:\temp\file.txt, and .txt is associated with the Notepad application, Windows will start Notepad. Because users can change the association of a file name extension, you cannot predict which application will start.

This functionality is not available when you specify standard input, output, and error files.

Return values

>=0	success; identification number of the started application is returned
  <0	error (that is, the negative value of the system error)

Context

ttdllbw library function.

Related help topics

    Client file access: overview
    Client file access: synopsis


app_status()

Syntax

long app_status( long app.id )

Description

This retrieves information about a specified application.

Arguments

app.id	The ID of the application for which you want to retrieve information, as returned by app_start().
Return values

<>0	success; application is running
    0	error;  application is not running – probably crashed after activating

Context

ttdllbw library function.

Related help topics

    Client file access: overview
    Client file access: synopsis


client2server()

Syntax

long client2server( string source, string dest, long text.mode [, long rm.file] [, long progress.window] )

Description

This copies a specified file from the client to the server. The function supports long file names.

Arguments

source	The source file name, on the client.
dest	The destination file name, on the server.
text.mode	This is a boolean value that specifies whether the file is to be copied in text or binary mode: <>0 text mode     0 binary mode
rm.file	Use this optional argument to specify whether the source file must be deleted after it has been copied: <>0 source file is deleted     0 source file is not deleted
progress.window	Use this optional argument to specify whether a progress indicator must be displayed to indicate the progress of the copy action: <>0 progress indicator is displayed     0 progress indicator is not displayed
Notes

In order to use a progress indicator, you must first create it with create.progress.indicator(). You then use change.progress.indicator() to change its value. If you specify the PROGRESS.STOP and/or PROGRESS.CANCEL modes when creating the indicator, the user can stop or cancel the copy operation before it has completed. In both cases, the destination file is deleted.

Return values

  0	success
  1	error; process canceled by the user
<0	error; source file not copied to the destination file

Example

client2server ("C:\Program Files\Test.txt2", bse.tmp.dir$() & "/test1.txt",
false, false)

Context

ttdllbw library function.

Related help topics

    Client file access: overview
    Client file access: synopsis


create.local.directory()

Syntax

long create.local.directory( string dirent )

Description

This creates a specified directory on a client system. You must have write permission in the parent directory to do this. Access permissions for the new directory are set to read, write, and execute for all users.

The function supports long file names.

Arguments

dirent	The directory name. This must include the full path to the directory, including the drive name. For example:  create.local.directory("C:/Program Files/mydir")
Return values

    0	success
<>0	error; probably no permission

Context

ttdllbw library function.

Related help topics

    Client file access: overview
    Client file access: synopsis


remove.local.directory()

Syntax

long remove.local.directory( string dirent )

Description

This deletes a specified directory on the client system. The function supports long file names.

Arguments

dirent	The directory name. The name must include the full path to the directory, including the drive name. For example:  remove.local.directory("C:/Program Files/Mydir")
Return values

    0	success
<>0	error; probably no permission

Context

ttdllbw library function.

Related help topics

    Client file access: overview
    Client file access: synopsis


remove.local.file()

Syntax

void remove.local.file( string filename )

Description

This deletes a specified file on the client system. The function supports long file names.

Arguments

filename	The name of the file that must be deleted. The name must include the full path to the file, including the drive name. For example:  remove.local.file ("C:/Program Files/Mydir/Myfile.txt").
Context

ttdllbw library function.

Related help topics

    Client file access: overview
    Client file access: synopsis


seq.close.local()

Syntax

void seq.close.local( long lfn )

Description

This empties the buffers associated with the specified file and closes the file. If the remove.after.use flag was set when the file was opened, the file is removed after it is closed.

Arguments

lfn	The file pointer to the file that must be closed, as returned by seq.open.local() when the file was opened.
Notes

You cannot use seq.*() functions in combination with the seq.*.local() functions. So, you cannot use seq.close.local() on a file that was opened with seq.open().

Context

ttdllbw library functions.

Related help topics

    Client file access: overview
    Client file access: synopsis


seq.fstat.local()

Syntax

long seq.fstat.local( string filename, ref long nr.bytes )

Description

This retrieves information about a specified file on a client system. The function supports long file names.

Arguments

filename	The name of the file. If you do not specify a path name, the file is searched for in the directory where BW is loaded.
nr.bytes	This returns the size of the file in bytes.
Notes

You cannot use seq.*() functions in combination with the seq.*.local() functions. So, you cannot use seq.fstat.local() on a file that was opened with seq.open().

Return values

>=0	success
  <0	error; probably file does not exist

Context

ttdllbw library function.

Example

seq.fstat.local("C:\Program Files\Test.txt", len.in.bytes)

Related help topics

    Client file access: overview
    Client file access: synopsis


seq.open.local()

Syntax

long seq.open.local( string filename, string mode(2), [long remove.after.use] )

Description

This opens a specified file on the client system. It returns a file pointer, which you can use to identify the file in subsequent operations. The function supports long file names.

Arguments

filename	The name of the file that must be opened. If you do not specify a path name, the file is searched for in the directory where BW is loaded.
mode	The mode in which the file must be opened. This can be one of the following options: “r” Open for reading. “w” Create for writing. “a” Open for writing at end of file, or create for writing. In addition, you can add "t" to any of the above options if you want the file to be opened in text mode.
remove.after.use	Use this optional argument to specify whether or not the file must be removed after it has been closed by seq.close.local(): <>0  file is removed     0 file is not removed
Note

You cannot use seq.*() functions in combination with the seq.*.local() functions. So, you cannot use seq.seek() or seq.rewind(), for example, on a file that was opened with seq.open.local().

Return values

  >0	success; file pointer is returned
<=0	error; file could not be opened

Context

ttdllbw library function.

Example

seq.open.local("C:\Program Files\Test.txt", "rt", false)

Related help topics

    Client file access: overview
    Client file access: synopsis


seq.read.local()

Syntax

long seq.read.local( ref string buf, ref long size, long lfn )

Description

This reads a specified number of bytes from a specified file into buf.

Arguments

buf	This returns the data read from the file.
size	This returns the number of bytes read from the file.
lfn	The file pointer, as returned by seq.open.local() when the file was opened.
Note

You cannot use seq.*() functions in combination with the seq.*.local() functions. So, you cannot use seq.read.local() on a file that was opened with seq.open().

Return values

>=0	success
  <0	error; probably lfn not connected

Context

ttdllbw library function.

Related help topics

    Client file access: overview
    Client file access: synopsis


seq.write.local()

Syntax

long seq.write.local( string buf, long size, long lfn )

Description

This writes data from the specified buffer to the specified file, beginning at the current file position.

Arguments

buf	The data that must be written to the file.
size	The number of bytes that must be written to the file.
lfn	The file pointer, as returned by seq.open.local() when the file was opened.
Note

You cannot use seq.*() functions in combination with the seq.*.local() functions. So, you cannot use seq.write.local() on a file that was opened with seq.open().

Return values

>=0	success
  <0	error; probably lfn not connected

Context

ttdllbw library function.

Related help topics

    Client file access: overview
    Client file access: synopsis


server2client()

Syntax

long server2client( string source, string dest, long text.mode, [long progress.window] )

Description

This copies a specified file from the server to the client. The function supports long file names.

Arguments

source	The source file name, on the server.
dest	The destination file name, on the client.
text.mode	This is a boolean value that specifies whether the file is to be copied in text or binary mode: <>0 text mode     0 binary mode
progress.window	Use this optional argument to specify whether a progress indicator must be displayed to indicate the progress of the copy action: <>0 progress indicator is displayed     0 progress indicator is not displayed
Notes

In order to use a progress indicator, you must first create it with create.progress.indicator(). You then use change.progress.indicator() to change its value. If you specify the PROGRESS.STOP and/or PROGRESS.CANCEL modes when creating the indicator, the user can stop or cancel the copy operation before it has completed. In both cases, the destination file is deleted.

Return values

  0	success
  1	error; process canceled by the user
<0	error; source file not copied to the destination file

Example

server2client( bse.tmp.dir$() & "/test1.txt", "C:\Program Files\Test.txt",
false, false )

Context

ttdllbw library function.

Related help topics

    Client file access: overview
    Client file access: synopsis


Colors: overview

Use the rgb() function to compose colors by specifying their red, green, and blue intensities. You can then use these colors, for example, when creating graphical objects such as windows, push buttons, labels, and so on.  Use the other functions to retrieve the red, green, or blue intensity of an existing color.

On a monochrome display, colors are converted to fill patterns. On a 16-color display, the closest match to the composed color is used. Use get.display() to check the number of colors available on the display.

In addition to composing your own colors, you can use the following predefined colors:

RGB.BLACK
RGB.MAGENTA
RGB.RED
RGB.BLUE
RGB.GREEN
RGB.WHITE
RGB.YELLOW
RGB.GRAY
RGB.CYAN

Related help topics

    Colors: synopsis


Colors: synopsis

long	blue.component	( long color )
long	green.component	( long color )
long	red.component	( long color )
long	rgb	( long red, long green, long blue )
Related help topics

    Colors: overview


blue.component(), green.component(), red.component()

Syntax

long blue.component( long color )

long green.component( long color )

long red.component( long color )

Description

These return the values of the blue, green, and red components respectively of an rgb color.

Context

3GL library function.

Example

long new_color, red_int, green_int, blue_int

new_color = rgb(46,139,87)

red_int = red.component( new_color )	| 46

green_int = green.component( new_color )	| 139

blue_int = blue.component( new_color )	| 87

Related help topics

    Colors: overview
    Colors: synopsis


rgb()

Syntax

long rgb( long red, long green, long blue )

Description

Use this to compose a color by specifying its red, green, and blue intensities. The intensities must be in the range 0 to 255.

Return values

A long which can be used as a color in graphical contexts such as windows, user interface controls, and so on.

Context

3GL library function.

Example

long new_color, red_int, green_int, blue_int

new_color = rgb(46,139,87)

red_int = red.component( new_color )	| 46

green_int = green.component( new_color )	| 139

blue_int = blue.component( new_color )	| 87

Related help topics

    Colors: overview
    Colors: synopsis


Company operations: overview and synopsis

Overview

Use these functions to switch to another company and to retrieve information about the current company.

Synopsis

long	compnr.check	( long new_compnr )
string	get.company	( )
long	get.compnr	( )
long	switch.to.company	( long new_compnr )


compnr.check()

Syntax

long compnr.check( long new_compnr )

Description

This switches to another company and sets the read-only variable COMPNR to the specified company number. It checks whether the user is authorized for the new company, and switches company only if so.

Notes

compnr.check() and switch.to.company() perform similar functions, but switch.to.company() performs additional checks. So switch.to.company() makes heavier demands on system resources.

Be aware that when there is a switch to another company, the user's first day of the week does not change, even if the new company has a different first day of the week. switch.to.company() returns an error value if the old and new companies have different first days of the week. compnr.check() does not.

Super users are authorized for all company numbers. They always have authority to switch to a different company number. In addition, super users can use the data dictionary to authorize other users for particular company numbers.

Return values

TRUE (<>0)	user is authorized; company switched
FALSE (0)   	user is not authorized; company not switched

Context

Bshell function.

Example

if ( not compnr.check(200) ) then

message( "No permission to change to this company number" )

endif

Related help topics

    Company operations: overview and synopsis


get.company()

Syntax

string get.company( )

Description

This returns the name of the current company.

Context

3GL library function.

Related help topics

    Company operations: overview and synopsis


get.compnr()

Syntax

long get.compnr( )

Description

This returns the ID number of the current company.

Context

Bshell function.

Related help topics

    Company operations: overview and synopsis


switch.to.company()

Syntax

long switch.to.company( long new_compnr )

Description

This switches to another company and sets the read-only variable COMPNR to the specified company number. It performs several checks before switching company and switches company only if the checks are successful. For example, it checks if the user is authorized to change to the new company, it checks if the package combination corresponds with the new company number, and it checks if the old and new companies have the same first day of the week.

Notes

compnr.check() and switch.to.company() perform similar functions, but switch.to.company() performs additional checks. So switch.to.company() makes heavier demands on system resources.

Be aware that when there is a switch to another company, the user's first day of the week does not change, even if the new company has a different first day of the week. switch.to.company() returns an error value if the old and new companies have different first days of the week; compnr.check() does not.

Super users are authorized for all company numbers. They always have authority to switch to a different company number. In addition, super users can also use the data dictionary to authorize other users for particular company numbers.

Return values

 1	success
-1	company not available
-2	no permission to change to this company
-3	package combination does not correspond with new company number
-4	first day of the week does not correspond to first day of the week of original company

Context

3GL library function.

Related help topics

    Company operations: overview and synopsis


Currency tables: overview and synopsis

Overview

Use this function to create and fill the multicurrency table. Currency rotation is based on the order of currencies in this table.

Synopsis

void	set.currencies	( long number.of.currency, string currency(3) )


set.currencies()

Syntax

void set.currencies( long number.of.currency, string currency(3) )

Description

Use this function to create and fill the multicurrency table. The function inserts a single entry in the table. Currency rotation is based on the order of currencies in this table.

Context

4GL library function. ???

You can use this function only in 4GL scripts.

Example

set.currencies( 1, "HFL" )

set.currencies( 2, "USD" )

set.currencies( 3, "DEM" )

Related help topics

    Currency tables: overview and synopsis


Database operations: overview

Use these functions for handling database input and output.

New features in BaanERP

In BaanERP, the functions db.curr(), db.first(), db.last(), db.next(), db.prev(),db.gt(), db.ge(), db.lt() and db.le() are implemented internally as SELECT statements. They are supported for backward compatibility only. In new applications, use queries instead.

In BaanERP, certain 4GL functions have Data Access Layer (DAL) equivalents. The following table lists these functions and their DAL equivalents.

4GL function	DAL function
on.main.table()	with.object.set.do()
on.old.occ()	with.old.object.values.do()
set.input.error()	dal.set.error.message() return(DALHOOKERROR)
skip.io()	dal.set.error.message() return(DALHOOKERROR)
abort.io()	dal.set.error.message() return(DALHOOKERROR)
db.update()	dal.update()
db.delete()	dal.destroy()
db.insert()	dal.new()
If a DAL exists for a particular table, it is preferable to use the DAL functions. The older functions access the database directly. When you make changes to the database with these functions, logic integrity checks programmed in the DAL are not executed. When you make changes to the database with the DAL functions, the relevant DAL hooks are executed automatically. This ensures the logic integrity of the database.

For further information about database handling in general and about the Data Access Layer, see Database Handling and Data Access Layer.

Table names and declarations

The naming syntax for tables, record buffers, and fields is:

 table tppmmmxxx	| table declaration

 rcd.tppmmmxxx	| record buffer of table

 ppmmmxxx.ffffffff	| logical field of table

where t stands for table, pp is the package code, mmm is the module code, xxx is the table number, and ffffffff  is a field name.

If a table is used in a script, it must be declared with the statement:

table tppmmmxxx

Declaration of a table implies declaration of all its fields and its record buffer. These do not need to be declared separately.

There are no functions for opening or closing a table. A table is automatically opened the first time it is accessed. It is automatically closed when the program ends.

Error handling

In BaanERP, there are two main categories of errors: operating system errors and database system errors. For an explanation of the error codes, consult your operating system or database system documentation, or see Error codes.

Normally, a program can detect only four of the database errors: EDUPL, EENDFILE, ENOREC, and EROWCHANGED. When other errors occur, an error message is displayed on screen. However, you can use the predefined variable error.bypass to suppress error messages and enable a program to detect some or all errors instead. This variable can have the following values:

0	This is the default value. The program can detect the following database errors: EDUPL, EENDFILE, ENOREC, and EROWCHANGED.  Some fatal errors cause a direct abort of the application. When this happens, the message 'Cannot continue' is displayed.  If you attempt to lock a record or table that is already locked by another process, the program returns to the retry point automatically a number of times (by default, 10 times) before stopping the session and displaying the error message.
1	The program can detect all errors. So no database error messages are displayed on screen.
A program can detect database errors in the following ways:

•	Test return values. For example:

 if db.insert( tpctst999 ) = EENDFILE then ...

•	Use db.error(). For example:

 db.insert( tpctst999 )

 if db.error( tpctst999 ) = EENDFILE then ...

•	Use the predefined variable e. For example:

 db.insert( tpctst999 )

 if e = EENDFILE then ...

•	The ENDSELECT and SELECTEMPTY statements automatically detect the EENDFILE and ENOREC errors respectively.

Related help topics

    Database operations: synopsis


Database operations: synopsis

void	abort.io	( string mesg(14) [, ...] )
long	abort.transaction	( )
void	activate.search	( )
long	commit.transaction	( )
void	dal.destroy	( string class_name, long object_set,    ref long retval, long prop_check   [, long mode [, long eflag]])
long	dal.get.property.flag	( string class_name, long object_set,    string prop_name )
void	dal.new	( string class_name, long object_set,    ref long retval, long prop_check   [, long mode [, long eflag]])
void	dal.set.property	( string class_name, long object_set,    const string prop_name, value,    long mode )
void	dal.start.business.method	( long|string set_id, string name,    ref long retval [, arg]... )
void	dal.update	( string class_name, long object_set,    ref long retval, long prop_check   [, long mode [, long eflag]] )
long	db.bind	( string table_name(9) [, ref string    buffer(.) [, long comp_nr]] )
long	db.change.order	( long table_id, long index_nr    [, long comp_nr] )
long	db.check.restricted	( long table_id, long mode,    ref string message(256) )
long	db.check.row.changed	( long table_id )
long	db.check.row.domains	( long table_id, ref string fld_name(18) )
long	db.clear.table	( long table_id[, long flag    [, long comp_nr]] )
long	db.columns.to.record	( long table_id )
long	db.create.table	( long table_id [, long comp_nr] )
long	db.curr	( long table_id [, long lock] )
long	db.delete	( long table_id [, long mode    [, long eflag]] )
long	db.drop.table	( long table_id [, long ignore_refs,    long comp_nr] )
long	db.eq	( long table_id [, long lock] )
long	db.error	( [long table_id] )
string	db.error.message	( )
long	db.first	( long table_id [, long lock] )
long	db.ge	( long table_id [, long lock] )
long	db.get.physical.compnr	( string tblname, long logical.compnr )
long	db.gt	( long table_id [, long lock] )
long	db.indexinfo	( long table_id, long index_nr,    ref long index_info(32,3),    ref long indexparts, ref long indexdups,    ref long indexactive )
long	db.insert	( long table_id [, long mode    [, long eflag]] )
long	db.last	( long table_id [, long lock] )
long	db.le	( long table_id [, long lock] )
long	db.lock.table	( long table_id [, long comp_nr] )
long	db.lt	( long table_id [, long lock] )
long	db.next	( long table_id [, long lock] )
long	db.nr.indices	( long table_id,  ref long nr_indices )
long	db.nr.rows	( long table_id, ref long nr_rows     [, long comp_nr] )
long	db.permission	( long table_id [, string field(18)    [, ref string buffer(.)]] )
long	db.prev	( long table_id [, long lock] )
long	db.record.to.columns	( long table_id )
long	db.ref.handle.mode	( string table_name(9), long mode )
long	db.retry.hit	( )
void	db.retry.point	( )
long	db.row.length	( long table_id,  ref long row_length )
long	db.set.to.default	( long table_id )
long	db.unbind	( long table_id )
long	db.update	( long table_id [, long mode    [, long eflag]] )
void	on.main.table	( function_name [, ...] )
void	restore.rcd.main	( long occurrence )
void	set.limits.off	( )
long	set.transaction.readonly	( )
void	skip.io	( string mesg(14) [, ...] )
void	store.occ.max	( )
void	store.occ.min	( )
void	to.key	( long key_number )
void	with.object.set.do	( string function_name, argument1,    argument2, ... )
void	with.old.object.values.do	( string function_name, argument1,    argument2, ... )
Related help topics

    Database operations: overview


abort.io()

Syntax

void abort.io( string mesg(14) [, ...] )

Description

This cancels the current database transaction.

After this function is called, new values entered on the form remain on the form and the predefined variable stp.abort.error is set to TRUE. In the case of a single-occurrence form, the transaction is then canceled without further actions. In the case of a multioccurrence form, the transaction is canceled but the user is given the opportunity to retry the updates that did not cause an error. If the user chooses to retry the updates, occurrences that caused an error are skipped and those that did not are updated. If the user chooses not to retry the transaction, the transaction is canceled without further action. The user can then start the update again or recover.

Arguments

mesg	This specifies a message defined in the data dictionary. The message is displayed on screen when abort.io() is called. If you specify an empty string here, the standard program displays a default message. The argument can contain substitution symbols such as %d or %s (see sprintf$()). The values that must be substituted are specified in the second, third, etc. arguments of the function. The number of arguments is variable.
Note

abort.io() is implicitly called by the standard program when a DALHOOKERROR is returned by, for example, a before.save.object() or after.save.object() function call.

Context

4GL library function.

You can use this function only in 4GL scripts. You can use it in the following event subsections (but not in programs of type 4):

before.write, before.rewrite, before.delete

after.write, after.rewrite, after.delete

after.skip.write, after.skip.rewrite, after.skip.delete

after.choice of choice.update.db

Example

main.table.io:

before.rewrite:

select tiitm001.*

from tiitm001 for update

where tiitm001.item between :item.f and :item.t

selectdo

tiitm001.cwar = "002"

db.update(ttiitm001, DB.RETRY)

selecterror

abort.io("pctsts0010", tiitm001.item)

| transaction canceled on item %s

endselect

Related help topics

    Database operations: overview
    Database operations: synopsis


abort.transaction()

Syntax

long abort.transaction()

Description

This cancels the current database transaction. No changes are stored in the database.

To commit a transaction and store changes made in the database, use commit.transaction() instead.

Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


activate.search()

Syntax

void activate.search()

Description

This forces a random search action on the main table. You call the function immediately after input to a field during insertion of a new record (standard command ADD.SET or DUPL.OCCUR) or during MODIFY.SET (if the predefined variable modify.prim.key is set to TRUE).

When a new record is being added to the database, the standard program normally executes a search action in the main table after input to the field(s) of the primary index. If the key values entered belong to an existing record in the main table, the standard program displays all the fields of that record and stops adding the new record. Otherwise, the user must fill the remaining fields; then the record is added to the main table.

In some applications, not all parts of the primary index appear on the form. In this case, the search operation in the main table occurs when the user leaves the last input field of the occurrence. You can force an earlier search action by calling activate.search() after input to any field of the occurrence.

Context

Bshell function.

You can use this function only in the 4GL event subsection on.input. You cannot use it in programs of type 4.

Example

| Suppose there are 2 input fields on the form, 'number' and

| 'name', which are not parts of the primary index of the main

| table. When the user leaves the field 'number', a search action in

| the main table should be done by the standard program:

field.number:

on.input:

activate.search()

Related help topics

    Database operations: overview
    Database operations: synopsis


commit.transaction()

Syntax

long commit.transaction()

Description

This ends the current transaction. All changes made during the transaction are stored in the database.

To cancel a transaction, use abort.transaction() instead.

Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


dal.destroy()

Syntax

void dal.destroy( string class_name, long object_set, ref long retval, long prop_check [, long mode [, long eflag]] )

Description

Use this to delete a database record. The function encapsulates the db.delete() function with the DAL hooks of the object set. If the before.destroy.object() hook fails, the database operation is cancelled.

Arguments

class_name	A string containing the name of the DAL.
object_set	The ID of an open object set (if this ID is not known, use the table ID).
retval	The return value of the object hooks (<0), of the db.delete() function (>0), or 0 if the function is successful.
prop_check	A boolean value that indicates whether or not property checks must be executed. If set to TRUE, the property checks are executed immediately before the before.destroy.object() hook. If set to FALSE, the property checks are not executed.
mode	Set this to DB.RETRY if retry points and the SELECT FOR UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
eflag	For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See Error handling.
Context

DAL function.

Related help topics

    Database operations: overview
    Database operations: synopsis


dal.get.property.flag()

Syntax

long dal.get.property.flag( string class_name, long object_set, string prop_name )

Description

Use this to retrieve the value of the has_changed flag (see property hooks) for any database property. The property must have been changed by the dal.set.property() function.

Remark

This function is only supported when it is called from method.is.allowed or a property check function. When this is called from before.save.object or after.save.object the result  is 0.

You can call this function from both UI and DAL scripts.

Arguments

class_name	A string containing the name of the DAL.
object_set	The ID of an open object set (if this ID is not known, use the table ID).
prop_name	A string containing the name of the field for which the has_changed value must be returned.
Return values

The function returns the value of the has_changed flag of the specified property. The possible values are:

0	property not changed
DAL_NEW	change caused by inserting a new object
DAL_UPDATE	change caused by updating an existing object

Properties with no check function in the DAL always return 0.

Context

DAL function.

Example

This function is programmed in DAL tdsls401.

function extern long tdsls401.oqua.check(long has_changed)

{

if tdsls400.stat = tdsls.stat.invoiced then

if has_changed or

dal.get.property.flag("tdsls401", ttdsls401,

"tdsls401.pric") then

dal.set.error.message("tdsls44042")

| You cannot change quantity or price, because

| the order is already invoiced

return(DALHOOKERROR)

endif

else

if tdsls401.oqua > tdsls401.comq then

dal.set.error.message(“tdsls44043”)

| Order quantity may not exceed committed

| quantity

return(DALHOOKERROR)

endif

endif

…

return(0)

}

Related help topics

    Database operations: overview
    Database operations: synopsis


dal.new()

Syntax

void dal.new( string class_name, long object_set, ref long retval, long prop_check [, long mode [, long eflag]] )

Description

Use this to add a new record to the database. The function encapsulates the db.insert() function with the DAL hooks of the object set. If the before.save.object() hook fails, the database operation is cancelled.

Arguments

class_name	A string containing the name of the DAL.
object_set	The ID of an open object set (if this ID is not known, use the table ID).
retval	The return value of the object hooks (<0), of the db.insert() function (> 0), or 0 if the function is successful.
prop_check	A boolean value that indicates whether or not property checks must be executed. If set to TRUE, the property checks are executed immediately before the before.save.object() hook. If set to FALSE, the property checks are not executed.
mode	Set this to DB.RETRY if retry points and the SELECT FOR UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
eflag	For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See Error handling.
Context

DAL function.

Related help topics

    Database operations: overview
    Database operations: synopsis


dal.set.property()

Syntax

long dal.set.property( string class_name, long object_set, const string prop_name, value, long mode )

Description

In order to notify the DAL about a change to the value of a property, you must use this function to change the value. Using this function ensures that the relevant property hooks are executed when the value is changed. If you use an assignment or the db.* functions to change a property value, the DAL is not notified of the change. Consequently, the property checks in the DAL are not executed.

Remark

The property check is not executed by calling this function, only the has_changed flag is set. The return value of this function is therefore not the return value of the property check, but 0.

There is another function: dal.set.property.with.check which does the same as dal.set.property and additionally calls the property check. The only difference is that with dal.set.property.with.check you don’t specify the mode, it is always using DAL_UPDATE. So the function dal.set.property.with.check only has 4 arguments. This function returns the return value of the property check.

You can call this function from both UI and DAL scripts.

Arguments

class_name	A string containing the name of the DAL.
object_set	The ID of an open object set (if this ID is not known, use the table ID).
prop_name	The name of the property whose value must be changed.
mode	Use this to indicate the value for the has_changed flag of the property. The possible values are DAL_NEW or DAL_UPDATE.
Return values

The return value of the property check.

Context

DAL function.

Example

This is an example of using the function in a DAL script to update an object in another object set.

| This function is in the DAL of tdsls401

function extern long after.update.object(long mode)

{

long ret

if mode = DAL_NEW then

old.amnt = 0

endif

select tdsls400.*

from 	tdsls400 for update

where tdsls400.orno =:tdsls401.orno

selectdo

dal.set.property("tdsls400", ttdsls400, "tdsls400.amnt",

tdsls400.amnt - old.amnt + tdsls401.amnt, DAL_UPDATE)

dal.update("tdsls400", ttdsls400, ret, true, db.retry)

endselect

return(ret)

}

Related help topics

    Database operations: overview
    Database operations: synopsis


dal.start.business.method()

Syntax

void dal.start.business.method( long|string set_id, string name, ref long retval [, arg]... )

Description

This starts a specified business method.

The business method must be implemented as a function of type EXTERN LONG. If this is the first call to a particular class (that is, table), the before.open.object.set() hook is automatically called before the business method is called.

Arguments

set_id	Indicates the name of the DAL that implements the business method. The set_id argument can be a long (use in external programs) or a string (use in UI scripts).
name	The name of the business method.
retval	The return value. Negative values are reserved for the calling mechanism. For example: -1 DALNOOBJSET -2 DALNOMETHOD The business method may return only DALHOOKERROR, 0, or positive numbers.
arg	Use these optional arguments to pass arguments to the business method.
Context

DAL function.

Example

dal.start.business.method("cfcmd100", "print.object.set", feature.f, feature.t)

function extern long print.object.set(

domain cfcmd.feat	feature.f,

domain cfcmd.feat	feature.t),

{

domain	dcbool	show.pi

show.pi = tcmcs.dll0011.show.progress.indicator()

if show.pi then

init.progress.indicator(feature.f, feature.t)

endif

select cfcmd100.*

from cfcmd100

where	cfcmd100.feat inrange :feature.f and :feature.t

order by cfcmd100._index1

selectdo

if show.pi then

|* calculate progress percentage

prgi.val = prgi.val + prgi.stp

if prgi.tot > 0 then

prgi.prc = (prgi.val / prgi.tot) * 100

endif

if change.progress.indicator(prgi.prc) then

|* user pressed cancel/stop button

return(0)

endif

endif

prnt.data = "cfcmd110"

print.record(1)

endselect

return(0)

}

Related help topics

    Database operations: overview
    Database operations: synopsis


dal.update()

Syntax

void dal.update( string class_name, long object_set, ref long retval, long prop_check [, long mode [, long eflag]] )

Description

Use this to update an existing database record. The function encapsulates the db.update() function with the DAL hooks of the object set. If the before.save.object() hook fails, the database operation is cancelled.

Arguments

class_name	A string containing the name of the DAL.
object_set	The ID of an open object set (if this ID is not known, use the table ID).
retval	The return value of the object hooks (<0), of the db.insert() function (>0), or 0 if the function is successful.
prop_check	A boolean value that indicates whether or not property checks must be executed. If set to TRUE, the property checks are executed immediately before the before.save.object() hook. If set to FALSE, the property checks are not executed.
mode	Set this to DB.RETRY if retry points and the SELECT FOR UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
eflag	For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See Error handling.
Context

DAL function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.bind()

Syntax

long db.bind( string table_name(9) [, ref string buffer(.) [, long comp_nr]] )

Description

This creates a pointer to a specified table. It returns a table ID that you use in other database calls to identify the table. The pointer is to a table with a particular company number and record buffer. You can create additional pointers to the same table by calling the function with a different company number and/or record buffer.

Arguments

table_name	The table name.
buffer	This optional argument specifies the record buffer to be used for the table. If you omit this argument, or if you specify an empty string, the default record buffer is used (that is, rcd.tppmmmxxx).
comp_nr	This optional argument specifies a company number for the table. The default company is the company of the user. If you include this argument, you must also include the buffer argument. So, if you want to specify a company other than the default company but want to use the default record buffer, specify the default buffer or an empty string in the buffer argument.
Note

When you create more than one pointer to a table, you must use a different record buffer for each one.

Return values

>0      	success; pointer is returned
  0     	error

Context

Bshell function.

Example

long tcmcs001_id

if (switch.to.company(200) > 0) then

tcmcs001_id = db.bind("ttcmcs001")

db.first(ttcmcs001_id)

endif

...

db.first(ttcmcs001)

Related help topics

    Database operations: overview
    Database operations: synopsis


db.change.order()

Syntax

long db.change.order( long table_id, long index_nr [, long comp_nr] )

Description

This makes a specified index the current index. After this action, the record pointer is undefined.

Arguments

table_id	The table ID, as returned by db.bind().
index_nr	The number of the index that you want to become the current index. The index must exist.
comp_nr	This optional argument specifies a company number for the table. The default company is the company of the user.
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.check.restricted()

Syntax

long db.check.restricted( long table_id, long mode, ref string message(256) )

Description

In a table definition, it is possible to set restrictions on update and/or delete actions for records that are referenced by other tables. These restrictions mean that you cannot delete and/or update the primary key that is referenced by another table. This function checks whether there are references to the current record with delete and/or update restrictions. This function can take a long time to complete if no reference counter is kept (lookup mode).

Arguments

table_id	The table ID, as returned by db.bind().
mode	Use to specify whether you want to check for delete or update restrictions. Possible values are: 1 delete mode 2 update mode
message	This returns the reference message of the table. This message is defined in the data dictionary.
Return values

 0	no reference found
 1	one or more references found
-1	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.check.row.changed()

Syntax

long db.check.row.changed( long table_id )

Description

This checks whether a record that has been locked with a delayed lock has yet been changed.

Arguments

table_id	The table ID, as returned by db.bind().
Return values

     0	record has not been changed
<>0	error
EROWCHANGED	record has been changed

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.check.row.domains()

Syntax

long db.check.row.domains( long table_id, ref string fld_name(18) )

Description

This checks whether the current record of a specified table conforms to the domain definitions in the data dictionary. All fields of the record are checked in turn until an error occurs. The function returns when the first error is encountered.

Arguments

table_id	The table ID, as returned by db.bind().
fld_name	This returns the name of the first incorrect field.
Return values

 0	no errors
-1	invalid table ID
ENOTINRANGE	error in a field

If an error is returned, you can retrieve information about the specific error using db.error.message().

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.clear.table()

Syntax

long db.clear.table( long table_id [, long flag [, long comp_nr]] )

Description

This deletes all data from a specified table. Reference counters are automatically updated.

By default, all deleted records are saved in rollback segments. Consequently, using this function to clear a large table can result in reduced performance and, in some cases, can cause overflow of the internal rollback segments.

Arguments

table_id	The table ID, as returned by db.bind().
flag	Use this optional argument to indicate whether the delete operation must be performed as a single transaction or as multiple transactions. The possible values are:
	0	WITH.ROLLBACK	The table is cleared in a single transaction. All records are saved in rollback segments. This is the default option.
	1	NO.ROLLBACK	The table is cleared in one or more transactions, depending on the number of records in the table. Each transaction is automatically committed after 20 records have been deleted. The number of records deleted in the final transaction can be 20 or less; this depends on how many records remain to be deleted.  When you use this option, transactions are small and records are not saved in rollback segments. When you use this option, you must place db.clear.table() at the start of the transaction.
comp_nr	This optional argument specifies a company number for the table. The default company is the company of the user.
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


 db.columns.to.record()

Syntax

long db.columns.to.record( long table_id )

Description

The record buffer of a table is used for reading records from that table. When you bind to a table (see db.bind()) and specify that the default record buffer is to be used, the contents of the table fields are automatically copied to the buffer. This does not happen when you specify a record buffer other than the default buffer. Consequently, you must call this function to copy the field values to the buffer if you have filled the fields before reading from the database.

Arguments

table_id	The table ID, as returned by db.bind().
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.create.table()

Syntax

long db.create.table( table table_name [, long comp_nr] )

Description

This creates a new database table.

Arguments

table_name	The name for the new table.
comp_nr	This optional argument specifies a company number for the table. The default company is the company of the user.
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.curr()

Syntax

long db.curr( long table_id [, long lock] )

Description

This reads the current record from a specified table.

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


 db.delete()

Syntax

long db.delete( long table_id [, long mode [, long eflag]] )

Description

This deletes the current record. The record pointer is not changed, so the current record is undefined after the record has been deleted.

Arguments

table_id	The table ID, as returned by db.bind().
mode	Set this to DB.RETRY if retry points and the SELECT FOR UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
eflag	For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See Error handling.
Return values

    0	success
 >0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.drop.table()

Syntax

long db.drop.table( long table_id [, long ignore_refs] [, long comp_nr] )

Description

This deletes a specified table. Data and indices associated with the table are also deleted. Reference counters are automatically updated.

Arguments

table_id	The table ID, as returned by db.bind().
ignore_refs	If you set this optional argument to DB.IGNORE.ALL.REFS, the data is deleted regardless of whether it is referenced by other tables.
comp_nr	This optional argument specifies a company number for the table. The default company is the company of the user.
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.eq()

Syntax

long db.eq( long table_id [, long lock] )

Description

This reads from a specified table the record whose key value equals a certain predefined value. Before calling db.eq(), you must assign the required value to the key field. For example, the following code retrieves the item with item number 001 from the items table:

tiitm001.item = "001"

db.eq( ttiitm001 )

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.error()

Syntax

long db.error( [long table_id] )

Description

Use this to retrieve the error code returned by the most recent database action. If you specify a table ID, the function retrieves the most recent error code returned by an action on that table.

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.error.message()

Syntax

string db.error.message()

Description

Some errors returned by a database action have an associated error message. This message provides additional information about the error. Use the db.error.message() function to retrieve the error message (if any) associated with the most recent error code returned by a database action.

Return values

The error message associated with the most recent error that occurred. Or an empty string if no message is associated with the error.

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.first()

Syntax

long db.first( long table_id [, long lock] )

Description

This reads the first record from a specified table. It uses the current index to search the table.

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.ge()

Syntax

long db.ge( long table_id [, long lock] )

Description

This reads from a specified table the record whose key value is greater than or equal to a certain predefined value. Before calling db.ge(), you must assign the required value to the key field. For example:

tiitm001.item = "001"

db.ge( ttiitm001 )

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.gt()

Syntax

long db.gt( long table_id [, long lock] )

Description

This reads from a specified table the record whose key value is greater than a certain predefined value. Before calling db.gt(), you must assign the required value to the key field. For example:

tiitm001.item = "001"

db.gt( ttiitm001 )

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.indexinfo()

Syntax

long db.indexinfo( long table_id, long index_nr, ref long index_info(32,3), ref long indexparts, ref long indexdups, ref long indexactive )

Description

This returns information about the parts of a specified index.

Arguments

table_id	The table ID, as returned by db.bind().
index_nr	The index number.
index_info	This returns the start position, length, and type of the index parts (up to a maximum of 32 parts): index_info(i,1) Start position in the logical record of part i of the index. index_info(i,2) Length of part i. index_info(i,3) Type of part i. The possible values are: DB.BYTE DB.TIME DB.INTEGER DB.TEXT DB.LONG DB.MAIL   DB.FLOAT  DB.ENUM DB.DOUBLE DB.BITSET DB.STRING DB.COMBINED   DB.DATE DB.MULTIBYTE
indexparts	Returns the number of parts in the index.
indexups	Indicates whether or not duplicate values are permitted.
indexactive	Indicates whether or not the index is active.
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.insert()

Syntax

long db.insert( long table_id [, long mode [, long eflag]] )

Description

This adds a new record to a specified table. The record pointer does not change.

Arguments

table_id	The table ID, as returned by db.bind().
mode	Set this to DB.RETRY if retry points and the SELECT FOR UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
eflag	For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See Error handling.
Return values

    0	success
 >0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


 db.last()

Syntax

long db.last( long table_id [, long lock] )

Description

This reads the last record from a specified table. It uses the current index to search the table.

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.le()

Syntax

long db.le( long table_id [, long lock] )

This reads from a specified table the record whose key value is less than or equal to a certain predefined value. Before calling db.le(), you must assign the required value to the key field. For example:

tiitm001.item = "001"

db.le( ttiitm001 )

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.lock.table()

Syntax

long db.lock.table( long table_id )

Description

This locks a specified table. Other users cannot then write to or delete the table or any parts of the table. Nor can they lock the table or any parts of the table. The lock is released by commit.transaction() or abort.transaction().

Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.lt()

Syntax

long db.lt( long table_id [, long lock] )

Description

This reads from a specified table the record whose key value is less than a certain predefined value. Before calling db.lt(), you must assign the required value to the key field. For example:

tiitm001.item = "001"

db.lt( ttiitm001 )

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.next()

Syntax

long db.next( long table_id [, long lock] )

This reads the next record from a specified table. It uses the current index to search the table. If there is no current record, the function returns an error message.

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.nr.indices()

Syntax

long db.nr.indices( long table_id, ref long nr_indices )

Description

This returns the number of indices that exist on a specified table.

Arguments

table_id	The table ID, as returned by db.bind().
nr_indices	Returns the number of indices on the table.
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.nr.rows()

Syntax

long db.nr.rows( long table_id, ref long nr_rows [, long comp_nr] )

Description

This returns the number of rows that a specified table contains.

Arguments

table_id	The table ID, as returned by db.bind().
nr_rows	Returns the number of rows in the table.
comp_nr	This optional argument specifies a company number for the table. The default company is the company of the user.
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.permission()

Syntax

long db.permission( long table_id [, string field(18) [, ref string buffer(.)]] )

Description

Use this to check the access permissions that a user has to a specified table or table field.

Arguments

table_id	The table ID, as returned by db.bind().
field	To check the permissions for a particular field, enter the field name here. If you do not specify a field here, or if you specify an empty string, the function returns the permissions for the table.
buffer	A user's permissions for a table or table field can depend on the contents of a record. In this case, you must specify the record buffer of the table in the buffer argument. The function returns the user's permissions for the record in the record buffer. If a user's permissions depend on the contents of a record, and you do not specify the buffer argument, the function returns PERM.UNKNOWN.
Return values

The function returns a long that indicates the permissions that the user has on the table or on a specified field of that table. The return value consists of one of, or a combination of, the following codes:

NO.PERMISSION	1
PERM.READ	2
PERM.MODIFY	4
PERM.WRITE	8
PERM.DELETE	16
NO.RESTRICTION	(PERM.READ+PERM.MODIFY+PERM.WRITE+PERM.DELETE)
PERM.UNKNOWN	32

So, if the value 6 is returned, the user is permitted to both read and modify the specified table or table field.

Context

Bshell function.

Example

long p

string buffer(18)

if attr.permission = PERM.UNKNOWN then

p = db.permission(ttccom001, "", buffer)

else

p = attr.permission

endif

if p > PERM.READ then

....

else

| modifications not allowed in table tccom001 for this user

endif

Related help topics

    Database operations: overview
    Database operations: synopsis


db.prev()

Syntax

long db.prev( long table_id [, long lock] )

Description

This reads the previous record from a specified table. It uses the current index to search the table. If there is no current record, the function returns an error message.

Arguments

table_id	The table ID, as returned by db.bind().
lock	By default, the record is not locked before reading. Use this optional argument to apply a lock to the record. The possible values are: DB.LOCK lock record for update DB.DELAYED.LOCK apply a delayed lock to the record; the lock is  applied immediately before the update action
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.record.to.columns()

Syntax

long db.record.to.columns( long table_id )

Description

When you bind to a table (see db.bind()) and specify that the default record buffer is to be used, the contents of the buffer are automatically copied to the table fields in your program script. This does not happen when you specify a record buffer other than the default buffer. Consequently, you must call this function to copy the field values from the buffer to the table fields in your program script.

Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.ref.handle.mode()

Syntax

long db.ref.handle.mode( string table_name(9), long mode )

Description

Use this to check whether a full table scan (FTS) is necessary during delete or update operations. Delete and update operations can take a long time to complete when the table is referenced by other tables but no reference counter is kept (cascade, nullify, or lookup mode). When there is no index on the foreign key in the child table, normally a full table scan is required to search for referring records.

Arguments

table_name	The table name, without the leading 't' character.
mode	Possible modes: DB.REF.UPDATE DB.REF.DELETE
Return values

0	full table scan is not necessary
1	full table scan is necessary

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.retry.hit()

Syntax

long db.retry.hit()

Description

Use this to check whether the client database layer has returned to a retry point. You must set the retry point by using db.retry.point() before you call db.retry.hit(). See also Database handling.

Return values

    0	retry point defined but not returned to
<>0	system returned to retry point

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.retry.point()

Syntax

void db.retry.point()

Description

This sets a retry point for the current transaction. The program returns to this point if an error occurs during the transaction; the transaction is then retried. When you include a retry point for a transaction, you must set it before the start of the transaction.

Context

Bshell function.

See also

Database handling

Related help topics

    Database operations: overview
    Database operations: synopsis


db.row.length()

Syntax

long db.row.length( long table_id, ref long row_length )

Description

Use this to retrieve the length of records in a specified table.

Arguments

table_id	The table ID, as returned by db.bind().
row_length	This returns the number of bytes in a record of the specified table.
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.set.to.default()

Syntax

long db.set.to.default( long table_id )

Description

This sets bound variables in the program script to the default values defined in the data dictionary.

Arguments

table_id	The table ID, as returned by db.bind().
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.unbind()

Syntax

long db.unbind( long table_id )

Description

This deletes the specified table pointer.

Arguments

table_id	The table pointer, as returned by db.bind().
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.update()

Syntax

long db.update( long table_id [, long mode [, long eflag]] )

Description

This rewrites the current record. When updating a record with this function, you are permitted to update the primary key of the record.

Arguments

table_id	The table ID, as returned by db.bind().
mode	This has two possible values:
	DB.RETRY	Set this value if retry points and the SELECT FOR UPDATE statement are being used. The actual database action is postponed until the transaction is committed.
	DB.DELAYED.LOCK	This option is available only for records for which a delayed lock has been set with db.eq().
eflag	For some errors, it is possible to indicate the action the system must perform when the error occurs. You use this argument to specify the required action(s). See Error handling.
Return values

    0	success
 >0	error

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


on.main.table()

Syntax

void on.main.table( function_name [, ...] )

Description

This copies the contents current record of the main table to the record buffer of that table, saves the record, and executes the specified function. After that the saved record buffer is restored. This enables you to perform actions on the record contents without affecting the values in the table.

Arguments

function_name	The name of the function that must be executed. The function must be of type void.
. . .	Use these optional arguments to pass one or more arguments to the function.
Context

4GL library function.

You can use this function only in 4GL scripts. You cannot use it in the before.program section because the main table has not yet been defined at this point. The function is not relevant to programs of type 4.

In DAL scripts, with.object.set.do() is the equivalent of on.main.table().

Example

| Suppose you have a table to which you can add numbers only

| if a certain value is present in the main table

declaration:

long go_ahead

field.pctst999.number:

check.input:

on.main.table( check_number, 5 )

if not go_ahead then

set.input.error("pctst0003", 5)    |"Number %d not present"

endif

functions:

function void check_number( long number )

{

select pctst999.*

from pctst999

where pctst999.number = :number

as set with 1 rows

selectdo

go_ahead = TRUE

selectempty

go_ahead = FALSE

endselect

return

}

Related help topics

    Database operations: overview
    Database operations: synopsis


restore.rcd.main()

Syntax

void restore.rcd.main( long occurrence )

Description

This updates the main table with the contents of the buffer of the specified occurrence. It also makes the specified occurrence the current occurrence.

Arguments

occurrence	The occurrence number.
Context

4GL library function.

You can use this function only in 4GL scripts. You cannot use the function in before.program sections.

Related help topics

    Database operations: overview
    Database operations: synopsis


set.limits.off()

Syntax

void set.limits.off()

Description

This removes the limits set with the store.occ.max() and/or store.occ.min() functions. The entire table can then be accessed again.

Context

4GL library function.

You can use this function only in 4GL scripts. You cannot use the function in before.program sections or in programs of type 4.

Related help topics

    Database operations: overview
    Database operations: synopsis


set.transaction.readonly()

Syntax

long set.transaction.readonly()

Description

This defines a transaction as read only, with read consistency. The transaction can only read records (without locks) from the database; it cannot update the database. Read consistency is retained during the entire transaction. That is, your view of the database does not change even when the database is updated by other users.

When included, this function must be the first command of a transaction. So, you must include it either at the start of the program or immediately following a commit.transaction() or abort.transaction() call.

Because it is not possible to update the database in a read-only transaction, you can use only the following database calls in the transaction:

db.first()	db.lt()
db.last()	db.le()
db.next()	db.set.to.default()
db.prev()	db.change.order()
db.gt()	db.indexinfo()
db.ge()	db.nr.indices()
db.eq()	db.nr.rows()
db.cur()	db.row.length()
db.bind()	db.record.to.columns()
db.unbind()	db.columns.to.record()
db.error()

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


skip.io()

Syntax

void skip.io( string mesg(14) [, ...] )

Description

Use this to skip the current database action on the current record. The predefined variable stp.skip.error indicates whether or not skip.io() has been called.

Arguments

mesg	This specifies a message that is defined in the data dictionary. This message is displayed on screen when you call skip.io(). If you specify an empty string, the standard program displays a default message. The message can contain substitution symbols such as %d or %s (see sprintf$()). The values that must be substituted are specified in the second, third, etc. arguments of the function. The number of arguments is variable.
Note

For performance reasons, it is preferable to use query.extend.where() instead of skip.io().

Context

4GL library function.

You can use this function only in 4GL scripts. You cannot use it in programs of type 4. You can use it in the following event subsections:

after.read, read.view
before.write, before.rewrite, before.delete

Example

main.table.io:

before.delete:

if pctst999.number = 0 then

skip.io("pctsts0010")

| record with number zero may not be deleted

endif

Related help topics

    Database operations: overview
    Database operations: synopsis


store.occ.max(), store.occ.min()

Syntax

void store.occ.max()

void store.occ.min()

Description

Normally, standard commands that access records of the main table can access all records of that table. You can use these functions to limit the records that can be accessed to those whose key values are within a specified range. Use store.occ.max() to define the upper limit of the range. Use store.occ.min() to define the lower limit of the range. If you wish, you can define only a maximum or only a minimum limit.

Before you call either of these functions, you must fill the key value with the required maximum or minimum value. If you set a limit that has previously been defined, the new value of the limit overwrites the previous value of the limit.

Use set.limits.off() to switch off the limits defined with these functions.

Note

For performance reasons, it is preferable to use query.extend.where() instead of these functions.

Context

4GL library functions.

You can use these functions only in 4GL scripts. You cannot use them in programs of type 4 or in before.program sections.

Examples

Example 1

| Suppose that on the first form you can access the entire main

| table while on the second form you can access only records in the range

| 20 to 100

form.2:

before.form:

pctst999.number = 20     | Fill minimum key value

store.occ.min()          | Set minimum

pctst999.number = 100    | Fill maximum key value

store.occ.max()          | Set maximum

after.form:

set.limits.off()

Example 2

before.form:

tibom010.mitm = "X"

set.min(tibom010.pono)

store.occ.min()

set.max(tibom010.pono)

store.occ.max()

after.form:

set.limits.off()

Related help topics

    Database operations: overview
    Database operations: synopsis


 to.key()

Syntax

void to.key( long key_number )

Description

Use this to change the key of the main table without user interaction. The key_number argument specifies the new key.

When changing the key of the main table within the on.main.table() function, you must use db.change.order() instead. Also, to change the key of a table other than the main table, you must use db.change.order().

You can also use execute(change.order) to change the key of the main table. In this case, the user selects the new key.

Note that during execution of the ADD.SET, MODIFY.SET and MARK.DELETE commands, the current key is saved and the primary key becomes the current key. After the database has been updated, the standard program restores the saved key.

Context

4GL library function.

You can use these functions only in 4GL scripts and only in programs of type 1, 2, and 3. You can use the function in the following event subsections:

on.choice, after.choice
init.form, before.form, after.form
on.entry

Related help topics

    Database operations: overview
    Database operations: synopsis


with.object.set.do()

Syntax

void with.object.set.do( string function_name, argument1, argument2, ... )

Description

This copies the contents of the current record of the main table to the record buffer of that table, saves the record, and executes the specified function. After that the saved record buffer is restored. This enables you to perform actions on the record contents without affecting the values in the table.

You can call this function in any DAL hook. It is the equivalent of the on.main.table() function used in UI scripts.

Arguments

function_name	The name of the function that must be executed. The function must be of type void.
argument1,  . . .	Use these optional arguments to pass one or more arguments to the function.
Context

DAL function.

Related help topics

    Database operations: overview
    Database operations: synopsis


with.old.object.values.do()

Syntax

void with.old.object.values.do( string function_name, argument1, argument2, ... )

Description

This executes the specified function for the current occurrence, using the old values of the record. The record must have been previously modified.

You can call this function in the before.save.object() hook of a DAL script. It is the equivalent of the on.old.occ() function used in UI scripts.

Arguments

function_name	The name of the function that must be executed. The function must be of type void.
argument1, ...	Use these optional arguments to pass one or more arguments to the specified function.
Context

DAL function.

Related help topics

    Database operations: overview
    Database operations: synopsis


db.get.physical.compnr()

Syntax

long db.get.physical.compnr( string tblname, long logical.compnr )

Description

Use this to retrieve the physical company number for the specified table (tblname) and logical company number (logical.compnr).

Arguments

tblname	The name of the table.
logical.compnr	The name of the logical company.
Return values

  0	success
-1	error, the tblname or the logical.compnr is not correct. (e is set to E_BADARG)

Context

Bshell function.

Related help topics

    Database operations: overview
    Database operations: synopsis


Dates, times, time zones: overview

Use these functions to manipulate dates, times, and time zones.

Universal Coordinated Time

BaanERP provides time-zone independent date and time support. The user interface always shows local dates and times. Internally, however, BaanERP stores dates and times in Universal Coordinated Time (UTC). It stores both date and time in a single long integer referred to as the UTC long format. This integer represents the number of seconds since 0:00 hour, January 1, 1970 (in UTC). The use of a long integer imposes an upper date limit of 2038.

Time zones

The UTC functions described in this section support conversion between local dates and times and UTC. Users can set their local time zone via the user interface. 3GL/4GL programs can modify the time zone at runtime using various time zone functions.

Week handling

BaanERP handles week numbering according to ISO:5601. Week 01 is the week that includes the first Thursday of the year or January 4th. Monday is the first day of the week (that is, day 1). Sunday is the last day of the week (that is, day 7).

In the company-data settings in the data dictionary it is possible to define the first day of the week (that is, day 01) for individual BaanERP users. If a user’s first day of the week is Monday, then week numbering follows the ISO standard. However, if a user’s first day of the week is other than Monday (Sunday or Wednesday, for example), the week number is calculated differently. The week number is always the ISO week number of the Monday that occurs in the user’s week.

The following diagram illustrates this:

In the example, the user’s first day of the week is a Wednesday. The week number of the week beginning Wednesday 9th and ending Tuesday 15th  is the ISO week number for the Monday that occurs in that week. The ISO week number of Monday 14th is week 6, so Wednesday 9th to Tuesday 15th is week 6.

Note

For an explanation of date and time formats, see Formatting Output.

Related help topics

    Dates, times, time zones:  synopsis


Dates, times, time zones: synopsis

Local dates/times

long	date.num	( )
string	date.to.inputstr$	( long dayno, string format(7),    long length )
long	date.to.num	( long yearno, long monthno,    long month_dayno )
string	dte$	( )
long	inputstr.to.date	( string inputstr(.), string format(7) )
long	num.to.date	( long dayno, ref long yearno,    ref long monthno, ref long month_dayno )
string	num.to.date$	( long dayno, long mode )
long	num.to.week	( long dayno, ref long week_dayno,    ref long year_dayno, ref long weekno    [, ref long yearno] )
long	time.num	( )
long	week.to.num	( long weekno, long yearno,    long week_dayno )
UTC conversion

long	date.to.utc	( long yearno, long monthno,    long month_dayno, long hours,    long minutes, long seconds )
long	input.to.utc	( const string value(),    const string format() )
long	inputstr.to.utc	( const string date.inputstr(),    string date.format(7),    const string time.inputstr(),    string time.format(7) )
long	local.to.utc	( long local_days, long local_time,    ref long utc )
long	utc.num	( )
long	utc.to.date	( long utc, ref long yearno,    ref long monthno, ref long month_dayno,   ref long hours, ref long minutes,    ref long seconds )
long	utc.to.input	( long lvalue, const string format() )
long	utc.to.inputstr$	( long utc, string date.format(7),    string time.format(7),    ref string local.date(),    ref string local.time() )
long	utc.to.local	( long utc, ref long local_days,    ref long local_time )
long	utc.to.week	( long utc, ref long week_dayno,    ref long year_dayno, ref long weekno,    ref long hours, ref long minutes,    ref long seconds [, ref long yearno] )
long	week.to.utc	( long weekno, long yearno,    long week_dayno, long hours,    long minutes, long seconds )
Time zones

long	choose.time.zone.from.list	( )
long	date.to.date	( long in_date, long in_time,    const string in_zone(),   const string out_zone(),    ref long out_date, ref long out_time )
long	get.time.zone	( ref string time_zone() )
long	set.time.zone	( string time_zone(50) )
long	timezone.exists	( string timezone(50) )
Related help topics

    Dates, times, time zones:  overview


choose.time.zone.from.list()

Syntax

long choose.time.zone.from.list()

Description

This starts a session where the user can choose a time zone from a list. The function then calls set.timezone() with the time zone selected by the user.

Return values

 0	new time zone set
-1	user aborted operation; time zone not set

Context

3GL library function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


date.num()

Syntax

long date.num()

Description

This returns the number of days from 01-01-0001 to the system date.

Return values

The number of days from 01-01-0001 to the system date. Or -1 if an error occurs.

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


date.to.date()

Syntax

long date.to.date( long in_date, long in_time, const string in_zone(), const string out_zone(), ref long out_date, ref long out_time )

Description

This converts a date and time in one time zone to the corresponding date and time in a different time zone.

Arguments

in_date	The date in the source time zone, specified as the number of days since 01-01-0001.
in_time	The time in the source time zone, specified as the number of seconds since 00:00 hour.
in_zone	The source time zone.
out_zone	The time zone to which the source date and time must be converted.
out_date	The number of days since 01-01-0001 in the target time zone.
out_time	The number of seconds since 00:00 hour in the target time zone.
Return values

 0	success
-1 	error

Context

3GL library function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


date.to.inputstr$()

Syntax

string date.to.inputstr$( long dayno, string format(7), long length )

Description

This converts a specified number of days since 01-01-0001 to a date input string.

Arguments

dayno	A number of days since 01-01-0001.
format	The format for the date string, specified by using the substitution symbols  %Dxxx[, lang] or %D(format). See sprintf.
length	The length of the date string: 6: year represented by 2 characters (century not included) 8: year represented by 4 characters (century included).
Return values

The formatted input string. Or an empty string if an error occurs.

Context

Bshell function.

Example

This example creates a default input string for the data.input function.

string inpstring(8)

inpstring = date.to.inputstr$( 727000, "%D002,3", 8 )

If the %D002 format for language 3 is MDY, the string returned is "06171991" (that is, June 17, 1991). If it is DWY, and the first day of the week is Sunday, the string returned is "2251991" (that is, day 2, week 25, 1991).

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


date.to.num()

Syntax

long date.to.num( long yearno, long monthno, long month_dayno )

Description

This returns the number of days since 01-01-0001 for a specified year, month, and day of the month.

Return values

The number of days since 01-01-0001. Or -1 if an error occurs.

Context

Bshell function.

Example

  long no_of_days

  no_of_days = date.to.num( 1991, 04, 20 ) | Returns 726942

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


date.to.utc()

Syntax

long date.to.utc( long yearno, long monthno, long month_dayno, long hours, long minutes, long seconds )

Description

This converts the specified local date and time to UTC long format.

Return values

The UTC long format value.  Or -1 if an error occurs.

Context

3GL library function.

Example

long utc

utc = date.to.utc( 1991, 04, 20, 23, 12, 45 )

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


dte$()

Syntax

string dte$()

Desription

This returns the current date and time in the format MMDDYYHHMMSS.

Notes

The standard variable date$ provides the current date in the format DDMMYY.

The standard variable time provides the current time in the format HHMM.

dte$() cannot be subscripted. To extract part of the return value, use a temporary string, as shown in the example below.

Return values

A string containing the current date and time.

Context

Bshell function.

Example

This example prints the current time in the format HH:MM:SS.

string  dat(12)

dat = dte$()

print dat(7;2), ":", dat(9;2), ":", dat(11;2)

Related Help Topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


get.time.zone()

Syntax

long get.time.zone( ref string time_zone() )

Description

This returns the current time zone. The program must supply a buffer of size 50 to store the result.

Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


inputstr.to.date()

Syntax

long inputstr.to.date( string inputstr(.), string format(7) )

Description

This converts a date input string to the number of days since 01-01-0001.

Arguments

inputstr	The date input string, possibly input by the user and retrieved using the function data.input.
format	Indicates the format of the input string, specified by using the substitution symbols %Dxxx[, lang] or %D(format). See sprintf.
Return value

The number of days from 01-01-0001 to the date specified in the input string. Or -1 if an error occurs.

Context

Bshell function.

Example

This example assumes that %D002,3 represents the format MDY.

long dat

dat = inputstr.to.date( "06171991", "%D002,3" )

| dat now contains 727000

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


inputstr.to.utc()

Syntax

long inputstr.to.utc( const string date.inputstr(), string date.format(7), const string time.inputstr(), string time.format(7) )

Description

This converts the specified local date and time input strings to UTC long format.

Arguments

date.inputstr	A date string (in local time).
date.format	Indicates the format of the date string, by using the substitution symbols %Dxxx[, lang] or %D(format). See sprintf.
time.inputstr	A time string (in local time).
time.format	Indicates the format of the time string, by using the substitution symbols %Uxxx[, lang] or %U(format). See sprintf.
Return values

The UTC long format value. Or -1 if an error occurs.

Context

3GL library function.

Related help topics

    Dates, Times, Time Zones:  Overview
    Dates, Times, Time Zones:  Synopsis


input.to.utc()

Syntax

long input.to.utc( const string value(), const string format() )

Description

This converts a local date or local time string to UTC long format.

Arguments

value	A date string or a time string (in local time).
format	Indicates the format of the input string.  For a date string, use the substitution symbols %Dxxx[, lang] or %D(format). See sprintf.  For a time string, use the substitution symbols %Uxxx[, lang] or %U(format). See sprintf.
Return value

The UTC long format value. Or -1 if an error occurs.

Context

3GL library function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


local.to.utc()

Syntax

long local.to.utc( long local_days, long local_time, ref long utc )

Description

This converts a local date and time to UTC long format.

Arguments

local_days	A number of days since 01-01-0001.
local_time	A number of seconds since 00:00 hours.
utc	The UTC long format value corresponding to the specified local date and time.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


num.to.date()

Syntax

long num.to.date( long dayno, ref long yearno, ref long monthno, ref long month_dayno )

Description

This converts a specified number of days since 01-01-0001 to the corresponding year, month, and day of the month.

Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


num.to.date$()

Syntax

string num.to.date$( long dayno, long mode )

Description

This converts a specified number of days since 01-01-0001 to the corresponding date, formatted as a date string. The sequence of day, month, and year in the string depends on the user data settings defined in the data dictionary. The separator character used is also defined in the data dictionary.

Arguments

dayno	A number of days since 01-01-0001.
mode	Specifies certain characteristics of the date string format: 0: Year as YY without separators (for example, “311290”) 1: Year as YY with separators (for example, “31/12/90”) 2: Year as YYYY without separators (for example, “31121990”) 3: Year as YYYY with separators (for example, “31/12/1990”).
Return values

The formatted date string. Or an empty string if an error occurs.

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


num.to.week()

Syntax

long num.to.week( long dayno, ref long week_dayno, ref long year_dayno, ref long weekno [, ref long yearno] )

Description

This converts a specified number of days since 01-01-0001 to the corresponding day of the week, day of the year, and week number of the year.

Arguments

dayno	A number of days since 01-01-0001.
week_dayno	The day of the week. This depends on which day is defined as the first day of the week in the user data settings in the data dictionary.
year_dayno	The day number in the year.
weekno	The week number in the year. See Week handling.
yearno	The year number. This argument is optional.
Notes

If the day of the week lies in the week that includes the turn of the year, weekno returns either 53, 0, or 1.  The rules applied are:

•	Yearno argument included

•	If less that 4 days of the week belong to the old year, weekno returns 1 and yearno returns the number of the new year.

•	If 4 or more days belong to the old year, weekno returns 53 and yearno returns the number of the old year.

•	Yearno argument not included

•	If the day belongs to the old year, weekno returns 53.

•	If the day belongs to the new year and there are less that 4 days of the new year in the week, weekno returns 0.

•	If the day belongs to the new year and there are more that 3 days of the new year in the week, weekno returns 1.

Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


set.time.zone()

Syntax

long set.time.zone( string time_zone(50) )

Description

This sets the local time zone at run time.

Return values

 0 	 success
-1 	 error

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


time.num()

Syntax

long time.num()

Description

This returns the current time as the number of seconds since 00:00.

Return values

The current time as the number of seconds since 00:00.

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


timezone.exists()

Syntax

long timezone.exists( string timezone(50) )

Description

This checks that the input argument contains the name of a valid time zone.

Return value

 0 	 success
-1 	 error

Context

3GL library function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


utc.num()

Syntax

long utc.num()

Description

This returns the current local date and time in UTC long format.

Return values

The UTC long format value. Or -1 if an error occurs.

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


utc.to.date()

Syntax

long utc.to.date( long utc, ref long yearno, ref long monthno,
ref long month_dayno, ref long hours, ref long minutes,
ref long seconds )

Description

This converts a UTC long format value to the corresponding year, month, day, and so on, in local time.

Return values

 0 	 success
-1 	 error

Context

3GL library function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


utc.to.input()

Syntax

string utc.to.input( long lvalue, const string format() )

Description

This converts a UTC long format value to an input date string or an input time string (in local time). The format specified determines whether the function returns a date string or a time string.

Arguments

lvalue	A UTC long format value.
format	The format for the input string.  For a UTC date, use the substitution symbols %uxxx[,lang] or %u(format). For a UTC time, use the substitution symbols %Uxxx[,lang] or %U(format).
Return values

 0 	 success
-1 	 error

Context

3GL library function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


utc.to.inputstr$()

Syntax

long utc.to.inputstr$( long utc, string date.format(7), string time.format(7), ref string local.date(), ref string local.time() )

Description

This converts a UTC long format value to a local date string and a local time string.

Arguments

utc	A UTC long format value.
date.format	Indicates the format for the returned date string, by using the substitution symbols %uxxx[,lang] or %u(format). See sprintf.
time.format	Indicates the format for the returned time string, by using the substitution symbols %Uxxx[,lang] or %U(format). See sprintf.
local.date	The returned local date string.
local.time	The returned local time string.
Return values

 0 	success
-1	error

Context

3GL library function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


utc.to.local()

Syntax

long utc.to.local(long utc, ref long local_days, ref long local_time )

Description

This converts a UTC long format value to local date and time.

Arguments

utc	The UTC long format value.
local_days	The local date as the number of days since 01-01-0001.
local_time	The local time as the number of seconds since 00:00 hour.
Return values

 0 	 success
-1 	 error

Context

Bshell function.

Related help topics

    Dates, Times, Time Zones:  Overview
    Dates, Times, Time Zones:  Synopsis


utc.to.week()

Syntax

long utc.to.week( long utc, ref long week_dayno, ref long year_dayno, ref long weekno, ref long hours, ref long minutes, ref long seconds [, ref long yearno] )

Description

This converts a UTC long format value to the corresponding day of the week, day of the year, week of the year, and so on, in local time.

Arguments

dayno	The UTC long format value.
week_dayno	The day of the week. This depends on which day is defined as the first day of the week in the user data settings in the data dictionary.
year_dayno	The day number in the year.
weekno	The week number in the year. See Week handling.
hours, minutes, seconds	The time of day.
yearno	The year number. This argument is optional.
Notes

If the day of the week lies in the week that includes the turn of the year, weekno returns either 53, 0, or 1.  The rules applied are:

•	Yearno argument included

•	If less that 4 days of the week belong to the old year, weekno returns 1 and yearno returns the number of the new year.

•	If 4 or more days belong to the old year, weekno returns 53 and yearno returns the number of the old year.

•	Yearno argument not included

•	If the day belongs to the old year, weekno returns 53.

•	If the day belongs to the new year and there are less that 4 days of the new year in the week, weekno returns 0.

•	If the day belongs to the new year and there are more that 3 days of the new year in the week, weekno returns 1.

Return values

 0 	 success
-1 	 error

Context

3GL library function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


week.to.num()

Syntax

long week.to.num( long weekno, long yearno, long week_dayno )

Description

This returns the number of days since 01-01-0001 for a specified week number, year number, and day of the week. The day of the week is interpreted by using the day defined as the first day of the week in the user data settings in the data dictionary (see Week handling).

Return values

The number of days since 01-01-0001. Or -1 if an error occurs.

Context

Bshell function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


week.to.utc()

Syntax

long week.to.utc( long weekno, long yearno, long week_dayno, long hours, long minutes, long seconds )

Description

This converts a specified week number, year number, day number in week, and so on, in local time, to UTC long format. For information on week numbering, see Week handling.

Return values

The UTC long format value. Or -1 if an error occurs.

Context

3GL library function.

Related help topics

    Dates, times, time zones:  overview
    Dates, times, time zones:  synopsis


Directory and file operations: overview

Use these functions to perform various directory and file operations – for example:

•	to open, read, and close directories and directory entries

•	to move, copy, and delete files

•	to retrieve file information

•	to create directories and temporary files

•	to change the access permissions for a file

•	to handle sequential file input and output.

Related help topics

    Directory and file operations:  synopsis


Directory and file operations: synopsis

string	creat.tmp.file$	( [string pathname] )
long	dir.close	( long dfd )
string	dir.entry	( long dfd, long read_type, const long    return_type, const long filesize, const    long mode )
long	dir.open	( const string path )
long	dir.open.tree	( const string path [, long nlevels] )
long	dir.rewind	( long dfd )
long	file.chmod	( const string file, long mode )
long	file.chown	( string file, string user, string group )
long	file.cp	( const string source, const string target )
long	file.mv	( const string source, const string target )
long	file.mv.across.hosts	( const string source, const string target )
long	file.rm	( const string path )
long	file.stat	( string file_name(256), ref long file_size    [, ref long ctime, ref long mtime,    ref long atime ] )
long	fstat.info	( long fp, ref long size, ref long mode,    ref long inode, ref long dev, ref long uid,    ref long gid, ref long nlink, ref long ctime,   ref long mtime, ref long atime )
string	getcwd	( )
long	mkdir	( string path_name$ )
long	pathname	( string file_basename(16), string file_type,   ref string file_path(256) )
long	rm.dir	( const string path )
long	seq.clearerr	( long fp )
long	seq.close	( long fp )
long	seq.eof	( long fp )
long	seq.error	( long fp )
long	seq.flush	( long fp )
string	seq.getc$	( long fp )
long	seq.gets	( ref string line(), long nrbytes, long fp )
long	seq.islocked	( long mode, long offset, long size, long fp )
long	seq.lock	( long mode, long offset, long size, long fp )
long	seq.open	( string file(128), string openmode(2)    [, ref string pathnm()] )
string	seq.putc$	( string char, long fp )
long	seq.puts	( string line(2048), long fp )
long	seq.read	( ref string buffer(), long nrbytes, long fp )
long	seq.rewind	( long fp )
long	seq.seek	( long offset, long opt, long fp )
long	seq.tell	( long fp )
string	seq.ungetc$	( string char, long fp )
long	seq.unlink	( string path_name(128) )
long	seq.unlock	( long mode, long offset, long size, long fp )
long	seq.write	( string buffer(2048), long nrbytes, long fp )
long	stat.info	( string file_name(256), ref long size,    ref long mode, ref long inode, ref long dev,    ref long uid, ref long gid, ref long nlink,    ref long ctime, ref long mtime,    ref long atime )
Related help topics

    Directory and file operations:  overview


creat.tmp.file$()

Syntax

string creat.tmp.file$( [string pathname] )

Description

This creates a temporary file. By default, the file is created in the current directory. To create the file in a different directory, use the optional pathname argument to specify the full path to the required directory.

In UNIX environments, a unique temporary file is created with UNIX-privilege mode 0664.

Notes

It is recommended that you use this function in conjunction with the BSE_TMP environment variable. You can use the function bse.tmp.dir$() to retrieve the name of the directory defined by this variable. For example:

creat.tmp.file$( bse.tmp.dir$() )

Return values

The name of the temporary file.

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


dir.close()

Syntax

long dir.close( long dfd )

Description

This closes a specified directory and frees all memory allocated to it. The dfd argument is the pointer to the directory returned by dir.open() or dir.open.tree() when the directory was opened.

Return values

>=0	success
   -1   	no free pointer
   -2	directory could not be opened or found
   -3	bad directory descriptor

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


dir.entry()

Syntax

string dir.entry( long dfd, long read_type, const long return_type, const long filesize, const long mode )

Description

This retrieves entries from a previously opened directory. It retrieves the entries sequentially.

Arguments

dfd	The pointer to the required directory, as returned when the directory was opened by dir.open() or dir.open.tree().
read_type	Specifies the type of entry to be retrieved. Possible values are: TDIR directories TFILE files TDIR+TFILE directories and files
return_type	Returns the type of entry retrieved. Possible values are:  TDIR directory TFILE file
filesize	Returns the size of the entry retrieved.
mode	If the user can access the entry, this argument returns the type of access the user has. Possible options (returned as a bitset) are: STAT_READABLE read STAT_WRITEABLE read, write, and delete STAT_EXECUTABLE run program
Return values

The directory entry. Or an empty string if the end of the entry list has been reached.

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


dir.open()

Syntax

long dir.open( const string path )

Description

This reads the specified directory into memory. The path argument can have a maximum length of 2048 characters.

The function returns a pointer (dfd) to the directory data. dir.entry() , dir.rewind() , and dir.close() use this pointer to access the directory.

Return values

>0	a pointer to the directory data
 -1   	no free pointer
 -2	directory could not be opened or found
 -3	bad directory descriptor

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


dir.open.tree()

Syntax

long dir.open.tree( const string path [, long nlevels] )

Description

This is similar to dir.open() in that it reads a specified directory into memory. However, dir.open.tree() can retrieve up to 256 directory levels.

The function returns a pointer (dfd) to the directory data. dir.entry() , dir.rewind() , and dir.close() use this pointer to access the directory.

Arguments

path	The path to the required directory. This can have a maximum length of 2048 characters.
nlevels	Use this optional argument to indicate the number of directory levels that must be read. The default is one.
Notes

When a large directory tree is requested, this function can consume a large amount of memory and CPU time. This may block other processes in the same bshell for several minutes or longer, depending on the overall system load.

Return values

>0	a pointer to the directory data
 -1   	no free pointer
 -2	directory could not be opened or found
 -3	bad directory descriptor

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


dir.rewind()

Syntax

long dir.rewind( long dfd )

Description

This resets the read pointer of the specified directory to the beginning of the directory entry list. The dfd argument is the pointer to the directory returned by dir.open() or dir.open.tree() when the directory was opened.

Return values

>=0 	success
   -1	no free pointer
   -2	directory could not be opened or found
   -3	bad directory descriptor

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


file.chmod()

Syntax

long file.chmod( const string file, long mode )

Description

This sets the access permissions for a specified file.

Arguments

file	The name of the file.
mode	The type of access permissions that must be set. This can be a combination of the following values: User/owner S_IRWXU read, write, execute S_IRUSR read S_IWUSR write S_IXUSR execute, search Group S_IRWXG  read, write, execute S_IRGRP   read S_IWGRP   write S_IXGRP   execute, search Other (UNIX only) S_IRWXO   read, write, execute S_IROTH   read S_IWOTH   write S_IXOTH    execute, search
Note

Setting file access permissions is a system-dependent feature. To enable applications to be system independent, this function does not return an error code when a particular feature is unavailable.

Return values

  1	success
<0	error

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


file.chown()

Syntax

long file.chown( string file, string user, string group )

Description

This changes the owner and/or group of a file. You can use a single call to change both the owner and the group. Alternatively, you can specify either the user argument or the group argument as an empty string.

Arguments

file	The name of the file.
user	The new owner of the file.
group	The new group of the file.
Note

Setting users and groups for files is a system-dependent feature. To enable applications to be system independent, this function does not return an error code when a particular feature is unavailable.

Return values

  0	success
<1	error

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


file.cp()

Syntax

long file.cp( const string source, const string target )

Description

This copies a specified source file to a specified target file. Both files can be either local or remote. They can also be on different hosts (provided that the bshell can access both hosts).

Return values

  1	success
<0	error

Context

3GL library function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


file.mv()

Syntax

long file.mv( const string source, const string target )

Description

This moves a specified source file to the location specified in the target argument. The file can be either local or remote. Both source and target must be on the same host.

Return values

  1	success
<0	error

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


file.mv.across.hosts()

Syntax

long file.mv.across.hosts( const string source, const string target )

Description

This moves a specified source file to the location specified in the target argument. The file can be either local or remote. Source and target can be on different hosts.

Return values

  1	success
<0	error

Context

3GL library function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


file.rm()

Syntax

long file.rm( const string path )

Description

This deletes a specified local or remote file. The path argument must include the full path to the file, including the host name, where appropriate. For example: "host!/usr/myfile".

Return values

  1	success
<0	error

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


file.stat()

Syntax

long file.stat( string file_name(256), ref long file_size [, ref long ctime, ref long mtime, ref long atime ] )

Description

This returns information about a specified file. It is a short version of the stat.info() function.

Arguments

file_name	The name of the file for which information is required.
file_size	The file size in bytes.
ctime	The time when the file status was last changed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
mtime	The time when the file was last modified, as a number of seconds since 00:00:00 GMT, January 1, 1970.
atime	The time when the file data was last accessed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
Return values

    0	file exists
<>0	operating system error code

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


fstat.info()

Syntax

long fstat.info( long fp, ref long size, ref long mode, ref long inode, ref long dev, ref long uid, ref long gid, ref long nlink, ref long ctime, ref long mtime, ref long atime )

Description

This returns information about a specified file. It provides the same information as stat.info(). But instead of retrieving information about a named file, it returns information about an open file that is known by the file descriptor fp. This descriptor can be obtained, for example, from a successful seq.open() call.

Arguments

fp	The file descriptor, as returned, for example, by seq.open().
size	The file size in bytes.
mode	This contains a bit pattern that indicates the access permission (posix) of the file. Use the following defines to check the file mode: S_IRWXU   read, write, execute permission by owner S_IRUSR   read permission by owner S_IWUSR   write permission by owner S_IXUSR     execute, search permission by owner S_IRWXG   read, write, execute permission by group S_IRGRP   read permission by group S_IWGRP   write permission by group S_IXGRP    execute, search permission by group S_IRWXO   read, write, execute permission by others S_IROTH   read permission by others S_IWOTH   write permission by others S_IXOTH    execute, search permission by others S_ISUID set user id on execution (sbit) S_ISGID set group id on execution (sbit) S_ISVTX save text after execution
inode	inode number.
dev	Device where file is stored.
uid	User ID of the file’s owner.
gid	The file’s group ID.
nlink	Number of links to the file.
ctime	The time when the file status was last changed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
mtime	The time when the file was last modified, as a number of seconds since 00:00:00 GMT, January 1, 1970.
atime	The time when the file data was last accessed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
Notes

You can use the following macros to check the file type:

if ( S_ISDIR(mode) )	| file is a directory (perm: drwxrwxrwx)

if ( S_ISREG(mode) )	| file is an ordinary file (perm: -rwxrwxrwx)

if ( S_ISBLK(mode) )	| file is a block-oriented device (disk or tape)
  (perm: brwxrwxrwx)

if ( S_ISCHR(mode) )	| file is a character-oriented device
  (perm: crwxrwxrwx)

if ( S_ISFIFO(mode) )	| file is a fifo special file (perm: prwxrwxrwx)

if ( S_ISSOCK(mode) )	| file is a socket file (perm: srwxrwxrwx)

Return values

    0	success
<>0	operating system error code

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


getcwd()

Syntax

string getcwd( )

Description

This returns the current path as a string. Note that on Windows NT systems, pathnames can include drive letters (for example, c:/baan/bin).

Return values

The current path as a string. Or an empty string if an error occurs.

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


mkdir()

Syntax

long mkdir( string path_name$ )

Description

This creates a specified directory (local or remote). You must have write permission in the parent directory to do this. Access permissions for the new directory are set to read, write, and execute for all users. The path_name$ argument must include the full path to the directory, including the host name, where appropriate. For example:

mkdir( "host1!/usr/mydir" )

Return values

 1	success
 0	path already exists (only returned when creating a local directory)
-1	failure; probably no permission

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


pathname()

Syntax

long pathname( string file_basename(16), string file_type, ref string file_path(256) )

Description

This searches for and returns the location of a specified file.

The function uses the file $BSE/lib/fdver.pack_combination to find the file. ver refers to a particular release of the software; pack_combination refers to a particular package combination.

It is not necessary to use this function within functions such as db.bind(). These also use the file $BSE/lib/fdver.pack_combination to search for a path name.

Arguments

file_basename	The name of the file that must be found.  The file name must begin with xppmmm where pp is a package code, mmm is a module code, and x is a single character that corresponds to the file type, as shown in column one of the following list:
	Character d r o f m p i	Description data/domain definition report object form menu program script include file	file_type argument “D” “O” “O” “S” “M” “P” “P”
	For example, when searching for a report, the file name specified must begin with 'r'. The name of the report object located begins with 'o'.
file_type	The file type. Use the values shown in column three of the above list.
file_path	This returns the full path to the specified file.  If the file is not found, it returns the full path (including filename) where the file should be created.  If the file_type is unknown, or file_basename starts with an invalid character, this argument returns the value of file_basename.
Notes

Language codes are relevant to reports, forms, and menus. You can specify the language code for a report, form, or menu file by appending it to the file name (that is, adding it as the 16th character). If you do not include this, the current language is assumed.

Return values

0	success
ENOENT 	file not found

Context

Bshell function.

Example:

string file_path(256)

if pathname( "rpctst121200010", "O", file_path ) then

message( "File not found, must be created in %s", file_path )

endif

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


rm.dir()

Syntax

long rm.dir( const string path )

Description

This deletes the specified directory (local or remote). The path argument must include the full path to the directory, including the host name, where appropriate. For example: "host!c:\usr".

Return values

  1	success
<0	error

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.clearerr()

Syntax

long seq.clearerr( long fp )

Description

This resets the error and end-of-file indicators for the specified file. fp is the file pointer returned by seq.open() when the file was opened.

Return values

 0	success
-1	error; probably fp not connected

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.close()

Syntax

long seq.close( long fp )

Description

This flushes the buffers associated with the specified file and closes the file. fp is the file pointer returned by seq.open() when the file was opened. Buffers allocated by the standard i/o system are also flushed and closed. These actions are performed automatically when the process exits.

Return values

 0	success
-1	error; probably fp not connected
(the last system error is available in the e variable – for example, for file system full, e
will be ENOSPC (that is, 28) – for a list of error codes, see Errors)

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.eof()

Syntax

long seq.eof( long fp )

Description

This checks the end-of-file indicator of a specified file. fp is the file pointer returned by seq.open() when the file was opened.

An end-of-file indication lasts until it is cleared by seq.clearerr() or until the file is closed.

Return values

  0	end-of-file indicator not set
>0	end-of-file indicator set
 -1	error; probably fp not connected

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.error()

Syntax

long seq.error( long fp )

Description

This checks the error indicator of a specified file. The error indicator is set when an error occurs while reading from or writing to the file. It lasts until it is cleared by seq.clearerr() or until the file is closed. fp is the file pointer returned by seq.open() when the file was opened.

Return values

  0	error indicator not set
>0	error indicator set
 -1	error; probably fp not connected

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.flush()

Syntax

long seq.flush( fp )

Description

This causes all buffered data for a specified file to be written to that file. The file remains open. fp is the file pointer returned by seq.open() when the file was opened.

Return values

 0	success
-1	error; probably fp not connected
(the last system error is available in the e variable – for example, for file system full, e
will be ENOSPC (that is, 28) – for a list of error codes, see Errors)

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.getc$()

Syntax

string seq.getc$( long fp )

Description

This returns the next character from a specified file. fp is the file pointer returned by seq.open() when the file was opened. An empty string indicates either that the end-of-file has been reached or that an error has occurred.

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.gets()

Syntax

long seq.gets( ref string line(), long nrbytes, long fp [, mode, ref long there.was.more] )

Description

This reads one or more characters from a specified file.

Arguments

line	This stores the retrieved characters.
nrbytes	The maximum number of bytes to be read. Note that the function stops retrieving characters when a new line character is read or when the end of file is reached.  The maximum number of characters that can be read is 2048.
fp	The pointer to the file from which the characters are to be read, as returned by seq.open() when the file was opened.
mode	Use this optional argument to specify the read mode for seq.gets(). Possible values are:
	GETS_NORMAL	The function continues reading characters until either the buffer (line) is full, a new line character is read, or EOF is reached.  If the buffer is full, any remaining characters on the line being read are discarded.  This is the default mode.
	GETS_ALL_CHARS	The function continues reading characters until either the buffer (line) is full, a new line character is read, or EOF is reached.  If the buffer is full, the next seq.gets() call starts reading at the point where the current seq.gets() finished. The use of this mode ensures that all characters available in input file are eventually returned.
	GETS_SKIP_ALL	This is the same as GETS_NORMAL, except that if the last line in the file does not end with a new line character, that line is discarded completely and EOF is returned.
there.was.more	When characters are discarded in GETS_NORMAL or GETS_SKIP_ALL mode, or when more characters are available in the line (but the buffer is full) in GETS_ALL_CHARS mode, this argument is set to 1. Otherwise, the argument returns 0.

Return values

 0	success
-1	error; probably fp not connected or end of file reached

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.islocked()

Syntax

long seq.islocked( long mode, long offset, long size, long fp )

Description

This checks whether a specified file or segment of a file has been locked by seq.lock().

Arguments

mode	The type of lock you want to check for: SEQ_R_LCK read lock SEQ_W_LCK write lock SEQ_F_R_LCK file lock (read) SEQ_F_W_LCK file lock (write)
offset, size	To check whether a particular segment of the file has been locked, use these arguments to specify the offset of the segment from the beginning of the file and the length of the segment.
fp	The file pointer returned by seq.open() when the file was opened.
Return values

     0	file or file segment not locked
 <>0	file or file segment locked

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.lock()

Syntax

long seq.lock( long mode, long offset, long size, long fp )

Description

This sets read and write locks on a specified file or segment of a file.

Arguments

mode	The type of lock to set: SEQ_R_LCK read lock SEQ_W_LCK write lock SEQ_F_R_LCK file lock (read) SEQ_F_W_LCK file lock (write)
offset, size	To set a lock on a segment of the file, use these arguments to specify the offset of the segment from the beginning of the file and the length of the segment.  To extend a lock to the end of the file, set size to 0. To set a lock on the entire file, set both arguments to 0.
fp	The file pointer returned by seq.open() when the file was opened.
Notes

A read lock prevents any process from setting a write lock on the protected file or file segment. Multiple read locks can be set for the same file or file segment. The file with which the lock is associated must have been opened with read access (see seq.open() ).

A write lock prevents any process from setting a read lock or a write lock on the protected file or file segment. Only one write lock can exist for a particular file or file segment. The file with which the lock is associated must have been opened with write access.

Return values

>= 0	success
    -1	error; probably fp not connected
 < -1	operating system error code

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.open()

Syntax

long seq.open( string file(128), string openmode(2) [, ref string pathnm()] )

Description

This opens a specified file. It uses the file $BSE/lib/fdver.pack_combination to find the file. ver refers to a particular release of the software; pack_combination refers to a particular package combination (see pathname()).

Arguments

file	The file name.
openmode	The mode in which the file must be opened. This can be one of the following options:
	"r" "w" "a" "x" "r+" "w+" "a+" "x+"	Open for reading. The current file position is placed at the start of the file. Open for writing. The file is created if it does not already exist. The current file position is placed at the start of the file. Open for writing. The file is created if it does not already exist. The current file position is placed at the end of the file. Open for writing. This is the same as "w", except that the function fails if the file already exists.  Same as "r", but the file can also be written to. Same as "w", but the file can also be read.  Same as "a", but the file can also be read. Same as "x", but the file can also be read.
	Use the following modes to indicate whether the file is a binary or a text file. You can combine one of these modes with any one of the previous modes (for example, "rt+").
	"b" "t"	Use for binary files. This is the default mode and need not be specified.  The line separator(s) for text-files are different on Windows NT and UNIX systems. CRLF on the former; LF only on the latter. In addition, a Windows NT text file can include an EOF-character (^Z) that indicates the end of the file. This character should not be returned to a program reading the file. So, you must specify the "t" option when reading from or writing to a text file on Windows NT systems (for example, "at+".) This ensures that line separators and EOF characters are handled correctly. Never use the "t" option when opening a binary file; on Windows NT systems this will corrupt the file data. The "t" option has no effect on UNIX systems.
pathnm	This returns the full path to the file.
Notes

When you open a file for reading and writing, you cannot follow an output operation directly by an input operation. You must call seq.seek() or seq.rewind() to reset the current file position before the input operation.

Also, you cannot follow an input operation directly by an output operation, unless the input operation encounters the end-of-file indicator. You must call seq.seek() or seq.rewind() to reset the current file position before the output operation.

Return values

>= 1	success; file pointer returned for use in subsequent operations
  < 1	error; that is, the negative value of the system error (for example, for a permission error,
the system returns 13 and the function returns -13, or if the internal table is full, the function
returns -EAGAIN).

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.putc$()

Syntax

string seq.putc$( string char, long fp )

Description

This writes a specified character to a specified file. fp is the file pointer returned by seq.open() when the particular file was opened.

Return values

The character written to the file. Or an empty string if the end-of-file was reached or an error occurred.

The last system error is available in the e variable – for example, for file system full, e will be ENOSPC (that is, 28) – for a list of error codes, see Errors.

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.puts()

Syntax

long seq.puts( string line(2048), long fp )

Description

This writes the specified characters to a specified file, and appends a new line character. fp is the file pointer returned by seq.open() when the particular file was opened.

Return values

 0	success
-1	error; probably fp not connected
(the last system error is available in the e variable – for example, for file system full, e
will be ENOSPC (that is, 28) – for a list of error codes, see Errors)

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.read()

Syntax

long seq.read( ref string buffer(), long nrbytes, long fp )

Description

This reads a specified number of bytes from a specified file into buffer. fp is the file pointer returned by seq.open() when the particular file was opened.

Return values

>0	number of bytes read
  0	end-of-file
 -1	error; probably fp not connected

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.rewind()

Syntax

long seq.rewind( long fp )

Description

This sets the current file position to the beginning of the file. It is equivalent to: seq.seek( 0, 0, fp ).

Return values

 0	success
-1	error; probably fp not connected

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.seek()

Syntax

long seq.seek( long offset, long opt, long fp )

Description

This changes the current file position.

Arguments

offset	The new file position, as a number of bytes.
opt	This determines whether the specified offset is from the beginning of the file, the end of the file, or the current file position: 0 new position is offset from the beginning of the file 1 new position is offset from the current file position 2 new position is offset from the end of the file
fp	The file pointer returned by seq.open() when the particular file was opened.
Return values

>=0	success; returns new position in bytes from the beginning of the file
  <0	error; probably fp not connected; current file position is not changed

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.tell()

Syntax

long seq.tell( long fp )

Description

This returns the current file position, relative to the beginning of the file. The file position is measured in bytes. fp is the file pointer returned by seq.open() when the particular file was opened.

Take care when using this function on files that have been opened in append mode (that is, with the openmode argument set to a or a+). Before calling seq.tell(), always call seq.flush() after you have written to the file with seq.write().

Return values

>=0	success
   -1	error; probably fp not connected

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.ungetc$()

Syntax

string seq.ungetc$( string char, long fp )

Description

This puts back a specified character, retrieved by seq.getc$(). The character will be returned by the next seq.getc$() call on that file. This function works only if something has been read from the file and if the file is buffered. fp is the file pointer returned by seq.open() when the particular file was opened.

Return values

The character written to the file. Or an empty string if end-of-file is reached or an error occured.

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.unlink()

Syntax

long seq.unlink( string path_name(128) )

Description

This deletes the file indicated by the path_name argument.

Return values

  0	success
<0	error; that is, the negative value of the operating system error

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.unlock()

Syntax

long seq.unlock( long mode, long offset, long size, long fp )

Description

This removes a lock set by seq.lock().

Arguments

mode	The type of lock to remove: SEQ_R_LCK read lock SEQ_W_LCK write lock SEQ_F_R_LCK file lock (read) SEQ_F_W_LCK file lock (write)
offset, size	To remove a lock from a segment of the file, use these arguments to specify the offset of the segment from the beginning of the file and the length of the segment.  To remove a lock that extends to the end of the file, set size to 0. To remove a lock from the entire file, set both arguments to 0.
fp	The file pointer returned by seq.open() when the file was opened.
Notes

All locks set on a file by a particular process are removed automatically when the file descriptor for the file is closed by the process (see seq.close()) or when the process itself terminates.

Return values

>=0	success
   -1	error; probably fp not connected
 <-1	negative error value

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


seq.write()

Syntax

long seq.write( string buffer(2048), long nrbytes, long fp )

Description

This appends data from the specified buffer to the specified file, beginning at the current file position. The nrbytes argument indicates the number of bytes to be written to the file. fp is the file pointer returned by seq.open() when the particular file was opened.

Return value

>0	number of bytes actually written
  0	end-of-file
 -1	error; probably fp not connected
(the last system error is available in the e variable – for example, for file system full, e
will be ENOSPC (that is, 28) – for a list of error codes, see Errors)

Context

Bshell function.

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


stat.info()

Syntax

long stat.info( string file_name(256), ref long size, ref long mode, ref long inode, ref long dev, ref long uid, ref long gid, ref long nlink, ref long ctime, ref long mtime, ref long atime )

Description

This returns information about a named file. It provides the same information as fstat.info(), but for a named file.

Arguments

file_name	The name of the file. All files listed in the path name must be searchable. To specify a remote file, include the host name. For example: "host!/usr/myfile".
size	The file size in bytes.
mode	This contains a bit pattern that indicates the access permission (posix) of the file. Use the following defines to check the file mode: S_IRWXU   read, write, execute permission by owner S_IRUSR    read permission by owner S_IWUSR    write permission by owner S_IXUSR    execute, search permission by owner S_IRWXG   read, write, execute permission by group S_IRGRP   read permission by group S_IWGRP    write permission by group S_IXGRP    execute/search permission by group S_IRWXO    read, write, execute permission by others S_IROTH    read permission by others S_IWOTH    write permission by others S_IXOTH     execute, search permission by others S_ISUID set user id on execution (sbit) S_ISGID set group id on execution (sbit) S_ISVTX save text after execution
inode	inode number.
dev	Device where file is stored.
uid	User ID of the file’s owner.
gid	The file’s group ID.
nlink	Number of links to the file.
ctime	The time when the file status was last changed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
mtime	The time when the file was last modified, as a number of seconds since 00:00:00 GMT, January 1, 1970.
atime	The time when the file data was last accessed, as a number of seconds since 00:00:00 GMT, January 1, 1970.
Notes

You can use the following macros to check the file type:

if ( S_ISDIR(mode) )	| file is a directory (perm: drwxrwxrwx)

if ( S_ISREG(mode) )	| file is an ordinary file (perm: -rwxrwxrwx)

if ( S_ISBLK(mode) )	| file is a block-oriented device (disk or tape)
  (perm: brwxrwxrwx)

if ( S_ISCHR(mode) )	| file is a character-oriented device
  (perm: crwxrwxrwx)

if ( S_ISFIFO(mode) )	| file is a fifo special file (perm: prwxrwxrwx)

if ( S_ISSOCK(mode) )	| file is a socket file (perm: srwxrwxrwx)

Return values

    0	success
<>0	operating system error code

Context

Bshell function.

Example

long 	ret

long 	size, mode, inode, dev, uid, gid, nlink, ctime, atime, mtime

string file_name(256)

file_name = "/usr/bse/lib/ipc_info"

ret = stat.info( 	file_name,

size,

mode,

inode,

dev,

uid,

gid,

nlink,

ctime,

mtime,

atime )

if ret then

| stat.info failed, probably file not found

endif

if ( S_ISDIR( mode ) ) then

sprintf$( "%s is a directory", file_name )

endif

if ( bit.and( S_IRUSR, mode ) ) then

sprintf$( "User has read permission" )

endif

if ( bit.and( S_IWUSR, mode ) ) then

sprintf$( "User has write permission" )

endif

if ( bit.and( S_IXUSR, mode ) ) then

sprintf$( "User has execute permission" )

endif

Related help topics

    Directory and file operations:  overview
    Directory and file operations:  synopsis


DLL functions (executing): overview and synopsis

Overview

Use these functions to execute functions in a dynamic link library (DLL) at runtime. For an overview of dynamic link libraries and runtime dynamic linking, see Dynamic link libraries.

Synopsis

long	exec_dll_function	( string dll_name, string function_name    [, ref void return_value, arg, ...] )
long	exec_function	( long dll_id, long func_id [, ref void    return_value, arg, ...] )
long	get_function	( long dll_id, string function_name )
long	load_dll	( string dll_name [, long overload ] )
long	parse_and_exec_function	( string dll_name, string function_call    [, ref void return_value, ref string    return_call() ] )


exec_dll_function()

Syntax

long exec_dll_function( string dll_name, string function_name [, ref void return_value, arg, ...] )

Description

This loads a specified DLL and executes a specified function within that DLL. It provides a fast algorithm for executing a DLL function that is to be executed only once. If the DLL is already loaded, the identification number of the loaded DLL is used to search for the specified function. Otherwise, a load_dll(dll_name, 0) call is executed automatically. If a function is to be called more than once, it is faster to use the load_dll(), get_function(), and exec_function() combination.

Arguments

dll_name	The name of the DLL that must be loaded.
function_name	The name of the function that must be executed.
return_value	This stores the return value (if any) of the function.
arg ...	The arguments of the function (if any). These are function dependent.
Return values

 0	success
-1	error; DLL not found
-2	error; function not found

Context

Bshell function.

Example

long ret, ret2

ret=exec_dll_function("otisfc0220", "ptisfc0220.store.quantities",

ret2, tibom010.noun, tibom010.qana, tibom010.scpf )

Related help topics

    DLL functions: overview and synopsis


exec_function()

Syntax

long exec_function( long dll_id, long func_id [, ref void return_value,
arg, ...] )

Description

This executes a function previously loaded by a call to get_function(). After the function has been loaded, you can call exec_function() any number of times to execute the function.

Arguments

dll_id	The identification number of the DLL that contains the function, as returned by load_dll().
funct_id	The identification number of the function, as returned by get_function().
return_value	This stores the return value (if any) of the function.
arg ...	The arguments of the function (if any). These are function dependent.
Return values

 0	success
-1	error, DLL not found
-2	error, function not found

Context

Bshell function.

Example

This example loads the DLL "tisfc0220" and executes the function "tisfc0220.store.quantities" contained in that DLL.

long dll_id, func_id

long ret, ret2

dll_id = load_dll("otisfc0220")

if dll_id then

func_id = get_function( dll_id, "tisfc0220.store.quantities" )

if func_id then

select tibom010.noun, tibom010.qana, tibom010.scpf

from tibom010

selectdo

ret = exec_function( dll_id, func_id, ret2, tibom010.noun,
tibom010.qana, tibom010.scpf )

endselect

endif

endif

Related help topics

    DLL functions: overview and synopsis


get_function()

Syntax

long get_function( long dll_id, string function_name )

Description

This loads a specified function from a previously loaded DLL. It returns an identification number for the function.

Arguments

dll_id	The identification number of the DLL that contains the function, as returned by load_dll().
funct_name	The function name.
Return values

>0	function identifier
  0	error; function not found or DLL not loaded

Context

Bshell function.

Related help topics

    DLL functions: overview and synopsis


load_dll()

Syntax

long load_dll( string dll_name [, long overload ] )

Description

This loads a specified DLL.

You can use it in combination with get_function() and exec_function() to call and execute a function in a DLL. These three functions provide a fast algorithm for accessing a function that is to be executed more than once. You load the DLL and function only once and can then execute the function any number of times. load_dll() returns an identification number that the other functions use to identify a particular DLL.

You can also use load_dll() to replace one or more functions within a DLL by overloading a different DLL containing functions with the same names and arguments. But note that once a function has been loaded from a DLL, that DLL cannot subsequently be overloaded.

For a full discussion on function overloading, see Function overloading.

Arguments

dll_name	The name of the DLL.
overload	This optional argument sets the overload flag for the specified DLL. The possible values are: 0 places the DLL as the last element in the search list of all dynamically  loaded DLLs – this is the default option DLL_OVERLOAD places the DLL as the first element in the search list of all dynamically loaded DLLs DLL_SILENT_ERR suppresses error messages You can combine DLL_SILENT_ERR with either of the other options.
Notes

You cannot load the same DLL more than once within the same process. If you call load_dll() a second time, it returns the same identification number as it did the first time. However, you can use subsequent calls to load_dll() to change the value of the overload flag.

The load_dll() function must be called before the first function call to the DLL. Once a function has been found in one of the loaded DLLs, the function address is resolved. That address is used for all subsequent function calls; it cannot be replaced by overloading another DLL.

Return values

>0	DLL identifier
  0	error; DLL not found

Context

Bshell function

Related help topics

    DLL functions: overview and synopsis


parse_and_exec_function()

Syntax

long parse_and_exec_function( string dll_name, string function_call [, ref void return_value, ref string return_call() ] )

Description

This function is similar to exec_dll_function(). It loads a specified DLL and parses and executes a specified function within that DLL. If the DLL is already loaded, the identification number of the loaded DLL is used to search for the specified function. Otherwise, a load_dll(dll_name, 0) call is executed automatically.

Use this function only when the function and its arguments are known only at runtime. The function is intended for handing function calls received as strings from other processes.

Arguments

dll_name	The name of the DLL that must be loaded.
function_call	A string containing the function name and arguments. You can specify any function in this argument, except one that contains array arguments. To execute a function with array arguments, use exec_dll_function() instead.
return_value	This stores the return value (if any) of the function.
return_call	If the function call includes reference arguments, the value of these can change during execution of the function. This returns the parsed function call, so that you can check the values of reference arguments.
Note

If the function call contains reference arguments, the result of the function call (stored in return_call) cannot become longer than the length of the function_call argument.

Return values

 0	success
-1	error; DLL not found
-2	error; function not found
-3	syntax error in function call

Context

Bshell function.

Example

| assume the function my_max in DLL ttstdlib which returns the

| maximum of the two given arguments.

| object ottstdlib belongs to DLL ttstdlib

long   ret, ret2

long   a, b

string ret_call(80)

string funccall(80)

a = 30

b = 40

funccall = sprintf$("my_max(%d,%d)", a, b)

ret = parse_and_exec_function( "ottstdlib", funccall, ret2, ret_call )

| ret2 becomes 40

| ret_call becomes "my_max(30,40)"

Related help topics

    DLL functions: overview and synopsis


Dynamic SQL queries: overview

Dynamic SQL enables programs to compose and execute SQL statements at runtime. This is necessary, for example, when SQL statements are composed in response to user input.

You use the functions described in this section to handle dynamic SQL queries. Use sql.parse() to define the query. Once the query has been defined, use the other functions to bind variables in the SQL statement to BAAN 4GL variables, to execute the query, to fetch the results, and to end and delete the query. Note that there is no need to bind external variables. Once you have defined a query using sql.parse(), you can execute it any number of times, using different variables, without redefining it.

The sequence in which you use the functions is as follows:

sql.parse()

sql.select.bind()

sql.where.bind()

sql.exec()

sql.fetch()

sql.fetch()

...

sql.break()

sql.select.bind()

sql.where.bind()

sql.exec()

sql.fetch()

sql.fetch()

...

sql.break()

sql.close

For a general discussion of database handling, and embedded and dynamic SQL, see Database handling.

Related help topics

    Dynamic SQL queries:  synopsis


Dynamic SQL queries: synopsis

long	sql.break	( long sql_id )
long	sql.close	( long sql_id )
long	sql.exec	( long sql_id )
long	sql.fetch	( long sql_id )
long	sql.parse	( string query(.), [ long suppr_err ] )
long	sql.select.bind	( long sql_id, long pseudo_var, var_name(.) )
long	sql.set.rds.full	( long sql.id, long size )
long	sql.where.bind	( long sql_id, long pseudo_var, var_name(.) )
Related help topics

    Dynamic SQL queries:  overview


sql.break()

Syntax

long sql.break( long sql_id )

Description

This stops the specified query and clears any interim results. The sql_id argument indicates the query ID, as returned by sql.parse(). The function does not remove the query itself. So the query can be reused after binding to another variable, for example.

Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Dynamic SQL queries:  overview
    Dynamic SQL queries:  synopsis


sql.close()

Syntax

long sql.close( long sql_id )

Description

This deletes all internal information relating to the specified query. The sql_id argument indicates the query ID, as returned by sql.parse().

Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Dynamic SQL queries:  overview
    Dynamic SQL queries:  synopsis


sql.exec()

Syntax

long sql.exec( long sql_id )

Description

This initializes the specified query and evaluates any bind variables in the WHERE clause. Before calling this function, you must previously have called sql.parse() to define the query. The sql_id argument indicates the query ID, as returned by sql.parse().

Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Dynamic SQL queries:  overview
    Dynamic SQL queries:  synopsis


sql.fetch()

Syntax

long sql.fetch( long sql_id )

Description

This reads a single query result and stores the values retrieved in the variables specified in the SELECT list. The sql_id argument indicates the query ID, as returned by sql.parse(). You must call the function for each individual record in the result set.

Return values

    0	success
<>0	error

The function returns eendfile when it reaches the end of the result set. It returns enorec if the set is empty.

Context

Bshell function.

Related help topics

    Dynamic SQL queries:  overview
    Dynamic SQL queries:  synopsis


sql.parse()

Syntax

long sql.parse( string query(.), [ long suppr_err ] )

Description

This defines an SQL query that you can subsequently execute and retrieve the results of by using the other dynamic SQL functions. The query takes the form of a SELECT statement (see Database handling). If you set the optional argument suppr_err to 1, this suppresses error messages (the predefined variable e contains the error number).

Return values

  0	error
>0	query ID; this is used by the other functions to identify the particular query

Example

sql_id_1 = sql.parse( "select tccom010.cuno from tccom010" )

Context

Bshell function.

Related help topics

    Dynamic SQL queries:  overview
    Dynamic SQL queries:  synopsis


sql.select.bind()

Syntax

long sql.select.bind( long sql_id, long pseudo_var, var_name(.) )

Description

When you define an SQL statement with the sql.parse() function, you can define a pseudo variable for any or all of the fields specified in the SELECT statement. You do this by appending a number, prefixed by a colon [:], to each field. You use sql.select.bind() to bind a pseudo variable to a BAAN 4GL variable. As a result, the values of the field retrieved by the SELECT statement are stored in the 4GL variable. They can then be used elsewhere in the program.

Note that it is not necessary to bind external variables.

Arguments

sql_id	The query ID, as returned by sql.parse().
pseudo_var	The pseudo variable from the SELECT list. This is always a number.
var_name	The name of the BAAN 4GL variable to which the pseudo variable must be bound.
Return values

    0	success
<>0	error

Example

long sql_id

domain tccom.bpid, customer

sql_id = sql.parse( "select tccom100.cuno:1 " &  "from tccom100" )

sql.select.bind( sql_id, 1, customer )

.....

print customer

Context

Bshell function.

Related help topics

    Dynamic SQL queries:  overview
    Dynamic SQL queries:  synopsis


sql.set.rds.full()

Syntax

long sql.set.rds.full( long sql.id, long size )

Description

This sets the size of the RDBMS buffer. The buffer is used to send the result rows of a query from the database back to the client (that is, the bshell). For example, if a query fetches 20 rows and you have set the size of the buffer to 5, then the database sends the rows back to the client five at a time.

You call the function immediately after calling sql.parse().

Arguments

sql_id	The query ID, as returned by sql.parse().
size	The size of the buffer, in rows.
Return values

    0	success
<>0	error

Context

Bshell function.

Related help topics

    Dynamic SQL queries:  overview
    Dynamic SQL queries:  synopsis


sql.where.bind()

Syntax

long sql.where.bind( long sql_id, long pseudo_var, var_name(.) )

Description

This binds a pseudo variable from the WHERE clause of a specified SQL query to a BAAN 4GL variable. This enables the BAAN 4GL variable to be used in the WHERE clause. Note that there is no need to bind external variables.

Arguments

sql_id	The query ID, as returned by sql.parse().
pseudo_var	The pseudo variable from the WHERE clause. This is always a number. In the WHERE clause, it is entered as the number, prefixed by a colon [:].
var_name	The name of the BAAN 4GL variable to which the pseudo variable must be bound.
Return values

    0	success
<>0	error

Example

string city(30)

long sql_id

city = "London"

sql_id = sql.parse( "select tccom000.* " & "from tccom000 " &
"where tccom000.city = :1" )

sql.where.bind(sql_id, 1, city)

Context

Bshell function.

Related help topics

    Dynamic SQL queries:  overview
    Dynamic SQL queries:  synopsis


Enumerates and sets: overview and synopsis
Enumerates: overview and synopsis

Overview

Use these functions for handling enumerated domains and table fields.

Synopsis

domain	ask.enum	( string quescode(10),    domain default_enumvalue [, arg ] ... )
string	enum.descr$	( string domain code(12), enum_expr    [, string language_code] )
long	etol	( domain domain_value )
domain	ltoe	( long long_value )
void	set.enum.values	( enum_constant, ... )
void	set.enum.values.for.field	( const string field.name.string,      [ALL_ENUMS_EXCEPT], enum_value, ... )
Related help topics

    Enumerated constants


ask.enum()

Syntax

domain ask.enum( string quescode(10), domain default_enumval [, arg ] ... )

Description

This displays a message box containing a question and a number of possible responses. The responses are presented as push buttons. To respond to the question and close the message box, the user selects one of the push buttons.

The possible responses are defined in the data dictionary as an enumerated domain. By default, the function displays all of the defined enumerate values. To display a subset only, call set.enum.values() before calling ask.enum().

Arguments

quescode	The question to be displayed in the message box is defined in the data dictionary. This argument specifies the data dictionary code for the question.  If the question contains substitution symbols, use the third and subsequent arguments to specify the values to substitute for these symbols.
default_enumval	Specifies the enumerate value of the default answer. For example, yesno.yes. If this argument is empty, the default value specified in the data dictionary is used.
arg, …	The values to substitute for any substitution symbols that the question contains. See sprintf().
Notes

The question text and the push button labels are always in the language of the user. The return value of ask.enum() is always the name of the enumerate value and not its description. So the script in which the function is used remains language independent.

After execution of ask.enum(), the standard variable attr.enum.mask$ is cleared. This also happens when the standard program calls ask.enum().

Return values

The value of the enumerated domain that corresponds to the option selected by the user. This is always the name of the enumerate value and not its description.

Context

3GL library function.

Example

This example assumes an enumerated domain 'yesno'  with two possible constants: 'yesno.yes' and 'yesno.no'. It also assumes a question defined in the data dictionary with code "tccom00001". This question contains the string "Error %d in file %s; Try again [y/n]?". The default answer is yes.

ret = seq.open( filename, "w" )

while ( ret <= 0 )

    if ( ask.enum("tccom00001", yesno.yes, ret, filename )

                  = yesno.no) then

         return

    endif

    ret = seq.open( filename, "w" )

endwhile

Related help topics

    Enumerate:  overview and synopsis
    Enumerated constants


enum.descr$()

Syntax

string enum.descr$(string domain code(12), enum_expr
[, string language_code ] )

Description

This returns the description associated with a specific value in an enumerated domain.

Arguments

code	The name of the domain. The domain must be of type enumerated.
enum_expr	One of the possible values of the enumerated domain.
language_code	To retrieve the description in a language other than the user language, specify the relevant language code in this argument. This is an optional argument. The default language is the language of the user. Note that the language code of the user is available in the predefined, read-only variable language$.
Return values

The description of the specified enumerate value, either in the current user language or in another specified language.

The function returns an empty string, and displays an error message, if an unknown domain is specified or if no description exists in the data dictionary for the specified language.

Context

Bshell function.

Example

This example assumes an enumerated domain 'yesno'  with two possible constants: 'yesno.yes' and 'yesno.no'.  It also assumes that 1 is the language code for Dutch, 2 is the language code for English, and 3 is the language code for German. English is the current user language.

domain    yesno active     | enumerated domain

string    descr(25)

active = yesno.no

descr = enum.descr$("yesno", active, "1")  | descr contains "nee"

descr = enum.descr$("yesno", active)       | descr contains "no"

descr = enum.descr$("yesno", active, "3")  | descr contains "nein"

Related help topics

    Enumerates:  overview and synopsis
    Enumerated constants


etol()

Syntax

long etol( domain domain_value )

Description

This returns the numeric code corresponding to a specified value in an enumerated domain.

Context

Bshell function.

Example

See ltoe().

Related help topics

    Enumerates:  overview and synopsis
    Enumerated constants


ltoe()

Syntax

domain ltoe( long long_value )

Description

This returns the named constant corresponding to a specified numeric code. The numeric code represents one of the values in an enumerated domain.

Example

This example assumes an enumerated domain 'yesno'  with two possible constants: 'yesno.yes’ (=1) and 'yesno.no’ (=2).

domain    yesno active

long      enum_long

active = yesno.no

enum_long = etol( active )    | enum_long now contains 2

active = ltoe( 1 )            | active now equals yesno.yes

Related help topics

    Enumerates:  overview and synopsis
    Enumerated constants


set.enum.values()

Syntax

void set.enum.values( enum_constant, ... )

Description

This fills the predefined variable attr.enum.mask$ with a specified set of enumerate values. This is useful for restricting the values valid for the ask.enum() function. Any values not specified are not shown.

Notes

In the case of enumerated fields, use set.enum.values.for.field().

After execution of ask.enum(), the variable attr.enum.mask$ is cleared again. This also happens when the standard program calls ask.enum().

Context

3GL library function.

Related help topics

    Enumeratess:  overview and synopsis
    Enumerated constants


set.enum.values.for.field()

Syntax

void set.enum.values.for.field( const string field.name.string, [ALL_ENUMS_EXCEPT], [ enum_value, ... ] )

Description

This fills a listbox field with a specified set of enumerate values.

With set.enum.values(), the change to a set of enumerate values occurs immediately before input to the enumerated field. With set.enum.values.for.field(), the change occurs immediately after the conditions on which the change depends become true. To achieve this, include the function in the before.display.object section or in the when.field.changes section of each field on which the change depends.

Arguments

field.name.string	The name of the enumerated field. For example, "ttadv996.type". For an array field, include the array element. For example, "tttadv996.type(5)".
ALL_ENUMS_EXCEPT	This optional macro specifies that the succeeding list of enumerate values represents those values that are to be excluded from the enumerate set. Otherwise, the list of enumerate values represents the values that are to be included.
enum_value, …	The values to be displayed in the field, separated by commas [,]. This is an optional argument. If not included, all enumerate values defined for the field are available.
Notes

You can set enumerate values for the current occurrence only.

If the existing value of an enumerated field in not included in the new set, no value is selected in the list and no value is displayed in the display area of the listbox.

Context

4GL library function.

Example

field ttadv996.fld1:

when.field.changes:

if ttadv996.fld1 < SOME_VALUE then

set.enum.values.for.field("ttadv996.type", ttadv.ktex.session,

ttadv.ktex.form, ttadv.ktex.domain)

| no value is selected if the current value of

| ttadv996.type is not in the new set!

else

set.enum.values.for.field("ttadv996.type")

| all enum items are available

endif

Related help topics

    Enumerates:  overview and synopsis
    Enumerated constants


Events: overview

Use these functions for handling events.

Event-driven programs, such as BAAN 3GL scripts, are designed to respond to events. Usually, they consist of a main loop that waits for events to occur. When an event occurs, the program performs the appropriate actions to process the event. It then returns to its waiting state.

Most of the events that occur in a BAAN application relate to user interaction. When a user performs an action in the user interface (for example, clicking the mouse or pressing a keyboard key), this generates an event. The event consists of a package of information about the particular action. It is delivered to the event queue of the relevant process group and from there to the individual process that will handle the event. When the process retrieves the event from the event queue, it executes the piece of code appropriate for processing the particular type of event received.

Note that the event package takes the form of an array of longs. You retrieve the individual items of information in the array by using a set of parameters specific to the event type.

The event paradigm is used in both ASCII and graphical programming environments. But some events are relevant only in graphical environments (for example, mouse events).

For further information on user interface controls and process groups, see User interface controls and Process groups.

Related help topics

    Events:  synopsis
    Events:  event types
    Events:  array parameters
    Events:  sample program


Events: synopsis

long	next.event	( [long event(EVTMAXSIZE)] )
long	peek.event	( [long event(EVTMAXSIZE)] )
long	pending.events	( )
void	select.event.input	( long object_id, long masks )
long	send.event	( long proc_grp, long event(EVTMAXSIZE) )
Related help topics

    Events:  overview
    Events:  event types
    Events:  array parameters
    Events:  sample program


next.event()

Syntax

long next.event( [long event(EVTMAXSIZE)] )

Description

This removes the event at the top of the event queue and stores it in event. If the event queue is empty, the function waits (that is, it is blocked) until an event arrives. To time out the next.event() function, use set.timer().

Arguments

event(EVTMAXSIZE)	An array of longs containing details of the event. You retrieve the contents of the event array by using a set of parameters specific to the event type. See Event array parameters. The EVTMAXSIZE constant indicates the number of elements in the array.
Return values

The event type. See Event types.

Context

Bshell function.

Example

long event(EVTMAXSIZE), object_id

select.event.input( object_id, EVTBUTTONPRESSMASK +

EVTBUTTONRELEASEMASK + EVTKEYPRESSMASK + EVTBUTTONMOTIONMASK )

next.event( event )

on case evt.type( event )

case EVTBUTTONPRESS:

...

case EVTKEYPRESS:

...

default:

...

endcase

Related help topics

    Events:  overview
    Events:  synopsis
    Events:  event types
    Events:  array parameters
    Events:  sample program


peek.event()

Syntax

long peek.event( [long event(EVTMAXSIZE)] )

Description

This reads the event at the top of the event queue and stores it in event. It does not remove the event from the queue. If the event queue is empty, the function waits (that is, it is blocked) until an event arrives. To time out the peek.event() function, use set.timer().

Arguments

event(EVTMAXSIZE)	An array of longs containing details of the event. You retrieve the contents of the event array by using a set of parameters specific to the event type. See Event array parameters. The EVTMAXSIZE constant indicates the number of elements in the array.
Return values

The event type. See Event types.

Context

Bshell function.

Example

long event(EVTMAXSIZE), object_id

select.event.input( object_id, EVTBUTTONPRESSMASK +

EVTBUTTONRELEASEMASK + EVTKEYPRESSMASK + EVTBUTTONMOTIONMASK )

while peek.event() = EVTBUTTONMOTION

next.event( event )

....

endwhile

Related help topics

    Events:  overview
    Events:  synopsis
    Events:  event types
    Events:  array parameters
    Events:  sample program


pending.events()

Syntax

long pending.events()

Description

This returns the number of events present in the event queue of the process group. Note that including the function in an empty loop uses a lot of processor time. For example:

while not pending.events()

endwhile

Return values

>0	number of events in event queue
  0	empty queue

Context

Bshell function.

Example

long event

if pending.events() > 0 then

next.event( event )

else

....

endif

Related help topics

    Events:  overview
    Events:  synopsis
    Events:  event types
    Events:  array parameters
    Events:  sample program


select.event.input()

Syntax

void select.event.input( long object_id, long masks )

Description

This defines which event types can be generated by the specified object.

Arguments

object_id	The ID of the object to which the specified masks apply.
masks	A combination of one or more values that indicate the event types that the specified object can generate. If the event queue already contains events not specified by this function, they are NOT removed from the queue. The possible event mask values are: EVTNOEVENTMASK    No events EVTALLEVENTMASK All events EVTBUTTONPRESSMASK Mouse button press events EVTBUTTONDPRESSMASK Mouse button double press events EVTBUTTONRELEASEMASK Mouse button release events EVTBUTTONMOTIONMASK    Mouse pointer motion events EVTKEYPRESSMASK Key press events EVTRESIZEWINDOWMASK    Resize window events EVTBUTTONSELECTMASK    Control button select events EVTFIELDSELECTMASK Field select events EVTGRIDEVENTMASK Grid events EVTLISTBOXSELECTMASK    List box item select events EVTMENUSELECTMASK Menu item select events EVTSCROLLBARSELECTMASK  Scrollbar select events EVTTABSELECTMASK Tab frame events EVTTREESELECTMASK Tree events EVTCHANGEFOCUSMASK     Change focus events EVTSETFOCUSMASK Set focus events EVTIOEVENTMASK I/O events EVTOLEEVENTMASK OLE events EVTTERMINATIONMASK Termination events EVTHELPEVENTMASK Help events
Notes

Events of type EVTCLIENTMESSAGE, EVTBUCKETMESSAGE, and EVTTIMEREVENT are always selected.

You cannot add to the currently selected events by calling select.event.input() with the additional masks. You must specify all required event masks each time you call the function.

Context

Bshell function.

Example

long object_id

select.event.input( object_id, EVTBUTTONPRESSMASK + EVTKEYPRESSMASK )

Related help topics

    Events:  overview
    Events:  synopsis
    Events:  event types
    Events:  array parameters
    Events:  sample program


send.event()

Syntax

long send.event( long proc_grp, long event(EVTMAXSIZE) )

Description

This sends an event from the current process to the specified process group. It enables event-driven communication between processes. A process can send any event type using this function. Note that this is the only way to send events of type EVTCLIENTMESSAGE.

If the sending process requires an immediate response, use suspend(0) to force a context switch; that is, to force the system to give processor time to the destination process.

Arguments

proc_grp	The ID of the process group.
event	The event that must be sent to the process group. For details of the content of the event array, see Event array parameters.
Return values

TRUE	success
FALSE   	error

Context

Bshell function.

Example

This example sends a message that indicates the start of sending.

#define START_SEND	1

long process, event(EVTMAXSIZE)

evt.type( event )	= EVTCLIENTMESSAGE

evt.client.sender( event )  	= pid

evt.client.command( event )	= START_SEND

if not send.event( get.pgrp(process), event ) then

message( "Process %d is not responding", process )

endif

Related help topics

    Events:  overview
    Events:  synopsis
    Events:  event types
    Events:  array parameters
    Events:  sample program


Event types

The following section lists all available event types and describes their context.

EVTBUTTONPRESS	Occurs when a mouse button is pressed.
EVTBUTTONDPRESS	Occurs when a mouse button is double pressed.
EVTBUTTONRELEASE	Occurs when a mouse button is released after being pressed.
EVTBUTTONMOTION	Occurs when the mouse is moved while at least one mouse button is pressed.
EVTKEYPRESS	Occurs when a keyboard key is pressed.
EVTRESIZEWINDOW	Occurs when a main window (DsCmwindow) is resized.
EVTBUTTONSELECT	Occurs when a control button is selected. Examples of control buttons are push buttons (DsCpushButton), check boxes (DsCcheckBox), option buttons (DsCradioButton), toolbar buttons (DsCtoolBar), and drawn buttons (DsCdrawnButton).
EVTFIELDSELECT	Occurs when a new value is entered in an edit field (DsCfield).
EVTGRIDEVENT	Occurs when a grid control (DsCgrid) is modified.
EVTLISTBOXSELECT	Occurs when one or more items are selected in a combo box (DsCcomBox), a drop-down combo box (DsCdDComBox), a drop-down list box (DsCdDListBox), or a list box (DsClistBox).
EVTMENUSELECT	Occurs when a menu item is selected in a bar menu object (DsCbarMenu).
EVTSCROLLBARSELECT	Occurs when a scrollbar (DsCscrollbar or DsCslider) is moved or selected.
EVTTABSELECT	Occurs when a tab is selected in a tab frame control (DsCtabFrame).
EVTTREESELECT	Occurs when an item in a tree control (DsCtree) is expanded, collapsed, or selected.
EVTCHANGEFOCUS	Occurs when the keyboard focus is moved. The user can move the focus from one object to another by pressing the TAB key or an arrow key.
EVTSETFOCUS	Occurs when an object receives keyboard focus by the user clicking on it with the mouse.
EVTIOEVENT	Occurs when data is available on a socket, when a connection request is pending on a socket, and when an I/O error occurs on a socket.
EVTOLEEVENT	Occurs when some action is performed on an OLE object in a graphical window (DsCgwindow). Only BAAN Windows can generate this event.
EVTTERMINATION	Occurs when a Windows application started by BAAN Windows (Notepad, for example) terminates. Only BAAN Windows can generate this event.
EVTHELPEVENT	Occurs in response to a request for help on a user interface object.
EVTBUCKETMESSAGE	Occurs when a process sends a bucket message, using bms.send().
EVTCLIENTMESSAGE	Occurs when a process sends a client message, using send.event().
EVTTIMEREVENT	Occurs when a timer sends an event.
Related help topics

    Events:  overview
    Events:  synopsis
    Events:  array parameters
    Events:  sample program


Event array parameters

The event argument included in next.event(), peek.event(), and send.event() consists of an array of longs that contain details of the incoming or outgoing event. You retrieve the contents of an event array by using the set of parameters defined for the particular event type. These parameters are listed below, by event type.

All events

Mouse button events

Mouse motion events

Window resize events

Control button events

Field select events

Grid events

List-box item select events

Menu item select events

Scrollbar select events

Tab frame events

Tree events

Change focus events

I/O events

OLE events

Application termination events

Help events

Client events

Bucket message events

Timer events

All events

evt.type( event )	The event type.
evt.window( event )	The ID of the object that generated the event.
Mouse button events:

EVTBUTTONPRESS, EVTBUTTONDPRESS, and EVTBUTTONRELEASE

evt.button.x( event )	X-position of mouse action in window.
evt.button.y( event )	Y-position of mouse action in window.
evt.button.state( event )	Indicates which modifier keys are held down when the mouse button is pressed. Possible values are: EVTSHIFTMASK EVTCONTROLMASK EVTBUTTON1MASK EVTBUTTON2MASK EVTBUTTON3MASK
evt.button.button( event )	Indicates which mouse button is pressed. Possible values are: EVTBUTTON1 left mouse button EVTBUTTON2 middle mouse button EVTBUTTON3 right mouse button
evt.button.rootx( event )	Absolute x-position of mouse action on desktop.
evt.button.rooty( event )	Absolute y-position of mouse action on desktop.
Mouse motion events

EVTBUTTONMOTION

evt.motion.x( event )	X-position of mouse pointer in window during motion.
evt.motion.y( event )	Y-position of mouse pointer in window during motion.
evt.motion.state( event )	Indicates which modifier keys are held down while the mouse pointer is moved. Possible values are: EVTSHIFTMASK EVTCONTROLMASK  EVTBUTTON1MASK EVTBUTTON2MASK EVTBUTTON3MASK
evt.motion.rootx( event )	Absolute x-position of mouse pointer on desktop during motion.
evt.motion.rooty( event )	Absolute y-position of mouse pointer on desktop during motion.
Keypress events

EVTKEYPRESS

evt.keypress.key( event )	ASCII or TSS value of pressed key.
evt.keypress.state( event )	Indicates which modifier keys are held down while the key is being pressed. Possible values are: MOD_CTRL MOD_SHIFT MOD_ALT
Window resize events

EVTRESIZEWINDOW

evt.resize.columns( event )	New width in number of columns (character window).
evt.resize.rows( event )	New height in number of rows (character window).
evt.resize.width( event )	New width in pixels (graphical window).
evt.resize.height( event )	New height in pixels (graphical window).
Control button events

EVTBUTTONSELECT

evt.button.return( event )	Return value of the button, where relevant.
evt.button.checkstate( event )	The state of toolbar buttons, check boxes and option buttons. Possible values are: EVTBUTTONCHECKED button pressed or checked EVTBUTTONUNCHECKED button released or unchecked
Field select events

EVTFIELDSELECT

There are no parameters specific to these event types. See All events.

Grid events

EVTGRIDEVENT

evt.grid.row( event )	Row index (1-based index).
evt.grid.column( event )	Column index (1-based index).
evt.grid.width( event )	Column width.
evt.grid.height( event )	Row height.
evt.grid.range.left( event )	Index of leftmost column of range.
evt.grid.range.top( event )	Index of topmost row of range.
evt.grid.range.right( event )	Index of rightmost column of range.
evt.grid.range.bottom( event )	Index of bottommost row of range.
evt.grid.selmark( event )	Mark state of a selection. Possible values are: DSGRIDMARKNONE nothing marked   DSGRIDMARKNEW new mark DSGRIDUNMARK unmark DSGRIDADDMARK add mark
evt.grid.reason( event )	The action that caused the event. Possible values are:  EVTGRIDCHANGEDATA data changed   EVTGRIDCHANGEFOCUS internal focus moved to another cell EVTGRIDACTIVATE selection activated by double-click  EVTGRIDFOCUSCHANGEDBYMOUSE   internal focus moved to           another cell by mouse click EVTGRIDMARKRANGE range selected  EVTGRIDMARKCELL cell selected  EVTGRIDMARKROW row selected  EVTGRIDMARKCOLUMN column selected EVTGRIDRESIZEROW row height changed  EVTGRIDRESIZECOLUMN column width changed  EVTGRIDMOVEROW row moved EVTGRIDMOVECOLUMN column moved  EVTGRIDBUTTONPRESS control button pressed  EVTGRIDLISTBOXSELECT item selected in list box    EVTGRIDRESETSELECTION all rows, columns, cells unselected
The value of the evt.grid.reason parameter determines which of the other parameters are included as part of the event. For example, if the event reason is EVTGRIDRESIZEROW, then evt.grid.row and evt.grid.height must be included in the event. Similarly, if the event reason is EVTGRIDMARKRANGE, then evt.grid.range.left, evt.grid.range.top, evt.grid.range.right, and evt.grid.range.bottom must be included in the event.

List box item select events

EVTLISTBOXSELECT

evt.listbox.item_id( event )	ID of the selected list-box item.
evt.listbox.reason( event )	The action that caused the event. Possible values are: EVTLISTBOXREASONTEXT   text typed in edit field of combo box  EVTLISTBOXREASONACTIVATE   item double-clicked  EVTLISTBOXREASONSELECTION  selection changed
evt.listbox.selcount( event )	Number of selected items.
Menu item select events

EVTMENUSELECT

evt.menu.return( event )	ID of the selected menu item.
Scrollbar select events

EVTSCROLLBARSELECT

evt.scrollbar.action( event )	The action that caused the event. Possible values are:  SBUP SBDOWN SBPRESS  SBMOVE  SBRELEASE SBPGUP SBPGDOWN SBHOME SBEND
evt.scrollbar.value( event )	Current position in scrollbar.
Tab frame events

EVTTABSELECT

evt.tab.index( event )	Index of selected tab (1-based index)
Tree events

EVTTREESELECT

evt.tree.item_id( event )	ID of the tree item that caused the event.
evt.tree.reason( event )	The action that caused the event. Possible values are:  EVTTREEREASONACTIVATE leaf in tree activated EVTTREEREASONEXPAND tree node expanded EVTTREEREASONCOLLAPSE tree node collapsed EVTTREEREASONSELECT tree item selected
Change focus events

EVTCHANGEFOCUS and EVTSETFOCUS

evt.focus.object( event )	The object that currently has keyboard focus (EVTCHANGEFOCUS). The object that has received keyboard focus (EVTSETFOCUS).
evt.focus.key( event )	Indicates the key that caused an EVTCHANGEFOCUS event. Possible values are: KEY_TAB KEY_BACKTAB KEY_UP KEY_DOWN KEY_RIGHT KEY_LEFT KEY_HOME KEY_END KEY_PGUP KEY_PGDOWN
I/O events

EVTIOEVENT

event.array(1)	The event type. This is always EVTIOEVENT.
event.array(2)	The reason that the event was sent. Possible values are: EVTSOCKHASDATA       data is available on the socket specified in event.array(3) EVTSOCKIOERROR error occurred on the socket specified in event.array(3) EVTCONNECTREQUEST connection request is pending on the                socket specified in event.array(3)
event.array(3)	The file pointer of the relevant socket.
OLE events

EVTOLEEVENT

evt.ole.event( event )	The OLE event type. Possible values are:
	EVTOLECREATEINSTANCE EVTOLESETHOSTNAMES EVTOLESHOWWINDOW EVTOLEHIDEWINDOW EVTOLELOADDATA EVTOLESAVEDATA EVTOLECLOSE EVTOLELOCKSERVER EVTOLEUNLOCKSERVER EVTOLEDATACHANGED EVTOLERELEASED EVTOLEAUTOMATION EVTOLESHOWOBJECT EVTOLEOBJECTWINDOWVISIBLE EVTOLEOBJECTWINDOWINVISIBLE	class factory wants to create an object request hostnames request to make object visible request to make object invisible request to load an embedded object with data request to save an embedded object server closes embedded object set lock to keep application running reset lock embedded object data has changed all references to object released automation request to call DLL function request to scroll embedded object in view object in running mode object not in running mode
evt.ole.size( event )	For a data change or data save event, this stores the size of the data.
evt.ole.subobject( event )	If the OLE object is an embedded object, displayed in a graphical window (DsCgwindow), this indicates the ID of the graphical subobject in the gwindow.
Application termination events

EVTTERMINATION

evt.termination.reason( event )	The action that caused the event. Possible values are: DSTerminationSetDir DSTerminationOpenStdin DSTerminationOpenStdout DSTerminationOpenStderr DSTerminationCreateProcess DSTerminationCreateThread DSTerminationNormalExit
evt.termination.exitcode( event )	The application’s exit code.
Help events

EVTHELPEVENT

evt.help.return( event )	Return value of the control button, toolbar button, or menu option for which help is requested. This is -1 for all other object types.
evt.help.row( event )	Grid row index if help requested for a grid object. This is -1 for all other object types.
evt.help.column( event )	Grid column index if help requested for a grid object. This is -1 for all other object types.
evt.help.reason( event )	EVTHELPCOMMAND help requested using F1  EVTHELPCONTEXT help in context-sensitive help mode
Client events

EVTCLIENTMESSAGE

evt.client.sender( event )	Process ID of sender.
evt.client.command( event )	Application-specific command code.
evt.client.argument( event )	Application-specific argument.
Bucket message events

EVTBUCKETMESSAGE

evt.bms.sender( event )	Process ID of sender.
evt.bms.command( event )	Application-specific command code.
evt.bms.argument( event )	Application-specific argument.
Timer events

EVTTIMEREVENT

evt.timer.id( event)	ID of timer that sent the event.
Related help topics

    Events:  overview
    Events:  synopsis
    Events:  event types
    Events:  sample program


Events: sample program

long event(EVTMAXSIZE)

while TRUE

next.event(event)

on case evt.type(event)

case EVTKEYPRESS:

on case evt.keypress.key(event)

case KEY_RETURN:

....

case KEY_ESC:

....

break

          endcase

          break

case EVTCHANGEFOCUS:

on case evt.focus.key(event)

case KEY_TAB:

case KEY_DOWN:

| set focus on next field

case KEY_BACKTAB:

case KEY_UP:

| set focus on previous field

endcase

break

case EVTBUTTONSELECT:

if ( evt.button.return(event) = ABORT.BUTTON ) then

| ABORT.BUTTON is the return value of the button pressed

return

endif

break

endcase

endwhile


Runtime expressions: overview and synopsis

Overview

Use these functions to compile and evaluate expressions at runtime. This is particularly useful when expressions or formulas are stored in a database or can be entered by a user.

Use of these functions increases system load and should be avoided, where possible.

Synopsis

double	d.expr	( long expr_id [, arg] )
long	expr.compile	( "expression" )
void	expr.free	( long expr_id )
long	l.expr	( long expr_id [, arg] )
string	s.expr$	( long expr_id [, arg] )


d.expr()

Syntax

double d.expr( long expr_id [, arg] )

Description

Executes (or evaluates) an expression previously compiled by expr.compile. The result is always converted to a double.

Arguments

expr_id	The ID of the compiled expression, as returned by expr.compile.
arg	If the expression contains the characters '$$', the value specified by this argument is substituted for those characters. This is an optional argument.
Note

You can execute compiled expressions multiple times without recompiling. The current values of the variables are used each time.

Return value

The result of the expression converted to a double.

Context

Bshell function.

Related help topics

    Runtime expressions: overview and synopsis


expr.compile()

Syntax

long expr.compile( "expression" )

Description

This compiles the specified expression and returns an ID number for the compiled expression. The expression can be executed subsequently using l.expr(), d.expr(), or s.expr$(). Because variables included in the expression must be know at runtime, they must be declared as external variables.

You can execute compiled expressions multiple times without recompiling. The current values of the variables are used each time.

Notes

The expression can include any of the following features:

•	An assignment, specified by using :=. For example:

("a:=3")

•	Merged expressions, separated by commas (,). For example:

("a:=3, b:=7, c-8")

•	Operators. These have the same function as in normal expressions. Integer division is an exception. Normally, integer division returns an integer (for example, 45/30 returns 1). With these functions, integer division returns a double (for example, 45/30 returns 1.5).

•	The IN keyword. Use this to check whether a value lies within a specified range.

•	The following constants:

PI         ( = 3.1415927... )
TRUE
FALSE

•	Conditional expressions. For example:

("a:= (a) ? 0 : a")

•	Numerical ranges. For example:

("a IN [12,30]") or ("a IN [12,30] [50,100] [200,500]")

•	In expressions on forms, you can use the following characters:

$$ 	represents the current field name
$# 	represents the current domain name

        For example: "$$ IN [30,40]"

•	The following functions:

abs()	atan()	edit()	log()	pos()	sin()	tan()
acos()	chr()	exp()	log10()	pow()	sqrt()	tanh()
asc()	cos()	int()	max()	round()	str()	val()
asin()	cosh()	len()	min()	rpos()	strip()
time()	current time in HHMM format

date() 	current date in number of days since January 1, 0001

date(YYYY,MM,DD)	date constant – for example:

 	("date() IN [ date(1988,1,1), date(1992,1,1) ]")

utc()	current date and time in UTC long format

utc(YYYY,MM,DD,HH,MM,SS)	specified local date/time in UTC long format

fmin()	returns the minimum value of a 4GL variable, domain, or table field

fmax()	returns the maximum value of a 4GL variable, domain, or table field

•	String regular expressions. These are string constants which can contain the following characters:

^ 	means the beginning of the string

$	means the end of the string

. 	means any character

*	takes the previous character 0 or more times

[]	means one of the characters between [] – for example:

[abcd123] or [a-z] or [a-zA-Z]

[^]	means any character except the characters after ^

""	means a double quote within a string

The result of a regular expression that includes IN is 0 if the expression is FALSE. If the expression is TRUE, the result is a long containing 4 bytes. The first two bytes contain the length of the substring; the last 2 bytes contain the position of the substring in the string.

Expression	Result length          position
"abcdefg" IN "def"	3	4
"abcdefg" IN "^def$"		FALSE
"abcdefg" IN "^[a-z]*$"	7	1
"abcdefg" IN "^a"	1	1
"abcdefg" IN "^b"		FALSE
"abcdefg" IN "g$"	1	7
"abcdefg" IN "^a.*g$"	7	1
"abcdefg" IN "^[^a].*"		FALSE
"abcdefg" IN "^[^b-z]"	1	1
You can retrieve the length and position from the result with store.long() and load.short(). For example:

long       expr_id, lng, length_res, pos_res
string     tmp(4)
expr_id    = expr.compile( """abcdefg"" IN ""def""" )
lng        = l.expr( expr_id )
store.long( lng, tmp )
length_res = load.short( tmp(1;2) ) | length_res contains 3
pos_res    = load.short( tmp(3;2) ) | pos_res contains 4

Return value

An ID for the compiled expression.

Context

Bshell function.

Related help topics

    Runtime expressions: overview and synopsis


expr.free()

Syntax

void expr.free( expr_id )

Description

This frees the memory allocated to a compiled expression. expr_id is the ID of the compiled expression, as returned by expr.compile. It is important to call this function when you have finished with an expression.

Context

Bshell function.

Related help topics

    Runtime expressions: overview and synopsis


l.expr()

Syntax

long l.expr( long expr_id [, arg] )

Description

Executes (or evaluates) an expression previously compiled by expr.compile. The result is always converted to a long.

Arguments

expr_id	The ID of the compiled expression, as returned by expr.compile.
arg	If the expression contains the characters '$$', the value specified by this argument is substituted for those characters. This is an optional argument.
Note

You can execute compiled expressions multiple times without recompiling. The current values of the variables are used each time.

Return value

The result of the expression converted to a long.

Context

Bshell function.

Related help topics

    Runtime expressions: overview and synopsis


s.expr$()

Syntax

string s.expr$( long expr_id [, arg] )

Description

Executes (or evaluates) an expression previously compiled by expr.compile. The result is always converted to a string.

Arguments

expr_id	The ID of the compiled expression, as returned by expr.compile.
arg	If the expression contains the characters '$$', the value specified by this argument is substituted for those characters. This is an optional argument.
Note

You can execute compiled expressions multiple times without recompiling. The current values of the variables are used each time.

Return value

The result of the expression converted to a string.

Context

Bshell function.

Related help topics

    Runtime expressions: overview and synopsis


Form and form field operations: overview

Use these functions to perform form and form field operations. For example:

•	to disable and enable commands and fields

•	to display particular fields

•	to update total fields

•	to execute a function for one or all occurrences on a form

•	to execute standard commands

•	to display default field values

•	to make fields visible or invisible

•	to mark and unmark occurrences

•	to display fill characters in fields

•	to refresh the current record

•	to reset a field to its previous value

Related help topics

    Form and form field operations:  synopsis


Form and form field operations: synopsis

void	add.view.field	( long index.nr, const string fname )
void	blank.all	( )
long	change.field.label	( const string fname, long element, const string label1[, const string label2[,const string label3]] )
void	check.all.input	( )
void	choice.again	( )
void	disable.commands	( string command [, string command]... )
void	disable.fields	( [ long mode,] string field [, occurrence]    [, string field [, occurrence]]... )
void	disable.group	( long group.nr, [long disable.mode] )
void	display	( field )
void	display.all	( )
void	display.curr.occ	( )
void	display.fld	( long occurrence, field )
void	display.occ	( long occurrence )
void	display.total.fields	( string fieldname1, long value1 [, string    fieldname2, long value2] ... )
void	do.all.occ	( function_name [, ...] )
void	do.occ	( long occurrence, function_name [, ...] )
void	do.occ.without.update	( long occurrence, function_name [, ...] )
void	enable.commands	( string command [, string command]... )
void	enable.fields	( string field [, string field]... )
void	enable.group	( long group.nr )
void	execute	( long command )
long	get.field.label	( const string fname, long element, ref string    label1 mb, ref string label2 mb, ref string    label3 mb )
void	get.screen.defaults	( )
void	group.invisible	( long group.nr )
void	input.again	( )
void	inputfield.invisible	( string field_name(18) [, string    field_name(18)]... )
void	inputfield.password	( string field_name(18) [, string    field_name(18)]... )
void	inputfield.visible	( string field_name(18) [, string    field_name(18)]... )
long	is.field.invisible	( string field_name(18) )
void	make.current	( )
void	mark.occ	( long occurrence )
void	on.old.occ	( function_name [, ...] )
void	print.const	( [string fill_string(127)] )
void	refresh.curr.occ	( )
void	remove.mark	( )
void	set.fields.default	( )
void	stp.reset.value	( )
void	to.field	( field )
void	to.form	( long form_number )
long	to.group	( long group.nr )
void	update.occ	( )
Related help topics

    Form and form field operations:  overview


add.view.field()

Syntax

void add.view.field( long index.nr, const string fname )

Description

The view fields for a dynamic session are determined by the view column in the Available Indices by Session session. Dependent child fields of the index fields are also displayed. You use this function to add a view field that is not part of the index and that is not a child field of one of the index fields.

Standard use the new field-property "View" instead. For conditional view-fields this function can still be used in the before.program section.

Arguments

index.nr	The index identifier. If this is 0, the field is not associated with any index. It is always a view field.
fname	The name of the form field to be added. To specify a particular element of an array field, append the element number (in parentheses) to the field name. For example: "ttadv301.labl(2)".
Context

4GL library function.

You can use this function only in the before.program and in the after.form.read section of 4GL scripts.

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


blank.all()

Syntax

blank.all()

Description

This clears all display fields and input fields on the current form. Display only and input only fields (that is, display and input fields that are not included in the form’s TAB sequence) are not cleared.

Context

4GL library function.

You can use this function only in 4GL scripts. You must also use it only in combination with the standard program.

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


change.field.label()

Syntax

long change.field.label( const string fname, long element, const string label1[, const string label2[,const string label3]] )

Description

Use this to set the label for a specified field. A field can have up to three lines of text (label-lines). The new label-line(s) replace the current label-line(s). The function requires that the specified field already has a (dummy) label in the form-definition. When the field is not in the grid, the label in the form-definition should have at least the same number of label-lines, as specified with this function.

This function is relevant to dynamic forms only!

Arguments

fname	The name of the field whose label must be set.
element	For an array field, use this to specify the array element for which you want to set the label. For multi-currency fields the element number must be -1.
label1	The first (top) label-line.
label2	The second label-line. (optional)
label3	The third label-line. (optional)
Return values

 0	success
-1	session is not dynamic
-2	field not found

Context

4GL library function.

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


check.all.input()

Syntax

void check.all.input()

Description

This executes all check.input subsections (if any) included in the program script. When an input error is detected, the choice.again() function is automatically executed. If a check.input subsection is included for an array field, it is executed for each element in the array.

When a DAL is used, the property checks in the DAL are executed after the check.input subsections of the UI script are executed.

Context

4GL library function.

The standard program automatically calls this function before saving a record in the database. Application programmers can include this function only in before.choice subsections of a script.

 Example

choice.cont.process:

before.choice:

check.all.input()

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


choice.again()

Syntax

void choice.again()

Description

This cancels execution of a standard command and transfers control to the standard program. Statements programmed after this function will never be executed. You can call this function during execution of a standard command. You can also call the function in field sections, as these are called indirectly during execution of some commands.

Context

4GL library function.

You can use this function only in 4GL scripts. You can use it in the following event subsections:

before.choice, on.choice, after.choice
before.field, before.input, on.input, after.input, when.field.changes, after.field

Example

field.pctst999.item:

after.input:

if pctst999.item = 99999 then

mess("pctst.0001",1)

choice.again()

endif

| Modifying a record with item = zero is not allowed

choice.modify.set:

before.choice:

if pctst999.item = 0 then

mess("pctst.0002",1)

choice.again()

endif

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


disable.commands()

Syntax

void disable.commands( string command [, string command]... )

Description

This disables the specified standard and/or form command(s). Standard commands are identified by their command IDs. Form commands are identified either by a function name, a session code, or a menu code.

Note

The standard program can enable and disable form commands depending on the number of occurrences currently selected in the form.

Context

4GL library function.

Example

disable.commands( "test.function", "ttadv3500m000", ADD.SET )

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


disable.fields()

Syntax

void disable.fields( [ long mode,] string field [, occurrence] [, string field [, occurrence] ... )

Description

This disables single-occurrence and multi-occurrence fields on a form.

To disable all fields of a group, see disable.group().

Arguments

mode	This is an optional argument. It has two possible values: DISABLE This is the default mode and does not need to be specified. READONLY The field(s) become read-only fields that cannot be edited by the user.
field [,occurrence]	This identifies the field to be disabled.  For a single-occurrence field, this is the field name. For a multioccurrence field, this can be either the field name or the field name followed by an occurrence number (depending on whether you wish to disable all occurrences of the field or only one particular occurrence).  For array fields, UTC fields, and segmented fields, you can append suffixes to the field name to indicate the particular element or segment to be disabled. If you omit these suffixes, all elements/segments are disabled. • To disable a particular element of an array field, append the element number (in parentheses) to the field name. The element number must be an integer, formatted as a string. It cannot be a variable. For example: "tfmod100.perd(10)". • To disable only the date or time element of a UTC field, append either .date or .time to the field name. For example: "ttadv300.cdat.time". • To disable a particular segment of a segmented field, append  .segment.segment_id to the field name. For example: "tiitm001.item.segment.1".
Context

4GL library function.

You can use the function in the following 4GL sections: before.display.object and when.field.changes. Include it in the before.display.object section if you want to disable fields after the data has been read from the database but before the fields are displayed on the form. Include it in the when.field.changes section if you want to disable certain fields whenever the content of a related field changes.

Examples

| Disable two named single-occurrence fields

disable.fields( "tccom010.beca", "tccom010.dsca" )

| Change to read-only fields the current occurrences of the multi-

| occurrence fields tccom010beca and tcccom101.dsca

disable.fields( READONLY, "tccom010.beca", actual.occ, "tccom010.dsca",
actual.occ )

| Disable element number 10 of an array field

disable.fields( "tfmod100.perd(10)" )

| Disable elements 1 to 12 of an array field

for i  = start to 12

disable.fields( "month(" & str$(i) & ")" )

endfor

| Disable the date element of a UTC field

ttaad500.fidt = 0

disable.fields( "ttaad500.fidt.date" )

| Disable the first and second segments of a segmented field

disable.fields( "tcibd001.dfit.segment.1", "tcibd001.dfit.segment.2" )

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


display(), display.all(), display.curr.occ(), display.fld(), display.occ()

Syntax

void display( field )

void display.all()

void display.curr.occ()

void display.fld( long occurrence, field )

void display.occ( long occurrence )

Description

Use these functions to display specified fields on a form. Usually, the standard program displays fields automatically, either when the form is opened or when data in a related input field is changed. However, there are situations when you need to use these functions to display fields. For example, to display stand-alone fields, to display fields that are not in the input field TAB sequence, or to send data to the form during batch processes.

display()	Displays a single-occurrence field. You cannot use this to display a field for all occurrences.
display.all()	Displays all fields of all occurrences.
display.curr.occ()	Displays all fields of the current occurrence.
display.fld()	Displays a specified field of a specified occurrence. To display a field for all occurrences, use the following construction: for i= 1 to filled.occ display.fld( i, field ) endfor
display.occ()	Displays all fields of a specified occurrence.
Arguments

field	Indicates the field to be displayed. This can be the field number or a string containing the field name. For example: display( "pctstqqq.item" )  display( 5 ) display.fld( actual.occ, "pctstqqq.item" )
occurrence	The occurrence for which the field(s) are to be displayed. You can use the predefined variable actual.occ here. This always contains the number of the current occurrence.
Notes

These functions always display the current value of the specified fields.

The current field pointer and form status are always saved when a display function is called and then restored when the function has terminated.

Non-database fields must be declared as extern in the program script.

The functions display.fld(), display.occ(), and display.curr.occ() are valid only for forms of type 2 or 3 (multioccurrence).

The functions display.all(), display.occ(), and display.curr.occ() do not affect stand-alone fields. To display a value for a stand-alone field use display() or display.fld().

Context

4GL library functions.

You can use these functions only in 4GL scripts. You cannot use them in a before.program section, as there is no current form at that stage. Also, to avoid recursion, do not use the functions in before.display and after.display subsections of the same field.

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


display.total.fields()

Syntax

void display.total.fields( string fieldname1, long value1 [, string fieldname2, long value2 ] ... )

Description

When a total line is included in a form, this function displays total values for specified fields in the grid. The function takes one or more pairs of arguments. In each pair, the first argument is the field name; the second argument is the total value for that field.

The fields must be defined on the form as multioccurrence form fields. They must also be declared in the UI script. Alternately, the fields can be table fields.

To add a total line to a grid, add the following code to the UI script:

before.program:

fattr.total.line = true

Then for every update that effects the total fields, call display.total.fields() to display the new totals.

The total line can display an enum value. To do this, the description of the enum must be passed using enum.descr$() . For example:

display.total.fields( "tffbs.dbcr", enum.descr$( "tfgld.dbcr",
 	tfgld.dbcr.debit ) )

Notes

Total fields are always read-only. They cannot be disabled or enabled.

Total fields have the same display properties as the fields above them.

If a field specified by the function is an array field, the total value is displayed in the first field of the array. Subsequent fields in the array cannot be addressed by the function.

Context

4GL library function.

Example

before.program:

fattr.total.line = true

choice.first.set:

after.choice:

display.total.fields( "whwmd000.amnt1", tot_1, "whwmd000.amnt2", tot_2 )

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


do.all.occ()

Syntax

void do.all.occ( function_name [, ... ] )

Description

This executes the specified function for all occurrences on the current form. When included in the before.choice subsection of a choice.update.db section, the function is executed only for updated occurrences.

Arguments

function_name	The name of the function that must be executed. The function must be of type void.
...	Use these optional arguments to pass one or more arguments to the specified function. Use commas (,) to separate the arguments.
Context

4Gl library function.

You can use this function only in 4GL scripts, of types 1, 2, and 3. You can use it in the following event subsections:

before.choice, on.choice, after.choice
before.input, on.input, after.input, check.input
when.field.changes
before.zoom, after.zoom

See also

do.occ(), do.occ.without.update(), on.old.occ()

Example

declaration:

long old_inventory

choice.cont.process:

on.choice:

do.all.occ( update_occurrences, 9999 )

main.table.io:

before.rewrite:

on.old.occ( get_old_inventory )

pctst999.change = pctst999.item - old_inventory

functions:

function void update_occurrences( long new_val )

{

pctst999.special = new_val

}

function void get_old_inventory()

{

old_inventory = pctst999.item

}

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


do.occ()

Syntax

void do.occ( long occurrence, function_name [, ...] )

Description

This locks the specified occurrence and executes the specified function for that occurrence.

Arguments

occurrence	The occurrence number.
function_name	The name of the function that must be executed. The function must be of type void.
...	Use these optional arguments to pass one or more arguments to the specified function. Use commas (,) to separate the arguments.
Context

4Gl library function.

You can use this function only in 4GL scripts, of types 2 and 3. You can use it in the following event subsections:

before.choice, on.choice, after.choice
before.input, on.input, after.input, check.input
when.field.changes
before.zoom, after.zoom

See also

do.all.occ(), do.occ.without.update(), on.old.occ()

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


do.occ.without.update()

Syntax

do.occ.without.update( long occurrence, function_name [, ...] )

Description

This executes the specified function for a specified occurrence, without any locking or update actions.

Arguments

occurrence	The occurrence number.
function_name	The name of the function that must be executed. The function must be of type void.
...	Use these optional arguments to pass one or more arguments to the specified function. Use commas (,) to separate the arguments.
Context

4Gl library function.

You can use this function only in 4GL scripts, of types 2 and 3. You can use it in the following event subsections:

before.choice, on.choice, after.choice
before.input, on.input, after.input, check.input
when.field.changes
before.zoom, after.zoom

See also

do.all.occ(), do.occ(), on.old.occ()

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


enable.commands()

Syntax

void enable.commands( string command [, string command]... )

Description

This enables the specified standard and/or form command(s). Standard commands are identified by their command IDs. Form commands are identified either by a function name, a session code, or a menu code.

Notes

The standard program can enable and disable form commands depending on the number of occurrences currently selected in the form.

You cannot use enable.commands() to enable commands that have been disabled either in the form definition or because the user is not authorized for the commands.

Context

4GL library function.

Example

enable.commands( "test.function", "ttadv3500m000", ADD.SET )

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


enable.fields()

Syntax

void enable.fields( string field [, string field]... )

Description

This enables the specified single-occurrence and/or multi-occurrence field(s) on a form.

To enable all fields of a group, see enable.group().

The field argument identifies the field to be enabled. For a single-occurrence field, this is the field name. For a multioccurrence field, this can be either the field name or the field name followed by an occurrence number (depending on whether you wish to enable all occurrences of the field or only one particular occurrence).

For array fields, UTC fields, and segmented fields, you can append suffixes to the field name to indicate the particular element or segment to be enabled. If you omit these suffixes, all elements/segments are enabled.

•	To enable a particular element of an array field, append the element number (in parentheses) to the field name. The element number must be an integer, formatted as a string. It cannot be a variable. For example: "tfmod100.perd(10)".

•	To enable only the date or time element of a UTC field, append either .date or .time to the field name. For example: "ttadv300.cdat.time".

•	To enable a particular segment of a segmented field, append .segment.segment_id to the field name. For example: "tiitm001.item.segment.1".

Context

4GL library function.

You can use this function in the following 4GL event subsections: before.display.object and when.field.changes. Include it in the before.display.object section if you want to enable fields after the data has been read from the database but before the fields are displayed on the form. Include it in the when.field.changes section if you want to enable certain fields whenever the content of a related field changes.

Examples

| Enable two named single-occurrence fields

enable.fields( "tccom010.beca", "tccom010.dsca" )

| Enable element number 10 of an array field

enable.fields( "tfmod100.perd(10)" )

| Enable elements 1 to 12 of an array field

for i  = start to 12

enable.fields( "month(" & str$(i) & ")" )

endfor

| Enable the date element of a UTC field

ttaad500.fidt = 0

enable.fields( "ttaad500.fidt.date" )

| Enable the first and second segments of a segmented field

enable.fields( "tcibd001.dfit.segment.1", "tcibd001.dfit.segment.2" )

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


execute()

Syntax

void execute( long command )

Description

This executes the specified standard command. Normally, standard commands are activated by the user. This function enables applications to execute standard commands without user intervention. This is useful, for example, if you want to display the first record of the main table when a session is started.

Infinite recursion is possible when using this command. For example, if you include execute(add.set) in the after.choice subsection of choice.add.set. So, never use this function to execute a standard command in its own choice sections.

Note

For a list of all standard commands and the program types in which you can use them, see Standard commands.

Context

4GL library function.

You can use this function in 4GL scripts only. You can use it in the following event subsections:

before.choice, on.choice, after.choice
init.form, before.form, after.form, on.entry

You cannot use the function in the after.choice section of choice.update.db.

Example

form.2:

init.form:

execute( first.set )

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


get.field.label()

Syntax

long get.field.label( const string fname, long element, ref string label1 mb, ref string label2 mb, ref string label3 mb )

Description

This retrieves the label text associated with the specified field. The function is relevant to dynamic forms only.

Arguments

fname	The field name.
element	For an array field, use this to specify the array element for which you wish to retrieve the label.
label1 to label3	A field can have up to three labels. These return the text of the first, second, and third labels respectively (if they exist).
Return values

>0	number of lines in the label (1, 2, or 3)
-1	session is not dynamic
-2	field not found

Context

4GL library function.

Example

group.1:

before.group:

form.hcur = attr.currency$

lines = get.field.label("tfacp200.amth", 1, label1, label2, label3 )

newlabel = label1 & " [" &form.hcur & "]"

change.field.label("tfacp200.amth", 1, newlabel )

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


get.screen.defaults()

Syntax

void get.screen.defaults()

Description

The save.defaults standard command enables users to save the current field values of a session as the default values for that session. The get.screen.defaults() function displays the default values for all fields on all forms of the current session. It is often used at the start of update or print programs, where the user must specify some parameters before executing the session.

If no user defaults are defined, set.fields.default() is executed automatically.

Context

4GL library function.

You can use this function only in form sections of 4GL scripts.

Example

form.1:

init.form:

get.screen.defaults()

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


group.invisible()

Syntax

void group.invisible( long group.nr )

Description

This hides the specified group completely, including all associated fields, labels, and subgroups. The group.nr argument specifies the group number, as defined in the form editor.

This function is relevant to dynamic forms only.

Context

4GL library function.

You can use this function only in the before.program and in the after.form.read section of 4GL scripts.

Example

before.program:

group.invisible(3)

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


input.again()

Syntax

void input.again()

Description

After input by a user, this forces the user to input the data again. If there is an input error, it is preferable to use set.input.error() in the check.input subsection for the field.

Context

4GL library function.

You can use this function only in 4GL scripts. You can use it in the following event subsections:

on.input, after.input, when.field.changes, after.field, before.checks
before.zoom

Example

field.pctst999.item:

on.input:

if pctst999.item(1;1) = "p" then

print_item()

input.again()

endif

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


inputfield.invisible()

Syntax

void inputfield.invisible( string field_name(18) [, string
  field_name(18)]... )

Description

This hides the specified field(s) completely. In dynamic sessions, associated labels and dependent child fields are also hidden. To hide a particular element of an array field, append the element number (in parentheses) to the field name. For example: "ttadv301.labl(2)".

Note that when the predefined variable attr.echo is set to off, the field value is not displayed but the field itself remains visible.

Note

Use inputfield.visible() to redisplay the field again. Use is.field.invisible() to check whether a specified field is currently visible or invisible.

Context

4GL library function.

You can use this function only in 4GL scripts.

For dynamic forms, you can use this function only in the before.program and in the after.form.read section. When this function is called in the after.form.read section also the label and/or the button belonging to the input field is removed.

Example

before.program:

inputfield.invisible( "ttadv200.cpac", "ttadv200.crel" )

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


inputfield.password()

Syntax

void inputfield.password( string field_name(18) [, string
  field_name(18)]... )

Description

This causes input to the specified field to be displayed as asterisks (*). To specify a particular element of an array field, append the element number (in parentheses) to the field name. For example: "ttadv301.labl(2)".

Context

4GL library function.

You can use this function only in 4GL scripts. For dynamic forms, you can use this function only in the before.program section.

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


inputfield.visible()

Syntax

void inputfield.visible( string field_name(18) [, string
  field_name(18)]...  )

Description

Use this to redisplay one or more fields made invisible by inputfield.invisible(). To redisplay a particular element of an array field, append the element number (in parentheses) to the field name. For example: "ttadv301.labl(2)".

Note

Use is.field.invisible() to check whether a specified field is currently visible or invisible.

Context

4GL library function.

You can use this function only in 4GL scripts. For dynamic forms, you can use this function only in the before.program section.

Example

before.field:

inputfield.visible( "ttadv200.cpac" )

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


is.field.invisible()

Syntax

long is.field.invisible( string field_name(18) )

Description

This checks whether a specified field is currently visible or invisible. To specify a particular element of an array field, append the element number (in parentheses) to the field name. For example: "ttadv301.labl(2)".

Note

Use inputfield.invisible() to hide a field. Use inputfield.visible() to redisplay it again. For dynamic forms, you can use this function only in the before.program section.

Return values

FALSE	field is visible
TRUE	field is invisible

Context

4GL library function.

You can use this function only in 4GL scripts.

Example

if not is.field.invisible( "ttadv200.cpac" ) then

display( "ttadv200.cpac" )

endif

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


make.current()

Syntax

void make.current()

Description

This reads the current main table record and displays it on screen. Calling this function is similar to calling execute(find.data), except that if the specified record is not present, make.current() does not read the next record.

Context

4GL library function.

You can use this function only in 4GL scripts. You can use it in the following event subsections:

before.choice, on.choice, after.choice
init.form, before.form, after.form

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


mark.occ()

Syntax

void mark.occ( long occurrence )

Description

This marks the specified occurrence with a reverse bar, makes the marked record the current record in the database, and sets the predefined variable actual.occ to the marked occurrence.

The following predefined variables are relevant to this function:

marked	Use this to check whether an occurrence is marked or not. This can also be tested in the on.exit subsection of a zoom process.
mark.status	This is available in the subsections before.choice and after.choice of choice.mark.occur. It indicates the type of marking that the standard program is executing. It can have the following values: DUPL.OCCUR  during marking for copying TEXT.MANAGER  during marking for edit text 0 in all other cases and when not marking
Note

Use remove.mark() to unmark the occurrence.

Context

4GL library function.

You can use this function only in 4GL scripts, and only in choice and form sections of those scripts. You cannot use it in programs of type 4.

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


on.old.occ()

Syntax

void on.old.occ( function_name [, ...] )

Description

This executes the specified function for the current occurrence, using the old values of the record. The record must have been previously modified.

Arguments

function_name	The name of the function that must be executed. The function must be of type void.
...	Use these optional arguments to pass one or more arguments to the specified function. Use commas (,) to separate the arguments.
Note

In DAL scripts, with.old.object.values.do() is the equivalent of on.old.occ().

Context

4Gl library function.

You can use this function only in 4GL scripts. You can use it in the following event subsections:

before.rewrite, after.rewrite
before.write,  after.write      (in the case of dupl.occur or global.copy)

See also

do.all.occ(), do.occ(), do.occ.without.update()

Example

declaration:

long old_inventory

choice.cont.process:

on.choice:

do.all.occ( update_occurrences, 9999 )

main.table.io:

before.rewrite:

on.old.occ( get_old_inventory )

pctst999.change = pctst999.item - old_inventory

functions:

function void update_occurrences( long new_val )

{

pctst999.special = new_val

}

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


print.const()

Syntax

void print.const( [string fill_string(127)] )

Description

This displays a specified constant string value in the current form field. The current value of the database field is not affected.

If you do not include the fill_string argument, the field is filled with asterisk characters (*). If the argument is a string of length one, the field is filled with the specified character. If the argument is a string of length greater than one, the specified string is displayed in the field, without repetition. The maximum length for the string is 127 characters.

Context

Bshell function.

You can use this function only in 4GL scripts.  As it operates on the current field, you can use it only in field sections.

Example

field.pctst999.desc:

after.display:

if pctst999.number = 0 then

print.const("?")	| Display "????????" in the current field

endif

if pctst999.number = 99999 then

print.const(" ")	| Blank the current field

endif

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


refresh.curr.occ()

Syntax

void refresh.curr.occ()

Description

This reads the current record and refreshes it on screen. All references on the form are read again. For example, in the case of a zoom from a field to a session where the record can be modified, calling refresh.curr.occ() refreshes the occurrence on the parent form also.

Note that the function locks the record before reading it; this is necessary for delayed locks.

Context

4GL library function.

You can use this function only in 4GL scripts. You cannot use it in programs of type 4.

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


remove.mark()

Syntax

void remove.mark()

Description

This unmarks an occurrence previously marked by using mark.occ(). Do not use this function to remove marks set by the standard program.

Context

4GL library function.

You can use this function only in 4GL scripts, and only in choice and form sections of those scripts. You cannot use it in programs of type 4.

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


set.fields.default()

Syntax

void set.fields.default()

Description

It is possible to define default values for form fields with the form editor. For all fields of the current form, this function sets the corresponding script variables to the default form values.

The function is often used before batch or print programs, where the user must specify some parameters for the batch run.

Context

4GL library function.

You can use this function only in form sections of 4GL scripts.

See also

get.screen.defaults()

Example

form.1:

init.form:

set.fields.default()

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


stp.reset.value()

Syntax

void stp.reset.value()

Description

This resets the value in the current field to its previous value. You can use this function only after input to the field.

Context

4GL library function.

You can use this function only in 4GL scripts. You can use it in the following event subsections:

on.input, after.input, check.input

In a check.input subsection, you cannot use this function before a save operation. To ensure this, program the section as follows:

check.input:

if not before.update.check then

stp.reset.value()

endif

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


to.field()

Syntax

void to.field( field )

Description

This transfers control of the standard program to the specified field after input to or display of the current field. This overrides the TAB sequence of the form. You can specify the field by using the field number or a string containing the field name.

After handling the specified field, control passes to the next field in the TAB sequence.

Note

In a well-designed GUI, users (and not the application) select and initiate the actions to be performed. Using to.field() removes control from the user. Therefore it does not conform to good GUI design principles.

Context

4GL library function.

You can use this function only in 4GL scripts. You can use it in the following event subsections:

after.input, after.display, after.field

See also

to.form()

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


to.form()

Syntax

void to.form( long form_number )

Description

This forces a switch from the current form to the specified form. The form_number argument must specify an existing form in the session, and must be in the range one to the value of the predefined variable number.forms. During the switch operation, the after.form subsection of the current form is executed and the init.form and before.form subsections of the new form are executed. The init.form subsection is executed only the first time a form becomes current.

The following predefined variables are relevant to this function:

number.forms	indicates the total number of forms in the session
form.prev	indicates the previous form number
form.curr	indicates the current form number
form.next	indicates the next form number
Note

In a well-designed GUI, users (and not the application) select and initiate the actions to be performed. Using to.form() removes control from the user. Therefore it does not conform to good GUI design principles.

This function is not relevant for dynamic forms.

Context

4GL library function.

You can use this function only in 4GL scripts, and only in choice and form sections of those scripts.

Example

| Suppose there is a special form (form 4) for a form command.
| When the user chooses this command, form 4 is started.

declaration:

long old_curr_form

function extern my.form.command()

{

old_curr_form = form.curr

to.form( 4 )

. . . 	| perform some action(s)

to.form( old_curr_form )

}

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


to.group()

Syntax

long to.group( long group.nr )

Description

Use this to make the first form on which the specified group occurs the current form. This function is relevant to dynamic forms only.

In a well-designed GUI, users (and not the application) select and initiate the actions to be performed. Using to.group() removes control from the user. Therefore it does not conform to good GUI design principles.

Return values

1	success
0	group not found

Context

4GL library function.

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


update.occ()

Syntax

void update.occ()

Description

The standard program automatically detects changes a user makes to a field. However, it cannot detect changes to field values made in the program script. When you modify a field of the main table in the program script, you must call update.occ() to switch on the update.status flag of the standard program.  This ensures when that the database is next updated, the modifications are saved to the database. The database update action can be initiated either by the user or within the script (use execute(update.db)).

Before the update.db command is executed, the user can undo the changes with the recover.set command. If you do not want users to be able to undo changes, you can force an immediate update by calling execute(update.db) in the script.

Context

4GL library function.

You can use this function only in 4GL scripts, and only in choice and field sections of those scripts.

Example

choice.cont.process:

on.choice:

do.all.occ(update.occurrences)

functions:

function void update.occurrences()

{

tiitm001.special = 9999

update.occ()              | Sets flag to indicate change

}

See also

do.occ()

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


enable.group()

Syntax

void enable.group( long group.nr )

Description

This enables all the fields of the specified (dynamic) group. See enable.fields.

This function is relevant to dynamic forms only.

Context

4GL library function.

Example

|Enable group
enable.group(7)

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


disable.group()

Syntax

void disable.group( long group.nr, [long disable.mode] )

Description

This disables all the fields of the specified (dynamic) group. See disable.fields.

There is a second, optional, argument that can have two possible values:

DISABLE	The default mode, it does not need to be specified.
READONLY	In this mode the fields become read-only and cannot be edited by the user.

This function is relevant to dynamic forms only.

Context

4GL library function.

Example

|Disable group
disable.group(7)
disable.group(5,READONLY)

Related help topics

    Form and form field operations:  overview
    Form and form field operations:  synopsis


Formatting input and output: overview and synopsis

Overview

Use these functions for formatting input and output strings.

Synopsis

string	edit$	( expression, string format(.) )
string	sprintf$	( string format(.) [, expression, ...] )
long	string.scan	( str_expr, string format(.) [, variable, ...] )
string	vsprintf$	( string format(.) [, ...] )


edit$()

Syntax

string edit$( expression, string format(.) )

Description

This formats an expression according to a specified format.

Arguments

expression	The expression that must be formatted. This can be a floating point expression, an integer expression, or a string expression that returns an integer or a floating point value.
format	A string that defines the required format. The following formatting characters are available:
	9	Use to reserve a position for a digit. Inserts a 0 if there is no significant digit in that position.
	Z	Use to reserve a position for a digit. Inserts a space if there is no significant digit in that position. You can use this both before and after the decimal sign.
	V	Use to indicate the position of the decimal sign. No decimal sign is displayed. To display a decimal sign, you must enter ‘D’, a period [.], or a comma [,] immediately after this character, depending on which decimal sign you wish to use.
	D	Use to display the decimal sign as defined in the data dictionary.
	T	Displays a thousand sign. The representation of the thousand sign is defined in the data dictionary.
	-	If this is the first or last character in a format string, a negative value is prefixed or suffixed by a minus sign [-] and a positive value is prefixed or suffixed by a space. Minus signs in other positions have the same meaning as ‘Z’.
	+	If this is the first or last character in a format string, a negative value is prefixed or suffixed by a minus sign [-] and a positive value is prefixed or suffixed by a plus sign [+]. Plus signs in other positions have the same meaning as ‘Z’.
	*	If this is the first character in a format string, all spaces to the left of the most significant digit are filled with asterisks [*].
	All characters other than those described above are copied directly to the output string. Periods [.] and commas [,] are exceptions. These are reserved for use as decimal signs and thousand signs.  If the format expression is enclosed by parentheses, these are displayed only if the result is negative.
Return values

The function returns the formatted expression. If the specified expression does not fit in the format string, the result is filled with the overflow characters defined in the data dictionary.

Note

To include currency symbols or to use formats defined in the data dictionary, use sprintf$().

Context

Bshell function.

Examples

These examples assume that the decimal sign, thousand sign, and overflow character are defined in the data dictionary as a period [.], comma [,] and hash sign [#] respectively

Expression	Format	Result	Remarks
5286.45	9999VD99	5286.45
463.897	9999VD99	0463.89
34.65	9999VD99	0034.65
-3.1	9999VD99	#######	overflow
5286.45	ZZZZVD99	5286.45
463.897	ZZZZVD99	463.89
34.65	ZZZZVD99	34.65
-3.1	ZZZZVD99	-3.10
5286.45	----VD99	5286.45	no space for -
463.897	----VD99	463.89
34.65	----VD99	34.65
-3.1	----VD99	-3.10
5286.45	++++VD99	5286.45	no space for +
463.897	++++VD99	+463.89
34.65	++++VD99	+34.65
-3.1	++++VD99	-3.10
34.65	+ZZZVD99	+34.65
-3.1	+ZZZVD99	-3.10
5286.45	ZZZZVD99-	5286.45
-3.1	ZZZZVD99-	3.10-
5286.45	ZZZZVD99+	5286.45+
-3.1	ZZZZVD99+	3.10-
5286.45	*ZZZVD99	######	overflow
463.897	*ZZZVD99	463.89
34.65	*ZZZVD99	*34.65
-3.1	*ZZZVD99	*-3.10
5286.45	ZTZZZVD99	5,286.45
463.897	ZTZZZVD99	463.89
5286.45	ZDZZZVD99	5.286.45
463.8970	ZZZVD99ZZ	463.897
-3.1	(ZZZVD99)	(3.10)
3.1	(ZZZVD99)	3.10
Related help topics

    Formatting input and output: overview and synopsis


sprintf$()

Syntax

string sprintf$( string format(.) [, expression, ...] )

Description

This formats a string and returns the formatted string. The format argument contains zero or more ordinary characters and substitution symbols. The ordinary characters are copied directly to the output string. The substitution symbols specify formats for the values specified in the expression arguments and are substituted by these formatted values.

The substitution symbols are used in the sequence in which they are specified. The first substitution symbol is used for the first expression argument. The second substitution symbol is used for the second expression argument, and so on.

In addition to a range of numeric type expressions, the function supports dates, amounts, single-byte strings, multibyte strings, bidirectional strings, and combined normal and bidirectional strings. input strings that contain bidirectional strings must be specified in logic order. The result is also returned in logic order.

Substitution symbols

Substitution strings have the following syntax:

%[-][min][.max]type

The elements of a substitution string have the following meanings:

%	All substitution strings begin with a percentage character [%]. To output the percentage character itself, specify it as ‘%%’.
-	An optional flag indicating that the output string is to be left justified. If this is omitted, the output string is right justified by default.
min	Specifies the minimum length of the output field. If the output string has fewer characters than the minimum field width, it is filled out with spaces. By default, these are inserted at the start of the field. If the ‘-‘ flag is specified, the spaces are inserted at the end of the string.  Instead of an integer constant, you can specify the length with an asterisk [*]. In this case, the corresponding expression argument must supply the length.
max	Specifies either the maximum number of digits after the decimal sign (for ‘%e’ and ‘%f’ substitution types), the maximum number of digits (for ‘%g’ substitution types), or the maximum string length (for ‘%s’, ‘%A’, ‘%D’, ‘%u’, and ‘%U’ substitution types). Instead of an integer constant, you can specify the length with an asterisk [*]. In this case, the corresponding expression argument must supply the length.
type	The type of conversion to be applied to the substituted value (see below).
The type element can have one of the following values:

%Axxx[,CUR]	Use for amounts.  xxx is the code for an amount format defined in the data dictionary. CUR indicates the currency code to use. It this is omitted, the default currency of the company of the user is used.
%Dxxx[,lang]	Use for dates.  xxx is the code for a date format defined in the data dictionary. lang indicates the language code to use. If this is omitted, the current user language is used. The expression that is substituted for this symbol must specify a number of days since 01-01-0001.
%D(format)	Use for dates. This option enables you to define your own date format by using the following subformats of the ‘%D’ format: %m  month in year 1 - 12 %w  week in year 0 - 53 week 0 in previous year                     week 53 in current year %W week in year 1 - 53      week 53 in previous year %d day in month 1 - 31 %e day in week 1 - 7 %j day in year 1 - 365 %y year without century 01 - 99 %Y year with century 1 - 9999 %h name of month  (‘Jan’ - ‘Dec’) (abbreviated) %H name of month (‘January’ - ‘December’) %a name of day (‘Sun’ - ‘Sat’) (abbreviated) %A      name of day (‘Sunday’ - ‘Saturday’) You can combine these subformats with other formats. Note that strings returned by name of month and day formats are language dependent.
%uxxx	Use for UTC dates. xxx is the code for a UTC date format defined in the data dictionary.
%Uxxx	Use for UTC times. xxx is the code for a UTC time format defined in the data dictionary.
%u(format)	Use for UTC dates. This option enables you to define your own date format by using the subformats described for the ‘%D(format)’ symbol. You can combine these subformats with other formats.  Note that strings returned by name of month and day formats are language dependent.
%U(format)	Use for UTC times. This option enables you to define your own time using the following subformats of the ‘%U’ format. %H hours in 24 hour format %L hours in 12 hour format %m minutes %s seconds %a substitutes the am/pm symbol as defined for the user language %x time separator as specified for the user language You can combine these subformats with other formats.
%d	Use for long values.
%e	Use for double values with exponent.
%f	Use for doubles values with 6 decimal places.
%g	Use for double values.
%s	Use for single-byte and multibyte strings.
%o	Use for octal representations of numbers.
%x	Use for hexadecimal representations of numbers.
%@format@	Use for formatting values by using the formatting characters described for edit$().
Return values

The formatted string. If you specify an invalid format, sprintf$() returns a percentage character [%].

Context

Bshell function.

Examples

Format	Value	Result
%f	1.2	"1.200000"
%10f	1.2	"  1.200000"
%10.2f	1.2	"      1.20"
%-10.2f	1.267	"1.27      "
%10.6g	1234.567	"   1234.57"
%10.2e	12.34	"  1.23e+01"
%-10.2e	12.34	"1.23e+01  "
%10d	1	"         1"
%10d	-1	"        -1"
%-10d	1	"1         "
%-10d	-1	"-1        "
%10s	"12"	"        12"
%-10s	"12"	"12        "
%10s	"123456789012"	"123456789012"
%.10s	"123456789012"	"1234567890"
%@ZZVD99@	1.267	"     1.26"
Format	Result
%s	Returns the full string.
%20s	Right justifies the string in a field of 20 positions. If the string is longer 20 positions, the field is lengthened to accommodate the full string.
%-20s	Left justifies the string in a field of 20 positions. If the string is longer 20 positions, the field is lengthened to accommodate the full string.
%20.20s	Right justifies the string and limits its size to 20 positions. Partially displayable multibyte characters (2 characters wide) will be spaced out.
Strings

string result(80), word(20)

word = "word"

result = sprintf$("This is a '%*s' of 10 positions",10,word)

| result contains "This is a '      word' of 10 positions"

Doubles

string result(80)

result = sprintf$("number: %-*.*f",10,2,1.2")

| result contains "number: 1.20      "

| minimum length of the double value is 10 positions

| number of digits after decimal sign is 2

Amounts

| Suppose the default currency is USD ($)

| and A001 is defined as "$$ 999T999T999VD99"

string result(80)

result = sprintf$("%A001", 1234.56)

| result contains "$ 000,001,234.56"

result = sprintf$("%-10A001,hfl", 1234.56)

| result contains "fl 000.001.234,56"

result = sprintf$("%-.10A001,hfl", 1234.56)

| result contains "001.234,56"; there is insufficient space

| for currency symbol

Dates

| Suppose date format 002 is: "year/month/day in month"

string result(80)

result = sprintf$("%D002", 727168)

| result contains "1991/12/2"

| Example of substitution symbol %D(format)

string result(80)

result = sprintf$("%D(Date: %02d/%02m/%04Y)", date.num())

| result contains "Date: 12/07/1993"

result = sprintf$("Date: %D(%02d %-20H %04Y)", date.num())

| result contains "Date: 12 June                 1993"

UTC dates and times

| Date format 002 is "year/month/day in month"

| Time format 001 is "12 hour format:minutes:seconds AM/PM symbol"

string result(80)

result = springf$("%u002 %001", utc.num(), utc.num())

| Result contains "1997/01/01 10:02:53 pm"

string result(80)

result = sprintf$("UTC: %u(%02d/%02m/%04Y) %U(%02h%x%02m%x%025 %a)", utc.num(), utc.num())

| result contains "UTC: 22/07/1997 06:24:53 am"

| provided that for the user's language the time

| separator is ":" and the AM symbol is "am"

Related help topics

    Formatting input and output: overview and synopsis


string.scan()

Syntax

long string.scan( str_expr, string format(.) [, variable, ...] )

Description

This scans an input string (str_expr) for one or more fields and stores each individual field found in the first available variable argument. The format argument contains conversion symbols that the function uses to interpret the input string and retrieve the individual field values. The conversion symbols indicate the types of values expected:

%s	expects a single-byte or multibyte string

%f	expects a double

%d	expects a long

An input field is defined as all characters up to the next separator character or up to the next character that does not match the type of the corresponding conversion symbol.

A separator character is a single character used to separate individual values in the input string. It can be a space character, or any other character that is not used within individual fields in the input string. You cannot use multibyte characters as separators.

The string.scan() function scans the input string using each conversion symbol in the format argument in turn. For each conversion symbol, it scans the input string for characters that match the specified format. It stops scanning when it meets a separator character or a character that does match the expected type.

For example, consider the following function call:

string.scan( input_string, "%d|%f",long,double )

In this case, the function expects input_string to contain two separate numeric values. It reads the input string until it meets a pipe [|] character (this is the separator specified in the format argument). It then converts the characters read (excluding the separator) to a long value and stores that value in the long variable. The function then continues scanning the input string using the next conversion symbol in the format argument.

Note that if two conversion symbols are separated by more than one separator character, the function ignores those characters unless they match the input.

Return values

The function returns the number of scanned fields.

Context

Bshell function.

Example

double D

long L

string S(80)

long ret

ret = string.scan("string 123 456.78","%s %d %f",S,L,D)

| S contains "string", L contains 123, D contains 456.78

ret = string.scan("string|123|456.78","%s|%d|%f",S,L,D)

| S contains "string", L contains 123, D contains 456.78

Related help topics

    Formatting input and output: overview and synopsis


vsprintf$()

Syntax

string vsprintf$( string format(.) [, ...] )

Description

This acts the same as sprintf$(), except that the arguments to be substituted for the substitution symbols in the format argument are not known until run time.

Context

Bshell function.

Example

extern string my.message(256)   mb

function void create.my.message ( string X(14), ... )

{

my.message = vsprintf$( form.text$(X), ... )

}

Related help topics

    Formatting input and output: overview and synopsis


Functions with varying numbers of arguments: overview

In the BAAN 3GL programming language, you can define a function with a varying number of arguments. For example:

function long change.attributes( long id, ... )

{

......

}

The ellipses [...] in the function definition indicates that the number of function arguments is variable, up to a maximum of 255. The function call determines how many and which arguments the function uses.

The functions described in this section enable programs to check how many arguments a function uses, to retrieve their types and values, and to assign values to them.

The arguments cannot be arrays.

Related help topics

    Functions with varying numbers of arguments:  synopsis
    Functions with varying numbers of arguments:  sample program


Functions with varying numbers of arguments: synopsis

long	get.argc	( )
long	get.arg.type	( long arg_no )
double	get.double.arg	( long arg_no )
long	get.long.arg	( long arg_no )
string	get.string.arg	( long arg_no )
long	put.double.arg	( long arg_no, double value )
long	put.long.arg	( long arg_no, long value )
long	put.string.arg	( long arg_no, string value )


get.argc()

Syntax

long get.argc()

Description

This returns the number of arguments that the function in which get.argc() is implemented contains. Once you know this number, you can read and write to particular arguments using the other functions.

Context

Bshell function.

Related help topics

    Functions with varying numbers of arguments:  overview
    Functions with varying numbers of arguments:  synopsis
    Functions with varying numbers of arguments:  sample program


get.arg.type()

Syntax

long get.arg.type( long arg_no )

Description

This returns the type of the specified argument.

Arguments

arg_no	The sequence number of an argument of the function in which get.arg.type() is called.
Return values

The function can return any of the following values:

DB.LONG	DB.DOUBLE
DB.STRING  	DB.MULTIBYTE

Context

Bshell function.

Related help topics

    Functions with varying numbers of arguments:  overview
    Functions with varying numbers of arguments:  synopsis
    Functions with varying numbers of arguments:  sample program


get.double.arg(), get.long.arg(), get.string.arg()

Syntax

double get.double.arg( long arg_no )

long get.long.arg( long arg_no )

string get.string.arg( long arg_no )

Description

These return the value of a specified argument. For get.double.arg(), the argument must be of type double. For get.long.arg(), the argument must be of type long. For get.string.arg(), the argument must be of type string or multibyte string.

Arguments

arg_no	The sequence number of an argument of the function in which get.double.arg(), get.long.arg(), or get.string.arg() is called.
Return values

The value of the specified argument.

Context

Bshell functions.

Related help topics

    Functions with varying numbers of arguments:  overview
    Functions with varying numbers of arguments:  synopsis
    Functions with varying numbers of arguments:  sample program


put.double.arg(), put.long.arg(), put.string.arg()

Syntax

long put.double.arg( long arg_no, double value )

long put.long.arg( long arg_no, long value )

long put.string.arg( long arg_no, string value )

Description

These assign a value to a specified argument. For put.double.arg(), the argument must be of type double. For put.long.arg(), the argument must be of type long. For put.string.arg(), the argument must be of type string or multibyte string.

Arguments

arg_no	The sequence number of an argument of the function in which put.double.arg(), put.long.arg(), or put.string.arg() is called.
value	The value to assign to the argument.
Return values

 0	success
-1	error; probably invalid argument number

Context

Bshell functions.

Related help topics

    Functions with varying numbers of arguments:  overview
    Functions with varying numbers of arguments:  synopsis
    Functions with varying numbers of arguments:  sample program


Functions with varying numbers of arguments: sample program

function long change.attributes( long id, ...)

{

long i, long_value

double double_value

for i = 2 to get.argc()

on case get.arg.type(i)

case DB.LONG:

long_value = get.long.arg(i)

......

break

case DB.DOUBLE:

double_value = get.double.arg(i)

......

break

default:

......

break

endcase

endfor

}

function call:

change.attributes( window_id, DS_BACKGROUND, CW.GREEN, DS_FOREGROUND,
CW.WHITE, DS_WIDTH, 80, DS_HEIGHT, 40 )

Related help topics

    Functions with varying numbers of arguments:  overview
    Functions with varying numbers of arguments:  synopsis


Interprocess communication (bshell): overview

Use these functions to handle communication between different BAAN processes running in the same bshell.

BMS messages

The BMS mechanism supports broadcast messages, enabling messages to be sent to multiple processes. Messages can be up to 2048 characters long.

The sender process can use process IDs or masks to determine which processes a message is sent to.

•	Masks: A mask is a character string used to control which messages a process can receive. It can be added to any process by using the bms.add.mask() function. If the sender of a message specifies a mask for that message, the message is sent only to those processes to which the specified mask has been added.

•	Process IDs: Instead of, or in addition to a mask, the sender of a message can specify the process ID of the process for which the message is intended. The message is then sent only to that process. If a mask is also specified for the message, the process can receive the message only if the mask was previously added to the process.

Receiving processes can use masks and levels to control which messages it receives.

•	Masks: If a particular mask is added to a process, the process can receive all messages sent with that mask.

•	Levels: The sender of a message can specify a level for that message. Receiving processes can then choose which level of messages they wish to receive.

There are four predefined broadcast messages that the system can send to processes. Processes must set the bms.shutdown, bms.exit, bms.exit.child, bms.startup, and bms.startup.child masks to receive these messages.

•	bms.shutdown: When this mask is set for a process, the message “bms.shutdown” is sent to the process when all processes that do not have this mask set have ended. It indicates that the process must exit because the bshell wants to stop.

•	bms.exit: When this mask is set for a process, the exit value of an ended process is sent to the process. The received message contains the string “exit<exit.value>”. The process number of the exited process is provided in evt.bms.sender(event).

•	bms.exit.child: When this mask is set for a process, the exit value of an ended child process is sent to the process. The received message contains the string “exit.child<exit.value>”.

•	bms.startup: When this mask is set for a process, the message “startup” is sent to the process when a process is started.

•	bms.startup.child: When this mask is set for a process, the message “startup.child” is sent to the process when a child process is started.

Note that when one of the above message is sent, evt.bms.command(event) is zero.

Bucket messages

Bucket messages provide a simple mechanism for two processes to exchange small packets of information (up to 100 characters long). A process uses send.bucket() or send.wait() to send a data string to another specified process. A process calls receive.bucket$() to receive the next bucket message sent to it by any other process.

See also

Interprocess communication (operating-system level)

Related help topics

    Interprocess communication (bshell):  synopsis
    Interprocess communication (bshell):  sample programs


Interprocess communication (bshell): synopsis

BMS messages

void	bms.add.mask	( string mask(32) [, long processno] )
void	bms.delete.mask	( string mask(32) [, long processno] )
string	bms.receive$	( [ref long level, long wait.flag,    ref string mask()] )
long	bms.receive.buffer	( ref string broadcast(), ref long no.bytes    [, long level, long wait.flag, ref string    mask()] )
long	bms.send	( string broadcast(2048), long    level_or_evt[(EVTMAXSIZE)], string mask(32),   long processno [, long no.bytes] )
Bucket messages

string	receive.bucket$	( ref long processno )
long	send.bucket	( long processno, string bucket(100) )
long	send.wait	( long processno, string bucket(100) )
Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  sample programs


bms.add.mask()

Syntax

void bms.add.mask( string mask(32), [, long processno] )

Description

This adds the specified mask to a process. If you specify a process number, the mask is added to that process. Otherwise, the mask is added to the current process.

Context

Bshell function.

Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  synopsis
    Interprocess communication (bshell):  sample programs


bms.delete.mask()

Syntax

void bms.delete.mask( string mask(32), [, long processno] )

Description

This removes the specified mask from a process. If you specify a process number, the mask is removed from that process. Otherwise, the mask is removed from the current process.

Context

Bshell function.

Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  synopsis
    Interprocess communication (bshell):  sample programs


bms.receive$()

Syntax

string bms.receive$( [ ref long level, long wait.flag, ref string mask()] )

Description

Use this to receive a broadcast message. If no arguments are included, the function returns the first broadcast message sent to the process.

Arguments

level	This optional argument specifies a message level. The following values are available:   0 the function returns the first broadcast message sent to the process  >0 the function returns the first broadcast message sent with the specified  level  <0 the function returns the first broadcast message sent with a level less  than or equal to the absolute value of the specified level This argument returns the process ID of the sending process. The process ID overwrites the specified level.
wait.flag	This optional argument indicates whether the process must wait for a broadcast message if no message has yet been sent:     0 wait <>0 do not wait If you include this argument, you must also include the level argument.
mask	This optional argument returns the mask (if any) sent with the message.
Return values

The received broadcast message.

Context

Bshell function.

Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  synopsis
    Interprocess communication (bshell):  sample programs


bms.receive.buffer()

Syntax

long bms.receive.buffer( ref string broadcast(), ref long no.bytes [, long level, long wait.flag, ref string mask()] )

Description

Use this to receive a broadcast message. The function can retrieve a complete record, including ‘\0’ characters.

Arguments

broadcast	This returns the received broadcast message.
no.bytes	This returns the number of bytes in the broadcast message.
level	This optional argument specifies a message level. The following values are available:   0 the function returns the first broadcast message sent to the process  >0 the function returns the first broadcast message sent with the specified  level  <0 the function returns the first broadcast message sent with a level less  than or equal to the absolute value of the specified level
wait.flag	This optional argument indicates whether the process must wait for a broadcast message if no message has yet been sent:     0 wait <>0 do not wait If you include this argument, you must also include the level argument.
mask	This optional argument returns the mask (if any) sent with the message.
Return values

The ID of the sending process.

Context

Bshell function.

Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  synopsis
    Interprocess communication (bshell):  sample programs


bms.send()

Syntax

long bms.send(( string broadcast(2048), long level_or_evt[(EVTMAXSIZE)], string mask(32), long processno [, long no.bytes] )

Description

Use this to send a broadcast message to one or more processes.

Arguments

broadcast	The message that must be sent.
level_or_evt	Use this either to specify a level for the message (1 or 2, for example) or to specify an event array with the following information: evt.type( event )  this is always EVTBUCKETMESSAGE evt.bms.sender( event )     sender ID (this is filled automatically) evt.bms.command( event ) command ID evt.bms.argument( event ) some argument The specified event is sent to each process to which the broadcast message is sent.
mask	If you specify a mask in this argument, the message is sent to all processes to which that mask has been added. If you also specify a process ID in the processno argument, the process is sent only to the specified process.
processno	If you specify a process ID in this argument, the broadcast message is sent only to that process. If you specify 0 for this argument, the mask argument is used to indicate the processes to which the message is sent.
no.bytes	The size of the broadcast message, in bytes.
Notes

If bms.send() specifies a mask and no processes have that mask set, the file ‘$BSE/lib/bms_mask’ is searched for a line beginning with the mask name. Lines in this file have the following syntax:

<mask>:<process>:<y/n>:[boot]

When a line is found that begins with the specified mask, the process specified in that line is started. If the line contains ‘y’, the mask is automatically added to the process. The broadcast message and event are then sent to the process. If the line contains ‘n’, the mask is not added to the process and so the process does not receive the message and event. If the line ends with the word ‘boot’, the specified process is always started automatically before any other process when the bshell starts. For example:

| suppose the file '$BSE/lib/bms_mask' contains the following line:
| calculator:ottstpcalc:y

long event(EVTMAXSIZE), bms_id

bms_id = bms.send( "", event, "calculator", 0 )

Return values

  0	error
>0	the process ID of the last process to which the broadcast message was sent

Context

Bshell

See also

Events

Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  synopsis
    Interprocess communication (bshell):  sample programs


receive.bucket$()

Syntax

string receive.bucket$( ref long processno )

Description

This waits for a bucket message to be sent to the calling process by another process. It then returns that message. The processno argument returns the process ID of the sending process.

Context

Bshell function.

Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  synopsis


send.bucket()

Syntax

long send.bucket( long processno, string bucket(100) )

Description

This sends a bucket message to a specified process. If the specified process is sleeping, it is automatically started. It can retrieve the message by calling receive.bucket$().

Arguments

processno	The process ID of the process to which the message must be sent, as returned by functions such as activate() and act.and.sleep(). In subprocesses, the predefined variable parent indicates the process ID of the parent process.
bucket	The message string.
Return values

>0	the process ID of the called process
 -1	error

Context

Bshell function.

Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  synopsis


send.wait()

Syntax

long send.wait( long processno, string bucket(100) )

Description

This sends a bucket message to a specified process and waits for a reply. The receiving process must send a reply by using send.bucket() or send.wait(). Note that the waiting process cannot receive any message string contained in the reply.

Arguments

processno	The process ID of the process to which the message must be sent, as returned by functions such as activate() and act.and.sleep(). In subprocesses, the predefined variable parent indicates the process ID of the parent process.
bucket	The message string.
Notes

send.wait() is used to synchronize two processes. When a reply is sent with send.bucket() the processes appear to run simultaneously.

When a process that is waiting for a reply from one process receives a message from another process, it is wakened automatically and the data sent is lost.

Return values

>0	the process ID of the process that sends the reply
- 1	error

Context

Bshell function.

Example

Process 1:

long process

process = activate("process2")

send.bucket(process, "")   	| This is the reply, data can not be

| received in process 2

Process 2:

send.wait(parent, "I am waiting for a reply")

Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  synopsis


BMS messages: sample programs

Example 1

| process 1

ret = bms.send("do_action_1", 0, "tfgld1201s000", 0)

| background process "tfgld1201s000"

bms.add.mask("bms.shutdown")	| to detect the shutdown event

| which is sent by the system

....

bucket = bms.receive$()

if bucket = "bms.shutdown" then

end.process()	| contains del.window command

else

if bucket = "do_action_1" then

action_1()

endif

endif

Example 2

long    event(EVTMAXSIZE)

string  bms.ret(2048)

while true

next.event(event)

on case evt.type(event)

case EVTBUCKETMESSAGE:

bms.ret = bms.receive$()

handle.bucket.message( bms.ret )

break

case EVTKEYPRESS:

....

case EVTBUTTONPRESS:

....

endcase

endwhile

function handle.bucket.message( const string bms.str() )

{

string  key.of.record(100)

on case bms.str

case "first":

key.of.record = get.first.record()

bms.send(key.of.record, event, "", evt.bms.sender(event))

break

case "last":

key.of.record = get.last.record()

bms.send(key.of.record, event, "", evt.bms.sender(event))

break

case "next":

key.of.record = get.next.record()

bms.send(key.of.record, event, "", evt.bms.sender(event))

break

case "prev":

key.of.record = get.prev.record()

bms.send(key.of.record, event, "", evt.bms.sender(event))

break

endcase

}

Related help topics

    Interprocess communication (bshell):  overview
    Interprocess communication (bshell):  synopsis


Interprocess communication (cross-platform): overview

The Baan C Socket Interface is an Interprocess Communication (IPC) mechanism that enables cross-platform IPC over TCP/IP sockets. It is available on all platforms where the Baan Runtime Tools are available.

The Baan C Socket Interface supports bidirectional communication between two related or unrelated processes that are running on the same or on different hosts. One process is the server, the other is the client. A server process can use the socket mechanism to communicate with multiple clients. A client process can use the socket mechanism to communicate with multiple servers. Moreover, a process can be a server for one connection and a client for another.

The functions provided by the socket interface enable client processes to request a connection with a particular server and to create a socket on which to send data to and receive data from the server. They enable servers to accept connection requests from clients, and to create sockets on which to send data to and receive data from clients.

Using the functions

•	The server process calls sock.listen() to create a socket to which clients can send connection requests. The new socket is used only for receiving connection requests.

•	The server process calls sock.accept() to accept a connection request from a client process and to create a connected socket on which it can send data to and receive data from the client. The connection request is sent by the client to the listen socket created by the server with sock.listen().

•	A client process calls sock.connect() to request a connection with a particular server. The connection request is sent to the listen socket on the server. If the server accepts the request (with sock.accept()), the client creates a connected socket on which it can send data to and receive data from the server.

•	Both client and server processes use sock.send(), followed by sock.flush(), to send data to the other process via a connected socket. They use sock.recv() to read data from a connected socket.

•	When a socket is no longer needed, or if an error has occurred on the socket, the socket owner can close the socket by calling sock.close(). The process that created the socket is normally the socket owner. However, ownership of a socket can be transferred to another process with the sock.inherit() function.

Message retrieval

Data is delivered across a socket connection as a string of bytes without message boundaries. Consequently, when a process reads data from a socket, there is no guarantee that the data received belongs to a single message or consists of an entire message. Possible solutions are:

•	Including a length field, of fixed size, as the first field of a message. The receiver can then read the message based on the length value specified in the length field.

•	Including a type field, of fixed size, as the first field of a message. The receiver can then read the message based on the message size indicated by the specified message type.

Binary data transfer

To read binary data that has been stored in a buffer by sock.recv(), you must use the load.*() functions. When sending binary data with sock.send(), you must store the data in the send buffer by using the store.*() functions.

Both sets of functions assume that data is stored in big endian format (that is, highest byte first). If it is stored in little endian format, you must set the endian argument in the load.*() functions to 1. For example:

long	total.len

string	receive.buffer( 200 )

load.long( total.len, receive.buffer, 1 )

When sending data of type float or double over a socket, the store.float(), store.double(), load.float(), and load.double() functions do not convert the data. The data is stored in and retrieved from the send and receive buffers in the native format of the calling machine. So, do not rely on these functions to solve platform differences in floating-point storage formats. One possible solution it to convert floating-point numbers to a printable format before sending them over the socket connection.

See also

Interprocess communication (operating-system level)
Interprocess communication (bshell)

Related help topics

    Interprocess communication (cross-platform): synopsis


Interprocess communication (cross-platform): synopsis

long	sock.accept	( long socket )
long	sock.close	( long socket [, linger.timeout] )
long	sock.connect	( string host.name, string service.name,    long timeout )
long	sock.flush	( long socket )
long	sock.inherit	( long socket )
long	sock.listen	( string service.name )
long	sock.recv	( long socket, ref string data, long num.bytes )
long	sock.send	( long socket, string data, long num.bytes )
Related help topics

    Interprocess communication (cross-platform): overview


sock.accept()

Syntax

long sock.accept( long socket )

Description

A server process uses this to accept a connection request received on a socket created by sock.listen(). The function returns a valid connected socket on which the server process can send data to and receive data from the client process.

Arguments

socket	The file descriptor of a listen socket created by sock.listen().
Notes

If a program calls sock.accept() when there is no connection request pending on the listen socket, the program is put into a sleeping state until a connection request is received. When a request subsequently arrives, the program resumes and sock.accept() returns a connected socket.

If the calling application enables I/O events by calling select.event.input( 0, EVTIOEVENTMASK ), before calling sock.accept(), the application will receive an event in the following situations:

•	When data is available on the connected socket. To retrieve the data, the application can call sock.recv() on the socket specified in the event.

•	When an I/O error occurs on the connected socket. In this case, the application must call sock.close() to close the socket specified in the event.

You use next.event() to retrieve events from the event queue. For details of I/O events, see I/O events.

Return values

  >0	success; a descriptor for the connected socket is returned
<=0	error; the predefined variable e contains the error number

Context

Bshell function.

Related help topics

    Interprocess communication (cross-platform): overview
    Interprocess communication (cross-platform): synopsis


sock.close()

Syntax

long sock.close( long socket [, long linger.timeout] )

Description

This closes a specified socket.

Arguments

socket	The file descriptor of a socket created by sock.connect(), sock.accept(), or sock.listen().
linger.timeout	By default, sock.close() waits for five seconds to enable unsent data to be sent. Use this optional argument to specify a different timeout value. Possible values are: >0 Specifies the number of seconds the functions must wait for unsent data  to be sent. The bshell blocks during this timeout period.    0 The function returns immediately, and any unsent data is discarded.   -1 The function returns immediately, while unsent data is still being sent. The linger timeout is ignored when closing a socked returned by sock.listen().
Note

When a program terminates, all open sockets are automatically closed, with the default linger timeout (that is, five seconds).

Return values

  0	success
 -1	error; the predefined variable e contains the error number

Context

Bshell function.

Related help topics

    Interprocess communication (cross-platform): overview
    Interprocess communication (cross-platform): synopsis


sock.connect()

Syntax

long sock.connect( string host.name, string service.name, long timeout )

Description

A client process uses this to initiate a socket connection with a specified server. If the server accepts the connection request, the function returns a valid connected socket on which the client process can send data to and receive data from the server process. The function does not return until either there is a valid connection, or the connection request fails, or a specified timeout expires.

Arguments

host.name	The name of the host where the server process is located. The host name is resolved via a platform-specific lookup mechanism such as the /etc/hosts file or the Domain Name System (DNS). You can specify the host name as a dotted-decimal IP address, but this is not recommended.
service.name	The specifies the name of a service that maps to a port number. The service name is translated to a port number via a platform-specific lookup mechanism such as the /etc/services file or Yellow Pages (YP).  If you do not know the service name, you can specify the port number directly. For example: sock.connect( "10.1.2.39", "23", -1)
timeout	This specifies a timeout period (in seconds) after which the connection request is canceled if there is no response from the system specified by host.name.  If you specify a timeout of <=0, sock.connect() waits until it either succeeds or fails. If possible, do not specify timeout periods of less than five seconds. If you do, connection requests can fail due to a slow network. Note that the bshell blocks while sock.connect() is being executed.
Notes

If the calling application enables I/O events by calling select.event.input( 0, EVTIOEVENTMASK ), before calling sock.connect(), the application will receive an event in the following situations:

•	When data is available on the connected socket. To retrieve the data, the application can call sock.recv() on the socket specified in the event.

•	When an I/O error occurs on the connected socket. In this case, the application must call sock.close() to close the socket specified in the event.

You use next.event() to retrieve events from the event queue. For details of I/O events, see I/O events.

Return values

  >0	success; a descriptor for the connected socket is returned
<=0	error; the predefined variable e contains the error number

Context

Bshell function.

Related help topics

    Interprocess communication (cross-platform): overview
    Interprocess communication (cross-platform): synopsis


sock.flush()

Syntax

long sock.flush( long socket )

Description

You use sock.send() to place data in the send buffer of a connected socket. The data is automatically transferred on the socket when the buffer is full. But you can also call sock.flush() to transfer the data on the socket.

It is important to always check the return value of sock.flush() to verify whether or not the data has been sent successfully.

Arguments

socket	The file descriptor of a socket created by sock.connect() or sock.accept().
Notes

When the transport system has insufficient buffer space to hold the data to be transmitted, sock.flush() blocks the entire bshell until sufficient space is available. So, be careful not to overflow a receiving program by sending excess data.

If sock.flush() fails, the calling program must call sock.close() to close the socket.

Return values

 0	success
-1	error; the predefined variable e contains the error number

Context

Bshell function.

Related help topics

    Interprocess communication (cross-platform): overview
    Interprocess communication (cross-platform): synopsis


sock.inherit()

Syntax

long sock.inherit( long socket )

Description

A process calls this function in order to take over ownership of a specified socket from another process. The socket is removed from the list of open files for the process that originally owned the socket; it is added to the list of open files for the calling process. The socket is automatically closed when the new owner process terminates.

The use of sock.inherit() is required when a server starts a new process to handle a connection returned by sock.accept(). The new process must call sock.inherit() to become the owner of the socket. If it does not, then terminating the server program will close the socket handled by the new process as well.

Arguments

socket	The file descriptor of a socket created by sock.connect() or sock.accept().
Notes

The sock.inherit() function is valid only for sockets created by sock.connect() or sock.accept().

The new process does not inherit event settings from the original process. If required, the calling application must explicitly enable I/O events by calling select.event.input( 0, EVTIOEVENTMASK ), before calling sock.inherit(). The application will then receive an event in the following situations:

•	When data is available on the connected socket. To retrieve the data, the application can call sock.recv() on the socket specified in the event.

•	When an I/O error occurs on the connected socket. In this case, the application must call sock.close() to close the socket specified in the event.

You use next.event() to retrieve events from the event queue. For details of I/O events, see I/O events.

Return values

 0	success
-1	error; the predefined variable e contains the error number

Context

Bshell function.

Related help topics

    Interprocess communication (cross-platform): overview
    Interprocess communication (cross-platform): synopsis


sock.listen()

Syntax

long sock.listen( string service.name )

Description

A server calls this function to create a listen socket that it can use to receive connection requests from clients. The function binds the new socket to the address specified by INADDR_ANY and the service specified by service.name. It returns a valid listen socket that sock.accept() can access in order to accept connection requests.

Arguments

service.name	This specifies the name of a service that maps to a port number. The service name is translated to a port number via a platform-specific lookup mechanism such as the /etc/services file or Yellow Pages (YP).  If you do not know the service name, you can specify the port number directly. For example: sock.listen( "23" )
Notes

If the calling application enables I/O events by calling select.event.input( 0, EVTIOEVENTMASK ), before calling sock.listen(), the application will receive an event when a connection request is pending on the socket. The application can then call sock.accept() on the socket specified in the event. You use next.event() to retrieve events from the event queue. For details of I/O events, see I/O events.

When the calling application does not want to accept any new connections, it must close the listen socket by calling sock.close().

Return values

  >0	success; a descriptor for the listen socket is returned
<=0	error; the predefined variable e contains the error number

Context

Bshell function.

Related help topics

    Interprocess communication (cross-platform): overview
    Interprocess communication (cross-platform): synopsis


sock.recv()

Syntax

long sock.recv( long socket, ref string data, long num.bytes )

Description

Both client and server processes use this function to read data from a specified connected socket. The function returns only when the number of bytes specified by num.bytes has been received.

Arguments

socket	The file descriptor of the local socket, as returned by sock.connect() or sock.accept().
data	This returns a pointer to the buffer where the data is stored.
num.bytes	This specifies the number of bytes that must be retrieved. This must not exceed the maximum buffer size (currently, this is 4Kb).
Notes

If an application attempts to read more data than has actually arrived on the socket, the entire bshell blocks until the number of bytes specified has been received. It is the responsibility of the calling program to ensure that it never calls sock.recv() for more data than can be expected.

If an application calls sock.recv() before data is available on the socket, the application is put into a sleeping state until data arrives. When data subsequently arrives, the program resumes and sock.recv() returns the data.

Return values

>0	success; the number of bytes retrieved is returned (this is always the same number
as specified by num.bytes)
  0	EOF; the other end of the socket has been closed by its owner process
 -1	error; the predefined variable e contains the error number

When the return value is 0 or -1, the application must close the local socket by calling sock.close().

Context

Bshell function.

Related help topics

    Interprocess communication (cross-platform): overview
    Interprocess communication (cross-platform): synopsis


sock.send()

Syntax

long sock.send( long socket, string data, long num.bytes )

Description

You use sock.send() to place data in the send buffer of a connected socket. The data is automatically transferred on the socket when the buffer is full. But you can also call sock.flush() to transfer the data on the socket.

Arguments

socket	The file descriptor of the local socket, as returned by sock.connect() or sock.accept().
data	This points to the buffer where the data must be stored.
num.bytes	This specifies the number of bytes that must be sent. This must not exceed the maximum buffer size (currently, this is 4Kb).
Notes

When the transport system has insufficient buffer space to hold the data to be transmitted, sock.send() blocks the entire bshell until sufficient space is available. So, be careful not to overflow a receiving program by sending excess data.

Return values

>0	success; the number of bytes sent is returned (this must always be the same number
as specified by num.bytes)
 -1	error; the predefined variable e contains the error number

When the return value is -1, the application must close the local socket by calling sock.close().

Context

Bshell function.

Related help topics

    Interprocess communication (cross-platform): overview
    Interprocess communication (cross-platform): synopsis


Interprocess communication (operating-system level): overview
Interprocess communication (OS level): overview

These functions enable BAAN processes in different bshells to communicate with each other. On UNIX platforms you can use both the message queue and pipe mechanisms. On Windows NT platforms you can currently use only message queues.

Message queues

With the *.message functions, BAAN processes in different bshells can communicate with each other by means of UNIX message queues or NT mailslots (referred to here as mailboxes). A process can create new mailboxes, connect to existing mailboxes, and read from and write to those mailboxes.

Processes use the open.message() function both to create a new mailbox and to connect to an existing mailbox. The arguments of the open.message() function include a project number and the name of a file that is readable by all processes that want to use the mailbox. The project number and some attribute of the specified file are used internally to generate a numeric key that uniquely identifies the mailbox. All processes that want to use the same mailbox must generate the same key, so they must call open.message() with the same project number and file name arguments.

Once a process has connected to a particular mailbox, it can write to it and read from it by using the send.message() and recv.message() functions. When there is no further use for a particular message queue, you must explicitly destroy it by calling close.message().

On UNIX platforms, the mailbox functions can use the UNIX message queue ID instead of the mailbox key to address a particular mailbox. To do this, all functions must specify 1 in the optional fast argument. Using the UNIX message queue ID has both advantages and disadvantages. For example:

•	The UNIX system call to convert the mailbox key to a message queue ID (msgget()) is called only once – that is, during open.message(). It is not called during send.message(), recv.message(), or close.message(). So, the load on the UNIX system is reduced.

•	You cannot use a message queue key that was not returned by open.message().

•	Some errors, such as a removed message queue, can be difficult to detect.

On Windows NT, only the bshell that created a certain queue can read from this queue . So, multiple readers reading messages from the same message queue does not work on Windows NT, nor the situation where one process creates a queue and tells another process to read from this queue.

There is no such restriction on the write-side (any process can write to any queue).

Please use mailboxes in such a way that it works on both UNIX and Windows NT!

Pipes

On UNIX platforms, the bshell can use unnamed pipes to communicate with an external UNIX process started by the same bshell.

On Windows NT, this has not been implemented in the bshell.

Related help topics

    Interprocess communication (OS level): synopsis
    Interprocess communication (bshell):  overview


Interprocess communication (operating-system level): synopsis
Interprocess communication (OS level): synopsis

Message queues

void	close.message	( long key [, long fast] )
long	open.message	( long project, string name$, long action    [, long fast] )
long	recv.message	( long key, long sender.key, long time,    ref string message$ [, long fast] )
long	send.message	( long dest.key, long sender.key,    string message$ [, long fast] )
Pipes

long	pipe.clearerr	( long pipe_id )
long	pipe.close	( long pipe_id )
long	pipe.eof	( long pipe_id )
long	pipe.error	( long pipe_id )
long	pipe.flush	( long pipe_id )
long	pipe.gets	( ref string line(80), long nr_of_bytes,    long pipe_id )
long	pipe.open	( string pathnm(128), string openmode(2) )
long	pipe.puts	( string line(80), long pipe_id )
long	pipe.read	( ref string buffer(1024), long nr_of_bytes,    long pipe_id )
long	pipe.write	( string buffer(1024), long nr_of_bytes,    long pipe_id)
Related help topics

    Interprocess communication (OS level): overview


close.message()

Syntax

void close.message( long key [, long fast] )

Description

This removes the specified mailbox. All messages in the mailbox are also automatically removed.

Arguments

key	The mailbox key, as returned by open.message().
fast	Set this optional argument to 1 if you are using the UNIX message queue ID instead of the mailbox key to identify the mailbox.
Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


open.message()

Syntax

long open.message( long project, string name$, long action [, long fast] )

Description

Use this to create a new mailbox or to connect to an existing mailbox. You must call this function before you can read from or write to the mailbox.

Arguments

project	A number in the range 1 to 255 that indicates the project to which the mailbox belongs.
name$	This identifies a particular mailbox within the specified project. The argument must contain the name of a file that can be read by all processes that want to use the mailbox.  The function uses the specified project number and some attribute of the specified file to generate a mailbox key that uniquely identifies the mailbox. The contents of the file are not used or changed by the function. Note that within a project, the specified file must be clearly associated with a particular mailbox.
action	This argument can have one of the following values: 0 If the mailbox does not already exist, a new one is created. 1 This is similar to 0, except that instead of using a file name specified in name$, the system creates a unique file name ("$BSE/TMP/PostB<pid>").  When specifying this option, specify name$ as an empty string (""). 2 If the mailbox does not already exist,  a new one is not created.
fast	Set this optional argument to 1 if you are using the UNIX message queue ID instead of the mailbox key to identify the mailbox.
Return values

This returns a unique key for the opened mailbox. It returns -1 if an error occurs (the predefined variable e contains the error number).

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.clearerr()

Syntax

long pipe.clearerr( long pipe_id )

Description

This resets the error and end-of-file indicators on the specified pipe.

Arguments

pipe_id	The pipe ID, as returned by pipe.open().
Return values

 0	success
-1	error; most probably no connected stream on pipe_id

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.close()

Syntax

long pipe.close( long pipe_id )

Description

This clears any buffers associated with the specified pipe and closes the file. Buffers allocated by the standard input/output system are also cleared. Note that pipe.close() is performed automatically when the process exits.

Arguments

pipe_id	The pipe ID, as returned by pipe.open().
Return values

   -1	error
   -2	child process is not allowed to read/write anymore
>=0	exit value of child process (0 is OK)

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.eof()

Syntax

long pipe.eof( long pipe_id )

Description

This checks the end-of-file indicator on the specified pipe. Note that the end-of-file indicator lasts until the pipe is closed, unless you explicitly clear it by calling pipe.clearerr().

Arguments

pipe_id	The pipe ID, as returned by pipe.open().
Return values

<>0	end-of-file indicator read on specified pipe
    0	end-of-file indicator not read

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.error()

Syntax

long pipe.error( long pipe_id )

Description

This checks the error indicator on the specified pipe to determine whether an error has occurred when reading or writing to the pipe. Note that the error indicator lasts until the pipe is closed, unless you explicitly clear it by calling pipe.clearerr().

Arguments

pipe_id	The pipe ID, as returned by pipe.open().
Return values

<>0	error has occurred when reading or writing to the pipe
     0	no error has occurred

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.flush()

Syntax

long pipe.flush( long pipe_id )

Description

This writes any buffered data associated with a pipe to the related file. The stream remains open.

Arguments

pipe_id	The pipe ID, as returned by pipe.open().
Return values

 0	success
-1	error; most probably no connected stream on pipe_id

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.gets()

Syntax

long pipe.gets( ref string line(80), long nr_of_bytes, long pipe_id )

Description

This reads a maximum of one line from the specified pipe.

Arguments

line	This stores the characters read from the pipe.
nr_of_bytes	This specifies the maximum number of bytes to be read from the pipe. The function stops reading when it encounters a newline character or when it has read the number of bytes specified by this argument, whichever comes first.
pipe_id	The pipe ID, as returned by pipe.open().
Return values

 0	success
-1	error; most probably no connected stream on pipe_id

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.open()

Syntax

long pipe.open( string pathnm(128), string openmode(2) )

Description

This creates a UNIX process with the specified name and links an input and/or output stream to it. It returns a pointer to the pipe; this is used to identify the pipe in subsequent operations.

Arguments

pathnm	The path name for the UNIX process.
openmode	Use this to specify whether the pipe is opened for reading, writing, or both. The possible values are: "r" create for reading "w" create for writing "rw" create for reading and writing
Return values

>=1	success; a pointer to the pipe is returned
  <1	error; that is, the negative value of the system error (for example, for a permission error,
the system returns 13 and the function returns -13, or if the internal table is full, the function
returns -EAGAIN).

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.puts()

Syntax

long pipe.puts( string line(80), long pipe_id )

Description

This writes data to the specified pipe. It automatically appends a newline character to the data.

Arguments

line	The data to be written to the pipe.
pipe_id	The pipe ID, as returned by pipe.open().
Return values

 0	success
-1	error; most probably no connected stream on pipe_id

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.read()

Syntax

long pipe.read( ref string buffer(1024), long nr_of_bytes, long pipe_id )

Description

This reads a specified number of bytes from the specified pipe.

Arguments

buffer	This stores the characters read from the pipe.
nr_of_bytes	This specifies the maximum number of bytes to be read from the pipe. The function stops reading when it has read the number of bytes specified by this argument or when it reaches the end of the file, whichever comes first.
pipe_id	The pipe ID, as returned by pipe.open().
Return values

 >0	the number of bytes read
   0	end-of-file
  -1	error; most probably no connected stream on pipe_id

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


pipe.write()

Syntax

long pipe.write( string buffer(1024), long nr_of_bytes, long pipe_id )

Description

This appends a specified number of bytes to the specified pipe.

Arguments

buffer	This stores the characters that must be written to the pipe.
nr_of_bytes	This specifies the maximum number of bytes to be written to the pipe. The function stops writing to the pipe when it has written this number of bytes or when it reaches the end of the file, whichever comes first.
pipe_id	The pipe ID, as returned by pipe.open().
Return values

 >0	the number of bytes written
   0	end-of-file
  -1	error; most probably no connected stream on pipe_id

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


recv.message()

Syntax

long recv.message( long key, long sender.key, long time, ref string message$ [, long fast] )

Description

This reads a message from the specified mailbox. The process must previously have connected to the mailbox by calling open.message().

Arguments

key	The mailbox key, as returned by open.message().
sender.key	Messages sent with the send.message() function have an associated sender key which identifies the sender. To retrieve the next message from a particular sender, specify that sender's key here. Otherwise specify zero – in this case the function retrieves the next message in the mailbox, regardless of the sender.
time	Use this to specify the maximum time that the function must wait before returning. If you set this to -1, the function waits until a message arrives in the mailbox.
message$	This stores the retrieved message.
fast	Set this optional argument to 1 if you are using the UNIX message queue ID instead of the mailbox key to identify the mailbox.
Return values

This returns the sender key. It returns -1 if an error occurs (the predefined variable e contains the error number).

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


send.message()

Syntax

long send.message( long dest.key, long sender.key, string message$ [, long fast]) )

Description

This stores a message in the specified mailbox. The process must previously have connected to the mailbox by calling open.message().

Arguments

dest.key	The mailbox key, as returned by open.message().
sender.key	This is a unique key that identifies the sender of the message. Processes reading from the mailbox can use this filter out messages from other senders.
message$	This is the message to be sent to the mailbox.
fast	Set this optional argument to 1 if you are using the UNIX message queue ID instead of the mailbox key to identify the mailbox.
Return values

This returns 0 when successful. Otherwise it returns an error number.

Context

Bshell function.

Related help topics

    Interprocess communication (OS level): overview
    Interprocess communication (OS level): synopsis


Mathematical operations:  overview

Use these functions to perform mathematical operations of various types – for example:

•	to perform logarithmic and square root calculations

•	to perform geometrical calculations (cosine, sine, tangent, and so on)

•	to perform rounding operations

•	to compare values and return the maximum or minimum

•	to set variables to their maximum or minimum values

•	to calculate the absolute value of numeric expressions

•	to convert floating point expressions to integer values

•	to compare the values of two doubles to determine if they are equal.

Related help topics

    Mathematical operations:  synopsis


Mathematical operations:  synopsis

double	abs	( num_expr )
double	acos	( double x )
double	asin	( double x )
double	atan	( double x )
double	cos	( double x )
double	cosh	( double x )
long	double.cmp	( double double1, double double2, double    tolerance )
double	exp	( double x )
double	format.round	( double value, string format [,long mode] )
long	int	( double_expr )
double	log	( double x )
double	log10	( double x )
long	lpow	( long x, long y )
double	max	( double x, double y )
double	min	( double x, double y )
double	pow	( double x, double y )
double	round	( double value, long diga, long mode )
void	set.fmax	( variable [, string domain_name(.)] )
void	set.fmin	( variable [, string domain_name(.)] )
void	set.max	( variable [, string domain_name(.)] )
void	set.min	( variable [, string domain_name(.)] )
double	sin	( double x )
double	sinh	( double x )
double	sqrt	( double x )
void	table.round	( [field, field, ..., "table", "table", ...] )
double	tan	( double x )
double	tanh	( double x )
Related help topics

    Mathematical operations:  overview


abs()

Syntax

double abs( num_expr )

Description

This returns the absolute value of the specified numeric expression. The expression can be of type integer or floating point.

Return values

The absolute value of the numeric expression.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


acos()

Syntax

double acos( double x )

Description

This computes the arc cosine of x. The value of x must be in the range [-1, 1].

Return values

The arc cosine of x, expressed as a floating point number in the range [0, π] radians.

Context

Bshell process.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


asin()

Syntax

double asin( double x )

Description

This computes the arc sine of x. The value of x must be in the range [-1, 1].

Return values

The arc sine of x, expressed as a floating point number in the range [-π/2, π/2] radians.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


atan()

Syntax

double atan( double x )

Description

This computes the arc tangent of x.

Return values

The arc tangent of x, expressed as a floating point number in the range [-π/2, π/2] radians.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


cos()

Syntax

double cos( double x )

Description

This computes the cosine of x, in radians. The x argument can be a long or a double.

Return values

The cosine of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


cosh()

Syntax

double cosh( double x )

Description

This computes the hyperbolic cosine of x.

Return values

The hyperbolic cosine of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


double.cmp()

Syntax

long double.cmp( double double1, double double2, double tolerance )

This compares two doubles to determine whether or not their values are equal.

Arguments

double1	A double value.
double2	A double value.
tolerance	Specifies a tolerance value for the function. If the difference between the two doubles is less than this value, the doubles are considered equal. Do not use a tolerance of 0.
Return values

 0 	the difference between the doubles is less than the tolerance
-1	double1 is less than double2 (the difference is greater than the tolerance)
 1	double1 is greater than double2 (the difference is greater than the tolerance)

Context

Bshell function.

Example

double doub1, doub2

if not double.cmp( doub1, doub2, 0.0001 ) then

| the two doubles are equal

.....

endif

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


exp()

Syntax

double exp( double x )

Description

This returns the exponent of x. That is, it computes the value of the mathematical constant e (2.7182818) raised to the power of x.

Return values

The exponent of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


format.round()

Syntax

double format.round ( double value, string format [,long mode] )

Description

The rounds a value according to a specified format.

Arguments

value	The value to be rounded.
format	The format for the returned value. For example %10.5f or %5.10g. See sprintf$().
mode	This argument is optional. If it is not included, the default mode is 1. 0: truncate (for example, both 1.5 and 1.49 are rounded down to 1) 1: normal round (for example, 1.5 is rounded up to 2; 1.49 is rounded down to 1) 2: round up (for example, both 1.5 and 1.49 are rounded up to 2)
Return values

The rounded value.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


int()

Syntax

long int ( double_expr )

Description

This converts the result of a floating point expression to an integer value. It returns only the integer portion of the result.

If the result of double_expr is positive, it is incremented by 0.0000001 before conversion. If the result is negative, it is decremented by 0.0000001 before conversion. This is done to avoid rounding problems.

Note

Assigning a floating point value to a variable of type long also converts a floating point value to an integer. But, in this case, the value is not incremented or decremented before truncation.

Return values

The integer result.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


log()

Syntax

double log( double x )

Description

This computes the natural logarithm of x. The value of x must be greater than zero.

Return values

The log of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


log10()

Syntax

double log10( double x )

Description

This computes the base 10 logarithm of x. The value of x must be greater than zero.

Return values

The base 10 log of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


lpow()

Syntax

long lpow( long x, long y )

Description

This computes the value of x raised to the power of y. The y argument must be positive.

Return values

The value of x to the power of y.

If y is zero, the return value is always 1.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


max()

Syntax

double max( double x, double y )

Description

This compares the values of the two arguments and returns whichever is the greatest. The arguments can be of type long or double or can contain any numeric expression.

Return values

The greatest of the two values.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


min()

Syntax

double min( double x, double y )

Description

This compares the values of the two arguments and returns whichever is the smallest. The arguments can be of type long or double or can contain any numeric expression.

Return values

The lesser of the two values.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


pow()

Syntax

double pow( double x, double y )

Description

This computes the value of x raised to the power of y. If x is zero, y must be positive. If x is negative, y must be an integer.

 Return values

The value of x to the power of y.

If y is zero, the return value is always 1.0.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


round()

Syntax

double round( double value, long diga, long mode )

Description

This rounds a given value to a specified number of decimal places.

Arguments

value	The value to be rounded.
diga	The number of decimal places to which value is to be rounded.
mode	0 truncate (for example, both 1.5 and 1.49 are rounded down to 1) 1 normal round (for example, 1.5 is rounded up to 2; 1.49 is rounded  down to 1) 2 round up (for example, both 1.5 and 1.49 are rounded up to 2)
Return values

The rounded value. Or the original value (value) if an error occurs.

Because the return value is of type double, the number of digits after the decimal sign is always 6. For example, round(1.345, 2, 1) returns 1.350000.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


set.fmax(), setfmin(), set.max(), set.min()

Syntax

void set.fmax( variable [, string domain_name(.)] )

void set.fmin( variable [, string domain_name(.)] )

void set.max( variable [, string domain_name(.)] )

void set.min( variable [, string domain_name(.)] )

Description

These set a specified variable to its maximum or minimum value. Use set.max() and set.min() for standard variables. Use set.fmax() and set.fmin() for multibyte strings.

Arguments

variable	The name of the variable to be set. This can be a single variable or an array.
domain	This argument is optional. It specifies the domain name of the variable. If this argument is included, the variable is set to the maximum or minimum value of the domain.
Notes

This table shows the maximum and minimum values of variable types supported by BaanERP.

Type	Minimum value	Maximum value
byte/enumerated	0	127
integer	-32768	32767
long/set/date/text/time	-2147483648	2147483647
float	-999999999999.9e20	999999999999.9e20
double	-999999999999.9e64	999999999999.9e64
string[1]	chr(1)	"~" (max length 1024)
enumerated/set	1	depends on set definition
date	0	3652059
time	0	2147483647
multibyte string	configurable using the TSS dictionary programs (session: Maintain Locale Data)	configurable using the TSS dictionary programs (session: Maintain Locale Data)
Context

Bshell functions.

Example

long value

set.min( value )	| value contains -2147483648

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


sin()

Syntax

double sin( double x )

Description

This computes the sine of x, in radians. The x argument can be a long or a double.

Return values

The sine of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


sinh()

Syntax

double sinh( double x )

Description

This computes the hyperbolic sine of x.

Return values

The hyperbolic sine of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


sqrt()

Syntax

double sqrt( double x )

Description

This computes the non-negative square root of x. The x argument must not be less than zero. It can be of type long or double.

Return values

The non-negative square root of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


table.round()

Syntax

void table.round( [field, field, ..., "table", "table", ...] )

Description

This rounds the values in certain tables and table fields according to parameters defined in the domain definition in the data dictionary.

Arguments

(no arguments)	The function rounds all fields of the main table.
field [, field] …	The names of one or more table fields. The function rounds the values in all specified fields.
table [, table] …	The names of one or more tables. The function rounds all fields in the specified tables. You must specify table names within quotes – for example, “tpctst999”.
Note

You can specify any combination of tables and fields, in any order.

Context

Bshell function.

Examples

table.round()	| Rounds all fields of main table

table.round(pctst999.price, "tpctst888", pctst999.value)

| Rounds the two specified fields and all fields of the
                  specified table

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


tan()

Syntax

double tan( double x )

Description

This computes the tangent of x, in radians. The x argument can be a long or a double.

Return values

The tangent of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


tanh()

Syntax

double tanh( double x )

Description

This computes the hyperbolic tangent of x.

Return values

The hyperbolic tangent of x.

Context

Bshell function.

Related help topics

    Mathematical operations:  overview
    Mathematical operations:  synopsis


Memory operations: overview and synopsis

Overview

Use these functions to perform various memory operations. For example:

•	to allocate and deallocate memory at run time

•	to compare the values in two memory spaces

•	to copy data from one memory space to another

•	to set the content of a memory space.

Synopsis

long	alloc.mem	( ref variable, long dim1 [, long dim2, ...] )
void	array.info	( void var, ref long nr.dims, ref long   dim.array(4) )
long	cmp.mem	( var1, var2 [, long count] )
void	copy.mem	( ref destination, source [, long count] )
void	free.mem	( variable )
long	set.mem	( ref destination, source [, long count] )


alloc.mem()

Syntax

long alloc.mem( ref variable, long dim1 [, long dim2, ...] )

Description

This allocates memory space to the specified variable at run time (up to a maximum of 5Mb). The variable can be a string or an array (of any type). It must be declared as BASED. With multi-dimensional arrays, each dimension must be initialized to 1 at declaration. Once alloc.mem() has allocated memory for a variable, that variable behaves in the same way as any other variable.

When you call alloc.mem() a second time for the same variable, information already present is retained, but the variable is reallocated to a different part of memory. This is relevant only if you want to increase or decrease the memory space assigned to an array. Because the contents of array elements are contiguous in memory, you can change only the number of elements in the array (the first index in the case of longs and doubles; the second index in the case of strings). Changing the size of array elements during reallocation causes loss of information.

Note

Remember to use free.mem() to deallocate memory space when it is no longer required.

Return values

 0	success
-1	insufficient memory available

Context

Bshell function.

Example

long     i, j, k

string   c(1)     based

string   st(1,1)  based

double   d(1,1,1) based

alloc.mem(c, 10)        | Allocate a string with length 10

alloc.mem(st, 20, 5)    | Allocate 5 strings of length 20

alloc.mem(d, 2, 5, 6)   | Allocate an array of doubles with 3 dimensions

for i=1 to 2

for j=1 to 5

for k=1 to 6

d(i,j,k) = k*j

endfor

endfor

endfor

alloc.mem(d, 4, 5, 6)   | Reallocate array of doubles

alloc.mem(st, 20, 8)    | Reallocate 8 strings

Related help topics

    Memory operations: overview and synopsis


array.info()

Syntax

void array.info( void var, ref long nr.dims, ref long dim.array(4) )

Description

This returns the number of dimensions in a specified array variable and the size of each dimension.

Arguments

var	The name of the array variable.
nr.dims, dim.array	These return the number of dimensions in the array and the size of each dimension. If var specifies a non-array variable, nr.dims returns 0 and dim.array returns dim.array(1) = 0. If var specifies a string, such as s1(10), nr.dims returns 1 and dim.array returns dim.array  = 10.
Example

long    a3(3,5,7)

string  s3(3,5,7)

long    nr.dims

long    dim.array(4)

string  b4(1,1,1,1) based

array.info( a3, nr.dims, dim.array )

| Returns:

|  nr.dims = 3

|  dim.array(1) = 3

|  dim.array(2) = 5

|  dim.array(3) = 7

array.info( s3, nr.dims, dim.array )

| Returns:

|  nr.dims = 3

|  dim.array(1) = 3

|  dim.array(2) = 5

|  dim.array(3) = 7

array.info( b4, nr.dims, dim.array )

| Returns:

|  nr_dims = 4

|  dim.array(1) = 0

|  dim.array(2) = 0

|  dim.array(3) = 0

|  dim.array(4) = 0

Context

Bshell function.

Related help topics

    Memory operations: overview and synopsis


cmp.mem()

Syntax

long cmp.mem( var1, var2 [, long count] )

Description

This compares the values of two variables or arrays. By default, the values are compared for the length of the shortest argument. If you specify the optional count argument, the function compares the first count digits or characters of both arguments.

Return values

The return values depend on the types of the variables.

Variables are of different types:

1

Variables are longs or doubles:

0	values are equal
1	values are different

Variables are strings or arrays of type long, double, or string:

<0	first argument is less than second
=0	arguments are equal
>0	first argument is greater than second

Context

Bshell function.

Example

long l_arr(2,2), lng_arr(3,5), ret

fill_long_arrays()

ret = cmp.mem( lng_arr, l_arr )  | The first 4 elements are checked

if ret = 0 then

message( "values are equal" )

else

if ret > 0 then

message( "First array greater than second" )

else

message( "First array less than second" )

endif

endif

Related help topics

    Memory operations: overview and synopsis


copy.mem()

Syntax

void copy.mem( ref destination, source [, long count] )

Description

This copies the memory space from the source argument to the destination argument. By default, the total length of source is copied. But, if the destination argument is shorter than the source argument, then source is truncated. Use the optional count argument to copy a specified number of bytes only.

You can use this function to copy single variables or entire arrays. You cannot copy variables of different types. It you attempt to do this, the destination argument remains unchanged.

Context

Bshell function.

Example

long i,j

long src(5,5)

long des(3,3)

for i=1 to 5

for j=1 to 5

src(i,j)=i*j

endfor

endfor

copy.mem(des,src)    | des contains the first 9 elements of src

Related help topics

    Memory operations: overview and synopsis


free.mem()

Syntax

void free.mem( variable )

Description

This deallocates memory space previously allocated to the specified variable by alloc.mem(). The freed memory becomes available for another allocation. The variable cannot be used again after deallocation, unless it is reallocated memory space again using alloc.mem().

Context

Bshell function.

Related help topics

    Memory operations: overview and synopsis


set.mem()

Syntax

long set.mem( ref destination, source [, long count] )

Description

The stores the value of source in the destination argument. By default, the value of source is repeated in destination until the latter is completely filled. Use the optional count argument to repeat the value of source a specific number of times only. Elements in the destination argument which are not overwritten remain unchanged.

Return values

 0	success
-1	error

Context

Bshell function.

Example

| To set a string array to spaces

string string_array(20, 5, 5)

long ret

ret = set.mem( string_array, "" )

| To store a long in a string

string str1(20)

long ret

ret = set.mem( str1, "10", 5 )

| str1 now contains "1010101010"

Related help topics

    Memory operations: overview and synopsis


Message handling: overview and synopsis

Overview

Use these functions for handling status messages, error messages, and other messages that are output to the screen or to a log file.

The status area of 4GL forms

4GL programs (except type 4 programs) usually display a status area consisting of four status fields. The standard program uses all four fields. 4GL programs can display messages in the first two fields (see the status functions below).

Field	Length	Normal contents
1	15	application dependent/database action
2	15	field type during input / zoom
3	3	Caps Lock key status
4	3	Num Lock key status
Synopsis

void	clean.mess	( )
long	dal.count.error.messages	( )
long	dal.get.error.message	( ref string msg )
long	dal.get.first.error.message	( ref string msg, ref string code )
void	dal.reset.error.messages	( long amt )
void	dal.set.error.message	( string mess.or.code [, arg ...] )
string	form.text$	( string messcode(14) [, string    language code ] )
void	mess	( string messcode(14), long mode     [, arg, ...] )
void	message	( string mess_str(.) [, arg, ...] )
void	set.input.error	( string messcode(14) [, ...] )
void	status.del	( )
void	status.field	( long fieldnr, string strg(15) )
void	status.mess	( string strg(15) )
void	status.off	( [long mode] )
void	status.on	( [long mode] )


clean.mess()

Syntax

void clean.mess()

Description

This removes a message that was displayed by using the mess() function with its mode argument set to 0.

Context

3GL library function.

Related help topics

    Message handling: overview and synopsis


dal.count.error.messages()

Syntax

long dal.count.error.messages()

Description

This returns the number of DAL error messages currently in the message buffer.

Context

DAL function.

Return value

The number of messages in the message buffer.

Related help topics

    Message handling: overview and synopsis


dal.get.error.message()

Syntax

long dal.get.error.message(ref string msg)

Description

This retrieves the next DAL error message from the message buffer. It retrieves the messages on a last-in-first-out (LIFO) basis.

Return value

The number of messages that remain in the message buffer.

Context

DAL function.

This function is provided for use by external applications. It is not normally used in DAL or UI scripts.

Related help topics

    Message handling: overview and synopsis


dal.get.first.error.message()

Syntax

long dal.get.first.error.message(ref string msg, ref string code)

Description

This retrieves the first available DAL error message from the message buffer, together with the message code. It retrieves the messages on a first-in-first-out (FIFO) basis. The message is removed from the buffer.

Note that FIFO message retrieval is slightly slower than LIFO message retrieval.

Return value

The number of messages that remain in the message buffer.

Context

DAL function.

Related help topics

    Message handling: overview and synopsis


dal.reset.error.messages()

Syntax

void dal.reset.error.messages(long amt)

Description

This clears DAL error messages from the message buffer.

Arguments

amt	0 clear the entire buffer >0 clear all but the specified number of messages; the most recent  messages are the messages that are cleared  <0 clear the specified number of the most recent messages
Context

DAL function.

Examples

If there are 6 messages in the message buffer, the following examples have the same result:

dal.reset.error.messages(-4)	| clears the 4 most recent messages

dal.reset.error.messages(2)	| clears all but the 2 oldest messages

Related help topics

    Message handling: overview and synopsis


dal.set.error.message()

Syntax

void dal.set.error.message(string mess.or.code [, arg ...])

Description

Use this to set an error message to be displayed by the standard program or by external applications when a DAL hook returns a negative value.

Arguments

mess.or.code	Specifies either the data dictionary code for the message or a literal string. In the latter case, the value of mess.or.code must start with the at sign [@]. Note that using a literal string makes the script language dependent.
arg ....	Use these optional arguments to pass arguments to the mess.or.code variable.
Context

DAL function.

Related help topics

    Message handling: overview and synopsis


form.text$()

Syntax

string form.text$( string messcode(14) [, string language_code ] )

Description

This retrieves a message from the data dictionary. It is used for constructing strings with parameter substitution. For messages to the screen, use mess().

Arguments

messcode	The message code of the required message.
language_code	The language code. If you do not specify a language code, the user language is used. Otherwise the message with the specified language is retrieved (if available).
Return value

The message string.

Context

3GL library function.

Example

| Suppose there is a message code "pcgen00016" in the data

| dictionary with the text "Error %d in file %s".

string error(80)

long lfn_log

lfn_log = seq.open("./err.log", "a")  	| Open for adding text

error = form.text$("pcgen00016")      	| error now contains
| "Error %d in file %s"

error = sprintf$(error, e, filename$) 	| error now contains, for example

| "Error 13 in file tttmir001"

seq.puts( error, lfn_log )	          	| writes error to file "err.log"

seq.close( lfn_log )

Related help topics

    Message handling: overview and synopsis


mess()

Syntax

void mess( string messcode(14), long mode [, arg, ...] )

Description

This retrieves a message from the data dictionary and displays it on screen. Using this function makes your program script language independent.

Arguments

messcode	The message code (including the package code). The language code of the user is automatically added. Both the message code and the user language must be available in the data dictionary.
mode	This specifies how the message can be removed:
	1	The message is displayed in a separate window and the user must click a button in that window to remove the message.
	0	The message is displayed on the status bar. The user cannot remove the message. It remains until removed by the clean.mess() function.
arg ...	The message string in the data dictionary can contain format characters for parameter substitution. The values which must be substituted are specified in the 3rd, 4th, ... arguments of the function. The number of these arguments is variable.
Note

In 3GL scripts, the variable graphical.mode must be set to 1 if you want the message to be displayed in a separate window.

Context

3GL library function.

Example

| Suppose there is a message code "pcgen00016" in the data

| dictionary with the text "Error %d in file %s"

mess("pcgen00016",1,e,filename$)   | Prompt for ENTER

mess("pcgen00016",0,e,filename$)   | Display message and continue

                                   | (if there is a current form)

Related help topics

    Message handling: overview and synopsis


message()

Syntax

void message( string mess_str(.) [, arg, ...] )

Description

This displays the specified message string on screen.

In character-based windows, the message is displayed on the message line of the window. The message "PRESS <RETURN>" is displayed at position 61 of that line. If mess_str is longer than 60 characters, a window is created at the foot of the screen to display the message. In graphical forms, a separate window is created.

The system removes the message when the user presses ENTER or clicks a button.

Arguments

mess_str	The message string to be displayed. This can contain format characters for parameter substitution. For details about formatting a string see the sprintf().
arg ...	The message string can contain format characters for parameter substitution. The values which must be substituted are specified in the 2nd, 3rd, ... arguments of the function. The number of these arguments is variable.
Note

Using message() makes your program script language dependent. If you require language independency, use mess() instead.

Context

3GL library function.

Example

| Suppose the user enters a non-existent code 123 (from

| pctst999.item) and you want to display the message:
| "Code (123) not found."

message("Code (123) not found.")

| However it is better to use parameter substitution:

message("Code (%d) not found.", pctst999.item)

| The following construction gives the message "Error 13 in file
| tpctst999", for example:

message("Error %d in file %s", e, filename$)

Related help topics

    Message handling: overview and synopsis


set.input.error()

Syntax

void set.input.error( string messcode(14) [, arg, ...] )

Description

This causes the standard program to display the specified error message and to force input again in the same input field. If you specify an empty string, no error message is displayed.

Arguments

messcode	The message code of the required message. This must be defined in the data dictionary. This argument can contain format characters for parameter substitution.
arg ...	The messcode argument can contain format characters for parameter substitution. The values which must be substituted are specified in the 2nd, 3rd, ... arguments of the function. The number of these arguments is variable.  For details about formatting a string see the sprintf().
Notes

You can use set.input.error() only in check.input event sections of a 4GL script. The error message is displayed after the entire section has been executed. Consequently, you cannot display two error messages with this function. The predefined variable stp.check.input.error indicates whether set.input.error() has been called.

Before a choice.update.db (except at delete) section, all check.input sections of all fields are executed. If one error is set with set.input.error(), the remaining sections are not executed. In a type 4 program, which does not support choice.update.db, you can call the function check.all.input() in a before.choice section. With the predefined variable before.update.check (read-only), you can control if the input check is executed before update or during input.

Context

4GL library function.

You can use this function only in 4GL scripts, and only in check.input subsections of those scripts.

See also

dal.set.error.message

Example

field.pctst900.item:

check.input:

if before.update.check then

set.input.error("pctsts0001")      | before update

else

set.input.error("pctsts0002", e)   | during input

endif

Related help topics

    Message handling: overview and synopsis


status.del()

Syntax

void status.del()

Description

This clears the first status field in the status area.

Context

3GL library function.

Related help topics

    Message handling: overview and synopsis


status.field()

Syntax

void status.field( long fieldnr, string strg(15) )

Description

This displays the specified message string in a specified status field of a 4GL form.

In previous BAAN releases, there were 5 status fields, numbered 1to 5. Status fields 1 to 4 in the current release correspond to fields 2 to 5 in previous releases. This function uses the old numbering system. For example:

status.field( 2, "replace" )   | displays message in first field

status.field( 3, "replace" )   | displays message in second field

Note

This function is supported for backward compatibility only. To display a message in the first status field, use status.mess() instead.

Context

Bshell function.

Related help topics

    Message handling: overview and synopsis


status.mess()

Syntax

void status.mess( string strg(15) )

Description

This displays the specified message in the first status field of a 4GL form.

Context

3GL library function.

Related help topics

    Message handling: overview and synopsis


status.off()

Syntax

void status.off( [long mode] )

Description

This disables the status line on a 4GL form. The line remains on the screen, but it does not display any subsequent status messages.

Arguments

mode	By default, the status line is disabled for the current process only. To disable the status line for all processes of the current main window, set this optional argument to 1.
Context

Bshell function.

Related help topics

    Message handling: overview and synopsis


status.on()

Syntax

void status.on( [long mode] )

Description

This enables the status line on a 4GL form after it has been disabled by status.off().

Arguments

mode	By default, the status line is enabled for the current process only. To enable the status line for all processes of the current main window, set this optional argument to 1.
Context

Bshell function.

Related help topics

    Message handling: overview and synopsis


Multibyte strings: overview and synopsis

Overview

Use these functions for handling multibyte strings.

The characters sets used in some parts of the world require more than a single byte per character. BAAN software provides multibyte character support via the BAAN Super Set (TSS). TSS is a super set of both ASCII and multibyte character sets. In TSS, a character can occupy from one to four bytes, as required. Multibyte characters always start with the escape code 0x9b. So they can always be recognized within a string.

See also String operations.

Synopsis

string	mb.cast$	( string_expr )
string	mb.cast.to.str$	( string_expr )
long	mb.char	( long charvalue )
long	mb.char.info	( string ch$ )
long	mb.display	( string_expr, ref string substr$, long space,    [, long flags] )
long	mb.export$	( string target$, string source$ [, long setid ] )
long	mb.ext.clean$	( ref string ext.string )
long	mb.hasbidi	( string_expr )
long	mb.import$	( string target$, string source$ [, long setid ] )
long	mb.isbidi	( )
long	mb.isbidi.language	( string lang )
string	mb.locale.info	( long info_flag )
string	mb.localename$	( )
string	mb.long.to.str$	( long charvalue )
long	mb.nsets	( )
string	mb.rev$	( string_expr [, long flags] )
long	mb.scrpos	( string_expr, long pos )
long	mb.set.info	( long setid, ref string name, ref string desc,   ref long n_items )
long	mb.strpos	( string_expr, long pos )
long	mb.tss.clean$	( ref string tss.string )
long	mb.type	( string_expr )
long	mb.width	( string_expr )


mb.cast$()

Syntax

string mb.cast$( string_expr )

Description

This converts a specified string to a multibyte string. The content of the string remains the same.

Return values

The multibyte string.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.cast.to.str$()

Syntax

string mb.cast.to.str$( string_expr )

Description

This converts a specified string to a single-byte string. The content of the string remains the same.

Return values

The single-byte string.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.char()

Syntax

long mb.char( long charvalue )

Description

This function tests if a specified character code represents a multibyte character. It is mainly used in conjunction with the next.event() function, which returns a character as a long value.

Return values

2	charvalue is a multibyte character
1	charvalue is an ISO-8859/1 character
0	charvalue is some other key (for example, a function key)

Context

Bshell function.

Example

This example filters out function keys but processes other characters.

long event(EVTMAXSIZE), ch

ch = evt.keypress.key(event)

if mb.char(ch) then

mb.long.to.str$( evt.keypress.key(event) )

| manage characters

endif

Related help topics

    Multibyte strings: overview and synopsis


mb.char.info()

Syntax

long mb.char.info( string ch$ )

Description

This identifies the character set to which a TSS character belongs. It returns the character set ID for the first character in the specified string.

In TSS, it is possible that several characters convert to one internal TSS area (parts of SHIFT-JIS and KANJI_EUC both convert to one command area; that is, JIS). In that case, the function returns the lowest  of the character set IDs. For example, if SHIFT-JIS has the character set code 1, and KANJI-EUC has the code 2, then the function returns 1.

Return values

The ID of the character set for the first character in the specified string. Or -1 if ch$ is an empty string or if the TSS character could not be found in one of the TSS character sets.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.display()

Syntax

long mb.display( string_expr, ref string substr$, long space [, long flags] )

Description

This returns that part of a specified string that fits in a specified display space. The substring is equal to the source string if the source string fits in the display space. If one or more characters do not fit in the display space, a ghost character (default is >) is appended to the substring.

Arguments

string_expr	The source string.
substr$	The returned substring. This ends with a ghost character if some characters of the source string do not fit in the specified display space.
space	The size of the display space for the substring.
flags	These optional flags specify certain criteria for handling the substring. They are particularly useful for working with bidirectional strings.
	TSS_REVERSE	Reverse the substring if the current user environment is bidirectional and if string_expr contains bidirectional characters. The substring is ready for display.
	TSS_FILLOUT	Fill the substring with trailing spaces, so that the width of the string equals the display space. This is the default if no flags are specified.
	TSS_FORCE_REVERSE	Reverse the substring if string_expr contains bidirectional characters. The substring is ready for display.
	TSS_FILTER_ESC	Filter out escape sequences.
	TSS_FILTER_CF	Filter out code features.
Return values

An index to omitted characters if the string is truncated. Otherwise, the length of the string.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.export$()

Syntax

long mb.export$( string target$, string source$ [, long setid ] )

Description

This converts a string from the TSS character set to the external, native character set. By default, the setting of the current locale determines the character set to which the string is converted. Code features in the string are skipped.

Arguments

target$	The converted string. This can be a maximum of 1024 bytes.
source$	The source string that must be converted.
setid	If you do not want to base the conversion on the setting of the current locale, use this optional argument to specify the ID of the TSS character set to be used in the export operation.
Return values

> 0	the number of converted bytes
  -1	the target string was too small to contain the converted string
  -2	an incomplete character was found at the end of the string
  -3	character could not be converted.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.ext.clean$()

Syntax

long mb.ext.clean$( ref string ext.string )

Description

This replaces characters in a specified string with spaces, if those characters cannot be converted from native format to TSS.

Return values

>0	the position of the first character that could not be converted
  0	all characters can be converted.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.hasbidi()

Syntax

long mb.hasbidi( string_expr )

Description

This checks whether a specified string contains at least one bidirectional character. The function works regardless of the current user locale.

Return values

TRUE  	string contains a bidirectional character
FALSE	string does not contain a bidirectional character

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.import$()

Syntax

long mb.import$( string target$, string source$ [, long setid ] )

Description

This converts a string from the external, native character set to the TSS character set. By default, the setting of the current locale determines the native character set from which the string is converted.

Arguments

target$	The converted string. This can be a maximum of 1024 bytes.
source$	The source string that must be converted.
setid	If you do not want to base the conversion on the setting of the current locale, use this optional argument to specify the ID of the TSS character set to be used in the import operation.
Return values

> 0	the number of converted bytes
  -1	the target string was too small to contain the converted string
  -2	an incomplete character was found at the end of the string
  -3	character could not be converted.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.isbidi()

Syntax

long mb.isbidi( )

Description

This checks whether the current environment is a bidirectional one.

Return values

TRUE  	current environment is bidirectional
FALSE	current environment is not bidirectional

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.isbidi.language()

Syntax

long mb.isbidi.language( string lang )

Description

This checks whether the specified language is a bidirectional one. To use the function, you must link to the ttdllbidi library. The function checks the flag ‘%TF@ttaad110.bidi’ in the table ‘%TB@ttaad110’.

Return values

TRUE  	current language is bidirectional
FALSE	current language is not bidirectional

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.locale.info()

Syntax

string mb.locale.info( long info_flag )

Description

This returns information about the current locale.

Arguments

info_flag	Specifies the required information. The possible values are: TSS_GET_LOCALE_NAME returns the locale name TSS_GET_NLS_NAME returns the NLS name TSS_GET_TSS_NAME returns the name of the character set TSS_GET_IFACTOR    returns the internal mb factor TSS_GET_EFACTOR returns the external (database) factor
Return values

A string containing the requested information.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.localename$()

Syntax

string mb.localename$( )

Description

This returns the name of the current locale as defined in the file '$bse/lib/user/u<user>'. The file ‘$BSE/lib/tss_localex.x’  (where x.x is the bshell version) contains all locales that the system supports.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.long.to.str$()

Syntax

string mb.long.to.str$( long charvalue )

Description

This converts a character code to the equivalent string value. It accepts ISO-8859/1 and multibyte character codes only. Do not use it for other characters, such as function keys.

Return values

string 	success
empty string	illegal character code (an error message is logged)

Context

Bshell function.

Example

See mb.char().

Related help topics

    Multibyte strings: overview and synopsis


mb.nsets()

Syntax

long mb.nsets( )

Description

This returns the number of TSS character sets currently defined. This is useful for retrieving character set information using mb.set.info().

Context

Bshell function.

Example

See mb.set.info().

Related help topics

    Multibyte strings: overview and synopsis


mb.rev$()

Syntax

string mb.rev$( string_expr [, long flags] )

Description

This reverses the order of the characters in a specified string.

Arguments

string_expr	The source string.
flags	By default, this function reverses the string, whether or not the current user locale is bidirectional. Use these optional flags to override this default situation: TSS_REVERSE reverse string only if it contains bidirectional  characters and the current locale is bidirectional  TSS_FORCE_REVERSE reverse string only if it contains bidirectional characters
Notes

The order of ASCII characters does not change. Code features are treated as separators and their position does not change. For example:

Source string: h1, h2, and h3 are bidirectional characters

h1	h2	h3	A	B	C	cf(0)	D	E	F

Reversed string: Hebrew/Arabic

D	E	F	cf(0)	A	B	C	h3	h2	h1
Return values

The reversed string.

Context

Bshell function.

Examples

x = mb.rev$( y	)	| reverses always

x = mb.rev$( y, TSS_REVERSE )

| reverses when current locale is

| bidirectional and y contains bidirectional characters

if mb.hasbidi( y ) then

x = mb.rev$( y )	| reverses when y contains bidirectional characters

endif

Related help topics

    Multibyte strings: overview and synopsis


mb.scrpos()

Syntax

long mb.scrpos( string_expr, long pos )

Description

This converts a string position to a screen position. Code features are ignored.

Arguments

string_expr	The source string.
pos	A position in the string.
Return values

The screen position corresponding to the specified string position. Or -1 if pos lies beyond the end of the string.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.set.info()

Syntax

long mb.set.info( long setid, ref string name, ref string desc, ref long n_items )

Description

This returns information about a specified character set.

Arguments

setid	The character set ID.
name	The name of the character set.
desc	The description of the character set.
n_items	The number of defined ranges in the character set.
Return values

 0	success
-1	the set ID is not linked to a known character set

Context

Bshell function.

Example

long id, nr, n_items

string name(20), desc(80)

nr = mb.nsets()

for id = 0 to nr

if mb.set.info( id, name, desc, n_items ) <> -1 then

print name, cr$(), lf$()

endif

endfor

Related help topics

    Multibyte strings: overview and synopsis


mb.strpos()

Syntax

long mb.strpos( string_expr, long pos )

Description

This converts a screen position to a string position. Code features are ignored.

Arguments

string_expr	The source string.
pos	A screen position.
Return values

The string position corresponding to the specified screen position. Or -1 if pos lies beyond the end of the string.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.tss.clean$()

Syntax

long mb.tss.clean$( ref string tss.string )

Description

This replaces characters in a specified string with spaces, if those characters cannot be converted from TSS to native format.

Return values

  0	all characters can be converted
>0	the position of the first character that could not be converted.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.type()

Syntax

long mb.type( string_expr )

Description

This tests if a specified string is a multibyte string. It does not test the content of the string.

Return values

- 1	the string is not of type multibyte
  0	the string is of type multibyte

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


mb.width()

Syntax

long mb.width( string_expr )

Description

This returns the display width of a specified string; that is, the number of positions the string will occupy on the screen.

An ISO-8859/1 character has a display width of one screen position. A multibyte character has a display width of one or two screen positions.

Return values

The display width of the specified string.

Context

Bshell function.

Related help topics

    Multibyte strings: overview and synopsis


Plan Chart Manager: overview

The Plan Chart Manager is a graphical planning environment. You can use the Plan Chart Manager functions to develop applications that create and manipulate plan charts within this environment; the Plan Chart Manager acts as the server for the applications.

Planning board

The Plan Chart Manager provides a planning board, on which you can build and maintain plan charts on line. Users can open sessions in order to define and modify activities, relations between activities, and so on. The planning board consists of:

•	A time scale.

•	Horizontal lines (the planning board lines), on which users can place activities.

•	Columns that describe the activities.

Activities and relations

Activities are the building blocks of a plan. An activity is an event or series of actions, with a start and end time. On the planning board, activities are displayed as horizontal bars whose length represents the duration of the activity. The relations between the activities constitute the planning structure.

Time scale

You can define a different time unit for each plan, to be used in the time scale displayed at the top of the planning board. In principle, you can use any time unit, from a second to a year, as the base unit. In practice, day, week, and month are normally used, the day being the base unit. If required, you can define several time scales for each plan.

Plan Chart Manager events

The Plan Chart Manager communicates with a client application by means of events. Each user action within the Plan Chart manager generates an event. The client must include a loop to handle these events.

The Plan Chart manager generates the following event types:

PCM_EVTMENUSELECT	Occurs when the user selects a menu item of the planning board.
PCM_EVTPUSHBUTTON	Occurs when the user clicks on a button of the planning board.
PCM_EVTOBJECTPRESS	Occurs when the user clicks on an activity, relation, or marker on the planning board.
PCM_EVTOBJECTDPRESS	Occurs when the user double-clicks on an activity, relation, or marker.
PCM_EVTOBJECTMOVE	Occurs when the user moves an activity, relation, or marker.
PCM_EVTCLOSED	Occurs when the Plan Chart Manager is closed.
Colors

All colors must be composed by using the rgb() function. Or you can use one of the following predefined colors:

RGB.BLACK RGB.BLUE RGB.YELLOW	RGB.MAGENTA RGB.GREEN RGB.GRAY	RGB.RED RGB.WHITE RGB.CYAN
Related help topics

    Plan Chart Manager: synopsis
    Plan Chart Manager: example


Plan Chart Manager: synopsis

long	pcm.activate.session	( ref string session(), ref string title() )
void	pcm.change	( long plan_id [, flag, value ] ... )
void	pcm.change.object	( long plan_id, long object_id    [, flag, value ] ... )
long	pcm.create	( [ flag, value ] ...)
long	pcm.create.object	( long plan_id, long object_type    [, flag, value ] ... )
void	pcm.destroy	( long plan_id )
void	pcm.destroy.object	( long plan_id, long object_id )
void	pcm.get.data	( long evt_type, ref string arglist(), ... )
void	pcm.lock	( long plan_id, long lock )
void	pcm.refresh	( long plan_id )
void	pcm.send.bms.event	( long command, ref string arglist() )
Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: example


pcm.activate.session()

Syntax

long pcm.activate.session( ref string session(), ref string title() )

Description

This starts a specified 4GL session. It generates a new window for the session and ensures that it is handled correctly. You can use this function in combination with pcm.send.bms.event(), which sends changed values back to the application as events.

Arguments

session	The session code.
title	The title for the session window.
Return values

The function returns the process ID of the activated session.

Context

3GL library function.

Example

See pcm.send.bms.event()

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.change()

Syntax

void pcm.change( long plan_id [, flag, value ] ... )

Description

Use this function to change the attributes of a specified chart.

Arguments

plan_id	The ID of the chart whose attributes you want to change, as returned by pcm.create().
flag, value	Use these arguments to set new values for the chart attributes. For each attribute you specify, you must include the attribute type (for example, PcmPlanName or PcmPlanBackgroundColor), and the attribute value. For a list of the plan attributes, see pcm.create().
Context

3GL library function.

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.change.object()

Syntax

void pcm.change.object( long plan_id, long object_id [, flag, value ] ... )

Description

Use this function to change the attributes of an object that was created by pcm.create.object().

Arguments

plan_id	The ID of the chart to which the object belongs, as returned by pcm.create().
object_id	The ID of the object, as returned by pcm.create.object().
flag, value	Use these arguments to set new values for the object's attributes. For each attribute you specify, you must include the attribute type (for example, PcmMenuName or PcmTimescaleVisible), and the attribute value. For a list of the object attributes, see pcm.create.object().
Context

3GL library function.

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.create()

Syntax

long pcm.create( [ flag, value ] ... )

Description

This starts the Plan Chart Manager and creates a new chart with the specified attributes. It returns the variable plan_id, which is a unique identifier for the chart. You use plan_id in the other functions in order to identify the chart you want to work with.

Arguments

The arguments of pcm.create() consist of a series of attribute-value pairs. Each of these specifies an attribute type and a value for that attribute. The attributes available are as follows:

PcmPlanName(50)  (string)	The title of the chart.
PcmPlanFontHeight  (long)	The size of the font used in the chart.
PcmPlanLineHeight  (double)	The distance between the lines/activities.
PcmPlanBackgroundColor  (long)	The background color for the chart.
PcmPlanForegroundColor  (long)	The foreground color for the chart.
PcmPlanProgressColor  (long)	The color for the part of an activity that has been reported as completed.
PcmPlanActivityColor1 - PcmPlanActivityColor9  (long)	Use these to define the colors for activity groups. You can define up to nine activity groups, and assign a different color to each.
PcmPlanRelationColor1 - PcmPlanRelationColor9  (long)	Use these to define the colors for relation groups. You can define up to nine relation groups, and assign a different color to each.
PcmPlanMarkerColor1 -PcmPlanMarkerColor3  (long)	Use these to define the colors for marker groups. You can define up to three marker groups, and assign a different color to each.
PcmPlanCriticalColor (long)	The color for an activity or relation that is part of the critical path.
PcmPlanTimescaleStart  (double)	The starting point of the time scale. Specify a number that you translate into a date or time value when dividing the time scale.
PcmPlanTimescaleFinish (double)	The end point of the time scale.
PcmPlanTimescaleWidth  (double)	The width (number of characters) of each time unit on the time scale.
PcmPlanFreeTimeVisible  (long)	This indicates if the float must be displayed in the chart. The possible values are true or false.
PcmPlanCriticalVisible  (long)	Activities and relations that are part of the critical path can be shown in a particular color. This flag indicates if the critical path must be displayed in the chart. The possible values are true or false.
PcmPlanDelaysVisible  (long)	You can define lay-offs, holidays, and weekends as non-workdays and the Plan Chart Manager then takes this into account. This flag indicates if non-workdays must be shown hatched or not. The possible values are true or false.
PcmPlanRelationsVisible (long)	You can define relations between different objects by means of lines on the planning board. This flag indicates if the relations must be visible. The possible values are true or false.
PcmPlanRelationsStraight (long)	true a relation is represented by a straight line between two objects false a relation is represented by lines at right angles or  parallel to the objects
PcmPlanMarkersVisible  (long)	You can add a marker to an activity in order to plan certain standard actions – for example, "Principal's Approval". This flag indicates if such markers must be visible in the planning board. The possible values are true or false.
Return values

The function returns a unique ID for the new chart.

Context

3GL library function.

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.create.object()

Syntax

long pcm.create.object( long plan_id, long object_type [, flag, value ] ... )

Description

This creates an object of the specified type – for example, a menu item, an activity, a relation, or a marker.

The function returns the object_id, which in turn is used in the functions pcm.change.object() and pcm.destroy.object() to identify the particular object to be changed or deleted. The object_id is also used in submenus and with subactivities in order to indicate the parent of the menu or activity.

Arguments

plan_id	The ID of the plan to which you want to add the new object.
object_type	The object type. The possible values are: PCM_OT_MENU   a menu item PCM_OT_BUTTON  a button to which you can link sessions or options PCM_OT_TIMESCALE  a time scale PCM_OT_DELAY  delay time (that is, non workdays) PCM_OT_COLUMN  a column containing an activity description PCM_OT_ACTIVITY           an activity PCM_OT_RELATION  a relation PCM_OT_MARKER  an activity marker
flag, value	Use these arguments to define the object's attributes. For each attribute you specify, you must include the attribute type (for example, PcmMenuName or PcmTimescaleVisible), and the attribute value. The attributes of each object are listed in the section describing that object.
Return values

The function returns a unique ID for the new object.

Context

3GL library function.

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.destroy
pcm.destroy()

Syntax

void pcm.destroy( long plan_id )

Description

This ends the specified plan chart and removes all associated settings and objects.

Context

3GL library function.

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.destroy.object()

Syntax

void pcm.destroy.object( long plan_id, long object_id )

Description

This deletes the specified object.

Arguments

plan_id	The ID of the chart to which the object belongs, as returned by pcm.create().
object_id	The ID of the object, as returned by pcm.create.object().
Context

3GL library function.

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.get.data()

Syntax

void pcm.get.data( long evt_type, ref string arglist(), ... )

Description

When the client application receives an event from the Plan Chart Manager, use this function to read the event.

Arguments

evt_type	This specifies the type of the event you want to read.
arglist	This returns the argument list.
. . .	The third and subsequent arguments return individual event arguments. The number and meaning of the arguments depends on the event type. PCM_EVTMENUSELECT 3rd argument – long menu_id 4th argument – long object_type 5th argument – long object_id PCM_EVTPUSHBUTTON 3rd argument – long button_id 4th argument – long object_type 5th argument – long object_id PCM_EVTOBJECTPRESS 3rd argument – long object_type 4th argument – long object_id 5th argument – double time PCM_EVTOBJECTDPRESS 3rd argument – long object_type 4th argument – long object_id 5th argument – double time PCM_EVTOBJECTMOVE 3rd argument – long object_type 4th argument – long object_id 5th argument – double start 6th argument – double finish
Context

3GL library function.

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.lock()

Syntax

void pcm.lock( long plan_id, long lock )

Description

Use this function to lock and unlock the Plan Chart Manager (for example, when data is changed in a session).

Arguments

plan_id	The ID of the planning chart that you want to lock.
lock	This indicates whether the planning chart must be locked or unlocked. The possible values are: true The planning board is locked. The user cannot interact with it until it is  unlocked again. false The planning board is unlocked. This is the default value.
Context

3GL library function.

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.refresh()

Syntax

void pcm.refresh( long plan_id )

Description

This (re)draws the specified chart and updates the display with all new and changed objects.

Context

3GL library function.

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


pcm.send.bms.event()

Syntax

void pcm.send.bms.event( long command, ref string arglist() )

Description

Use this in a process started by pcm.activate.session() in order to send an event back to the application that started the session.

Arguments

command	The command to be sent back to the application. The Chart Manager places this in the variable evt.bms.command(event).
arglist	The argument list. The application can retrieve this string by calling bms.receive$().
Context

3GL library function.

Example

Application

| handle events

while next.event(event)

evt.bucket = bms.receive$()

on case evt.bms.sender(event)

case appl.pid:

pcm.bucket = evt.bucket

if pcm.bucket(1;1) = "0" then

item.f = pcm.bucket(2;16)

item.t = pcm.bucket(18;16)

else

if pcm.bucket(1;1) = "1" then

cprj.f = pcm.bucket(2;6)

cprj.t = pcm.bucket(8;6)

endif

endif

pcm.refresh(plan_id)

break

case ...

....

endcase

          ....

endwhile

| start session

tt.session.desc("ppmod1000m000", desc)

appl.pid = pcm.activate.session("ppmod1000m000", desc)

Other process

choice.cont.process:

before.choice:

event.bucket(1;1) = "0"

event.bucket(2;16) = item.f

event.bucket(18;16) = item.t

pcm.send.bms.event(0, event.bucket)

choice.end.program:

before.choice:

event.bucket(1;1) = "1"

event.bucket(2;6) = cprj.f

event.bucket(8;6) = cprj.t

pcm.send.bms.event(0, event.bucket)

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


PCM_OT_MENU - menu object

Overview

On the planning board, you can create a menu structure that consists of one or more menu items. Users can click on these items to initiate actions, such as starting a session. Each part of the menu structure consists of a parent menu item and related child menu item(s). You must create a PCM_OT_MENU object for each menu item.

Attributes

PcmMenuParent  (long)	This indicates the object ID of the item's parent item. The parent ID of a parent menu item is 0.
PcmMenuId    (long)	The unique identification number of the menu item. This is included in PCM_EVTMENUSELECT events, in order to identify the menu item to which the event relates.
PcmMenuName(50)  (string)	The description of the menu item.
PcmMenuSensitive   (long)	This indicates whether the menu item is currently enabled or disabled. The possible values are:  true The menu item is enabled. false The menu item is disabled and cannot be selected.
PcmMenuChecked  (long)	This specifies whether or not a tick is placed beside the menu item to indicate its 'selected' status. The possible values are: true A tick is placed beside the menu item. false No tick is placed beside the menu item, or an existing tick is removed.
Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


PCM_OT_BUTTON: Creating a button
PCM_OT_BUTTON – button object

Overview

On the planning board you can create buttons to which you can link sessions or options. You must create a PCM_OT_BUTTON object for each button.

Attributes

PcmButtonId (long)	The unique identification number of the button. This is included in PCM_EVTPUSSBUTTON events, in order to identify the button that the user selected.
PcmButtonName(50) (string)	The text string for the button's label.
PcmButtonSensitive (long)	This indicates whether the button is currently enabled or disabled. The possible values are:  true The button is enabled. false The button is disabled and cannot be selected.
Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


PCM_OT_TIMESCALE: Creating a time scale
PCM_OT_TIMESCALE – time scale object

Overview

A plan chart represents a projection of activities on a time scale. An efficient time scale is essential in order to make the chart as clear as possible. To divide the time scale, you require a base unit. In the Plan Chart Manager, any time unit, from seconds to years, can be used as the base unit. In practice, the base unit is usually one day.

You can define several time scales for each plan chart. You must create a PCM_OT_TIMESCALE object for each of the time scales included in the chart. You specify start and end dates for the time scale with the function pcm.create(). These can, for example, be specified as the number of days since 01-01-0001.

The following predefined variables are available for PCM_OT_TIMESCALE objects.

PCM_DAYNO	The number of days since 01-01-0001.
PCM_WEEKDAYNO	The day number in the week (1 to 7).
PCM_WEEKNO	The week number in the year (0 to 53).
PCM_MONTHDAYNO	The day number in the month (1 to 31).
PCM_MONTHNO	The month number in the year (1 to 12).
PCM_YEARNO	The day number in the year (1 to 366).
Attributes

PcmTimescaleVisible (long)	This flag indicates if the time scale must be visible on the planning board. The possible values are true and false.
PcmTimescaleDesc (string)	The format of the description on the time scale – for example, month numbers, day numbers, and so on. See sprintf$.
PcmTimescaleExprV (string)	This expression determines how the time scale must be divided and where the ticks indicating the divisions must be placed.
PcmTimescaleExprD (string)	This expression determines the value by which the substitution symbol specified in PcmTimescaleDesc must be replaced – for example, a day number.
PcmTimescaleInterval (double)	The interval for the time scale division.
Example

Base Unit: Day

Time Scale Division: Week Numbers

pcm.create.object ( plan_id, PCM_OT_TIMESCALE,

    PcmTimescaleVisible, TRUE,

    PcmTimescaleDesc, "Week %D(%w)",

PcmTimescaleExprV, "PCM_WEEKDAYNO = 1",

    PcmTimescaleExprD, "PCM_DAYNO",

    PcmTimescaleInterval, 1 )

In this example, the starting point of the time scale is a number representing the number of days since 01-01-0001. At each division, the Plan Chart Manager increments this value (ExprD) by 1 (Interval) and checks if this day coincides with the start date of a week (ExprV). If the latter expression is true, a mark is placed on the time scale containing a week number. In fact, if ExprV is true, the following statement is executed:

sprintf$(PcmTimescaleDesc, PcmTimescaleExprD)

that is,

sprintf$("Week %D(%wer)", PCM_DAYNO)

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


PCM_OT_DELAY: Defining delay time
PCM_OT_DELAY – delay time object

Overview

Delay time is a span of time characterized as non-working time – for example, weekends and holidays. It can be indicated in a chart by hatched lines. You must create a PCM_OT_DELAY object for each delay time period you want to include in the chart. The same delay time object can be repeated at regular intervals – to indicate weekends, for example.

Attributes

PcmDelayStart (double)	The starting point of the delay time on the time scale.
PcmDelayFinish (double)	The end point of the delay time on the time scale.
PcmDelayRepeat (long)	This indicates whether or not the delay time is repeated. The possible values are: true delay time is repeated false delay time occurs only once
PcmDelayInterval (double)	If PcmDelayRepeat = true, use this flag to specify the interval at which the delay time must be repeated. The format depends on the division of the time scale.
Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


PCM_OT_COLUMN: Defining columns
PCM_OT_COLUMN – column object

Overview

You can define up to nine columns for each chart plan. These columns contain the activity descriptions. The first column you define becomes the leftmost column on the planning board. You must create a PCM_OT_COLUMN object for each column you want to include in the chart.

Attributes

PcmColumnVisible (long)	This indicates whether or not the column is to be visible in the chart plan. The possible values are true and false.
PcmColumnName (string)	The title of the column. This is placed over the column.
PcmColumnWidth (double)	The column width, expressed in characters (up to 50).
PcmColumnIndent (long)	This indicates whether or not the texts relating to subactivities are indented. The possible values are: true texts relating to subactivities are indented false all texts start at the left margin of the column
Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


PCM_OT_ACTIVITY: Defining an activity
PCM_OT_ACTIVITY – activity object

Overview

An activity is an event or series of events with a start and end time. There are parent activities and subactivities. A parent activity can be an independent activity within a project or it can have one or more subactivities. Subactivities are always linked to a parent activity. Activities can be repeated in the plan chart.

An activity consists of the following parts:

•	part reported completed

•	part still to be executed

•	lower margin – that is, the number of time units the activity may start earlier that the defined start time

•	upper margin – that is, the number of time units by which the end time of the activity may be exceeded

You must create a PCM_OT_ACTIVITY object for each activity you want to include in the chart.

Attributes

PcmActivityParent (long)	The object ID of the activity's parent activity. The parent ID of a parent activity is 0.
PcmActivityBrother  (long)	An activity can occur several times in one project (repeated activity). The activity is placed several times on the same line, each time shifted in time. In this flag, specify the object ID of the activity that is to be repeated.
PcmActivityGroup    (long)	By grouping activities, you can assign different colors to different groups of activities. You can define up to nine activity groups. Use this attribute to specify the group number for the activity.
PcmActivityStart (double)	The starting point of the activity on the time scale.
PcmActivityFinish (double)	The end point of the activity on the time scale.
PcmActivityProgress (double)	The part of the activity reported completed (as a percentage).
PcmActivityFreeStart    (double)	The starting point of the free float of this activity as a value on the time scale. This value should be less than or equal to PcmActivityStart. The free float is the degree to which an activity can be moved in time without influencing the start or end time of other activities.
PcmActivityFreeFinish (double)	The end point of the free float of this activity as a value on the time scale. This value should be less than or equal to PcmActivityFinish.
PcmActivityTotalStart  (double)	The starting point of the total float of this activity as a value on the time scale. This value should be less than or equal to PcmActivityStart. The total float is the degree to which an activity may be moved in time without influencing the start or end time of the entire project.
PcmActivityTotalFinish    (double)	The end point of the total float of this activity as a value on the time scale. This value should be less than or equal to PcmActivityFinish.
PcmActivityText1 PcmActivityText9    (string)	An explanatory text for the activity. This is displayed in the specified column. You can create as many texts (per activity) as there are columns. See also PCM_OT_COLUMN.
PcmActivitySort    (string)	Activities can be sorted (for example, by start time). Use this to specify the string by which they must be sorted.
PcmActivityCritical    (long)	This flag indicates if the activity is part of the critical path. The critical path is the longest route between the start and end of the project. Any change in one of the activities or relations that are part of the critical path directly influences the project's end time. The possible values are: true the activity is part of the critical path false the activity is not part of the critical path
PcmActivityExpand    (long)	This flag determines if subactivities are shown on the plan chart. The possible values are: PCM_EM_EXPAND show subactivities PCM_EM_NOEXPAND        do not show subactivities PCM_EM_TOGGLE toggle between EXPAND and NOEXPAND
PcmActivityEdit    (long)	This flag determines whether or not users are authorized to modify or move the activity. The possible values are: PCM_ED_NOEDIT The user is not authorized to change or shift the                            activity in time. PCM_ED_START The user is authorized to shift the entire activity in                              time. This is done by dragging the start point of                          the activity with the mouse. PCM_ED_FINISH The user is authorized to shorten or lengthen the                          activity. This is done by dragging the end point of                   the activity with the mouse. You can combine PCM_ED_START + PCM_ED_FINISH in order to authorize users to both shift and change activities.
Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


PCM_OT_RELATION: Defining a relation between two objects
PCM_OT_RELATION – relation object

Overview

On the planning board you can record relations between different activities and/or markers. These relations define the mutual relationships between such objects. You can record, for instance, that certain activities must be completed before another activity can start. Also, two related activities can be separated by a mandatory interval (for example, if a coat of paint must dry for two days before the next activity can take place) or they can overlap.

You must create a PCM_OT_RELATION object for each relation you want to include in the chart.

The Plan Chart manager supports the following relation types:

start-start	Activity 1 can start as soon as activity 2 has started.
start-end	Activity 1 can start only when activity 2 is completed.
end-start	Activity 2 can start when activity 1 is completed.
end-end	Activity 2 can end only when activity 1 is completed.
Attributes

PcmRelationObject1  (long)	This specifies the object ID of object 1.
PcmRelationObject2    (long)	This specifies the object ID of object 2.
PcmRelationGroup (long)	By grouping relations, you can assign different colors to different groups of relations. You can define up to nine relation groups. Use this attribute to specify the group number for this relation.
PcmRelationType    (long)	The relation type. The possible values are: PCM_RT_STARTSTART PCM_RT_STARTEND PCM_RT_ENDSTART PCM_RT_ENDEND
PcmRelationDelay    (double)	The time span between the two related activities. This number is placed alongside the line that indicates the relationship (this can also be a negative value).
PcmRelationCritical    (long)	This flag indicates if the relation is part of the critical path. The critical path is the longest route between the start and end of the project. Any change in one of the activities or relations that are part of the critical path directly influences the project's end time. The possible values are: true the activity is part of the critical path false the activity is not part of the critical path
Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


PCM_OT_MARKER: Generating markers
PCM_OT_MARKER – marker object

Overview

You can place markers on the planning board to indicate when certain standard actions must take place – for example, "Principal's Approval". Markers are defined at a specific point in time. You must create a PCM_OT_MARKER object for each marker you want to include in the chart.

Attributes

PcmMarkerActivity (long)	The object ID of the activity that must be marked.
PcmMarkerType    (long)	The marker type. The possible values are: PCM_MT_RECTANGLE PCM_MT_TRIANGLE PCM_MT_DIAMOND PCM_MT_STAR PCM_MT_ARROW
PcmMarkerStart    (double)	The time where the marker is to be placed.
PcmMarkerText    (string)	A text explaining the marker.
PcmMarkerEdit    (long)	This flag determines whether or not users can move the marker. The possible values are:  PCM_ED_NOEDIT The user is not authorized to shift this marker in time. PCM_ED_START  The user is authorized to shift this marker in time.  This is done by dragging the starting point with the  mouse.
PcmMarkerGroup    (long)	By grouping markers, you can assign different colors to different groups of markers. You can define up to three marker groups. Use this attribute to specify the group number for this marker.
Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis
    Plan Chart Manager: example


Plan Chart Manager: example

#include   <bic_pcm>

#define    MI_MENU1        100

#define    MI_MENU2        101

#define    MI_BUTTON1      200

long plan_id

long time_start

long time_finish

long actv1

function main()

{

| check if display server supports graphics

if is.graphical.server() then

start.planboard()    | start pcm server; create objects

handle.event.loop()  | handle pcm events

endif

}

function long is.graphical.server()

{

long  srv_type, srv_data(SRVMAXSIZE)

srv_type = get.display.data(srv_data)

return( srv_type = DSBW )

}

function handle.event.loop()

{

string    data list(256)

long      event(EVTMAXSIZE)

while next.event(event)

on case evt.type(event)

case EVTBUCKETMESSAGE:

data list = bms.receive$()

on case evt.bms.sender(event)

case plan_id:

on case evt.bms.command(event)

case PCM_EVTMENUSELECT:

handle.evtmenuselect(data list)

break

case PCM_EVTPUSHBUTTON:

handle.evtpushbutton(data list)

break

case PCM_EVTOBJECTPRESS:

handle.evtobjectpress(data list)

break

case PCM_EVTOBJECTDPRESS:

handle.evtobjectdpress(data list)

break

case PCM_EVTOBJECTMOVE:

handle.evtobjectmove(data list)

break

case PCM_EVTCLOSED:

handle.evtclosed()

break

endcase

break

endcase

break

endcase

endwhile

}

function handle.evtmenuselect( ref string data list() )

{

long  menu_id         | selected menu

long  object_type     | type of selected object

long  object_id       | selected object

pcm.get.data( PCM_EVTMENUSELECT, data list,

menu_id, object_type, object_id )

on case menu_id

case MI_MENU1:

....

break

.

.

endcase

}

function handle.evtobjectdpress( ref string data list() )

{

long  object_type     | type of selected object

long  object_id       | selected object

double time           | time of selected object

pcm.get.data( PCM_EVTOBJECTDPRESS, data list,

                           object_type, object_id, time )

on case object_type

case PCM_OT_ACTIVITY:

pcm.change.object( plan_id, object_id,

                           PcmActivityExpand, PCM_EM_TOGGLE )

pcm.refresh(plan_id)

break

case PCM_OT_RELATION:

....

break

case PCM_OT_MARKER:

....

break

endcase

}

function handle.evtobjectmove()

{

long  object_type     | type of selected object

long  object_id       | selected object

double start          | new start time

double finish         | new finish time

pcm.get.data( PCM_EVTOBJECTMOVE, data list,

                           object_type, object_id, start, finish )

on case object_type

case PCM_OT_ACTIVITY:

move.activity( object_id, start, finish )

break

.

.

endcase

}

function move.activity( long actv_id, double strt, double fnsh )

{

pcm.change.object( plan_id, actv_id,

PcmActivityStart, strt,

PcmActivityFinish, fnsh,

PcmActivityFreeStart, strt - 1,

PcmActivityFreeFinish, fnsh + 2 )

pcm.refresh( plan_id )

}

function handle.evtclosed()

{

close.planboard()

exit(0)

}

function start.planboard()

{

long  par_menu, menu2, butt1

time_start = date.num()

time_finish = time_start + 100

plan_id = pcm.create(PcmPlanName, "Project 1993",

PcmPlanFontHeight,        15,

PcmPlanLineHeight,        2.0,

PcmPlanBackgroundColor,   RGB.WHITE,

PcmPlanForegroundColor,   RGB.BLACK,

PcmPlanTimescaleStart,    time_start,

PcmPlanTimescaleFinish,   time_finish,

PcmPlanTimescaleWidth,    3.0,

.

.

PcmPlanMarkersVisible,    TRUE )

| -- create objects

par_menu = pcm.create.object( plan_id, PCM_OT_MENU,

                                  PcmMenuParent, 0,

                                  PcmMenuId, MI_MENU1,

                                  PcmMenuName, "File" )

menu2 = pcm.create.object( plan_id, PCM_OT_MENU,

                               PcmMenuParent, par_menu,

                               PcmMenuId, MI_MENU2,

                               PcmMenuName, "open" )

butt1 = pcm.create.object( plan_id, PCM_OT_BUTTON,

                               PcmButtonId, MI_BUTTON1,

                               PcmButtonName, "Close" )

pcm.create.object( plan_id, PCM_OT_TIMESCALE,

                	 PcmTimescaleVisible, TRUE,

                	 PcmTimescaleDesc, "%D(%H)",

                	 PcmTimescaleExprV, "PCM_MONTHDAYNO = 1",

                	 PcmTimescaleExprD, "PCM_DAYNO",

                	 PcmTimescaleInterval, 1 )

pcm.create.object( plan_id, PCM_OT_TIMESCALE,

                	 PcmTimescaleVisible, TRUE,

              	 PcmTimescaleDesc, "%D(%d)",

 PcmTimescaleExprV, "TRUE",

                	 PcmTimescaleExprD, "PCM_DAYNO",

                	 PcmTimescaleInterval, 1 )

pcm.create.object( plan_id, PCM_OT_COLUMN,

                       PcmColumnVisible, TRUE,

                       PcmColumnName, "Id",

                       PcmColumnWidth, 10,

                       PcmColumnIndent, FALSE )

actv1 = pcm.create.object( plan_id, PCM_OT_ACTIVITY,

                      	    PcmActivityParent, 0,

                      	    PcmActivityStart, time_start + 5,

                      	    PcmActivityFinish, time_start + 20,

                      	    PcmActivityProgress, 0,

                      	    PcmActivityFreeStart, time_start + 4,

                      	    PcmActivityFreeFinish, time_start + 22,

                      	    PcmActivityText1, "Activity 1",

                      	    PcmActivityCritical, TRUE,

                      	    PcmActivityExpand, PCM_EM_EXPAND,

                      	    PcmActivityEdit, PCM_ED_START +
 PCM_ED_FINISH )

}

function close.planboard()

{

pcm.destroy(plan_id)

}

Related help topics

    Plan Chart Manager: overview
    Plan Chart Manager: synopsis


Processes: overview and synopsis

Overview

Use these functions for handling processes.

Synopsis

long	act.and.sleep	( string procname(.) [, "arg1", "arg2" ...] )
long	activate	( string procname(.) [, "arg1", "arg2" ...] )
long	argc	( )
string	argv$	( num_expr )
long	bshell.pid	( )
void	kill	( long processno )
long	pstat	( long pid, ref string progname,    ref long info(PSMAXSIZE) )
void	reactivate	( long processno )
void	signal	( long type, long action )
void	sleep	( long processno )
void	suspend	( long msec )
string	wait	( ref long process_id, long option )
long	wait.and.activate	( string procname(.) [, "arg1", "arg2", ...] )
See also

Process groups

Multitasking and the GUI


act.and.sleep()

Syntax

long act.and.sleep( string procname(.) [, "arg1", "arg2" ...] )

Description

This activates the specified process and places it in the sleeping process queue. It remains there until it is activated by calling the reactivate() function. You can remove the process with the kill() function. The process is automatically removed when the process group to which it belongs is killed.

Arguments

procname	The process to be activated. The argument can contain a session name (4GL programs) or the name of an object file (3GL programs).
arg1, arg2, ...	Use these optional arguments to pass arguments to the new process. The arguments are always converted to strings. The new process can access these arguments with the argv$() function.
Return values

  0	process cannot be activated
>0	process ID of activated process

Context

Bshell function.

Related help topics

    Processes: overview and synopsis


activate()

Syntax

long activate( string procname(.) [, "arg1", "arg2" ...] )

Description

This activates the specified process and places it in the running process queue. Execution starts when the bshell schedules CPU time for the process.

Arguments

procname	The process to be activated. The argument can contain a session name (4GL programs) or the name of an object file (3GL programs).
arg1, arg2, ...	Use these optional arguments to pass arguments to the new process. The arguments are always converted to strings. The new process can access these arguments with the argv$() function.
Return values

  0	process cannot be activated
>0	process ID of activated process

Context

Bshell function.

Related help topics

    Processes: overview and synopsis


argc()

Syntax

long argc()

Description

This returns the number of arguments of the current program. You can pass arguments to the program by activating it with the activate(), act.and.sleep(), or wait.and.activate() functions.

Context

Bshell function.

Example

string    str_arr(10, 4)           | 4 strings of length 10

activate("other_program", str_arr) | argc() in other_program has the value 5

Related help topics

    Processes: overview and synopsis


argv$()

Syntax

string argv$( num_expr )

Description

This returns the specified argument of the program as a string. The program name is stored in ARGV$(0). The last argument is stored in ARGV$( ARGC()-1 ).

You can pass arguments to the program by activating it with the activate(), act.and.sleep(), or wait.and.activate() functions. When you pass a string array as an argument, all elements of the array are passed as single arguments.

Return values

The specified argument as a string. Or an empty string (“”) if the argument does not exist.

Context

Bshell function.

Related help topics

    Processes: overview and synopsis


bshell.pid()

Syntax

long  bshell.pid()

Description

This returns the process ID of the current bshell (at operating system level).

Context

Bshell function.

Related help topics

    Processes: overview and synopsis


kill()

Syntax

void kill( long processno )

Description

This deletes the specified process from the bshell process queue. If the process is in a running state, it is interrupted.

Notes

Do not confuse this function with the kill command of the operating system. You can use kill() to kill process within the same bshell only. You cannot use it to kill the processes of other users.

If you kill a child process while the parent process is sleeping, the parent process is automatically wakened, provided that both processes are in the same process group.

Context

Bshell function.

Related help topics

    Processes: overview and synopsis


pstat()

Syntax

long  pstat ( long pid, ref string progname, ref long info(PSMAXSIZE) )

Description

This returns status information about a specified process.

Arguments

pid	The ID of the process for which you want to retrieve information. Specify a negative value here to retrieve information about the init process.
progname	This returns the process code.
info	This returns status information that you can retrieve with the following macros: ps.state(info) returns PSRUNNING, PSBLOCKING, PSSLEEPING, or  PSTERMINATING ps.group(info) returns the identifier of the process group to which the process  belongs ps.parent(info)   returns the identifier of the parent process of the process group
Return values

The process ID of the next process in the internal process list.

Context

Bshell function.

Example

long     info(PSMAXSIZE)

string   progname(512)

long     procid

procid = pstat( -1, progname, info )

while procid > 0

| process info

procid = pstat( procid, progname, info )

endwhile

 Related help topics

    Processes: overview and synopsis


reactivate()

Syntax

void reactivate( long processno )

Description

This activates the specified sleeping process.

Related help topics

    Processes: overview and synopsis


signal()

Syntax

void signal( long type, long action )

Description

This specifies whether the process in which it is called ignores child process signals or not.

Arguments

type	The signal type. Currently there is only one value for this argument: SIGCHLD Sent by a child process to its parent process when the child  process exits.
action	SIGIGN Ignore signals. The child exits without any action by the parent.  The child exits, sends an exit signal to its parent, and is  removed. This is the default action. SIGNOIGN Do not ignore signals. The child exits and waits until its  parent catches its exit signal. The parent catches the signal  with the wait() function. While the child process is waiting,  it is a zombie process.
Context

Bshell function.

Related help topics

    Processes: overview and synopsis


sleep()

Syntax

void sleep( long processno )

Description

This suspends execution of the specified process and places it in the sleeping process queue. To suspend execution of the your own process, specify the predefined variable pid in the processno argument.

Use reactivate() to activate a sleeping process. When a child process of a sleeping parent process exits, the parent process wakens automatically. When the last process is put in a sleeping state, the program automatically stops.

Note

Do not confuse this function with the UNIX sleep command. The latter suspends a process for a specified amount of time. In BaanERP scripts, you use suspend() to do this.

Context

Bshell function.

Related help topics

    Processes: overview and synopsis


suspend()

Syntax

void suspend( long msec )

Description

This stops execution of the current process for a specified number of milliseconds. You can specify any number of milliseconds in the range 0 to 2147483647 (the maximum value for a long).

Note

Do not confuse this function with the sleep() function. The latter puts another process in a sleeping state until it is reactivated with the reactivate() command.

Context

Bshell function.

Related help topics

    Processes: overview and synopsis


wait()

Syntax

string wait( ref long process_id, long option )

Description

This waits for one or all child processes to exit.

Arguments

process_id	This returns the process number of the child process that exited. If no child exited, it returns 0. If there are no child processes, or if all child processes were already ended before the function was called, it returns -1.
option	This can have one of the following values:
	WTHANG	If the parent process ignores child signals (see signal()), the function waits until all children have exited. The process_id argument returns the process ID of the last child process to exit. If the parent process does not ignore child signals (see signal()), the function waits until one child exits. The process_id argument returns the process ID of that child process.
	WTNOHANG	If the parent process ignores child signals (see signal()), the function does not block. If one or more child processes have previously exited and are in a zombie state, the process_id argument returns the process of the last child process that exited. If the parent process does not ignore child signals (see signal()), the function waits until one child exits. The process_id argument returns the process ID of that child process.
Return values

The exit value (a string) of the child process identified by the process_id argument.

Context

Bshell function.

Related help topics

    Processes: overview and synopsis


wait.and.activate()

Syntax

long wait.and.activate( string progname(.) [, "arg1", "arg2", ...] )

Description

This activates the specified program. The calling program is put in a waiting state. Because the calling program has not ended, it retains all its values.

In the called program, the predefined variable background is set to 1. By testing this variable, the program can check whether it is running as a foreground or background process. If required, the functioning of the program can be made dependent on this.

When the called program ends, the calling program is fetched from the waiting state and reactivated, starting from the statement immediately following the wait.and.activate() call. Note that this happens only when the two processes belong to the same process group.

Arguments

procname	The process to be activated. The argument can contain a session name (4GL programs) or the name of an object file (3GL programs).
arg1, arg2, ...	Use these optional arguments to pass arguments to the new process. The arguments are always converted to strings. The new process can access these arguments with the argv$() function.
Return values

  0	process cannot be activated
>0	process ID of activated program

Context

Bshell function.

Related help topics

    Processes: overview and synopsis


Process groups: overview

Use these functions to handle process groups.

A process group is a group of related, interdependent processes. One process is the group leader. Child processes are started by the leader or by one of its children. All processes belong to a process group.

Process groups have the following characteristics:

•	Each process group has its own event queue. Events are sent to the process group, not to individual processes.

•	When one process within a group starts another process, that process is automatically placed in the same process group.

•	For the group leader, the predefined variable background is set to zero, For child processes, this variable is set to 1.

•	When a process is killed or ended, its parent is automatically awakened, unless the parent and child are in different groups.

•	You use the grab.mwindow() function to set the process group to which a main window sends its events. After calling this function, all events that occur in the main window are sent to the process group.

See Processes for details of the functions available for handling processes.

Related help topics

    Process groups:  synopsis


Process groups: synopsis

long	get.pgrp	( long process_id )
void	grab.mwindow	( long mwindow, long process_group )
void	kill.pgrp	( long process_group )
long	set.pgrp	( long process_id, long group_id )
Related help topics

    Process groups:  overview


get.pgrp()

Syntax

long get.pgrp( long process_id )

Description

This returns the identification number of the process group to which the specified process belongs. If you specify an unknown process ID, -1 is returned.

Context

Bshell function.

Example

long group

group = get.pgrp( pid )

Related help topics

    Process groups:  overview
    Process groups:  synopsis


grab.mwindow()

Syntax

void  grab.mwindow ( long mwindow, long process_group )

Description

This specifies the process group to which a particular main window must send its events. After calling this function, all events that occur in the main window are sent to the process group. grab.mwindow() is mainly used immediately after creation of a new process group.

Arguments

mwindow	The ID of the main window.
process_group	The ID of the process group.
Context

Bshell function.

Example

long group mwindow

group = set.pgrp(pid, pid) | Create a new group

grab.mwindow(mwindow, group)

| Send all events to the new group

Related help topics

    Process groups:  overview
    Process groups:  synopsis


kill.pgrp()

Syntax

void kill.pgrp( long process_group )

Description

This ends all processes within the specified process group. All windows and graphical parts of the processes are removed.

Context

Bshell function.

Example

long child_group, child_pid

child_group = set.pgrp( child_pid, child_pid )

....

....

kill.pgrp( child_group )

Related help topics

    Process groups:  overview
    Process groups:  synopsis


set.pgrp()

Syntax

long set.pgrp( long process_id, long group_id )

Description

This places a specified process in a specified process group. If the process group ID is the same as the process ID, a new process group is created with the specified ID. The specified process becomes the leader of the new group.

The parent of the process does not change when you call this function.

Return values

The function returns the ID of the process group. If the specified group does not exist, and if the group ID is not the same as the process ID, the function returns -1.

Context

Bshell function.

Example 1

long any_group

set.pgrp(pid, pid)         | creates a new process group

set.pgrp(pid, any_group)   | sets pid in any_group

Example 2

long mwindow, child

mwindow = create.mwindow(....)

change.mwindow( mwindow )

child = activate( "my.program" )

if child then

set.pgrp( child, child )

grab.mwindow( mwindow, child )

endif

Related help topics

    Process groups:  overview
    Process groups:  synopsis


Progress indicators: overview and synopsis

Overview

A progress indicator provides feedback to the user on the progress of a lengthy operation. It consists of a rectangular bar that fills from left to right as the operation progresses, indicating the percentage of completion of the operation. It can also (or alternatively) display a series of text messages that describe the progress of the operation.

You can create progress indicators in both UI and DAL scripts.

Synopsis

long	create.progress.indicator	( string title() [, long mode] )
long	change.progress.indicator	( long percentage [, string message, ...] )
void	destroy.progress.indicator	( )
Related help topics

    Progress indicators:  sample program


create.progress.indicator()

Syntax

long create.progress.indicator( string title() [, long mode] )

Description

This creates a progress indicator with the specified title displayed in its title bar. The progress indicator is activated after the first update.

You can create only one progress indicator per session.

Arguments

title	The title for the progress indicator window.
mode	This optional argument can specify a combination of the following values: PROGRESS.BAR   Create a progress bar.  PROGRESS.STOP Add a Stop button to the progress bar window. The user  can click on this button to stop the operation; changes  already made are not canceled.  PROGRESS.CANCEL Add a Cancel button to the progress bar window. The user can click on this button to stop the operation; any  changes already made are canceled.  PROGRESS.NOAUTODESTROY The progress bar window is not automatically  destroyed when the progress bar value  changes to 100%.
Return values

 0	success
-1	error

Context

4GL library function.

Related help topics

    Progress indicators:  overview and synopsis
    Progress indicators:  sample program


change.progress.indicator()

Syntax

long change.progress.indicator( long percentage [, string message, ...] )

Description

This changes the value of the progress indicator.

Arguments

perc	A value in the range 0 – 100. This indicates the percentage of completion of the operation.
message	This optional argument displays a string that provides information about the progress of the operation. For example, if the process involves multiple stages, you could add a short description of each stage to the progress indicator. If you include more than one message argument, each successive message is displayed below the previous one.
Return values

0	No signal sent.
PROGRESS.STOP	Stop button pressed. Function must stop.
PROGRESS.CANCEL	Cancel button pressed. Function must stop and cancel any
changes made.

Context

4GL library function.

Related help topics

    Progress indicators:  overview and synopsis
    Progress indicators:  sample program


destroy.progress.indicator()

Syntax

void destroy.progress.indicator()

Description

Destroys the progress indicator.

Context

4GL library function.

Related help topics

    Progress indicators:  overview and synopsis
    Progress indicators:  sample program


Progress indicators: sample program

function x()

{

create.progress.indicator( form.text$("tdsls1100.01" ),

PROGRESS.BAR + PROGRESS.STOP )

for i = 1 to n

if change.progress.indicator((i*100)/n) then

abort.transaction()

break

endif

| process element i

endfor

}

    Progress indicators:  overview and synopsis


Random number generators: overview and synopsis

Overview

Use these functions for generating random numbers.

Synopsis

long	random	( )
double	rnd.d	( )
long	rnd.i	( [long range] )
void	rnd.init	( long seed )
void	srand	( long seed )


random()

Syntax

long random()

Description

This function uses a system-independent random number generator. On all systems, the generator will generate the same random numbers, provided that the same seed is supplied.

Calls to this function return successive random numbers in the range 0 to 32767. The function uses a multiplicative congruential random number generator, with period 232. The default seed is 1. To use a different seed, call srand() before starting the generator.

Return values

A random number.

Context

Bshell function.

Example

long r_number

srand( 200 )

r_number = random()

Related help topics

    Random number generators:  overview and synopsis


rnd.d()

Syntax

double rnd.d()

Description

This function uses a system-independent random number generator. On all systems, the generator will generate the same random numbers, provided that the same seed is supplied.

Calls to rnd.d() return successive random numbers in the range 0.0 to 1.0. Use rnd.init() to specify a seed value before starting the random number generator. If you do not do this, the first result of rnd.d() is undefined.

Return values

A random number in the range 0.0 to 1.0.

Context

Bshell function.

Related help topics

    Random number generators:  overview and synopsis


rnd.i()

Syntax

long rnd.i( [long range] )

Description

This function uses a system-independent random number generator. On all systems, the generator will generate the same random numbers, provided that the same seed is supplied.

Calls to rnd.i() return successive random numbers in the range 0 to 32767. You can specify a range argument if you want to limit the range further. The function then returns numbers in the range 0 to range-1.

Use rnd.init() to specify a seed value before starting the random number generator. If you do not do this, the first result of rnd.i() is undefined.

Return values

A random number in the default or specified range.

Context

Bshell function.

Related help topics

    Random number generators:  overview and synopsis


rnd.init()

Syntax

void rnd.init( long seed )

Description

rnd.d() and rnd.I() use a system-independent random number generator to generate random numbers. On all systems, the generator will generate the same random numbers, provided that the same seed is supplied.

rnd.init() resets the random number generator to the starting point specified by the seed argument (the seed can be any long value). If rnd.init() is not called before starting the generator, then the first results of rnd.d() and rnd.i() are undefined.

Context

Bshell function.

Related help topics

    Random number generators:  overview and synopsis


srand()

Syntax

void srand( long seed )

Description

random() generates random numbers using a multiplicative congruential random number generator. The default seed is 1. srand() resets the random number generator to the starting point specified by the seed argument (the seed can be any long value).

Context

Bshell function.

Example

long r_number

srand( 175 )

r_number = random()

Related help topics

    Random number generators:  overview and synopsis


Reports: overview and synopsis

Overview

Use these functions to activate reports and send data to them. Note that the rprt.* functions are short versions of the brp.* functions.

Synopsis

void	brp.close	( long brp_id )
long	brp.open	( string rep_name(16), string device(14),    long mode )
long	brp.open.language	( string rep_name(16), string lang, string    device(14), long mode )
void	brp.ready	( long brp_id )
long	choice.report	( ref string reportname(15) )
void	rprt_close	( [ long mess_flag ] )
long	rprt_open	( )
void	rprt_send	( )
Related help topics

    Spooling functions


brp.close()

Syntax

void brp.close( long brp_id )

Description

This stops the report writer for the specified report. brp_id is the report ID returned by brp.open() or brp.open.language() when the report was activated. The report is sorted (if necessary) and sent to the printer spooler.

If output from different reports is sent to one spool file, you can manage the opening and closing of the printer spooler in the script by calling spool.open before calling brp.open() and by calling spool.close after closing the last report with brp.close(). By default, the spooler is opened and closed automatically.

Context

Bshell function.

Example

See brp_open().

Related help topics

    Reports: overview and synopsis
    Spooling functions


brp.open()

Syntax

long brp.open( string rep_name(16), string device(14), long mode )

Description

This activates a specified report and opens a specified spooler device (if it is not already open). Several reports can be active simultaneously. In a 4GL script, the name of the current report is stored in the predefined variable spool.report. This variable is available in the on.choice subsection of a choice.print.data section.

Arguments

rep_name	The name of the report. Do not include a language code. The language of the user is automatically used.
device	The code of the device on which the report must be printed. This code must be defined in the data dictionary. If you specify an empty string here, you can use the mode argument to display a window in which the user can select the required device.
mode	0 User is not prompted to select a spooler device. 1 A window is displayed in which the user can select a spooler device. A  Cancel button enables the user to cancel the operation.  2 A window is displayed in which the user can select a spooler device. There is no option for canceling the operation.
Return values

>0	an ID for the activated report
  0	report could not be activated
 -1	spooler could not be opened

Context

Bshell function.

Examples

Example 1

brp_id1 = brp.open( "rtccom040101000", "F", 0 )

| Spooler is opened automatically

brp.ready( brp_id1 )

brp.close( brp_id1 )

Example 2

spool.open( "", spool.device, 1 )

| Open spooler in script

brp_id1 = brp.open( "rtccom040101000", "D", 1 )

| Spooler is not opened by report writer

brp_id2 = brp.open.language( "rtccom0401010003", spool.device, 1 )

| Open next report in language code 3

...

<store values>

brp.ready( brp_id1 )

brp.ready( brp_id2 )

...

brp.close( brp_id1 )         | Close reports

brp.close( brp_id2 )

spool.close()                | Close spooler in script

Related help topics

    Reports: overview and synopsis
    Spooling functions


brp.open.language()

Syntax

long brp.open.language( string rep_name(16), string lang, string device(14), long mode )

Description

This is the same as brp.open() in most respects, except that it includes a language argument. This enables you to specify a language for the report other than the default user language.

Return values

>0	an ID for the activated report
  0	report could not be activated
 -1	spooler could not be opened

Context

Bshell function.

Example

See brp_open().

Related help topics

    Reports: overview and synopsis
    Spooling functions


brp.ready()

Syntax

void brp.ready( long brp_id )

Description

This signals the report writer that a record is ready to be imported into a particular report. The report writer then prints the record. You call this function after filling the fields of a record that the report writer can process. The fields are specified in the report and must be declared as EXTERN in the program script.

Arguments

brp_id	This identifies the particular report into which the record must be imported. It is the ID returned by brp.open() or brp.open.language() when the report was activated.
Context

Bshell function.

Example

See brp_open().

Related help topics

    Reports: overview and synopsis
    Spooling functions


choice.report()

Syntax

long choice.report( ref string reportname(15) )

Description

This returns the name of a report from the session data in the data dictionary. The report is taken from the group defined in the predefined variable reportgrp (default = 1). If there is more than one report in the group, the user is presented with a menu from which to select the required report.

The returned name consists of 15 characters, starting with an “r”. The language code is not included in the name. If you call brp.open() with the report name returned by this function, the report is opened with the user language. If you call brp.open.language() with the report name returned by this function, the report is opened with the specified language.

Notes

The standard program calls choice.report() immediately before execution of the on.choice subsection of a choice.print.data section. By default a report from report group 1 is retrieved. To retrieve a report from a different group, you can assign any group to the predefined variable reportgrp in the before.choice subsection of the choice.print.data section.

Return values

>0	sequence number of report in the group
 -1	report not found, or no report selected by user

Context

3GL library function.

You can use this only in 4GL scripts, not in 3GL scripts.

Examples

Example 1

choice.print.data:

on.choice:

| choice.report()is always called by the standard program

brp_id = brp.open( reportname, "", 1 )

| report from default group 1

Example 2

choice.print.data:

before.choice:

reportgrp = 2

on.choice:

brp_id = brp.open( reportname, "", 1 ) | report from group 2

Example 3

function choice.and.open.report()

{

if choice.report( repname ) <= 0 then

return

endif

lfn.report = brp.open( repname, dep.device, 1 )

}

Related help topics

    Reports: overview and synopsis
    Spooling functions


rprt_close()

Syntax

void rprt_close( [ long mess_flag ] )

Description

This is a short version of brp.close(). It closes the report writer for the current report. You can use the function in a 4GL script in the subsection on.choice of the section choice.print.data. In this section, the predefined variable spool.report is available. This variable stores the name of the current report.

Arguments

mess_flag	This optional argument can have one of the following values: 0 If no data is printed, the following message appears: “No data present within selection” 1 If no data is printed, the following message appears: “No data found for report, no report is printed” 2 If no data is printed, no message appears.
Context

3GL library function.

Example

See rprt_open().

Related help topics

    Reports: overview and synopsis
    Spooling functions


rprt_open()

Syntax

long rprt_open( )

Description

This is a short version of brp.open(). It has the same effect as:

brp.open( spool.report, spool.device, 1 )

That is, it prints the current report to the default device. The predefined variables spool.report and spool.device store the names of the current report and default device respectively.

Return values

>0	an ID for the activated report
  0	report could not be activated
 -1	spooler could not be opened

Context

3GL library function.

Example

if rprt_open() <= 0 then     | Opens spooler and report

return

endif

.....

<store report values>

rprt_send()

rprt_close()

Related help topics

    Reports: overview and synopsis
    Spooling functions


rprt_send()

Syntax

void rprt_send( )

Description

This is a short version of brp.ready(). It has the same effect as:

brp.ready( spool.report )

That is, it signals the report writer that a record is ready to be imported into the current report. The predefined variable spool.report stores the name of the current report.

Context

3GL library function.

Example

See rprt_open().

Related help topics

    Reports: overview and synopsis
    Spooling functions


Resource sets: overview

Resources enable users to change certain display characteristics of their user interface (colors and fonts, for example) without any programming or recompiling. See session ttdsk3160m000 (Runtime resources).

Resources are grouped into resource sets. Resource sets relate to a particular package and user combination. A resource set contains all the resources that a particular application can use. It can also be shared by different applications.

Resource sets are created and maintained using the sessions ttdsk3150m000 (Maintain resource sets) and ttdsk3155m000 (Resource set elements). The sets are stored in the data dictionary.

The resource set functions enable programs to retrieve and set individual resources in resource sets.

Related help topics

    Resource sets:  synopsis


Resource sets: synopsis

void	rsc.boolean	( variable )
void	rsc.double	( variable )
void	rsc.enum	( variable )
string	rsc.font.spec	( long font_weight, long font_slant,    long font_height, long font_points,    long font_spacing, long font_width,    long font_charwidth )
void	rsc.get	( ref string values(), string package_code(2),    string resource_set(16), string resource_id(24),    ... )
void	rsc.long	( variable )
void	rsc.put	( string package_code(2), string resource_set(16),   string resource_id(24), string value(40)    [, string resource_id(24), string value(40)] ... )
void	rsc.setboolean	( variable, string value(40) )
void	rsc.setdouble	( variable, string value(40) )
void	rsc.setenum	( variable, string value(40) )
void	rsc.setlong	( variable, string value(40) )
void	rsc.setstring	( variable, string value(40) )
void	rsc.string	( variable )
Related help topics

    Resource sets:  overview


rsc.boolean(), rsc.double(), rsc.enum(), rsc.long(), rsc.string()

Syntax

void rsc.boolean( variable )

void rsc.double( variable )

void rsc.enum( variable )

void rsc.long( variable )

void rsc.string( variable )

Description

These convert a specified program variable to the corresponding resource value format (boolean, double, enum, and so on).

Context

3GL library function.

Example

See rsc.put().

Related help topics

    Resource sets:  overview
    Resource sets:  synopsis


rsc.font.spec()

Syntax

string rsc.font.spec( long font_weight, long font_slant, long font_height, long font_points, long font_spacing, long font_width, long font_charwidth )

Description

This returns a string that defines a font with the specified characteristics.

Arguments

font_weight	The font width. Possible values are: FNTMEDIUM, FNTBOLD or FNTNORMAL.
font_slant	The font slant. Possible values are: FNTROMAN or FNTITALIC.
font_height	The font height in pixels.
font_points	The font height in tenths of a point (a point is 1/72th of an inch).
font_spacing	The type of spacing. Possible values are: FNTFIXED or FNTVARIABLE.
font_width	The average width of the font, in tenths of a pixel.
font_charwidth	The average character width, in pixels. This overides the font_width value.
Return value

A string that defines a font with the specified characteristics.

Context

3GL library function.

Example

See rsc.put().

Related help topics

    Resource sets:  overview
    Resource sets:  synopsis


rsc.get()

Syntax

void rsc.get( ref string values(), string package_code(2), string resource_set(16), string resource_id(24), ... )

This retrieves one or more resource values from a specified resource set. You can use the following functions to store the resource value in a program variable: rsc.setboolean(), rsc.setdouble(), rsc.setenum(), rsc.setlong(), and rsc.setstring().

Arguments

values	The returned resource values. This argument must be long enough to accommodate the number of requested resources.
package_code	The package code.
resource_set	The resource set ID.
resource_id	One or more IDs of individual resources.
Context

3GL library function.

Example

long    foreground_color, background_color

string  gui_font(80)

domain  ttdsk.rsvl  resource.values(25)

| assume a defined resource set "desktop" in package "tt"

| containing resources "foreground", "background" and "font"

rsc.get( resource.values, "tt", "desktop", "foreground", "background", "font" )

rsc.setlong( foreground_color, resource_values(1,1) )

rsc.setlong( background_color, resource_values(1,2) )

rsc.setstring( gui_font, resource_values(1,3) )

| if, for example, resource_values(1,3) is empty, the variable

| gui_font is not changed.

Related help topics

    Resource sets:  overview
    Resource sets:  synopsis


rsc.put()

Syntax

void rsc.put( string package_code(2), string resource_set(16), string resource_id(24), string value(40) [, string resource_id(24), string value(40)] ... )

Description

This updates one or more resource values in a specified resource set. You can use the following functions to convert program variables to a resource value format: rsc.boolean(), rsc.double(), rsc.enum(), rsc.long(), and rsc.string().

Arguments

package_code	The package code.
resource_set	The resource set ID.
resource_id, value . . .	One or more name/value pairs. Each pair consists of the ID of a resource that must be updated and the new value for that resource.
Context

3GL library function.

Example

long   foreground_color, background_color

string gui_font(80)

foreground_color = RGB.RED

background_color = RGB.WHITE

gui_font = rsc.font.spec( FNTMEDIUM, FNTROMAN, 14, 0,FNTVARIABLE, 140, 0 )

rsc.put( "tt", "desktop", "foreground", rsc.long( foreground_color ),
"background", rsc.long( background_color ), "font",
rsc.string( gui_font ) )

rsc.reload()

Related help topics

    Resource sets:  overview
    Resource sets:  synopsis


rsc.setboolean(), rsc.setdouble(), rsc.setenum(), rsc.setlong(), rsc.setstring()

Syntax

void rsc.setboolean( variable, string value(40) )

void rsc.setdouble( variable, string value(40) )

void rsc.setenum( variable, string value(40) )

void rsc.setlong( variable, string value(40) )

void rsc.setstring( variable, string value(40) )

Description

These store a resource value of a particular type in a specified program variable.

Context

3GL library function.

Example

See rsc.get().

Related help topics

    Resource sets:  overview
    Resource sets:  synopsis


Runtime dictionary information: overview and synopsis

Overview

Use these functions to retrieve information from the runtime dictionary.

Synopsis

Include files (for tt.* functions)

#include <bic_tt>

Functions

long	rdi.audit.hosts	( string table_name(9), long comp_nr,    ref string hosts() )
long	rdi.column	( string column_name(18),    ref string domain_name(14),    ref long offset, ref long size,    ref long dept, ref long type,    ref long flag, ref string default_val(.) )
long	rdi.column.combined	( string column_name(18),    ref string child_columns(18,32) )
string	rdi.date.input.format$	( string date_format(7) )
long	rdi.domain	( string domain_name(14),    ref string oformat(.),    ref string lechar(.), ref string ilchar(.),   ref long adjust, ref string errmess(.),    ref long range_expr_id     [, ref long plen, ref string iformat(.) ] )
long	rdi.domain.byte	( string domain_name(14), ref long digits )
long	rdi.domain.combined	( string domain_name(14),    ref string child_domains(14,32) )
long	rdi.domain.date	( string domain_name(14), ref long digits )
long	rdi.domain.double	( string domain_name(14),    ref long digits_before,    ref long digits_after,    ref long divide_fact, ref long round_code )
long	rdi.domain.enum	( string domain_name(14),    ref long no_enum_items )
long	rdi.domain.enum.value	( string domain_name(14), long enum_item,    string language, ref string keyword(.),    ref string descr(.), ref long value )
long	rdi.domain.float	( string domain_name(14),    ref long digits_before,    ref long digits_after,    ref long divide_fact, ref long round_code )
long	rdi.domain.integer	( string domain_name(14), ref long digits)
long	rdi.domain.long	( string domain_name(14), ref long digits )
long	rdi.domain.set	( string domain_name(14),    ref long no_enum_items )
long	rdi.domain.set.value	( string domain_name(14), long enum_item,   string language, ref string keyword(.),    ref string descr(.), ref long value )
long	rdi.domain.string	( string domain_name(14), ref long length, ref long convert )
long	rdi.domain.text	( string domain_name(14), ref long digits )
long	rdi.first.day.of.week	( )
long	rdi.index	( string table_name(9), long index_no,    ref long parts(32,3), ref long duplicate,    ref long active )
long	rdi.reference	( string column_name(18),    ref string ref_column(18),    ref long ref_mode, ref string ref_mess()    [, long ignore_by_db] )
long	rdi.table	( string table_name(9), ref long no_keys,    ref long no_columns, ref long int_length,   ref long real_length )
long	rdi.table.column	( string table_name(9), long column_number,   ref string column_name(18),    ref string domain_name(14),    ref long offset, ref long size,    ref long dept, ref long type,    ref long flag, ref string default_val(.) )
void	tt.bobject.desc	( string b_object(10), ref string desc() mb )
long	tt.chm.appl.desc	( string appl(40), ref string desc() mb )
long	tt.chm.application	( string appl(40) )
long	tt.chm.chart	( string appl(40), string chart_name(16) )
long	tt.chm.charttype	( string appl(40), string chart_type(16) )
long	tt.company	( long company, ref string comp_desc() mb,    ref string deflt_curr(),    ref long first_weekday )
long	tt.currency	( string cur(3), ref string cur_desc() mb,    ref string thous_sign, ref string dec_sign,   ref string symbol() )
long	tt.device	( string device(9), ref string desc() mb,    ref long device type )
void	tt.field.desc	( string field(17), ref string desc() mb )
void	tt.index.desc	( string tabl(8), long indexnr,    ref string desc() mb )
long	tt.language	( string lang, ref string desc() mb,    ref string dec_sign, ref string thous_sign,   ref string date_sep, ref string time_sep )
long	tt.library	( string library.code(14),    ref string library.desc() mb )
void	tt.menu.desc	( string menu(13), string par_menu,    ref string desc() mb )
long	tt.menu.present	( string menu(13), string par_menu )
void	tt.report.desc	( string reprt(15), ref string desc() mb )
long	tt.reportgroup.exists	( string session(13), long report_group )
void	tt.session.desc	( string session(13), ref string desc() mb )
long	get.session.permission	( string session(13) )
long	tt.session.present	( string session(13) )
void	tt.short.field.desc	( string field(17), long length,    ref string desc() mb )
void	tt.table.desc	( string table(8), ref string desc() mb )
long	tt.user	( string user(12), ref string name() mb )
void	tt.chart.desc	( string chart, ref string desc() mb )
void	tt.comp.desc	( ref string desc() mb )


rdi.audit.hosts()

Syntax

long rdi.audit.hosts( string table_name(9), long comp_nr, ref string hosts() )

Description

This returns the names of the hosts on which audit information for a particular table is stored.

Arguments

table_name	The name of the table.
comp_nr	The company number of the table.
hosts	This returns a string containing the names of all hosts on which audit information for the specified table is stored. The host names are separated by commas [,]. The local host is referred to as 'localhost'.
Return values

 0	success
-1	error

Context

Bshell function.

Example

Suppose that the table ttadv100, within company 100, is mirrored on the local system and on a remote  system (host_99) and that the table is audited on both systems:

long ret

string hosts(20)

ret = rdi.audit.hosts("ttadv100", 100, hosts)

| after this function call, the 'hosts' argument contains:

| "localhost, host_99" or "host_99, localhost"

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.column()

Syntax

long rdi.column( string column_name(18), ref string domain_name(14), ref long offset, ref long size, ref long dept, ref long type, ref long flag, ref string default_val(.) )

Description

This returns information about a specified table column.

Arguments

column_name	The name of the column about which you want to retrieve information.
domain_name	This returns the name of the column's domain.
offset	This returns the position of the column in the row.
size	This returns the size of the column, in bytes.
dept	This returns the depth of the column (array columns only).
type	This returns the database type of the column. For example, DB.LONG, DB.FLOAT, and so on. For a list of all possible database types, see Database handling.
flag	This returns a bit pattern that represents one or more of the following values: DB.ARRAY DB.FILLED DB.CHILD
default_value	This returns the default value of the column.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.column.combined()

Syntax

long rdi.column.combined( string column_name(18), ref string child_columns(18,32) )

Description

This returns information about the child columns of a specified column.

Arguments

column_name	The name of the column for which you wish to retrieve information.
child_colums	This returns an array containing the names of the child columns of the specified column. It can contain the names of up to 32 child columns.
Return values

The function returns the number of filled children.

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.date.input.format$()

Syntax

string rdi.date.input.format$( string date_format(7) )

Description

This returns the input format defined in the data dictionary for a specified date format. The input format can be any combination of day-in-week (D), week-in-year (W), and year (Y), or any combination of day-in-month (D), month-in-year (M), and year (Y). For example, if the function returns MDY, the input format on a form field must be month, day-in-month, and year (for example, 12311998).

Arguments

date_format	A date format defined in the data dictionary. This must be specified as %Dn[,lang], where n is the date format code and lang is the language code. See sprintf$().
Return values

The input format defined in the data dictionary for the specified date format.

Context

Bshell function.

Example

string inpformat(3)

inpformat = rdi.date.input.format$( "D002,3" )

| inpformat e.g. now contains DWY.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain()

Syntax

long rdi.domain( string domain_name(14), ref string oformat(.), ref string lechar(.), ref string ilchar(.), ref long adjust, ref string errmess(.), ref long range_expr_id [, ref long plen, ref string iformat(.) ] )

Description

This returns information about a specified domain.

Arguments

domain_name	The name of the domain for which you want to retrieve information.
oformat	This returns the output format of the domain.
lechar	This returns the legal characters for the domain.
ilchar	This returns the illegal characters for the domain.
adjust	This returns the domain's alignment mode. Possible values are: RDI.NONE RDI.LEFT RDI.RIGHT RDI.CENTER
errmess	This returns the domain's error message.
range_expr_id	This returns the ID of the compiled expression for the range check.
plen	This returns the maximum field length used on forms and reports.
iformat	This returns the domain's internal format.
Return values

The function returns the domain type, or -1 if an errors occurs. The possible domain types are:

DB.BYTE        	DB.DOUBLE       	DB.ENUM
DB.INTEGER     	DB.STRING       	DB.BITSET
DB.LONG        	DB.DATE         	DB.COMBINED
DB.FLOAT       	DB.TEXT         	DB.MULTIBYTE

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.byte()

Syntax

long rdi.domain.byte( string domain_name(14), ref long digits )

Description

This returns information about a domain of type DB.BYTE.

Arguments

domain_name	The name of the domain.
digits	This returns the number of digits defined for the byte-type domain.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.combined()

Syntax

long rdi.domain.combined( string domain_name(14), ref string child_domains(14,32) )

Description

This returns information about a domain of type DB.COMBINED.

Arguments

domain_name	The name of the domain.
child_domains	This returns an array containing the names of the children of the specified domain. It can contain the names of up to 32 children.
Return values

The number of filled children.

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.date()

Syntax

long rdi.domain.date( string domain_name(14), ref long digits )

Description

This returns information about a domain of type DB.DATE.

Arguments

domain_name	The name of the domain.
digits	This returns the number of digits defined for the date-type domain.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.double()

Syntax

long rdi.domain.double( string domain_name(14), ref long digits_before, ref long digits_after, ref long divide_fact, ref long round_code )

Description

This returns information about a domain of type DB.DOUBLE.

Arguments

domain_name	The name of the domain.
digits.before	This returns the number of digits before the decimal point in the specified domain.
digits_after	This returns the number of digits after the decimal point.
divide_factor	This returns the divide factor for the specified domain.
round_code	This returns the rounding mode for the specified domain. Possible values are: 0 truncate (for example, both 1.5 and 1.49 are rounded down to 1) 1 normal round (for example, 1.5 is rounded up to 2; 1.49 is rounded  down to 1) 2 round up (for example, both 1.5 and 1.49 are rounded up to 2)
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.enum()

Syntax

long rdi.domain.enum( string domain_name(14), ref long no_enum_items )

Description

This returns information about a domain of type DB.ENUM.

Arguments

domain_name	The name of the domain.
no_enum_items	The number of enum items in the specified domain.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.enum.value()

Syntax

long rdi.domain.enum.value( string domain_name, long enum_item, string language, ref string keyword(.), ref string descr(.), ref long value )

Description

This returns information about a specified item in an enumerated domain.

Arguments

domain_name	The name of the domain.
enum_item	The numeric code of the enum item for which you want to retrieve information.
language	The language code for the enumerated domain.
keyword	This returns the name of the specified enum item.
descr	This returns the description of the specified enum item.
value	This returns the value of the specified enum item.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.float()

Syntax

long rdi.domain.float( string domain_name(14), ref long digits_before, ref long digits_after, ref long divide_fact, ref long round_code )

Description

This returns information about a domain of type DB.FLOAT.

Arguments

domain_name	The name of the domain.
digits.before	This returns the number of digits before the decimal point in the specified domain.
digits_after	This returns the number of digits after the decimal point.
divide_factor	This returns the divide factor for the specified domain.
round_code	This returns the rounding mode for the specified domain. Possible values are: 0 truncate (for example, both 1.5 and 1.49 are rounded down to 1) 1 normal round (for example, 1.5 is rounded up to 2; 1.49 is rounded  down to 1) 2 round up (for example, both 1.5 and 1.49 are rounded up to 2)
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.integer()

Syntax

long rdi.domain.integer( string domain_name(14), ref long digits )

Description

This returns information about a domain of type DB.INTEGER.

Arguments

domain_name	The name of the domain.
digits	This returns the number of digits defined for the integer-type domain.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.long()

Syntax

long rdi.domain.long( string domain_name(14), ref long digits )

Description

This returns information about a domain of type DB.LONG.

Arguments

domain_name	The name of the domain.
digits	This returns the number of digits defined for the long-type domain.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.set()

Syntax

long rdi.domain.set( string domain_name(14), ref long no_enum_items )

Description

This returns information about a domain of type DB.BITSET.

Arguments

domain_name	The name of the domain.
no_enum_items	The number of set items in the specified domain.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.set.value()

Syntax

long rdi.domain.set.value( string domain_name(14), long enum_item, string language, ref string keyword(.), ref string descr(.), ref long value )

Description

This returns information about a specified item in a set-type domain.

Arguments

domain_name	The name of the domain.
enum_item	The numeric code of the set item for which you want to retrieve information.
language	The language code for the set domain.
keyword	This returns the name of the specified set item.
descr	This returns the description of the specified set item.
value	This returns the value of the specified set item.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.string()

Syntax

long rdi.domain.string( string domain_name(14), ref long length, ref long convert )

Description

This returns information about a domain of type DB.STRING.

Arguments

domain_name	The name of the domain.
length	This returns the current length of the string.
convert	This returns the conversion mode of the domain. Possible values are: RDI.UPPER RDI.LOWER RDI.NONE
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.domain.text()

Syntax

long rdi.domain.text( string domain_name(14), ref long digits )

Description

This returns information about a domain of type DB.TEXT.

Arguments

domain_name	The name of the domain.
digts	This returns the number of digits defined for the text-type domain.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.first.day.of.week()

Syntax

long rdi.first.day.of.week( )

Description

This function returns the first day of the week defined in the user file in the data dictionary. The returned number is relative to Sunday (=1). So, for example, if the function returns 2, this indicates that Monday is the user's first day of the week.

Return values

The user's first day of the week.

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.index()

Syntax

long rdi.index( string table_name(9), long index_no, ref long parts(32,3), ref long duplicate, ref long active )

Description

This returns information about  a specified index.

Arguments

table_name	The name of the relevant table (omit the leading 't').
index_no	The index ID.
parts	This returns the start position, length, and type of the index parts (up to a maximum of 32 parts): parts(i,1) Start position of part i in record parts(i,2) Length of part i. parts(i,3) Type of part i. The possible values are: DB.BYTE DB.TIME DB.INTEGER DB.TEXT DB.LONG DB.MAIL   DB.FLOAT  DB.ENUM DB.DOUBLE DB.BITSET DB.STRING DB.COMBINED   DB.DATE DB.MULTIBYTE
duplicate	Indicates whether or not duplicate values are permitted. Possible values are: TRUE duplicates permitted FALSE    duplicates not permitted
active	Indicates whether or not the index is active. Possible values are: TRUE index is active FALSE       index is not active
Return values

The number of filled parts.

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.reference()

Syntax

long rdi.reference( string column_name(18), ref string ref_column(18), ref long ref_mode, ref string ref_mess() [, long ignore_by_db] )

Description

If a database column references a column in another table, use this function to retrieve information about the referenced column.

Arguments

column_name	The name of the column which references the column about which you want to retrieve information.
ref_column	This returns the name of the column to which the column specified in column_name refers.
ref_mode	This returns the relation type. Possible values are: 1 compulsory 2 compulsory unless empty 3 not compulsory
ref_mess	This returns the error message of the referenced column.
ignore_by_db	This indicates whether or not a referential integrity check is performed by the database driver. Possible values are: 1 check ignored 0 check performed by database driver
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.table()

Syntax

long rdi.table( string table_name(9), ref long no_keys, ref long no_columns, ref long int_length, ref long real_length )

Description

This returns information about a specified table.

Arguments

table_name	The table name (omit the leading 't').
no_keys	This returns the number of indices that have been created on the table.
no_columns	This returns the number of columns that are in the table, including the following columns: Refcntd Refcntu _compnr _dlock _index<number>  (a column for each index)
int_length	This returns the length of the internal  buffer.
real_length	This returns the length of a row in the table.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


rdi.table.column()

Syntax

long RDI.TABLE.COLUMN( string table_name(9), long column_number, ref string column_name(18), ref string domain_name(14), ref long offset, ref long size, ref long dept, ref long type, ref long flag, ref string default_val(.) )

Description

This returns information about a specified column which is identified by the table name and the column number. Note that the first columns in the table are reserved for the following columns: Refcntd, Refcntu, _compnr, _dlock, and _index<number> (one column for each index).

Arguments

table_name	The name of the table in which the column occurs (omit the leading 't').
column_number	The column number.
domain_name	This returns the name of the column's domain.
offset	This returns the position of the column in the row.
size	This returns the size of the column, in bytes.
dept	This returns the depth of the column (array columns only).
type	This returns the database type of the column. For example, DB.LONG, DB.FLOAT, and so on. For a list of all possible database types, see Database handling.
flag	This returns a bit pattern that represents one or more of the following values: DB.ARRAY DB.FILLED DB.CHILD
default_value	This returns the default value of the column.
Return values

 0	success
-1	error

Context

Bshell function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.bobject.desc()

Syntax

void tt.bobject.desc( string b_object(10), ref string desc() mb)

Description

This retrieves the description of a specified business object (b_object) and stores it in the desc argument.

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.chm.appl.desc()

Syntax

long tt.chm.appl.desc( string appl(40), ref string desc() mb )

Description

This retrieves the description of a specified Chart Manager application.

Arguments

appl	The name of the Chart Manager application. This takes the form: ppmmxxxx, where pp is the package code, mmm is the module code, and xxx is the name of the Chart Manager application. This argument must refer to a record in the Maintain Chart Manager Application Data session (ttchm110m000).
desc	This returns the description of the specified Chart manager application.
Return values

0	success
1	error; application not found

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.chm.application()

Syntax

long tt.chm.application( string appl(40) )

Description

This checks if the specified Chart Manager application is present in the runtime dictionary.

Arguments

appl	The name of the Chart Manager application. This takes the form: ppmmxxxx, where pp is the package code, mmm is the module code, and xxx is the name of the Chart Manager application. This argument must refer to a record in the Maintain Chart Manager Application Data session (ttchm110m000).
Return values

0	application not found
1	application found

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.chm.chart()

Syntax

long tt.chm.chart( string appl(40), string chart_name(16) )

Description

This checks if the specified chart is present in the specified Chart Manager application.

Arguments

appl	The name of the Chart Manager application. This takes the form: ppmmxxxx, where pp is the package code, mmm is the module code, and xxx is the name of the Chart Manager application. This argument must refer to a record in the Maintain Chart Manager Application Data session (ttchm110m000).
chart_name	The name of the chart.
Return values

0	success
1	error; chart or application not found

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.chm.charttype()

Syntax

long tt.chm.charttype( string appl(40), string chart_type(16))

Description

This checks if the specified chart type is present in the specified Chart Manager application.

Arguments

appl	The name of the Chart Manager application. This takes the form: ppmmxxxx, where pp is the package code, mmm is the module code, and xxx is the name of the Chart Manager application. This argument must refer to a record in the Maintain Chart Manager Application Data session (ttchm110m000).
chart_type	The chart type.
Return values

0	success
1	error; chart type or application not found

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.company()

Syntax

long tt.company( long company, ref string comp_desc() mb, ref string deflt_curr(), ref long first_weekday )

Description

This returns information about a specified company.

Arguments

company	The company number.
comp_desc	This returns the company description.
deflt_curr	This returns a string containing the default currency of the company.
first_weekday	This returns the first day of the week defined for the company in the data dictionary.
Return values

0	error; company not found
1	success

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.currency()

Syntax

long tt.currency( string cur(3), ref string cur_desc() mb, ref string thous_sign, ref string dec_sign, ref string symbol() )

Description

This returns information about a specified currency.

Arguments

cur	The currency code.
cur_desc	This returns the currency description.
thous_sign	This returns the thousands sign for the specified currency.
dec_sign	This returns the decimal sign for the specified currency.
symbol	This returns the currency symbol.
Return values

0	error; currency not found
1	success

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.device()

Syntax

long tt.device( string device(9), ref string desc() mb, ref long device_type )

Description

This returns information about a specified device.

Arguments

device	The device name.
desc	This returns the device description.
device_type	This indicates the device type. Possible values are: 1  physical printer 2  logical printer 3  append to file 4  rewrite file 5  auxiliary port 6  direct 7  display 8  Windows printer 9  Mail API
Return values

0	error; device not found
1	success

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.field.desc()

Syntax

void tt.field.desc( string field(17), ref string desc() mb)

Description

This retrieves information about a specified table field.

Arguments

field	The field name.
desc	This returns the field description.
Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.index.desc()

Syntax

void tt.index.desc( string tabl(8), long indexnr, ref string desc() mb )

Description

This returns information about  a specified table index.

Arguments

tabl	The table name.
indexnr	The index number.
desc	This returns the description of the specified index.
Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.language()

Syntax

long tt.language( string lang, ref string desc() mb, ref string dec_sign, ref string thous_sign, ref string date_sep, ref string time_sep )

Description

This returns information about a specified language.

Arguments

lang	The language for which you want to retrieve information.
desc	This returns the language description.
dec_sign	This returns the decimal sign defined for the language.
thous_sign	This returns the thousands sign defined for the language.
date_sep	This returns the date separator defined for the language.
time_sep	This returns the time separator defined for the language.
Return values

0	error; language not found
1	success

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.library()

Syntax

long tt.library( string library.code, ref string library.desc() mb )

 Description

This returns information about a specified library.

Arguments

library.code	The library code.
library.desc	This returns the library description.
Return values

0	error; library not found
1	success

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.menu.desc()

Syntax

void tt.menu.desc( string menu(13), string par_menu, ref string desc() mb )

Description

This returns information about a specified menu.

Arguments

menu	The menu name.
par_menu	In the case of parallel menus, specify the menu sequence number here. Otherwise, enter 1.
desc	This returns the description of the specified menu.
Context

3GL library function.

Example

tt.menu.desc( "tfgld0000m000", "1", desc )

Related help topics

    Runtime dictionary information: overview and synopsis


tt.menu.present()

Syntax

long tt.menu.present( string menu(13), string par_menu )

Description

This checks if the specified menu of the current package is present in the runtime dictionary.

Arguments

menu	The menu name.
par_menu	In the case of parallel menus, specify the menu sequence number here. Otherwise, enter 1.
Return values

0	error; menu not found
1	success

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.report.desc()

Syntax

void tt.report.desc( string reprt(15), ref string desc() mb )

Description

This retrieves the description of a specified report (reprt) and stores it in the desc argument.  The report code has the following format  (it must be prefixed by an "r"):

"r" & package-code & module-code & report-code

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.reportgroup.exists()

Syntax

long tt.reportgroup.exists( string session(13), long report_group )

Description

This checks if a specified report group (report_group) is present in the definition of the specified session (session).

When more than one report is linked to a session, the reports may be grouped. Report groups are useful when specific reports must be used in specific situations. The current report group is defined in the predefined variable reportgrp (the default report group is 1).

Return values

TRUE	report group exists
FALSE  	report group does not exist

Example

if tt.report group.exists("tccom0401m000", 2) then

reportgrp = 2         | else reportgrp = 1 (default)

endif

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.session.desc()

Syntax

void tt.session.desc( string session(13), ref string desc() mb )

Description

This retrieves the description of a specified session (session) and stores it in the desc argument.

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.session.present()

Syntax

long tt.session.present( string session(13) )

Description

This checks if the specified session of the current package is present in the runtime dictionary.

Return values

0	session not present
1	session present but not in the user configuration
2	session present and in the configuration of the user

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.short.field.desc()

Syntax

void tt.short.field.desc( string field(17), long length, ref string desc() mb )

Description

This returns the description of a specified table field.

Arguments

field	The field name.
length	The number of characters of the description that must be returned.
desc	This returns the field description. Only the first length characters of the description are returned.
Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.table.desc()

Syntax

void tt.table.desc( string table(8), ref string desc() mb )

Description

This retrieves the description of a specified table (table) and stores it in the desc argument.

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.user()

Syntax

long tt.user( string user(12), ref string name() mb )

Description

This retrieves the name of the specified user (user) and stores it in the name argument.

Return values

0	error; user not found
1	success

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


get.session.permission()

Syntax

long get.session.permission( string session(13) )

Description

Retrieves the permission of the session (session) in a bit.or (see return values).

Return values

0	Error, session not found

SESSION_NO_PERMISSION

SESSION_DELETE_PERMISSION

SESSION_INSERT_PERMISSION

SESSION_MODIFY_PERMISSION

SESSION_DISPLAY_PERMISSION

SESSION_PRINT_PERMISSION

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.chart.desc()

Syntax

void tt.chart.desc( string chart, ref string desc() mb )

Description

This retrieves the name of the specified chart (chart) and stores it in the desc argument.

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


tt.comp.desc()

Syntax

void tt.comp.desc( ref string desc() mb )

Description

This retrieves the name of the current company and stores it in the desc argument.

Context

3GL library function.

Related help topics

    Runtime dictionary information: overview and synopsis


Searching and sorting data: overview and synopsis

Overview

Use these functions for searching and sorting data. Use qss.search() to search the data for a particular value. Use qss.sort() to sort the data. The data can be a string or an array of type string, long, or double.

The qss.search() function can perform either a linear or a binary search. A binary search is faster than a linear search, but the data must first be sorted by qss.sort(). In practice, therefore, a binary search is efficient only when the data does not often change and so does not require repeated sorting. If the data is frequently modified, use a linear search on unsorted data instead; this avoids frequent calls to qss.sort().

Synopsis

long	qss.search	( long flag, void search, ref void tbl,    ref long def [, long dept] )
long	qss.sort	( ref void tbl, ref long def [, long dept] )
Related help topics

    Searching and sorting data:  sample programs


qss.search()

Syntax

long qss.search( long flag, void search, ref void tbl, ref long def [, long dept] )

Description

This searches a specified array for a particular value, which is referred to as the search key. By default, it reads the array sequentially until it finds the specified value (that is, it performs a linear search). To perform a binary search instead, you must first sort the data with qss.sort() and then call qss.search() with the flag argument set to QSS.SRC.IS.SORTED.

Arguments

flag	This specifies which array element is to be retrieved and the type of search to be performed. You can set the argument to one of the following possible values: QSS.FIRST Find the first record in the array; the search argument is ignored. QSS.LAST Find the last record in the array; the search argument is ignored. QSS.GT Find the first record greater than the search key. QSS.GTEQ Find the first record greater than or equal to the search key.  QSS.LESS Find the first record less than the search key. QSS.EQLE Find the first record less than or equal to the search key.  QSS.EQUAL Find the first record equal to the search key. QSS.NE Find the first record not equal to the search key. You can combine each of these options with one or more of the following options:
	QSS.SRC.IS.SORTED	Specifies a binary search. The array must previously have been sorted by using qss.sort().
	QSS.LOOKUP.FOR.STRUCT	When this flag is set, the function searches the array for a specified record pattern – that is, it searches for an array element that matches both the structure and value of the search key. The search argument must have the same layout and length as the elements in tbl.  When this flag is not set, the search argument is constructed as the concatenation of the key fields defined by the def argument (see Example 2).
	QSS.SRC.DUPL.ALLOWED	Specifies that the search key can occur more than once in the source array.
search	The value that you want to search for in the specified array. This is the search key.
tbl	This specifies the array that must be searched. It can be a string or an array of type string, long, or double, but it is usually an array of strings.
def	This indicates how the system is to search the array and against what conditions it must test the elements of the array.  The argument must be declared as follows: long def(x,4) | x is the number of search fields You can define several search fields (1 to x). For each search field, you define the four search properties by using the following functions. In each case, the field_number argument specifies the sequence number (1 to x) of the search field. • void qss.start( ref long def, long field_number, long position ) This indicates the search field's start position in the array element. For example, this allows you to search a string array for a character combination starting at the fourth character of the array element. • void qss.way( ref long def, long field_number, long way ) This defines the search order that must be used if the flag QSS.SRC.IS.SORTED is set. The argument way can be set to QSS.UP (ascending search) or QSS.DOWN (descending search). • void qss.type( ref long def, long field_number, long type ) This specifies the search field's type – for example, DB.LONG, DB.DOUBLE, DB.STRING, DB.DATE, and so on. • void qss.length( ref long def, long field_number, long length ) This specifies the length of the search field. This option is valid only for strings.  If you define fewer search fields than you have declared, you must close the def argument by calling qss.start() with a start position of zero. For example, if you have declared three search fieldss, as follows: def(3,4) but then create only two search fields, you must close the definition with the following call: qss.start(def,3,0)
dept	This indicates the number of array elements (starting with the first element) that must be searched if the function is not intended to search the entire array. By default, the function searches the entire array until it finds the required value.
Return values

>0	index in the array where the search key was found
-1	error; search argument not found
-11	search argument must be of same type as array;
def is not of type long array or tbl not of type array
-12	search argument not correct; string not expected
-13	dept must be positive
-14	def argument not correctly declared
-15	search argument does not fit in declared array
-16	QSS.TYPE not correct
-17	tbl argument not correct
-18	no definition found in def
-21	flag LOOKUP.FOR.STRUCT is used; search argument must be a string
-22	search argument not correct; probably a size problem – size of search
must match size of an element in tbl if LOOKUP.FOR.STRUCT is set or
(if LOOKUP.FOR.STRUCT is not set) must be at least the sum of lengths
of the key fields (set by qss.length())
-23	search argument not correct; probably a type problem

Context

Bshell function.

Related help topics

    Searching and sorting data:  overview and synopsis
    Searching and sorting data:  sample programs


qss.sort()

Syntax

long qss.sort( ref void tbl, ref long def [, long dept] )

Description

This function performs a fast sort a specified array.

Arguments

tbl	The name of the table or array to be sorted.
def	This determines how the array is to be sorted. The argument must be declared as follows: long def(x,4) | x is the number of sort fields You can define several sort fields (1 to x). When performing a sort, the system sorts on the first sort field. Then, if there are duplicate values in the first sort field, the system sorts on the second sort field, and so on.  For each sort field, you define the four sort properties by using the following functions. In each case, the field_number argument specifies the sequence number (1 to x) of the sort field. • void qss.start( ref long def, long field_number, long position ) This specifies the start position of the sort field in the array elements.  • void qss.way( ref long def, long field_number, long way ) This defines the sort order. The argument way can be set to QSS.UP (ascending sort) or QSS.DOWN (descending sort). • void qss.type( ref long def, long field_number, long type ) This specifies the sort field's type, for example. DB.LONG, DB.DOUBLE, DB.STRING, DB.DATE, and so on. • void qss.length( ref long def, long search_condition, long length ) This specifies the length of the sort field. This option is valid only when sorting strings. If you define fewer sort fields than you have declared, you must close the def argument by calling qss.start() with a start position of zero. For example, if you have declared three sort fields, as follows: def(3,4) but then create only two sort fields, you must close the definition with the following call: qss.start(def,3,0)
dept	This indicates the number of array elements to be sorted if the function is not intended to sort the entire array. By default, the function sorts the entire array.
Return values

 0	success
-1	error
-11	def is not of type long array or tbl not of type array
-13	dept must be positive
-14	def argument not correctly declared
-16	QSS.TYPE not correct
-17	tbl argument not correct
-18	no definition found in def

Context

Bshell function.

Related help topics

    Searching and sorting data:  overview and synopsis
    Searching and sorting data:  sample programs


Table searching and sorting: sample programs

Example 1

| You want to sort the following (string) array.

| The number is stored as a long on positions 8 to 11 by means of

| the function store.long(number, string_array(8,X))

string    string_array(11,5)

long      sort_def(2,4), search_def(1,4), ret

qss.start(sort_def, 1, 8)

qss.way(sort_def, 1, QSS.UP)

qss.type(sort_def, 1, DB.LONG)

qss.start(sort_def, 2, 1)

qss.way(sort_def, 2, QSS.DOWN)

qss.type(sort_def, 2, DB.STRING)

qss.length(sort_def, 2, 5)

| The function executes an ascending sort on position 8 of the

| string. The sort must be carried out as if this is a long value.

| In case of equal values, a descending sort is performed on the

| first five characters of the string.

ret = qss.sort(string_array, sort_def)

| After sorting the array will look as follows:

| If you want to know in which element the character combination

| 'iiii' is located and be sure that the argument to be searched

| is unique and cannot occur in the last two elements, the

| following search action must be started.

| It is assumed that the array is sorted.

qss.start(search_def, 1, 2)          | search from position 2

qss.type(search_def, 1, DB.STRING)

qss.length(search_def, 1, 4)

ret = qss.search(QSS.SRC.IS.SORTED + QSS.EQUAL, "iiii",

string_array, search_def, 4)

| ret will now contain the value 2

| if the search argument is not unique, the following search

| action may be started:

ret = qss.search(QSS.SRC.IS.SORTED + QSS.EQUAL +

QSS.SRC.DUPL.ALLOWED, "iiii",

                      string_array, search_def, 4)

Example 2

string  key(50)

string  bank(50,10)

long    country(2,4)        | Key on country code and bank number

long    sort_def(1,4)

long    index

|            12345678901234567890123456789012345678901234567890

bank(1,1) = "10010ING                           Utrecht     NL "

bank(1,2) = "10020ABN / AMRO                    Amsterdam   NL "

bank(1,3) = "10030Rabobank                      Ede         NL "

bank(1,4) = "20020National Westminster Bank     London      GB "

bank(1,5) = "30010Sparkasse                     Munchen     D  "

bank(1,6) = "40010Credit Lyonnais               Paris       F  "

bank(1,7) = "90010Citi Bank                     New York    USA"

bank(1,8) = "90020NBD Bank                      Grand RapidsUSA"

qss.start (country, 1, 48)

qss.type  (country, 1, DB.STRING)

qss.length(country, 1, 3)

qss.start (country, 2, 1)

qss.type  (country, 2, DB.STRING)

qss.length(country, 2, 5)

| WITHOUT LOOKUP.FOR.STRUCT

key = "NL"

index = qss.search(QSS.GTEQ, key, bank, country)

while index > 0 and bank(48,index;3) = "NL "

| process struct

key = bank(48,index;3) & bank(1,index;5)

index = qss.search(QSS.GT, key, bank, country )

endwhile

| WITH LOOKUP.FOR.STRUCT

key = "                                               NL "

index = qss.search(QSS.LOOKUP.FOR.STRUCT+QSS.GTEQ,

key, bank, country)

while index > 0 and bank(48,index;3) = "NL "

| process struct

index = qss.search(QSS.LOOKUP.FOR.STRUCT+QSS.GT,

bank(1,index), bank, country)

endwhile

| Sorting bank table on bank description

qss.start (sort_def, 1, 6)

qss.type  (sort_def, 1, DB.STRING)

qss.length(sort_def, 1, 2)

index = qss.sort( bank, sort_def)

Related help topics

    Searching and sorting data:  overview and synopsis


Spooling: overview and synopsis

Overview

Use these functions to handle printer devices and printing.

Synopsis

void	spool.buf	( const string buffer(.), long length )
void	spool.close	( )
void	spool.line	( )
long	spool.open	( string reportname(15), string device(14),    long mode )
Predefined variables

The following predefined variables are available for use with the spooler functions:

long	spool.date	Date to print.
long	spool.fontnumber	Font number: 1 LARGE 2 SMALL 3 MIDDLE
long	spool.id	Spooler ID.
long	spool.left.mrg	Left margin.
long	spool.pr.copies	Number of copies.
long	spool.pg.length	Length of page.
long	spool.pg.width	Width of page, including left margin.
long	spool.time	Time to print.
long	spool.view.rtl	Specifies whether the report is in a bidirectional language: true   bidirectional language false non-bidirectional language
string	spool.device(14)	Name of spooler device.
string	spool.fileout(100)	Path name for spooler output file.
string	spool.paper.type(6)	Type of paper.
string	spool.pr.line(300)	Line to print.
string	spool.report(20)	Report to be printed.
See also

Reports


spool.buf()

Syntax

void spool.buf( const string buffer(.), long length )

Description

This sends the contents of the buffer argument to the current spooler. The current spooler must be already open. The name of the current spooler is available in the predefined variable spool.id.

No new line characters or other separators are sent to the spooler. To include these, you must program them in the buffer yourself. The length argument specifies the length of the send string. If this is 0, the spooler calculates the length of the buffer at runtime.

Context

3GL library function.

Related help topics

    Spooling:  overview and synopsis


spool.close()

Syntax

void spool.close()

Description

This closes the spooler specified by the predefined variable spool.id. By default spool.id contains the ID of the current spooler. If more than one spooler is currently open, set spool.id to the ID of the required spooler before you call this function. After the spooler is closed, spool.id is set to zero.

Context

3GL library function.

Related help topics

    Spooling:  overview and synopsis


spool.line()

Syntax

void spool.line()

Description

This sends the contents of the predefined variable spool.pr.line and a newline character to the spooler specified by the predefined variable spool.id. By default spool.id contains the ID of the current spooler. If more than one spooler is currently open, set spool.id to the ID of the required spooler before you call this function. After this function has been executed, spool.pr.line is cleared.

Note that this function uses the relevant spooler predefined variables.

Context

3GL library function.

Related help topics

    Spooling:  overview and synopsis


spool.open()

Syntax

long spool.open( string reportname(15), string device(14), long mode )

Description

This opens a specified spooler device.

Arguments

reportname device	If you specify a report name in the reportname argument, it is stored in the predefined variable spool.report, and the current date and time are stored in the predefined variables spool.date and spool.time. The settings for the predefined variables spool.fontnumber, spool.paper.type, and spool.left.mrg are taken from the default settings for the specified report. If you specify a device name in the device argument, it is stored in the predefined variable spool.device. The settings for the predefined variables spool.paper.type, spool.left.mrg, spool.fileout, and spool.pg.length are taken from the default settings for the specified device.  If both reportname and device are specified, the defaults for the predefined variables are taken from the default settings for the specified report. The device name is stored in spool.device.  If both reportname and device are empty (""), the predefined variables retain their values from the previous spool action.
mode	This determines whether or not a window is displayed where the user can change the device settings: 0 no window displayed 1 window displayed with a Cancel button 2 window displayed without a Cancel button
Note

To use several spoolers simultaneously, first open all the spoolers. Then set the predefined variable spool.id to the relevant spooler ID before each spoolline() function call.

Return values

  0	spooler cannot be opened
>0	ID of opened spooler – this is also available in spool.id

Context

3GL function library.

Example 1

long spooler

spooler = spool.open("","",1)

spooler = spool.open("rtccom040101000","D",0)

Example 2

long spooler1, spooler2

spooler1 = spool.open("", "", 1)

spooler2 = spool.open("", "1", 0)

spool.pr.line = "Hello spooler1"

spool.id = spooler1

spool.line()

spool.pr.line = "Hello spooler2"

spool.id = spooler2

spool.line()

spool.id = spooler1

spool.close()          | close spooler 1

spool.id = spooler2

spool.close()          | close spooler 2

Related help topics

    Spooling:  overview and synopsis


SQL query extensions: overview

By default, the standard program reads the entire main table when retrieving data for a particular form, even though some records and fields may not be required. By default also, the standard program reads only those reference table fields that are included on the form, even though the UI script and/or the DAL script may require other reference table fields.

Query extensions define conditions that the standard program adds to the SELECT, FROM, and WHERE clauses of a database query in order to filter out unwanted records and fields of the main table and in order to include in the query all reference fields required by the form, UI script, and DAL script.

In the UI script, you program query extensions to minimize the number of records and fields of the main table read by the query and to retrieve any reference tables field that are required by the UI script but are not on the form. In the DAL script, you program query extensions to retrieve reference table fields that are required by the DAL script.

When the standard program executes a database query, it automatically adds the query extensions defined in UI and DAL scripts. So, in the case of main table fields, the standard program reads only those fields and records that meet the conditions set in the query extension in the UI script. In the case of reference tables, the standard program reads those fields included on the main table and also those mentioned in the UI and DAL scripts.

Building DAL query extensions

•	Identify the reference table fields required for method.is.allowed().

•	Identify the reference table fields required for executing checks in property and object hooks.

•	Extend the DAL query in the most efficient way possible (for example, avoid using table.*).

For example, define a normal query that specifies all the referenced fields/tables and then filter out unwanted fields/tables. Check the joins carefully to ensure that multiple records are not selected. Then split the query into strings appropriate for input to the query.extend.* functions.

•	Because the query must return the most recent values for reference table fields, you must use the buffered values for the fields. To do this, append a colon [:] to properties of the current class that are used in the query.extend.where() function.

•	Normally, you specify EXTEND_OVERWRITE as the mode for the query.extend.* functions. Use EXTEND_APPEND only when you want to further extend a query that has already been extended.

Building UI query extensions

•	Identify the reference table fields that are used in the UI script but not included on the form.

•	Eliminate any fields that have been included in the DAL query extension of the main table.

•	Identify the conditions required for filtering the data.

•	Identify the form fields and external variables that require table values and bind the form fields to the table fields.

•	Construct the query extension in the most efficient way possible. When dealing with non-zoom sessions, program the query extension in the before.program section. When dealing with zoom sessions, program the query extension in the before.zoom section. Note that, for zoom sessions, you use query extensions only for filtering out unwanted data from the main table.

•	Normally, you specify EXTEND_OVERWRITE as the mode for the query.extend.* functions. Use EXTEND_APPEND only when you want to extend further a query that has already been extended.

Related topics

•	SQL query extensions: synopsis


SQL query extensions: synopsis

void	clear.query.extend.in.zoom	( )
void	query.extend.select	( string extension_string [, mode] )
void	query.extend.select.in.zoom	( string extension_string )
void	query.extend.from	( string extension_string [, mode] )
void	query.extend.from.in.zoom	( string extension_string )
void	query.extend.where	( string extension_string [, mode] )
void	query.extend.where.in.zoom	( string extension_string )
Related topics

•	SQL query extensions: overview


clear.query.extend.in.zoom()

Syntax

void clear.query.extend.in.zoom()

Description

This clears a query extension that was previously defined in the before.zoom section of a zoom session. The standard program automatically clears the extension in the after.zoom section of the session. Use this function to force an earlier removal of the query extension. For example, to clear the query extension before defining an extension for another zoom session.

Context

4GL library function.

You can use this function only in the before.zoom section of UI scripts.

Example

See Query extensions: sample program

Related topics

•	SQL query extensions: overview

•	SQL query extensions: synopsis


query.extend.select()
query.extend.select(), query.extend.select.in.zoom()

Syntax

void query.extend.select( string extension_string [, mode] )

void query.extend.select.in.zoom( string extension_string )

Description

Use these to construct a query extension for the SELECT clause of a database query. Use query.extend.select() for non-zoom sessions. Use query.extend.select.in.zoom() for defining query filters for zoom sessions.

Arguments

extension_string	A string containing the names of the fields to be included in the SELECT statement. Use commas [,] to separate the field names.
mode	This optional argument can have one of the following values: EXTEND_OVERWRITE replaces any existing query extension  (this is the default mode) EXTEND_APPEND appends this extension to the existing extension
Context

4GL library functions.

You can use query.extend.select() in the before.program section of UI scripts and in the before.open.object() hook of DAL scripts. You can use query.extend.select.in.zoom() only in the before.zoom section of UI scripts.

Example

See Query extensions: sample program

Related topics

•	SQL query extensions: overview

•	SQL query extensions: synopsis


query.extend.from()
query.extend.from(), query.extend.from.in.zoom()

Syntax

void query.extend.from( string extension_string [, mode] )

void query.extend.from.in.zoom( string extension_string )

Description

Use this to construct a query extension for the FROM clause of a database query. Use query.extend.from() for non-zoom sessions. Use query.extend.from.in.zoom() for defining query filters for zoom sessions.

Arguments

extension_string	A string containing the names of the fields to be included in the FROM statement. Use commas [,] to separate the field names.
mode	This optional argument can have one of the following values: EXTEND_OVERWRITE replaces any existing query extension  (this is the default mode) EXTEND_APPEND appends this extension to the existing extension
Context

4GL library functions.

You can use query.extend.from() in the before.program section of UI scripts and in the before.open.object() hook of DAL scripts. You can use query.extend.from.in.zoom() only in the before.zoom section of UI scripts.

Example

See Query extensions: sample program

Related topics

•	SQL query extensions: overview

•	SQL query extensions: synopsis


query.extend.where()
query.extend.where(), query.extend.where.in.zoom()

Syntax

void query.extend.where( string extension_string [, mode] )

void query.extend.where.in.zoom( string extension_string )

Description

Use this to construct a query extension for the WHERE clause of a database query. Use query.extend.where() for non-zoom sessions. Use query.extend.where.in.zoom() for defining query filters for zoom sessions.

Arguments

extension_string	A string containing the names of the fields to be included in the WHERE statement. Use commas [,] to separate the field names.
mode	This optional argument can have one of the following values: EXTEND_OVERWRITE replaces any existing query extension  (this is the default mode) EXTEND_APPEND appends this extension to the existing extension
Note

Whenever possible, use the REFERS TO construction instead of the ._INDEX1 = construction. The standard program always uses the REFERS TO construction and automatically removes all duplicates.

In BaanERP, this function replaces the predefined variable query.extension that was used in earlier versions of the software.

Context

You can use query.extend.where() in the before.program section of UI scripts and in the before.open.object() hook of DAL scripts. You can use query.extend.where.in.zoom() only in the before.zoom section of UI scripts.

Example

See Query extensions: sample program

Related topics

•	SQL query extensions: overview

•	SQL query extensions: synopsis


Query extensions: sample program (simple)
Query extensions: sample program

This is an example of a simple query extension programmed in the DAL for the main table 'qmptc015'. The unit (qmptc021.cual) of the algorithm (qmptc015.algo) must have the same physical quantity as the unit defined in the table (qmptc015.chun).

function extern long before.open.object.set()

{

query.extend.select("qmptc021.cual")

query.extend.from("qmptc021")

query.extend.where(":qmptc015.algo refers to qmptc021")

}

function extern long qmptc015.algo.check(long has_changed)

{

if has_changed then

tcibd.dll0003.read.mcs001.tccu(qmptc015.chun,

  	 qmptc021.cual, basu.tccu, unit.tccu)

if basu.tccu <> unit.tccu then

dal.set.error.message("qmptcs011526")

|* Algorithm and characteristic units must have the

|* same physical quantity

return(DALHOOKERROR)

endif

endif

}

Related topics

•	SQL query extensions: overview

•	SQL query extensions: synopsis


Starting and stopping programs: overview and synopsis

Overview

Use these functions for starting and stopping programs and sessions.

Synopsis

void	abort	( )
void	end	( )
void	exit	( [EXITVALUE] )
long	run.baan.prog	( const string progname, const string    arguments, long mode )
long	run.prog	( const string progname, const string arguments,   long mode )
long	shell	( string command(.), long mode )
string	start.session	( long mode, const string session.code,    const string zoomname, const string    returnfld )
void	stop	( )
string	zoom.to$	( string process(14), long zoomcode,    string zoomname(18), string returnfld(18),   long formpos )


abort()

Syntax

void abort()

Description

This cancels execution of a program script and returns control to the application. The database is not updated. The function has the same effect in both 3GL and 4GL scripts.

Context

Bshell function.

Related help topics

    Starting and stopping programs:  overview and synopsis


end()

Syntax

void end()

Description

When used in a 3GL script, this ends the program and returns control to the application. The database is not updated.

When used in a 4GL script, the function has the same effect as the end.program standard command. When a 4GL script calls end() or execute(end.program), changes are stored in the database and  the program ends. Before the program ends, any before.choice subsections in a choice.end.program section are executed. The after.program section is also executed, if present.

Note

The functions end(), stop(), and exit() (without an exitvalue argument) in 3GL programs, and the function stop() in 4GL programs, all have the  same effect. That is, the program ends and returns control to the application. The database is not updated.

Context

3GL and 4GL library function.

Related help topics

    Starting and stopping programs:  overview and synopsis


exit()

Syntax

void exit( [EXITVALUE] )

Description

When included in a 3GL program that is not activated by a 4GL program, exit() has the same effect as end() and stop() in a 3GL program.

When included in a 4GL script, or in a 3GL program that is activated from a 4GL program with zoom.to$(), an exit value is returned to the calling program. The exitvalue argument can be of any type (except an array). It is always converted to a string. If no exit value is specified, an empty string is returned.

Context

Bshell function.

Related help topics

    Starting and stopping programs:  overview and synopsis


run.baan.prog(), run.prog()

Syntax

long run.baan.prog( const string progname, const string arguments, long mode )

long run.prog( const string progname, const string arguments, long mode )

Description

The function run.baan.prog() runs a BAAN program.

The function run.prog() runs an operating system command. It is a system-dependent function. It must not be used in applications that are distributed across different platforms.

Arguments

progname	The name of the program or command to be executed. run.baan.prog() expands progname to $BSE/bin/progname{release}.  If the progname argument in run.prog() does not supply the full path (absolute or relative), the system searches for the command using the standard facilities of the operating system platform (for example, under UNIX, all PATH elements are searched). The argument can specify a remote host. For example, if progname is “tahoe!sort”, the function runs the sort program on the tahoe host. The maximum number of remote programs that can run concurrently depends on available system resources.
arguments	The function start the program or command with the parameters specified here.
mode	This specifies the execution mode of the program or command. The possible values are: RP_WAIT      wait for the program to finish RP_NOWAIT    run as a background program
Note

Output from the program cannot be displayed. If the -q switch is available, use this to output the program results to a file.

Use these functions instead of the shell() function used in previous versions of BAAN.

Return values

  0	program executed successfully
<0	program could not be started
>0	program did not execute successfully

Note that the return value cannot be retrieved when the mode argument is set to RP_NOWAIT.

Context

Bshell function.

Related help topics

    Starting and stopping programs:  overview and synopsis


shell()

Syntax

long shell( string command(.), long mode )

Description

This starts the vt200 compatible terminal emulator to execute the command specified in the command argument. The shell (for example, UNIX, VMS, or MPE) process is connected with the bshell by means of a pseudo tty. Running a shell does not block the bshell. You can switch to another window and perform other tasks.

Arguments

command	The command to be executed.
mode	This can be a combination of the following options:
	0	No main window is created for the terminal emulator. This may result in starting a terminal emulator in the main window of the process that calls the shell function. The first status field displays "ottstpvtemul" while the shell process is running.
	SHELL_BACKGROUND	Background processing. No main window is created and the process produces no output. This is similar to SHELL_NO_OUTPUT + SHELL_NO_WAIT.
	SHELL_CLS	Current screen is cleared before the command is executed.
	SHELL_CONFIRM	Displays the message "Press RETURN", or its local equivalent, in the right lower corner of the window after the shell process has finished.
	SHELL_MAXWINSIZE	The terminal emulator sizes its main window to the maximum size. A new main window is created.
	SHELL_NO_WAIT	The shell function does not wait for the emulator to end. This is useful for starting shell processes (such as an editor) while continuing processing. The variable shell.pid is set to the process number of the activated terminal emulator process. A new main window is created.
	SHELL_NO_OUTPUT	The terminal emulator does produce any output. This implies the SHELL_NO_MWINDOW option.
	SHELL_MWINDOW	A main window is created. This displays the output of the shell command.
Notes

This function is supported for backward compatibility only. In new applications, use run.prog() and run.baan.prog() instead.

The function is available only for programs running under UNIX, and not for programs running under Windows NT.

Return values

>0	return code of command
  0	success
 -1	maximum number of pty's is reached; general error code
 -2	cannot open the master pty
 -3	pipe command failed
 -4	fork of reader process or shell process failed
 -6	cannot start terminal emulator

Examples

1	Run a shell command that creates no main window. Output can appear on the current main window. The bshell process waits for the shell command to end.

ret = shell("rm $BSE/tmp/file", 0)

2	Similar to example 1. The terminal emulator displays "Press <RETURN>" and waits for confirmation after the shell process has ended.

ret = shell("ls -l", SHELL_CONFIRM)

3	Run a shell command in the background. Output is displayed in a separate main window. The main window is stretched to its maximum possible size on the terminal display.

ret = shell("vi helloworld.c", SHELL_NO_WAIT + SHELL_MAXWINSIZE)

4	Run a shell command that produces no output. Errors can be caught by checking the return value of the shell function.

ret = shell("cp /tmp/a /tmp/b", SHELL_NO_OUTPUT)

Context

Bshell function.

Related help topics

    Starting and stopping programs:  overview and synopsis


start.session()

Syntax

string start.session( long mode, const string session.code, const string zoomname, const string returnfld )

Description

This starts a session from a program script.

Arguments

mode	Specifies the start mode for the new session. Possible values are: MODAL The parent session is blocked until the child session exits. MODELESS Parent and child are parallel sessions that can be manipulated  simultaneously. For dynamic sessions, the possible values are: SINGLE_OCC The session is started as a single-occurrence (details)  session. MULTI_OCC The session is started as a multioccurrence (overview) session.
session.code	The code of the session that must be started.
zoomname	The name of the calling process. This is used in the zoom.from sections in the child session. If no name is provided here, zoom.from sections in the child session are not executed.
returnfld	Indicates the name of the variable to be returned by the function. If you specify an empty string, the function returns the exit value of the zoom process. This argument is relevant only if the start mode is MODAL. You can also specify an index name in this variable. In this case, the values of all component fields of the index are set by the zoom session and exported back to the calling process.
Notes

You can use start.session() in both 3GL and 4GL programs, but only for starting 4GL sessions.

The function replaces other functions for starting sessions, such as zoom.to$() and start.main.session().

Return values

If you specify a variable name in the returnfld argument, the function returns the value of the specified variable. If you specify an index name in returnfld, the function returns the value of returnfld. If you specify an empty string in returnfld, the function returns the exit value of the zoom process. If the session is canceled, the function returns an empty string.

Context

4GL library function.

Related help topics

    Starting and stopping programs:  overview and synopsis


stop()

Syntax

void stop()

Description

This ends the program. The program immediately exits without updating the database and without executing any further sections. The function has the same effect in both 3GL and 4GL scripts.

Note

The functions end(), stop(), and exit() (without an exitvalue argument) in 3GL programs, and the function stop() in 4GL programs, all have the  same effect. That is, the program ends and returns control to the application. The database is not updated.

Context

3GL and 4GL library function.

Related help topics

    Starting and stopping programs:  overview and synopsis


zoom.to$()

Syntax

string zoom.to$( string process(14), long zoomcode, string zoomname(18), string returnfld(18), long formpos )

Description

Use this to zoom to another session or menu.

Arguments

process	Specifies the name of the session or menu that must be started.
zoomcode	This can be either Z.MENU or Z.SESSION, depending on whether it is a menu or session that is being started.
zoomname	The name of the calling process. This is used in the zoom.from sections in the called process. If no name is provided here, zoom.from sections in the child session are not executed.
returnfld	Indicates the name of the variable to be returned by the function. It must be the name of a variable in the called process. If an empty string is specified here, the function returns the exit value of the zoom process. If the argument is not filled, the function returns nothing.
formpos	Specifies the form position for displaying the window. The default is 0
Note

This function is supported for backward compatibility only. In new applications, use start.session() instead.

Return value

The variable specified in the returnfld argument.

Context

Bshell function.

Use this function only in combination with the standard program.

Related help topics

    Starting and stopping programs:  overview and synopsis


String operations: overview

Use these functions to manipulate strings in various ways. For example:

•	to check whether a string contains a long value or spaces

•	to check the number of characters or bytes in a string

•	to load numeric values stored in a string into variables of type long or double

•	to convert a number contained in a string to its numeric representation

•	to convert an integer or floating point number to a string

•	to convert a string to upper case or lower case

•	to search for a substring within a string

•	to strip leading and trailing spaces from strings

•	to align strings

•	to store a long or double in a string.

 Related help topics

    String operations:  synopsis


String operations: synopsis

string	concat$	( string separator, expr, ... )
long	isdigit	( string_expr )
long	isspace	( string_expr )
long	len	( string_expr )
long	len.in.bytes	( string_expr )
long	load.byte	( string record(long spos) )
double	load.double	( string record(long spos)    [, long endian] )
double	load.float	( string record(long spos)    [, long endian] )
long	load.long	( string record(long spos)    [, long endian] )
long	load.short	( string record(long spos)    [, long endian] )
long	lval	( string_expr )
void	not.fixed	( string string_var(.) )
long	pos	( string source(.), string pattern(.) )
long	rpos	( string source(.), string pattern(.) )
long	set.strip.mode	( long table_id, long mode )
long	set.symbol.strip.mode	( ref string str, long mode )
string	shiftc$	( string strg(.) )
string	shiftl$	( string strg(.) )
string	shiftr$	( string strg(.) )
void	store.byte	( long lng, ref string rec )
void	store.double	( double dbl, ref string rec )
void	store.float	( double dbl, ref string rec )
void	store.long	( long lng, ref string rec )
void	store.short	( long lng, ref string rec )
string	str$	( num_expr )
string	string.set$	( string_expr, num_expr )
string	strip$	( string strg(.) )
string	tolower$	( string_expr )
string	toupper$	( string_expr )
long	tt.align.according.domain	( string string_in(.), ref string    string_out(), string domain_name )
double	val	( string_expr )
Related help topics

    String operations:  overview


concat$()

Syntax

string concat$( string separator, expr, ... )

Description

This converts one or more expressions to strings and merges the expressions into a single string. You can use string.scan() to split the string again into its individual parts.

This function is used mainly by the report processor to save unsorted records in a sequential file for subsequent sorting.

Arguments

separator	The separator to be placed between individual values in the merged string.
expr ...	One or more expressions of type long, double, or string.
Context

Bshell function.

Example

string    ret(100)

long      a

string    b(5)

double    d

a = 10

b = "hello"

d = 1.123456

ret = concat$( "|",a*10,b,d )     | ret now contains "100|hello|1.123456"

Related help topics

    String operations:  overview
    String operations:  synopsis


isdigit()

Syntax

long isdigit( string_expr )

Description

This tests whether the result of string_expr contains a long value.

Return values

TRUE	string contains a long
FALSE 	string does not contain a long

Context

Bshell function.

Example

string str1(20)

if ( not isdigit(str1) ) then

message( "'%s' is not a number", str1 )

endif

Related help topics

    String operations:  overview
    String operations:  synopsis


isspace()

Syntax

long isspace( string_expr )

Description

This tests whether the result of string_expr contains only spaces or is empty.

Return values

TRUE	string is empty or contains only spaces
FALSE     	string is not empty and contains characters other than spaces

Context

Bshell function.

Example

string str1(20)

if ( not isspace(str1) ) then

message( "'%s' is not empty", str1 )

endif

Related help topics

    String operations:  overview
    String operations:  synopsis


len()

Syntax

long len( string_expr )

Description

This returns the number of characters in string_expr. For strings declared as FIXED, the total length of the string is returned. For non-fixed strings, the current length is returned. To retrieve the length of FIXED strings, excluding trailing spaces, use strip$().

Context

Bshell function.

Example

long      lng

string    var(20)

string    fix(20)    fixed

var = "abc"

fix = "abc"

lng = len( var )             | Returns 3

lng = len( fix )             | Returns 20

lng = len( strip$(fix) )     | Returns 3

Related help topics

    String operations:  overview
    String operations:  synopsis


len.in.bytes()

Syntax

long len.in.bytes( string_expr )

Description

This returns the number of bytes in string_expr. In the case of ASCII characters, the number of bytes equals the number of characters. In the case of multibyte characters, each character can consist of one or more bytes.

Context

Bshell function.

Related help topics

    String operations:  overview
    String operations:  synopsis


load.byte(), load.double(), load.float(), load.long(), load.short()

Syntax

long load.byte( string record(long spos) )

double load.double( string record(long spos) [, long endian] )

double load.float( string record(long spos) [, long endian] )

long load.long( string record(long spos) [, long endian] )

long load.short( string record(long spos) [, long endian] )

Description

These load numeric values stored in a string into variables of type long or double. These functions are machine independent and can be used (for example) in network communications.

Arguments

record	The string containing the numeric value that must be loaded into the long or double variable.
spos	This indicates the start position in the string of the numeric value to be loaded.
endian	These functions assume that the data in record is stored in big endian order (highest byte first). Where an application protocol uses little endian format instead, set this optional argument to 1 to indicate this.  The load.byte() function does not support this argument.
Context

Bshell functions.

Example

| Load two longs from a string

string longs(8)

long long_high, long_low

long_high = load.long( longs(1;4) )

long_low  = load.long( longs(5;4) )

Related help topics

    String operations:  overview
    String operations:  synopsis


lval(), val()

Syntax

long lval( string_expr )

double val( string_expr )

Description

These convert a string expression that consists of digits to its numeric representation.

lval() converts its argument to an integer. If the string contains a floating point number, the result is truncated. val() converts its argument to a floating point number. lval() is faster than val().

Return values

The specified string converted to a long or floating point number. Or 0 if the result of string_expr cannot be converted to a number.

Context

Bshell functions.

Related help topics

    String operations:  overview
    String operations:  synopsis


not.fixed()

Syntax

void not.fixed( string string_var(.) )

Description

You can fill a string with or without specifying a start position. If you specify a start position, unused positions in the string are filled with spaces. You can prevent the string from being filled out with spaces by calling not.fixed() before filling the string. Note that, when you assign a new value to the string variable, positions after the new value are not changed.

Note

This function does not work with variables declared as FIXED.

Context

Bshell function.

Example 1

string buf(10)

buf(5)    = "***"    | buf contains "    ***   " 	(length = 10)

buf       = "***"    | buf contains "***"     	(length = 3)

Example 2

string buf(10)

not.fixed( buf )

buf(5)    = "***"    | buf contains "    ***" 	(length = 7)

buf       = "***"    | buf contains "*** ***" 	(length = 7)

Related help topics

    String operations:  overview
    String operations:  synopsis


pos(), rpos()

Syntax

long pos( string source(.), string pattern(.) )

long rpos( string source(.), string pattern(.) )

Description

These return the start position of a specified substring (pattern) in a specified string (source). source and pattern can be either strings or string expressions.

pos() starts searching for the substring at the first position in the source string. rpos() starts searching at the last position in the source string. Both return the start position relative to the beginning of the source string.

Return values

The start position of the substring in the string. Or 0 if the substring is not found.

Context

Bshell functions.

Example

long posno

posno = pos("abcdabcd", "bcd")    | posno contains 2

posno = rpos("abcdabcd", "bcd")   | posno contains 6

Related help topics

    String operations:  overview
    String operations:  synopsis


set.strip.mode(), set.symbol.strip.mode

Syntax

long set.strip.mode( long table_id, long mode )

long set.symbol.strip.mode( ref string str, long mode )

Description

set.strip.mode() sets or resets the 'strip-on-assignment' flag for all string fields of the table specified by table_id. set.symbol.strip.mode() sets or resets the 'strip-on-assignment' flag for the variable specified by str. The mode argument indicates whether the flag is to be set on or off. 1 indicates set flag on, 0 indicates set flag off.

Notes

These functions do not affect the actual contents of the fields or variable.

If set.strip.mode() is the first call on a particular table, the table structure will be loaded.

Return values

 0	success
<0	error

Context

Bshell functions.

Example

table   tttaad200

string  s(100)

string  s2(100) fixed

string  s3(100)

if( set.strip.mode(tttaad2200, 1) < 0 ) or

( set.symbol.strip.mode(s2, 1) < 0 ) then

| handle error

endif

db.first(tttaad200)

s = tttaad200.user  | s contains username without trailing spaces

s2 = s              | s2 is fixed so username is filled out with spaces

s3 = s2             | s3 contains username without trailing spaces

Related help topics

    String operations:  overview
    String operations:  synopsis


shiftc$(), shiftl$(), shiftr$()

Syntax

string shiftc$( string strg(.) )

string shiftl$( string strg(.) )

string shiftr$( string strg(.) )

Description

These return the specified string with certain adjustments.

shiftc$() centers the string by equaling the number of leading and trailing spaces. If there is an odd number of spaces, the extra space becomes a trailing space. The returned string always has the same length as the input string.

shiftl$() removes any leading spaces from the input string.

shiftr$() moves the contents of the input string to the right, if there are trailing spaces. The length of the result is always the same as the length of the input string (this is not necessarily the declaration length).

Note

These functions do not change the input string.

Context

Bshell functions.

Example

shiftc$("  ABC      ")     | result  "    ABC    "

shiftl$("    ABC    ")     | result  "ABC    "

shiftr$("    ABC    ")     | result  "        ABC"

Related help topics

    String operations:  overview
    String operations:  synopsis


store.byte(), store.double(), store.float(), store.long(), store.short()

Syntax

void store.byte( long lng, ref string rec )

void store.double( double dbl, ref string rec )

void store.float( double dbl, ref string rec )

void store.long( long lng, ref string rec )

void store.short( long lng, ref string rec )

Description

These store a variable of type long or double in a string. Note that the numeric values are not converted to strings (see str$()). Instead, the real, machine-dependent, binary representation is used.

Context

Bshell functions.

Example

| Split a long into two shorts

long      source

long      high_part, low_part

string    tmp(4)

store.long( source, tmp )

high_part = load.short( tmp(1;2) )

low_part  = load.short( tmp(3;2) )

Related help topics

    String operations:  overview
    String operations:  synopsis


str$()

Syntax

string str$( num_expr )

Description

This converts an integer or floating point expression to a string.

Context

Bshell function.

Related help topics

    String operations:  overview
    String operations:  synopsis


string.set$()

Syntax

string string.set$( string_expr, num_expr )

Description

This returns a string that contains string_expr repeated num_expr times.

Context

Bshell function.

Example

string st(80)

st = string.set$("-", 10)          | st contains "----------"

st = string.set$( string.set$("-",3)&"+", 3 )

                                   | st contains "---+---+---+"

st = string.set$( chr(135), 5 )    | st contains 5 graphic symbols

Related help topics

    String operations:  overview
    String operations:  synopsis


strip$()

Syntax

string strip$( string_expr )

Description

This returns a specified string without trailing spaces. The input string remains unchanged.

Context

Bshell function.

Example

strip$("    ABC    ")      | result  "    ABC"

Related help topics

    String operations:  overview
    String operations:  synopsis


tolower$(), toupper$()

Syntax

string tolower$( string_expr )

string toupper$( string_expr )

Description

toupper$() converts all lower case characters in its argument to upper case. tolower$() converts all upper case characters in its argument to lower case. Both functions return the converted string expression. The input string remains unchanged.

Note

These functions can handle multibyte characters.

Context

Bshell functions.

Related help topics

    String operations:  overview
    String operations:  synopsis


tt.align.according.domain()

Syntax

long tt.align.according.domain( string string_in(.), ref string string_out(), string domain_name )

Description

This aligns a string according to the alignment method of a specified domain.

Arguments

string_in(.)	The input string. This must have the same length as the specified domain. If it is longer than the domain, its final characters are ignored. The input string remains unchanged by the function.
string_out()	The returned string, aligned according to the alignment method of the domain. This must be the same length as the specified domain.
domain_name	The name of the domain whose alignment method must be used to align the output string. The alignment method can be left, right, or centered.
Return values

0	success
-1	domain not found or domain is not of type string or multibyte string

Context

3GL library function.

Example

table   ttiitm001

domain  tcitem  item

long    ret

item = "  XY"

ret = tt.align.according.domain(item, tiitm001.item, "tcitem")

| Result tiitm001.item (if left adjusted): "XY              "

Related help topics

    String operations:  overview
    String operations:  synopsis


Structure Chart Manager: overview

The Structure Chart Manager is a tool that displays graphical tree structures. The functions described in this section enable programmers to create tree structures and to subsequently change their attributes.

A tree structure displays a list of items as an indented outline that reflects the hierarchical relationship between the items. The items in the tree structure are referred to as nodes. The first node in the tree is referred to as the root node. Nodes in a tree structure have a parent-child relationship. Each node can have a number of child nodes, which are indented below it in the tree structure. Every node, except the root node, has a parent node – that is, the node under which it is indented.

Each node has a node ID, which is its sequence number in the sequence of child nodes associated with a particular parent. Each node, except the root node, also has a parent ID, which is the ID of its parent node. The parent and node IDs of a node determine where the item is positioned within the tree structure.

Nodes must be created from the top down. That is, the parent node must be present before you can create a child node for that parent.

Interprocess communication (IPC)

Communication between the client program and the Structure Chart Manager is full-duplex. This means that the client can send information to the server and the server can send information to the client, simultaneously.

The Structure Chart Manager uses bucket messages for interprocess communication. When it sends a bucket message to the client, the client receives an event of type EVTBUCKETMESSAGE. So the client program must contain a loop to handle these events.

You can retrieve the command parameter of an event by using the following statement:

command = evt.bms.command(event)

The command parameter indicates the reason for the event. It can have any of the following values:

MSG.PUSH.BUTTON	Indicates that the user has clicked on a button in the Structure Chart.
MSG.NODE.PRESS	Indicates that the user has clicked on a node of the Structure Chart.
MSG.NODE.DPRESS	Indicates that the user has double-clicked on a node of the Structure Chart.
You use the following functions to retrieve data from the Structure Chart Manager after a bucket message has been received: get.tree.node.press, get.tree.node.dpress, get.tree.push.button, get.tree.default.

Colors

All colors must be composed by using the rgb() function. Or you can use one of the following predefined colors:

RGB.BLACK	RGB.MAGENTA	RGB.RED
RGB.BLUE	RGB.GREEN	RGB.WHITE
RGB.YELLOW	RGB.GRAY	RGB.CYAN

Related help topics

    Structure Chart Manager: synopsis
    Structure Chart Manager: example


Structure Chart Manager: synopsis

#include <bic_eis>

void	create.node	( string tree_name(25), string parent_id(25),   string node_id(25), string node_desc(80),   long node_class [, long process_id ] )
long	create.tree	( string tree_name(25),   string tree_title(80) )
void	create.tree.button	( string tree_name(25), long button_id,   string button_desc(80)   [, long process_id ] )
void	destroy.tree	( string tree_name(25) [, long process_id ] )
void	get.tree.default	( )
void	get.tree.node.dpress	( ref long event(), ref long process_id,   ref string node_id() )
void	get.tree.node.press	( ref long event(), ref long process_id,   ref string node_id() )
void	get.tree.push.button	( ref long event(), ref long process_id,   ref long button_id, ref string node_id() )
void	set.node.class	( string tree_name(25), string node_id(25),   long node_class [, long process_id ] )
void	set.node.class.color	( string tree_name(25), long node_class,   long class_color [, long process_id ] )
void	set.tree.background	( string tree_name(25), long color   [, long process_id ]
void	set.tree.font	( string tree_name(25), long visible_level,   long font [, long process_id ] )
void	set.tree.foreground	( string tree_name(25), long color   [, long process_id ] )
void	set.tree.linewidth	( string tree_name(25), long visible_level,   long linewidth [, long process_id ] )
void	set.tree.name	( string tree_name(25), string tree_title(80)   [, long process_id ] )
void	view.tree	( string tree_name(25), string node_id(25),   long depth [, long process_id ] )
Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: example


create.node()

Syntax

void create.node( string tree_name(25), string parent_id(25), string node_id(25), string node_desc(80), long node_class [, long process_id] )

Description

This adds a new node to a specified tree. The node_id, together with the parent_id, determine where the new node is located in the tree.

Arguments

tree_name	The name of the tree to which the node must be added.
parent_id	The ID of the parent node. Specify an empty string as the parent ID for the root node.
node_id	The ID for the new node.
node_desc	A description for the node. This is the label displayed for the node in the tree structure.
node_class	This is a number, in the range 1 to 9, that indicates the node class that must assigned to the node. The node class determines the color in which a node is displayed. You can subsequently assign a different class to the node by calling set.node.class() .  You use set.node.class.color() to define node classes.
process_id	This optional argument indicates the process ID of the server to which the node must be added, as returned by create.tree(). If you do not include this argument, the node is added to all servers with the name specified in tree_name.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


create.tree()

Syntax

long create.tree( string tree_name(25), string tree_title(80) )

Description

This starts the Structure Chart Manager for a specified tree. It returns the process ID of the tree. If there is more than one tree with the same name, you can specify the process ID in the other functions in order to identify a particular tree. The process ID is the unique identifier of a tree.

Arguments

tree_name	The name of the tree to be started.
tree_title	The title of the tree. This is displayed in the main window.
Notes

The tree structure is displayed only after you have called view.tree().

Return values

>0	success; returns the process ID of the new tree
  0	error

Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


create.tree.button()

Syntax

void create.tree.button( string tree_name(25), long button_id, string button_desc(80) [, long process_id ] )

Description

This adds a button to a specified tree. The client program can link a session or command to this button. An event is sent to the client when the user clicks on the button.

Arguments

tree_name	The name of the tree to which the button must be added.
button_id	The unique ID of the new button.
button_desc	The text for the button's label.
process_id	This optional argument indicates the process ID of the server to which the button must be added, as returned by create.tree(). If you do not include this argument, the button is added to all servers with the name specified in tree_name.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


destroy.tree()

Syntax

void destroy.tree( string tree_name(25) [, long process_id ])

Description

This ends the Structure Chart Manager for the specified tree.

Arguments

tree_name	The name of the tree that you want to kill.
process_id	This optional argument indicates the process ID of the tree that you want to end, as returned by create.tree(). If you do not include this argument, all trees with the name tree_name are killed.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


get.tree.default()

Syntax

void get.tree.default()

Description

When the client receives a bucket message that cannot be retrieved with get.tree.node.press,  get.tree.node.dpress or get.tree.push.button, call this function to remove the bucket message from the internal stack.

Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


get.tree.node.dpress()

Syntax

void get.tree.node.dpress( ref long event(), ref long process_id, ref string node_id() )

Description

Use this function to retrieve data from the Structure Chart Manager after an EVTBUCKETMESSAGE-type event, with a MSG.NODE.DPRESS command, has been received.

Arguments

event	The event containing the MSG.NODE.DPRESS command.
process_id	This returns the process ID of the Structure Chart Manager that sent the message.
node_id	This returns the ID of the relevant node.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


get.tree.node.press()

Syntax

void, get.tree.node.press( ref long event(), ref long process_id, ref string node_id() )

Description

Use this function to retrieve data from the Structure Chart Manager after an EVTBUCKETMESSAGE-type event, with a MSG.NODE.PRESS command, has been received.

Arguments

event	The event containing the MSG.NODE.PRESS command.
process_id	This returns the process ID of the Structure Chart Manager that sent the message.
node_id	This returns the ID of the relevant node.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


get.tree.push.button()

Syntax

void get.tree.push.button( ref long event(), ref long process_id, ref long button_id, ref string node_id() )

Description

Use this function to retrieve data from the Structure Chart Manager after an EVTBUCKETMESSAGE-type event, with a MSG.PUSH.BUTTON command, has been received.

Arguments

event	The event containing the MSG.PUSH.BUTTON command.
process_id	This returns the process ID of the Structure Chart Manager that sent the message.
node_id	This returns the ID of the relevant node.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


set.node.class()

Syntax

void set.node.class( string tree_name(25), string node_id(25), long node_class [, long process_id ] )

Description

Use this function to assign a different class to a particular node. The node class determines the color in which a node is displayed.

Arguments

tree_name	The name of the tree to which the specified node belongs.
node_id	The ID of the node to which you want to assign a new class.
node_class	This is a number, in the range 1 to 9, that indicates the node class that must assigned to the node. You use set.node.class.color() to define node classes.
process_id	This optional argument indicates the process ID of the tree for which you want to change the class of the specified node. If you do not include this argument, the node class is changed for the specified node in all trees with the name tree_name.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


set.node.class.color()

Syntax

void set.node.class.color( string tree_name(25), long node_class, long class_color [, long process_id ] )

Description

The node class assigned to a node determines the color in which the node is displayed. You use this function to define the color for a specified node class. You use set.node.class() to assign a class to a particular node.

Arguments

tree_name	The name of the tree for which the node class must be defined.
node_class	This is the identifier of the node class. It can be any number in the range 1 to 9.
class_color	This specifies the color for the node class. It consists of either a number returned by the rgb() function or one of the following predefined colors: RGB.BLACK RGB.MAGENTA RGB.RED RGB.BLUE RGB.GREEN RGB.WHITE RGB.YELLOW RGB.GRAY RGB.CYAN
process_id	This optional argument indicates the process ID of the tree for which the node class must be defined. If you do not include this argument, the new color is assigned to the specified node class in all trees with the name tree_name.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


set.tree.background()

Syntax

void set.tree.background( string tree_name(25), long color [, long process_id ] )

Description

This changes the background color of a specified tree.

Arguments

tree_name	The name of the tree whose background color you want to change.
color	This specifies the new background color for the tree. The value can be a number returned by the rgb() function or one of the following predefined colors: RGB.BLACK RGB.MAGENTA RGB.RED RGB.BLUE RGB.GREEN RGB.WHITE RGB.YELLOW RGB.GRAY RGB.CYAN
process_id	This optional argument indicates the process ID of the tree whose background color you want to change. If you do not include this argument, the new background color is applied to all trees with the name tree_name.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


set.tree.font()

Syntax

void set.tree.font( string tree_name(25), long visible_level, long font [, long process_id ] )

Description

This changes the font used for nodes at a particular level in a specified tree. Use load.font() to load the font that you want to use.

Arguments

tree_name	The name of the tree for which you want to change the font.
visible_level	This is a number, in the range 1 to 3, that specifies the node level to which the new font is to be applied. Visible level 1 specifies the highest level currently visible in the tree. Visible level 3 specifies levels three and below. See view.tree().
font	The font to be applied to the specified node level.
process_id	This optional argument indicates the process ID of the tree for which the font must be changed. If you do not include this argument, the new font is applied to the specified level in all trees with the name tree_name.
Context

3GL library function.

Example

long mask, font, proc_id

long request(FNTMAXSIZE)

long reply(FNTMAXSIZE)

proc_id = create.tree("test", "Test Structure Chart Manager")

mask = FNTHEIGHT + FNTWEIGHT + FNTSLANT

fnt.weight(request) = FNTMEDIUM

fnt.height(request) = 12

fnt.slant(request) = FNTROMAN

font = load.font(current.display(), mask, request, reply)

set.tree.font("test", 1, font, proc_id)

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


set.tree.foreground()

Syntax

void set.tree.foreground( string tree_name(25), long color [, long process_id ] )

Description

This changes the foreground color of a specified tree.

Arguments

tree_name	The name of the tree whose foreground color you want to change.
color	This specifies the new foreground color for the tree. The value can be a number returned by the rgb() function or one of the following predefined colors: RGB.BLACK RGB.MAGENTA RGB.RED RGB.BLUE RGB.GREEN RGB.WHITE RGB.YELLOW RGB.GRAY RGB.CYAN
process_id	This optional argument indicates the process ID of the tree whose foreground color you want to change. If you do not include this argument, the new foreground color is applied to all trees with the name tree_name.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


set.tree.linewidth()

Syntax

void set.tree.linewidth( string tree_name(25), long visible_level, long linewidth [, long process_id ] )

Description

This changes the line width (in pixels) used for nodes at a particular level in a specified tree. The default line widths are:

level 1	–	 4 pixels
level 2	–	 2 pixels
level 3	–	 1 pixel
level 4	–	 1 pixel

Arguments

tree_name	The name of the tree for which you want to change the line width.
visible_level	This is a number, in the range 1 to 3, that specifies the node level to which the new line width is to be applied. Visible level 1 specifies the highest level currently visible in the tree. Visible level 3 specifies levels three and below. See view.tree().
linewidth	The new line width (in pixels) to be applied to the specified node level.
process_id	This optional argument indicates the process ID of the tree for which the line width must be changed. If you do not include this argument, the new line width is applied to the specified level in all trees with the name tree_name.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


set.tree.name()

Syntax

void set.tree.name( string tree_name(25), string tree_title(80) [, long process_id ] )

Description

This changes the title of a specified tree.

Arguments

tree_name	The name of the tree whose title you want to change.
tree_title	This specifies the new title for the tree.
process_id	This optional argument indicates the process ID of the tree whose title you want to change. If you do not include this argument, the new title is applied to all trees with the name tree_name.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


view.tree()

Syntax

void view.tree( string tree_name(25), string node_id(25), long depth [, long process_id ] )

Description

This changes which levels are visible in a specified tree.

Arguments

tree_name	The name of the tree whose visible levels you want to change.
node_id	This specifies the ID of node that you want to become the new root node of the visible part of the tree.
depth	This specifies the number of levels that you want to be visible. The recommended number of visible levels is four.
process_id	This optional argument indicates the process ID of the tree whose visible levels you want to change. If you do not include this argument, the new settings are applied to all trees with the name tree_name.
Context

3GL library function.

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis
    Structure Chart Manager: example


Structure Chart Manager: example
Tree structures: example

#include   <bic_event>

#include   <bic_gc>

#include   <bic_eis>

#define	BUTN.ID.1	1

#define	BUTN.ID.2	2

#define	BUTN.ID.3	3

function main()

{

string     	tree.id(25)

string     	tree.title(80)

long  	process.id

tree.id = "exm"

tree.title = "Example Tree"

process.id = init.main.tree(tree.id, tree.title)

handle.event.loop()

exit.main.tree(process.id)

}

function long init.main.tree(string tree.id(25), string tree.title(80))

{

long  process.id

|-- activate Tree Server

process.id = create.tree(tree.id, tree.title)

|-- create nodes

create.node(tree.id, "", "1", "Root", 1, process.id)

create.node(tree.id, "1", "1.1", "Root Child 1", 2, process.id )

create.node(tree.id, "1", "1.2", "Root Child 2", 2, process.id )

create.node(tree.id, "1", "1.3", "Root Child 3", 3, process.id )

create.node(tree.id, "1.1", "1.1.1", "Root Child 1.1", 3, process.id)

create.node(tree.id, "1.1", "1.1.2", "Root Child 1.2", 1, process.id)

create.node(tree.id, "1.2", "1.2.1", "Root Child 2.1", 1, process.id)

create.node(tree.id, "1.2", "1.2.2", "Root Child 2.2", 2, process.id)

create.node(tree.id, "1.3", "1.3.1", "Root Child 3.1", 1, process.id)

|-- create buttons

create.tree.button(tree.id, BUTN.ID.1, "Button 1", process.id)

create.tree.button(tree.id, BUTN.ID.2, "Button 2", process.id)

create.tree.button(tree.id, BUTN.ID.3, "Button 3", process.id)

|-- change default colors

set.tree.background(tree.id, RGB.WHITE, process.id)

set.tree.foreground(tree.id, RGB.BLACK, process.id)

set.node.class.color(tree.id, 1, RGB.GREEN, process.id)

set.node.class.color(tree.id, 2, RGB.YELLOW, process.id)

set.node.class.color(tree.id, 3, RGB.RED, process.id)

|-- show root node with 2 underlying levels

view.tree(tree.id, "1", 3, process.id)

|-- return new process id

return(process.id)

}

function void exit.main.tree(string tree.id(25),  long process.id)

{

|-- kill Tree Server

destroy.tree(tree.id, process.id)

}

function void handle.event.loop()

{

long       event(EVTMAXSIZE)

long       process.id

long       button.id

string     node.id(25)

while ( TRUE )

next.event(event)

on case evt.type(event)

case EVTBUCKETMESSAGE:

on case evt.bms.command(event)

case MSG.PUSH.BUTTON:

get.tree.push.button(event, process.id, button.id,
node.id)

on case button.id

case BUTN.ID.1:

                                .

                                .

break

.

.

                         	endcase

                         	break

case MSG.NODE.PRESS:

get.tree.node.press(event, process.id, node.id)

                           .

                           .

                         break

case MSG.NODE.DPRESS:

                      get.tree.node.dpress(event, process.id, node.id)

                           .

                           .

                         break

default:

                         get.tree.default()

                         break

endcase

break

               .

               .

endcase

endwhile

}

Related help topics

    Structure Chart Manager: overview
    Structure Chart Manager: synopsis


Synchronized sessions: overview

BaanERP provides several mechanisms for starting one session from another – these are zoom fields, synchronized sessions, and the 4GL start.session() function. This section discusses synchronized sessions and associated functions.

When two sessions are synchronized, actions performed on one session window have a direct effect on the other session window. BaanERP implements two synchronization models:

•	Dialog synchronization

•	Child synchronization

Dialog synchronization

This synchronizes a multioccurrence parent session with a single-occurrence dialog session. Both sessions act on the same main table. The parent session can be a modeless multioccurrence display form or a modal multioccurrence zoom window.

When the user double-clicks on an occurrence in the parent session, the standard program automatically opens the synchronized dialog session (if it is not already open) and updates it with information from the selected record. Whether the dialog opens in edit or display mode depends on user authorization settings. The synchronized dialog is also opened automatically when the user initiates one of the following actions: insert record, edit record, or duplicate record.

When a record is saved in the synchronized dialog, the standard program automatically updates the occurrence in the parent window.

Parent and child forms must be of the following types:

Multioccurrence form	Dialog form
type 2	type 1
type 3	type 3 with single occurrence
Parent and child session settings must be as follows:

	Multioccurrence session	Dialog session
Session type	display	maintain
Start option	44 (get defaults)	0 (no start option)
Window type	list window	synchronized dialog
Main session	yes	no
Child synchronization

Normally, this is used to synchronize sessions that act on different main tables. In this case, the primary key of the parent's main table must be a subset of the primary key of the child's main table.

For example, take an Orders table that lists client orders, and an Order lines table that lists order lines per order. The primary key of the Orders session is orderno. The primary key of the Order lines session is orderlines.orderno. In the Order lines session, orderno is a foreign key that references the Orders table.

With child synchronization, you can synchronize a parent session that uses the Orders table with a child session that uses the Order lines table. The user chooses a form command to open the child session from the parent session. So the user can view the order lines associated with the orders listed in the parent session.

Related help topics

    Session synchronization:  synopsis
    Session synchronization:  sample program
    Session synchronization:  illustration


Synchronized sessions: illustration

Dialog synchronization

•	Sessions 1 and 2 form a set linked by dialog synchronization. Sessions 3 and 4 form another set linked by dialog synchronization.

•	You open session 2 by double-clicking a record in session 1. Double-clicking a different record in session 1 updates session 2 with information from the newly selected record. You open session 4 by double-clicking a record in session 3. Double-clicking a different record in session 3 updates session 4 with information from the newly selected record.

Child synchronization

•	Sessions 1 and 3 form a set linked by child synchronization.

•	You open session 3 by selecting a form command in session 1. The records displayed in session 3 depend on the arguments of the function associated with the form command. You could, for example, program the synchronization in such a way that each time the user selects a new record in session 1 and activates the form command, session 3 is updated to display the child records of the selected record.


Synchronized sessions: synopsis

Dialog synchronization

void	set.synchronized.dialog	( string sess_code )
Child synchronization

long	start.synchronized.child	( string sess_code [, string    parent.var,  string child.var ...] )
long	start.synchronized.child.with	( const long cmd )
long	stop.synchronized.child	( long child.id )
long	synchronize.with.child	( long child.id )
Related help topics

    Session synchronization:  overview
    Session synchronization:  sample program


set.synchronized.dialog()

Syntax

void set.synchronized.dialog( string sess_code )

Description

This synchronizes a multioccurrence parent session with a single-occurrence dialog. Both sessions act on the same main table.

When the user double-clicks on an occurrence in the parent session, the synchronized dialog is updated with information from the selected record. The synchronized dialog also automatically opens when the user initiates any of the following actions: insert record, edit record, or duplicate record. When a record is saved in the synchronized dialog, the standard program updates the occurrence in the parent window.

When the synchronized dialog is opened or updated, the synchronized.reason variable (read-only) is set. This indicates the command that caused the synchronization. The possible values are: ADD.SET, DUPL.OCCUR, MODIFY.SET, and DISPLAY.SET. This variable is available in all sections in the synchronized dialog session.

Arguments

sess_code	The session code of the single-occurrence dialog session.
Context

4GL library function.

You call the function in the before.program section of the multioccurrence parent session.

Related help topics

    Session synchronization:  overview
    Session synchronization:  synopsis


start.synchronized.child()

Syntax

long start.synchronized.child( string sess_code [, string parent.var,
  string child.var ...] )

Description

Use this to synchronize two sessions that act on different main tables. The function starts the specified child session when the user chooses a particular form command in the multioccurrence parent session. The primary key of the parent's main table must be a subset of the primary key of the child's main table.

Although you normally use this function to synchronize sessions that act on different main tables, it is also possible to use it to synchronize sessions that act on the same main table.

Arguments

sess_code	The session code of the child session.
parent.var child.var	These are optional arguments. You use them to synchronize particular variables in the parent and child sessions. For example, to display in the child session only order lines for the order currently selected in the parent session.  For each variable to be synchronized, specify the name of the relevant field in the parent's main table, followed by the name of the corresponding field in the child’s main table.  For each synchronization event (start.synchronized.child(), start.synchronized.child.with(), or synchronize.with.child()), the child session is refreshed, and the specified variables derive their values from the parent session.
Return values

>0	a unique identifier for the child process
  0	cannot start child
 -1	argument error

Context

4GL library function.

 Related help topics

    Session synchronization:  overview
    Session synchronization:  synopsis
    Session synchronization:  sample program


start.synchronized.child.with()

Syntax

long start.synchronized.child.with( const long cmd )

Description

To start a synchronized child with a command other than the default synchronization command, call this function before calling start.synchronized.child().

Although you normally use this function to synchronize sessions that act on different main tables, it is also possible to use it to synchronize sessions that act on the same main table.

Arguments

cmd	This specifies the ID of the required command. Click here [image] for a list of commands and command IDs.
Return values

The function returns the specified command or 0 if the command is illegal.

Context

4GL library function.

 Related help topics

    Session synchronization:  overview
    Session synchronization:  synopsis
    Session synchronization:  sample program


stop.synchronized.child()

Syntax

long stop.synchronized.child( long child.id )

Description

This ends a child session.

Arguments

child.id	The unique identifier for the child session to be stopped, as returned by start.synchronized.child() or start.synchronized.child.with().
Return values

  0 	 success
<0  	 error

Context

4GL library function.

 Related help topics

    Session synchronization:  overview
    Session synchronization:  synopsis


synchronize.with.child()

Syntax

long synchronize.with.child( ref long child.id )

Description

This refreshes (that is, resynchronizes) a child session. If the specified child session does not exist, the child.id argument is set to 0 on return.

Arguments

child.id	The unique identifier for the child session to be refreshed, as returned by start.synchronized.child() or start.synchronized.child.with().
Return values

  0 	 success
<0  	 error

Context

4GL library function.

 Related help topics

    Session synchronization:  overview
    Session synchronization:  synopsis
    Session synchronization:  sample program


Child synchronization: sample program

  declaration:

    long   field.proc

  before.program:

    field.proc = 0

    ...

  function extern field.process()       | called by Form Command

  {

    if field.proc then

          synchronize.with.child( field.proc )

    endif

    | field.proc is a reference variable that is set to zero when
    | child cannot be found

    if not field.proc then

          field.proc = start.synchronized.child ( "ttadv4127m000",

              "ttadv420.vers", "ttadv422.vers",

              "ttadv420.rele", "ttadv422.rele",

              "ttadv420.cust", "ttadv422.cust",

              "ttadv420.cpac", "ttadv422.cpac",

              "ttadv420.cmod", "ttadv422.cmod",

              "ttadv420.flno", "ttadv422.flno" )

    endif

  }

Related help topics

    Session synchronization:  overview
    Session synchronization:  synopsis


System and user information: overview and synopsis

Overview

Use these functions to retrieve system and user information.

Synopsis

string	bse.dir$	( )
string	bse.release$	( )
string	bse.tmp.dir$	( )
long	current.display	( )
long	get.display.data	( ref long server_data(SRVMAXSIZE) )
string	getenv$	( string env_var(256) )
long	group.exists	( const string groupname )
string	hostname$	( )
long	is.administrator	( )
long	ostype	( )
long	user.exists	( const string username )


bse.dir$()

Syntax

string bse.dir$( )

Description

This returns a string containing the name of the directory where the Baan Software Environment is installed. The function uses the environment variable BSE to retrieve the information. If this variable is not filled, bse.dir$() returns the string "/usr/bse".

Context

Bshell function.

Related help topics

    System and user information: overview and synopsis


bse.release$()

Syntax

string bse.release$( )

Description

This returns a string of 3 characters that contains the release number of BAAN Tools. For example,  "6.2".

Context

Bshell function.

Related help topics

    System and user information: overview and synopsis


bse.tmp.dir$()

Syntax

string bse.tmp.dir$( )

Description

This returns a string containing the name of the directory where temporary files can be created by the application. The function uses the environment variable BSE_TMP to retrieve the information. If this environment variable is not filled, bse.tmp.dir$() returns the string "$BSE/tmp". If the environment variable BSE is not filled, the function returns the string "/usr/tmp".

Note

To create temporary files with a unique name in the directory BSE.TMP.DIR, use the function call creat.tmp.file$( bse.tmp.dir$() ).

Context

Bshell function.

Related help topics

    System and user information: overview and synopsis


current.display()

Syntax

long current.display( )

Description

This returns the identification number of the current display. It is provided to support the use of multiple displays in future versions of the software. Currently it always returns zero (0)

Context

Bshell function.

Related help topics

    System and user information: overview and synopsis


get.display.data()

Syntax

long get.display.data( ref long server_data(SRVMAXSIZE) )

Description

This retrieves information about the display server. It stores the information in the array server_data. The predefined constant SRVMAXSIZE indicates the maximum size of the array.

You can retrieve the information using a set of predefined variables:

Information	Variable
Server type	typesrv.type(server_data) DSNOSERVER DSBX DSBA DSBW
Display width	srv.display.width(server_data)
Display height	srv.display.height(server_data)
Display width in millimeters	srv.display.width.mm(server_data)
Display height in millimeters	srv.display.height.mm(server_data)
Number of colors	srv.display.colors(server_data)
Microsoft operating system	srv.display.os.type(server_data) DSBW_WIN_311 DSBW_WIN_NT DSBW_WIN_95 NT4
Note

The above variables are valid only after a call to get.display.data().

Context

Bshell function.

Example

long win_width, srv_data(SRVMAXSIZE)

get.display.data( srv_data )

win_width = srv.display.width( srv_data ) / 2

.....

if srv.type( srv_data ) = DSBW then

if srv.display.os.type( srv_data ) = DSBW_WIN_95 then

.....

endif

endif

Related help topics

    System and user information: overview and synopsis


getenv$()

Syntax

string getenv$( string env_var(256) )

Description

This returns the value of a specified environment variable of the operating system. It returns an empty string if the variable is not available.

Context

Bshell function.

Example

string name(15)

name = getenv$("LOGNAME")

Related help topics

    System and user information: overview and synopsis


group.exists()

Syntax

long group.exists( const string groupname )

Description

This checks whether a specified group is defined on the system. Whether group names are case-sensitive or case-insensitive is a system-dependent feature.

Return values

1 (TRUE)	   	group exists
0 (FALSE)	group does not exist

Example

string groupid(12)

groupid = getenv$( "GROUP" )

if not group.exists( groupid ) then

mess( "First create group " & groupid &

" on the system and restart the installation", 0 )

exit()

endif

Context

Bshell function.

Related help topics

    System and user information: overview and synopsis


hostname$()

Syntax

string hostname$( )

Description

This returns the host name of the local machine.

If no host name is found, the function returns an empty string. If the host name is incorrect, the user can change it by setting the environment variable BSE_HOSTNAME.

Context

Bshell function.

Example

field.ttaad410.syst:

before.input:

if isspace(ttaad410.syst) then

ttaad410.syst = hostname$()

endif

Related help topics

    System and user information: overview and synopsis


is.administrator()

Syntax

long is.administrator()

Description

This checks whether or not the user that is running the bshell has administrator rights on the server that the bshell is running. On UNIX systems, the function returns TRUE if the user has root access to the system. On Windows NT systems, the function returns TRUE if the user belongs to the administrator group.

Return values

<>0 (TRUE)	user has administrator rights
    0 (FALSE)	user does not have administrator rights

Context

3GL library function.

Related help topics

    System and user information: overview and synopsis


ostype()

Syntax

long ostype()

Description

This returns a long value that indicates the operating system environment. The possible values are:

OS_WINDOWS_NT	Windows/NT
OS_WINDOWS_95 	Windows 95
OS_UNIX	All UNIX variants

Context

Bshell function.

Related help topics

    System and user information: overview and synopsis


user.exists()

Syntax

long user.exists( const string username )

Description

This checks whether a specified user is defined on the system. Whether user names are case-sensitive or case-insensitive is a system-dependent feature.

Return values

1 (TRUE)	   	user exists
0 (FALSE)	user does not exist

Context

Bshell function.

Related help topics

    System and user information: overview and synopsis


Text fields: overview

Use these functions for handling database text fields.

Text numbers

Every text stored in the database has a text number. A text field that is included in a database table is referenced in the table by its text number. The text itself, its key words, and so on, are stored in a separate table.

Text field names

The text_field, text_field_from, and text_field_to arguments must always contain a text field name. This name can be the name of a database field of type DB.TEXT, or it can be the name of a variable of type long. In both cases, the name must be enclosed by quote marks. When using a variable, this must be declared as EXTERN because the functions use the text_field argument indirectly to store the text number of the specified text. Database text field names are automatically declared as external.

Committing transactions

In the case of all text field transactions, you must commit the transaction yourself.

Related help topics

    Text fields:  synopsis


Text fields: synopsis

long	text.copy	( string text_field_to(17),    string text_field_from(17),    string kw1(17) mb, string kw2(17) mb,   string kw3(17) mb, string kw4(17) mb,   string tgroup(8), string edit_opt(15) )
long	text.copy.between.companies	( string text_field_to(17),    string text_field_from(17),    long source_company,    long target_company, string kw1(17) mb,   string kw2(17) mb, string kw3(17) mb,    string kw4(17) mb, string tgroup(8),   string edit_opt(15) )
long	text.copy.language	( long textnr, string lang_from,    string lang_to )
long	text.defaults	( string text_field(17),    ref string tgroup(8),    ref string edit_opt(15) )
long	text.delete	( string text_field(17), string lang )
long	text.edit	( string text_field(17), string lang,    string kw1(17) mb, string kw2(17) mb,    string kw3(17) mb, string kw4(17) mb,    string tgroup(8), string edit_opt(15),   long mode )
long	text.present.in.language	( long textnr, string lang    [, ref long nr_lines ] )
long	text.read	( string text_field(17), string lang,    ref string kw1(17) mb,    ref string kw2(17) mb,    ref string kw3(17) mb,    ref string kw4(17) mb,    ref string tgroup(8),    ref string edit_opt(15),    string tmp_file(256), long lock )
long	text.rewrite	( string text_field(17), string lang,    string kw1(17) mb, string kw2(17) mb,   string kw3(17) mb, string kw4(17) mb,   string tgroup(8), string edit_opt(15),    string tmp_file(256) [, long bidi] )
long	text.to.buf	( string text_field(17), string lang,    long nr_lines,  ref string buf(,)    [, long rtf.text] )
long	text.window	( string edit_opt(15),    ref long start_column,    ref long start_row,    ref long number_columns,    ref long number_rows )
long	text.write	( string text_field(17), string lang,    string kw1(17) mb, string kw2(17) mb,    string kw3(17) mb, string kw4(17) mb,   string tgroup(8), string edit_opt(15),   string tmp_file(256) [, long bidi] )
Related help topics

    Text fields:  overview


text.copy()

Syntax

long text.copy( string text_field_to(17), string text_field_from(17), string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15) )

Description

This makes a copy of the entire text of a specified text field, for all languages, and assigns it a new text number.

Arguments

text_field_to	The name of the new text field. See Text fields: overview. This returns the text number for the new text field.
text_field_from	The name of the text field that must be copied. See Text fields: overview.
kw1 to kw4	Use these arguments to specify key words for the new text. If you specify one or more of these arguments as an empty string, the corresponding key word(s) are copied from the original text. It is possible, for example, to specify two new key words and to copy the other two from the original text.
tgroup	This specifies the name of the text group to which the new text must be assigned. If you specify an empty string here, the text is assigned to the user's default group.
edit_opt	This specifies the type of window in which the text must be displayed.
Return values

>0	success; returns the number of lines copied
 -1	error; no permission for this text field

Example

This example copies the text from the text field tttxt008.help to a new text field named tttxt008.docu. A new text number is created for tttxt008.docu and this is returned in the first argument. Key words 1 and 2 are new. Key words 3 and 4 are copied from the original text.

ret=TEXT.COPY("tttxt008.docu", "tttxt008.help", "docu", "help", "",
"", "", "")

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.copy.between.companies()

Syntax

long text.copy.between.companies( string text_field_to(17), string text_field_from(17), long source_company, long target_company, string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15) )

Description

This copies the entire text of a specified text field, for all languages, from one company to another.

Arguments

text_field_to	The name of the new text field. See Text fields: overview. This returns the text number for the new text field.
text_field_from	The name of the text field that must be copied. See Text fields: overview.
source_company	This specifies the source company.
target_company	This specifies the destination company.
kw1 to kw4	Use these arguments to specify key words for the new text. If you specify one or more of these arguments as an empty string, the corresponding key word(s) are copied from the original text. It is possible, for example, to specify two new key words and to copy the other two from the original text.
tgroup	This specifies the name of the text group to which the new text must be assigned. If you specify an empty string here, the text is assigned to the user's default group.
edit_opt	This specifies the type of window in which the text must be displayed.
Return values

>0	success; returns the number of lines copied
 -1	error

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.copy.language()

Syntax

long text.copy.language( long textnr, string lang_from, string lang_to )

Description

This copies a specified text from one language to another.

Arguments

textnr	The text number of the text that must be copied.
lang_from	This specifies the language from which the text must be copied.
lang_to	This specifies the language to which the text must be copied.
Return values

>0	success; returns the number of lines copied
  0	error; text not found for source language

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.defaults()

Syntax

long text.defaults( string text_field(17), ref string tgroup(8), ref string edit_opt(15) )

Description

This retrieves the defaults for a specified text field.

Arguments

text_field	The name of the text field. See Text fields: overview. This returns the text number of the field.
tgroup	This returns the default text group of the text.
edit_opt	This returns the default window type for the text.
Return values

 0	success
-1	one default not found
-2	no permission

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.delete()

Syntax

long text.delete( string text_field(17), string lang )

Description

This deletes a specified text.

Arguments

text_field	The name of the text field that must be deleted. See Text fields: overview. This returns the text number of the field.
lang	The language for which the text must be deleted. To delete the text for all languages, specify an empty string here. In this case, the text number and all attributes of the text are deleted from the text manager. This also happens if the language you specify is the only language for which the text exists.
Return values

>0	success; returns the number of lines deleted
 -1	error

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.edit()

Syntax

long text.edit( string text_field(17), string lang, string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15), long mode )

Description

This opens an edit window in which the specified text can be edited. If text_field is an empty string, or if the text number associated with the specified text is 0, the text manager prompts the user to confirm whether or not a new text must be created. After editing, the text number is retrieved and returned in text_field.

Arguments

text_field	The name of the text field. See Text fields: overview. This returns the text number of the field.
lang	The language for which the text is to be edited.
kw1 to kw4	Use these arguments to specify the key words for the text.
tgroup	This specifies the name of the text group to which the new text must be assigned. If you specify an empty string here, the text is assigned to the user's default group.
edit_opt	This specifies the type of window in which the text must be displayed.
mode	This species the text mode. Possible values are: 1 read-only 3 read and write
Return values

The text number. Or -1 if an error occurs.

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.present.in.language()

Syntax

long text.present.in.language( long textnr, string lang [, ref long nr_lines ] )

Description

This tests whether a specified text is available in a specified language.

Arguments

textnr	The text number of the relevant text.
lang	The language for which you wish to test the availability of the text.
nr_lines	This optional argument returns the number of lines the text occupies in the specified language.
Return values

1 (true)	text available in specified language
0 (false)	text not available in specified language

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.read()

Syntax

long text.read( string text_field(17), string lang, ref string kw1(17), ref string kw2(17), ref string kw3(17), ref string kw4(17), ref string tgroup(8), ref string edit_opt(15), string tmp_file(256), long lock )

Description

This reads a specified text and stores it in a temporary file.

Arguments

text_field	The name of the text field that must be read. See Text fields: overview.  If the text number of the specified field is 0, a subprocess is started, which lists the texts associated with the current company and enables the user to select the text to be read. If no text is found, or if you abort the subprocess, text_field returns 0. Otherwise, it returns the text number of the retrieved text.
lang	The language for which the text must be retrieved.
kw1 to kw4	These return the key words associated with the specified text.
tgroup	This returns the name of the text group to which the text is assigned.
edit_opt	This returns the default window type for the text.
tmp_file	The name of the file in which the text must be stored. If this is an empty string, no text is retrieved and the function returns 0.
lock	By default, a lock is applied to the text field when it is read. To read the field without lock, set this argument to 0.
Return values

>0	success; returns the number of lines read
  0	no text found or subprocess aborted
 -1	no permission

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.rewrite()

Syntax

long text.rewrite( string text_field(17), string lang, string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15), string tmp_file(256) [, long bidi] )

Description

This writes text from a specified file to a specified text field. The new text and new text attributes replace the existing text and text attributes.

Arguments

text_field	The name of the text field to which the file must be copied. See Text fields: overview. If the specified text does not exist, nothing happens and the function returns 0.
lang	The language for which the text is to be rewritten.
kw1 to kw4	Use these arguments to specify key words for the text.
tgroup	This specifies the name of the text group to which the text must be assigned. If you specify an empty string here, the text is assigned to the user's default group.
edit_opt	This specifies the type of window in which the text must be displayed.
tmp_file	The name of the file where the new text is stored.
bidi	Use this optional argument to indicate the text alignment. Possible values are: true text is right justified false text is left justified; this is the default option
Return values

>0	success; returns the number of lines written to the text field
  0	no such text
 -1	no permission for text group

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.to.buf()

Syntax

long text.to.buf( string text_field(17), string lang, long nr_lines, ref string buf(,) [, long rtf.text] )

Description

This stores the text of a specified text field in a two-dimensional string array.

Arguments

text_field	The name of the text field that must be retrieved. See Text fields: overview.
lang	This specifies the relevant language.
nr_lines	This specifies the maximum number of lines that can be stored in the buffer.
buf	This specifies the buffer in which the text must be stored.
rtf.text	Set this argument to true if you want the text to be stored in RTF format instead of ASCII format. This is possible only when using a text group that supports RTF data.
Return values

>0	number of stored lines
  0	error
- 1	no permission to store the text

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.window()

Syntax

long text.window( string edit_opt(15), ref long start_column, ref long start_row, ref long number_columns, ref long number_rows )

Description

This returns information about a specified window type.

edit_opt	The name of the window type.
start_column	This returns the number of the column where the window starts.
start_row	This returns the number of the row where the window starts.
number_columns	This returns the number of columns in the window.
number_rows	This returns the number of rows in the window.
Return values

 0	success
-1	error; edit_opt not found

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


text.write()

Syntax

long text.write( string text_field(17), string lang, string kw1(17), string kw2(17), string kw3(17), string kw4(17), string tgroup(8), string edit_opt(15), string tmp_file(256) [, long bidi] )

Description

This adds a new text to the text manager and assigns a new text number to the text.

Arguments

text_field	The name of the new text field. See Text fields: overview. This returns the text number for the new field.
lang	This specifies the language for the new text.
kw1 to kw4	Use these arguments to specify key words for the text.
tgroup	This specifies the name of the text group to which the text must be assigned. If you specify an empty string here, the text is assigned to the user's default group.
edit_opt	This specifies the type of window in which the text must be displayed.
tmp_file	The name of the file where the text for the new field is stored.
bidi	Use this optional argument to indicate the text alignment. Possible values are: true text is right justified false text is left justified; this is the default option
Return values

>0	success; returns the number of lines written
 -1	error

Context

3GL library function.

Related help topics

    Text fields:  overview
    Text fields:  synopsis


Timers: overview and synopsis

Overview

Use the mtime() function to measure elapsed time. Use the other functions to start and end timers that generate timer events. You can use these events, for example, to time out blocking event functions.

Synopsis

void	kill.timer	( long timer_id )
long	mtime	( )
long	set.alarm	( long msec )
long	set.timer	( long msec )


kill.timer()

Syntax

void kill.timer( long timer_id )

Description

This ends a specified timer.

Argument

timer_id	The timer identifier, as returned by set.timer() or set.alarm() when the timer was created.
Note

A timer automatically terminates when the process that started it ends.

Context

Bshell function.

Related help topics

    Timers: overview and synopsis


mtime()

Syntax

long mtime()

Description

This measures the time elapsed since the first mtime() call. The function is common to all processes within the same bshell. That is, when it is called by a process, the result is the number of milliseconds since the function was first called by a process in the same bshell.

Return values

The first call returns 0. Subsequent calls return the number of milliseconds since the first call. A negative value is returned if an error occurs.

Note

The maximum time frame that mtime() can measure is 2147483647 milliseconds (approximately 596 hours).

Context

Bshell function.

Related help topics

    Timers: overview and synopsis


set.alarm()

Syntax

long set.alarm( long msec )

Description

This starts a timer that sends a single EVTTIMEREVENT event to the calling process after the number of milliseconds specified in the msec argument. The timer automatically ends after sending the event. The timer also ends automatically when the process ends or when the program explicitly kills it with kill.timer() .

Return values

A unique identifier for the timer.

Note

The kill.timer() function uses the identifiers returned by this function to specify which timer it is terminating.

Context

Bshell function.

See also

Events

Related help topics

    Timers: overview and synopsis


set.timer()

Syntax

long set.timer( long msec )

Description

This starts a timer that sends an EVTTIMEREVENT event to the calling process every msec milliseconds. The timer continues to send events until the process ends or until the program explicitly terminates the timer using kill.timer().

Return values

A unique identifier for the timer.

Note

The kill.timer() function uses the identifiers returned by this function to specify which timer it is terminating.

Context

Bshell function.

See also

Events

Example

tim.id = set.timer(2000)

next.event( event )

on case evt.type( event )

case EVTTIMEREVENT:

if (evt.timer.id(event) = tim.id )

message("My '2000' timer expired")

endif

break

endcase

Related help topics

    Timers: overview and synopsis


Secondary toolbars: overview and synopsis

Overview

Use the create.extra.toolbar() function to add a secondary toolbar to a form. Buttons on the toolbar represent form commands; they provide an alternative means of executing those commands.

You can create the button images yourself (as .gif files) or you can reuse existing images, where appropriate. Before you can add buttons to a secondary toolbar, you must move their .gif files to the $BSE/gif/gfd0002 directory.

Buttons on secondary toolbars are automatically disabled or enabled when the corresponding form commands are disabled or enabled (see disable.commands()).

Synopsis

void	create.extra.toolbar	( string form_command, string gif_file    [, string form_command, string gif_file ...] )


create.extra.toolbar()

Syntax

void create.extra.toolbar( string form_command, string gif_file
  [, string form_command, string gif_file ...] )

Description

This adds a secondary toolbar to a form.

Arguments

The buttons to be included on the toolbar are indicated by the function arguments. The arguments consist of one or more pairs of strings. In each pair, the first argument is the name of a form command; the second argument is the name of the .gif file that holds the required image.

To include a space between two groups of buttons, insert two empty strings in the argument list.

Return values

>0	success
  0	toolbar not allowed in this type of session
 -1	incorrect number of arguments

Context

4GL library function.

The most suitable location for this function is in the init.form section of your UI script.

Example

create.extra.toolbar( "check.out","checkout",

 "", "",

"edit.script", "modify1",

"compile", "compile",

"", "",

"check.in", "checkin" )

    Secondary toolbars: overview and synopsis


Variables (based): overview and synopsis

Overview

Use the at.base() function to base one variable (the based variable) on another variable (the basic variable). Both variables then use the same memory area.

The two variables must be of the same type. The possible types are string, string array, long array, and double array.

The based variable must be declared as BASED. If the two variables are in different processes, the basic variable must be declared as EXTERN.

Synopsis

long	at.base	( basic_variable [, arg ...], based_variable    [, arg ...] )
long	at.base	( long process_id, string name(.) [, arg ...],    based_variable [, arg ...] )


at.base()

Syntax

long at.base( basic_variable [, arg ...], based_variable [, arg ...] )

Description

Use this function to base one variable (the based variable) on another variable (the basic variable). The two variables then use the same memory area.

Arguments

basic_variable	The variable on which the based_variable is to be based. You can pass arguments to this variable. These specify the start position of the based variable within the basic variable. The default start position is 1.
based_variable	The based variable. You can pass arguments to this variable. These specify the length of the based variable. The length plus the start position must not exceed the length reserved for the basic variable. If you pass the argument -1 to the variable, the based variable uses the memory space of the basic variable from the specified start position to the end position. If this argument is 0, the variable uses the memory space of the basic variable from the specified start position for the declared length of the based variable. This variable must be declared as BASED.
Notes

If the variables are multidimensional long or double arrays, only the first element can differ in the declarations. This is because the array values are stored column by column.

Do not reallocate basic_variable (with alloc.mem()). Doing this can cause serious problems, such as a core dump or corrupted memory.

Context

Bshell process.

See also

at.base()

Example

In this example, the contents of the variable long_to_be_based(1, 1) are equal to the value of basic_long(4, 1). That is, a matrix of 2 by 5 longs.

long basic_long(5, 5)

long long_to_be_based(3, 5) based

at.base(basic_long, 4, 1, long_to_be_based, -1, 0)

Related help topics

    Variables (based):  overview and synopsis


at.base()

Syntax

long at.base( long process_id, string name(.) [, arg ...], based_variable
[, arg ...] )

Description

Use this function to base one variable (the based variable) on an external variable in another process (the basic variable). The two variables then use the same memory area.

Arguments

process_id	The ID of the process in which the basic variable is declared. This process must be started before the current process and must be ended after the current process.
name	The name of the external variable on which based_variable is to be based. You can pass arguments to this variable. These specify start position of the based variable within the basic variable. The default start position is 1. This variable must be declared as EXTERN.
based_variable	The based variable. You can pass arguments to this variable. These specify the length of the based variable. The length plus the start position must not exceed the length reserved for the basic variable. If you pass the argument -1 to the variable, the based variable uses the memory space of the basic variable from the specified start position to the end position. If this argument is 0, the variable uses the memory space of the basic variable from the specified start position for the declared length of the based variable. This variable must be declared as BASED.
Notes

If the variables are multidimensional long or double arrays, only the first element can differ in the declarations. This is because the array values are stored column by column.

If the process specified by process_id ends before the current process, the based variable can no longer be used. This is because the memory area allocated to the basic variable is freed. This can cause serious problems, such as a core dump or corrupted memory.

Context

Bshell process.

See also

at.base()

Example

Process 1

EXTERN string base_string(20,2,2)

Process 2

string string_to_be_based(20,2) based

long proc_id1

proc_id1 = activate("session_name_of_process1")

at.base( proc_id1, "base_string", string_to_be_based )

Related help topics

    Variables (based):  overview and synopsis


Variables (checking changes): overview

These functions provide a mechanism for checking changes to variables. The variables can be of type string, long, double, domain, or array.

You start the mechanism for a particular variable by calling on.change.check(). The current value of the variable becomes the checkpoint value for the checking mechanism. The variable is considered to have changed if its value differs from the checkpoint value. Using the checking mechanism slows down program execution.

Note that the report writer also uses these functions. And use of the functions in a report script can have unpredictable results.

Related help topics

    Variables (checking changes):  synopsis
    Variables (checking changes):  sample program


Variables (checking changes): synopsis

long	changed	( variable )
void	not.curr	( variable )
void	off.change.check	( variable )
void	on.change.check	( variable )
Related help topics

    Variables (checking changes):  overview
    Variables (checking changes):  sample program


changed()

Syntax

long changed( variable)

Description

This compares the current value of the specified variable with its checkpoint value to determine whether or not the value has changed.

Note

This function returns TRUE only if the value of the variable has changed since the last time you called the function.

Return values

TRUE	variable has changed
FALSE    	variable has not changed

Context

Bshell function.

Related help topics

    Variables (checking changes):  overview
    Variables (checking changes):  synopsis
    Variables (checking changes):  sample program


not.curr()

Syntax

void not.curr( variable )

Description

This switches the current and previous values of the specified variable. This is considered a value change by the checking mechanism. So if you subsequently call changed(), that function will return TRUE.

Context

Bshell function.

Related help topics

    Variables (checking changes):  overview
    Variables (checking changes):  synopsis
    Variables (checking changes):  sample program


off.change.check()

Syntax

void off.change.check( variable )

Description

This switches off the checking mechanism for the specified variable. Changes to the variable are no longer monitored by the checking mechanism.

Context

Bshell function.

Related help topics

    Variables (checking changes):  overview
    Variables (checking changes):  synopsis
    Variables (checking changes):  sample program


on.change.check()

Syntax

void on.change.check( variable )

Description

This starts the checking mechanism by setting a checkpoint for the specified variable. The current value of the variable becomes the checkpoint value.

Context

Bshell function.

Related help topics

    Variables (checking changes):  overview
    Variables (checking changes):  synopsis
    Variables (checking changes):  sample program


Variables (checking changes): sample program

string   city(10)

city = "Paris"

on.change.check( city )   | checkpoint value set to Paris

city = "Rotterdam"

on.change.check( city )   | checkpoint value now set to Rotterdam

city = "Amsterdam"

if ( changed(city) ) then

not.curr( city )

message( "City is changed, old city is: %s",city )  | city is Rotterdam

not.curr( city )

message( "New city is: %s",city )   | city is Amsterdam

endif

off.change.check(city)


Variables (interprocess transfer): overview and synopsis
Variables (inter-process transfer): overview and synopsis

Overview

Use these functions to access the variables of other processes. The variables can be of any type. They must be declared as external (with the keyword EXTERN).

Synopsis

long	get.var	( long processno, "variable", ref variable )
long	get.indexed.var	( long processno, "variable", ref variable,    long dim0 [, long dim1, long dim2,    long dim3 ] )
long	put.var	( long processno, "variable", expression )
long	put.indexed.var	( long processno, "variable", expression,    long dim0 [, long dim1, long dim2,    long dim3 ] )
long	import	( "variable", ref variable )
long	export	( "variable", expression )


get.var()

Syntax

long get.var( long processno, "variable", ref variable )

Description

This retrieves the value of the specified variable. The variable can be a single variable of any type or an array.

Arguments

processno	The process from which the variable is to be retrieved. You can specify the process ID, or you can use the predefined variables pid or parent.
“variable”	The name of the variable to be retrieved (this must be a lower case string). Alternately, you can specify a variable in which the name is stored.
variable	This stores the value of the retrieved variable.
Return values

0	error
1	success

Context

Bshell function.

Example

extern domain ttaad.cjob  cjob

form.1:

init.form:

get.var( parent, "cjob", ttaad500.cjob )

Related help topics

    Variables (interprocess transfer): overview and synopsis


get.indexed.var()

Syntax

long  get.indexed.var( long processno, "variable", ref variable, long dim0 [, long dim1, long dim2, long dim3 ] )

Description

This retrieves the value of the specified variable. It is the same as get.var() except that it enables retrieval of individual array elements.

Arguments

processno	The process from which the variable is to be retrieved. You can specify the process ID, or you can use the predefined variables pid or parent.
“variable”	The name of the variable to be retrieved (this must be a lower case string). The variable can be a single variable or an array and must be declared as external. Instead of specifying the variable name, you can specify a variable in which the name is stored.
variable	This stores the value of the retrieved variable or array element.
dim0 to dim3	Use these to specify a particular array element to be retrieved. To retrieve a single variable, set dim0 to 1 and omit the other dim arguments.
Return values

0	success
1	general error
2	incorrect number of dimensions
3	variable not found
4	array element not available

Context

Bshell function.

Example

extern long ltbl(10,5)

extern string block(10,5,5)

string ret_str(10)

long ret_lng

long e

ltbl(1,1) = 1

ltbl(2,2) = 2

ltbl(3,3) = 3

block(1,1,1) = "The"

block(1,1,2) = "quick"

block(1,2,1) = "brown"

block(1,2,2) = "jumps"

e = get.indexed.var( pid, "block", ret_str, 1, 2 )

| ret_str contains "quick     "

e = get.indexed.var( pid, "ltbl", ret_lng, 3, 3 )

| ret_lng is equal to 3

Related help topics

    Variables (interprocess transfer): overview and synopsis


put.var()

Syntax

long put.var( long processno, "variable", expression )

The assigns a new value to a specified variable in another process. The variable can be a single variable of any type or an array.

Arguments

processno	The process to which the destination variable belongs. You can specify the process ID, or you can use the predefined variables pid or parent.
“variable”	The name of the external variable in the other process (this must be a lower case string). Alternately, you can specify a variable in which the name is stored.
expression	The value to be assigned to the variable. If this is not the same type as the destination variable, it will be converted.
Return values

0	error; probably variable not found
1	success

Related help topics

    Variables (interprocess transfer): overview and synopsis


put.indexed.var()

Syntax

long put.indexed.var( long processno, "variable", expression, long dim0
[, long dim1, long dim2, long dim3 ] )

The assigns a new value to a specified variable in another process. It is the same as put.var() except that it enables a value to be assigned to an individual array element.

Arguments

processno	The process to which the destination variable belongs. You can specify the process ID, or you can use the predefined variables pid or parent.
“variable”	The name of the external variable in the other process (this must be a lower case string). Alternately, you can specify a variable in which the name is stored.
expression	The value to be assigned to the variable. If this is not the same type as the destination variable, it will be converted.
dim0 to dim3	Use these to specify a particular array element to which the new value is to be assigned. To assign a single variable value, set dim0 to 1 and omit the other dim arguments.
Return values

0	success
1	general error
2	incorrect number of dimensions
3	variable not found
4	array element not available

Example

extern string tst_str(25)

extern long   ltbl(10,5)

string ret_str(10)

long ret_lng

long e

ret_str = "Hello"

e = put.indexed.var( pid, "tst_str", ret_str, 1 )

ret_lng = 8

e = put.indexed.var( pid, "ltbl", ret_lng, 1, 1 )

ret_lng = 10

e = put.indexed.var( pid, "ltbl", ret_lng, 1, 2 )

ret_lng = 4

e = put.indexed.var( pid, "ltbl", ret_lng, 2, 1 )

ret_lng = 2

e = put.indexed.var( pid, "ltbl", ret_lng, 2, 2 )

| table is filled as follows:

| ltbl(1,1) = 8

| ltbl(1,2) = 10

| ltbl(2,1) = 4

| ltbl(2,2) = 2

Related help topics

    Variables (interprocess transfer): overview and synopsis


import()

Syntax

long import( "variable", ref variable )

Description

This is equivalent to get.var( parent, "variable", ref variable ).

Related help topics

    Variables (interprocess transfer): overview and synopsis


export()

Syntax

long export( "variable", ref variable )

Description

This is equivalent to put.var( parent, "variable", ref variable ).

Related help topics

    Variables (interprocess transfer): overview and synopsis


User interface objects: overview

BaanERP Tools provides a library of user interface objects and subobjects that you can use as the building blocks for a complete graphical user interface. The available object types include windows, graphs, graphical images, and a wide range of user interface controls such as menu bars, toolbars, scroll bars, list boxes, check boxes, and so on. The available subobjects consist of graphical parts, such as arcs, lines, and rectangles, which you can create in graphical windows.

Each object and subobject includes a set of attributes that defines its appearance and state. BaanERP Tools provides a set of functions that you can use to create and manipulate objects and subobjects, and to set and retrieve their attributes.

Each object and subobject has an identification number that is unique for all bshell processes.

Notes

You must always use the rgb() function to compose colors.

In the lists of attributes for each object type, the following flags are used:

C	You can define the attribute when creating the object with the functions create.object(), create.sub.object(), or create.sub.object.by.id().
S	You can define the attribute when changing the object with the functions change.object() or change.sub.object().
G	You can read the attribute with the functions get.object() or get.sub.object().
Q	You can query the attribute with the functions query.object() or query.sub.object().
Related help topics

    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


User interface objects: synopsis

void	change.object	( long object_id [, long attribute, value   [, size] ] ... )
void	change.sub.object	( long object, long sub_object_id [, long   attribute, value [, size] ] ... )
long	compress.pixmap	( long colormap(), long num_colors,    string pixmap(), long width,    long height, ref string buffer(),    ref long buffer_length )
long	create.object	( long type, long parent_object [, long    attribute, value [, size] ] ... )
long	create.sub.object	( long object, long type, [, long    attribute, value [, size] ] ... )
long	create.sub.object.by.id	( long object, long sub_object_id,    long type [, long attribute, value    [, size] ] ... )
long	decompress.pixmap	( string buffer(), ref long colormap(),   ref string pixmap() )
void	destroy.object	( long object_id )
void	destroy.sub.object	( long object, long sub_object_id )
long	get.object	( long object_id [, long attribute,    ref value [, ref value] ] ... )
long	get.pixmap.info	( ref string buffer(), ref long num_colors,   ref long width, ref long height )
long	get.sub.object	( long object, long sub_object_id    [, long attribute, ref value    [, ref size] ] ... )
void	inherit.object	( long process_nr, long object_id )
void	lower.object	( long object_id )
void	map.object	( long object_id )
long	query.object	( long object_id [, long attribute, value    [, size] ] ... [, long attribute,    ref value [, ref size] ] ... )
long	query.sub.object	( long object_id, long sub_object_id    [, long attribute, value [, size] ] ...   [, long attribute, ref value    [, ref size] ] ... )
void	raise.object	( long object_id )
void	set.focus	( long object_id )
void	set.sensitive	( long object_id, long status )
void	unmap.object	( long object_id )
void	unset.focus	( long object_id )
void	update.object	( long object_id )
Related help topics

    UI objects:  overview
    UI objects:  objects and subobjects
    UI objects:  example


Objects and subobjects

This table lists all the available object and subobject types. It also indicates which object types support child objects. Note that only the DsCgwindow object supports subobjects.

Object	Accepts children	Subobject	Accepts children
DsCbarMenu	no	DsCgpArc	no
DsCcheckBox	no	DsCgpComposite	no
DsCcolorCell	no	DsCgpGroupBox	no
DsCcolormap	no	DsCgpHeader	no
DsCcomBox	no	DsCgpImage	no
DsCdDComBox	no	DsCgpLine	no
DsCdDListBox	no	DsCgpOleSite	no
DsCdrawnButton	no	DsCgpPie	no
DsCfield	no	DsCgpPolygon	no
DsCfontSet	no	DsCgpPolyline	no
DsCframe	yes	DsCgpRectangle	no
DsCgc	no	DsCgpText	no
DsCgraph	no
DsCgrid	no
DsCgwindow	yes
DsClabel	no
DsClistBox	no
DsCmwindow	yes
DsCpixmap	no
DsCpushButton	no
DsCradioBox	yes
DsCradioButton	no
DsCrowColumn	yes
DsCscrollWindow	yes
DsCscrollbar	no
DsCslider	no
DsCstatusBar	no
DsCtabFrame	yes
DsCtemplate	no
DsCtoolBar	no
DsCtree	no
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  example


change.object()

Syntax

void change.object( long object_id [, long attribute, value [, size] ] ... )

Description

This changes the attribute values of the specified object.

Arguments

object_id	The object ID, as returned by create.object() when the object was created.
attribute, value, size	Use these arguments to set new values for the object's attributes. For each attribute you specify, you must include the attribute type (for example, DsNmaximum or DsNminimum), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


change.sub.object

Syntax

void change.sub.object( long object, long sub_object_id [, long attribute, value [, size] ] ... )

Description

This changes the attribute values of the specified subobject.

Arguments

object	The ID of the parent object, as returned by create.object() when the parent object was created.
sub_object_id	The ID of the subobject, as returned by create.sub.object() or create.sub.object.by.id() when the subobject was created.
attribute, value, size	Use these arguments to set new values for the subobject's attributes. For each attribute you specify, you must include the attribute type (for example, DsNgcBackground or DsNgcForeground), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


compress.pixmap()

Syntax

long compress.pixmap( long colormap(), long num_colors, string pixmap(), long width, long height, ref string buffer(), ref long buffer_length )

Description

This converts a specified colormap and pixmap to a picture in .gif format.

Arguments

colormap	The ID of the DsCcolormap object that must be converted.
num_colors	The number of colors defined by the specified colormap object.
pixmap()	The ID of the DsCpixmap object that must be converted.
width	The width of the pixmap, in pixels.
height	The height of the pixmap, in pixels.
buffer	This returns the data for the .gif picture. To access the .gif picture, you must write the buffer data to a file by calling seq.write().
buffer_length	This returns the length of the buffer.
Return values

TRUE (!=0)	success
FALSE (=0)	error

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


create.object()

Syntax

long create.object( long type, long parent_object [, long attribute, value [, size] ] ... )

Description

This creates a new object of the specified type.

Arguments

type	The type of object to be created. For example, DsCbarMenu or DsCcheckBox.
parent_object	The ID of the parent object. You must create an object within a parent object. The parent object can be a main window, another object, or the current display.
attribute, value, size	Use these optional arguments to set the object's attributes. For each attribute you specify, you must include the attribute type (for example, DsNmaximum or DsNminimum), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Return values

The ID for the new object, or 0 if an error occurs. You can subsequently use the returned ID as the object_id, parent_object, or object argument in other functions.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


create.sub.object()

Syntax

long create.sub.object( long object, long type [, long attribute, value [, size] ] ... )

Description

This creates a new subobject of the specified type. The subobject is drawn on the parent window. If the parent object is destroyed, its subobjects are also destroyed.

Arguments

object	The ID of the parent object, as returned by create.object() when the parent object was created. The parent object is always a DsCgwindow object.
type	The type of subobject to be created. For example, DsCgpArc or DsCgpLine.
attribute, value, size	Use these arguments to set the subobject's attributes. For each attribute you specify, you must include the attribute type (for example, DsNgcBackground or DsNgcForeground), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Return values

The ID for the new subobject or 0 if an error occurs. You can subsequently use the returned ID as the sub_object_id argument in other functions.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


create.sub.object.by.id()

Syntax

long create.sub.object.by.id( long object, long sub_object_id, long type [, long attribute, value [, size ] ] ... )

Description

This creates a new subobject with a specified ID. The subobject is drawn on the parent window. If the parent object is destroyed, its subobjects are also destroyed.

Arguments

object	The ID of the parent object, as returned by create.object() when the parent object was created. The parent object is always a DsCgwindow object.
sub_object_id	The ID for the new object.
type	The type of subobject to be created. For example, DsCgpArc or DsCgpLine.
attribute, value, size	Use these arguments to set the subobject's attributes. For each attribute you specify, you must include the attribute type (for example, DsNgcBackground or DsNgcForeground), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
Return values

The ID for the new subobject (as specified by the sub_object_id argument) or 0 if an error occurs. You can subsequently use the returned ID as the sub_object_id argument in other functions.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


decompress.pixmap()

Syntax

long decompress.pixmap( string buffer(), ref long colormap(), ref string pixmap() )

Description

This converts a picture in .gif format to a colormap and pixmap. The long array returned by the colormap argument can subsequently be used as the DsNcolorTable attribute of a DsCcolormap object. The string array returned by the pixmap argument can subsequently be used as the DsNdata attribute for a DsCpixmap object.

Arguments

buffer	The buffer containing the .gif file data, as returned by a seq.read() call.
colormap	This returns an array of rgb values that you can use as the DsNcolorTable attribute for DsCcolormap objects.
pixmap	This returns an array of indexes into the returned colormap. You can use this as the DsNdata attribute of DsCpixmap objects.
Return values

TRUE (!=0)	success
FALSE (=0)	error

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


destroy.object()

Syntax

void destroy.object( long object_id )

Description

This removes the specified object and all its children (if any).

Arguments

object_id	The object ID, as returned by create.object() when the object was created.
Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


destroy.sub.object()

Syntax

void destroy.sub.object( long object, long sub_object_id )

Description

This removes the specified subobject.

Arguments

object	The ID of the parent object, as returned by create.object() when the parent object was created.
sub_object_id	The ID of the subobject, as returned by create.sub.object() or create.sub.object.by.id() when the subobject was created.
Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


get.object()

Syntax

long get.object( long object_id [, long attribute, ref value [, ref size] ] ... )

Description

This retrieves information about a specified object.

Arguments

object_id	The object ID, as returned by create.object() when the object was created.
attribute	The attribute you want to retrieve (for example, DsNtitle or DsNbackground).
value	This returns the current value of the specified attribute.
size	For attributes of type void data and long array, this returns the size of the data or array.
Return values

TRUE	success
FALSE      error

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


get.pixmap.info()

Syntax

long get.pixmap.info( ref string buffer(), ref long num_colors, ref long width, ref long height )

Description

This retrieves information about a picture, in .gif format, that has been read with the seq.read() function. It returns the number of colors in the picture and the picture's width and height. When a picture is used in an object, the width and height values are necessary for determining the amount of memory that must be allocated for the picture.

Arguments

buffer	The buffer containing the data retrieved by seq.read().
num_colors	This returns the number of colors used in the picture.
width	This returns the width of the picture, in pixels.
height	This returns the height of the picture, in pixels.
Return values

TRUE	success
FALSE	error

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


get.sub.object()

Syntax

long get.sub.object( long object, long sub_object_id  [, long attribute, ref value [, ref size] ] ... )

Description

This retrieves information about a specified subobject.

Arguments

object	The ID of the parent object, as returned by create.object() when the object was created.
sub_object_id	The ID of the subobject of the specified parent object.
attribute	The attribute you want to retrieve (for example, DsNgcBackground or DsNgcForeground).
value	This returns the current value of the specified attribute.
size	For attributes of type void data and long array, this returns the size of the data or array.
Return values

TRUE	success
FALSE     	error

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


inherit.object()

Syntax

void inherit.object( long process_nr, long object_id )

Description

With this function, a process can inherit an object from its parent process. For example, a zoom process can use a pushbutton that was defined in the parent process.

Arguments

process_nr	The process ID of the parent process.
object_id	The ID of the object that must be inherited.
Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


lower.object()

Syntax

void lower.object( long object_id )

Description

This moves the specified object to the bottom of the object stack on the workspace.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


map.object()

Syntax

void map.object( long object_id )

Description

This makes the specified object visible, without changing the order of the objects on the workspace.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


query.object()

Syntax

long query.object( long object_id [, long attribute_in, value_in [, size_in] ] ...  [, long attribute_in, ref value_out [, ref size_out] ] ... )

Description

This retrieves information about a specified object, based on specified attribute values. For example, you can query a DsCgwindow object for the ID of the subobject that is located at specified x- and y-coordinates within the gwindow. Or you can query a DsCgrid object for the type of control that a specified column contains.

Arguments

object_id	The ID of the object to be queried, as returned by create.object() when the object was created.
attribute_in, value_in, size_in	You can use one or more sets of these arguments to specify the input attributes for the query. For each attribute you specify, you must include the attribute type (for example, DsNcolumns), and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
attribute_in, value_out, size_out	You can use one or more sets of these arguments to specify the output of the query. For each attribute you specify, you must include the attribute type (for example, DsNcontrol). The function returns the current value of the attribute. For attributes of type void data or long array, it also returns the size of the data or array.
Return values

TRUE	success
FALSE   	error

Context

Bshell function.

Examples

The following are examples of some of the situations in which you can use the query.object() function:

1	To retrieve the ID of the subobject located at a specified position within a graphical window. If there is more than one subobject at the specified location, the function returns the ID of the uppermost subobject.

long mwin_id, gwin_id, gp1, gp2, gp3, part

mwin_id = create.object( DsCmwindow, current.display(),
DsNbackground,  RGB.BLACK,

DsNminHeight,   400,

DsNminWidth,    650,

DsNflags,       DSNORMALSTATE+DSAUTORESIZE )

gwin_id = create.object( DsCgwindow, mwin_id,

DsNbackground,  RGB.BLUE,

DsNwidth,       200,

DsNheight,      100,

DsNx,           30,

DsNy,           30 )

update.object( gwin_id )

gp1 = create.sub.object( gwin_id, DsCgpRectangle,

DsNgcBackground, RGB.WHITE,

DsNheight,       50,

DsNwidth,        50,

DsNx,            0,

DsNy,            0 )

gp2 = create.sub.object( gwin_id, DsCgpArc,

DsNgcBackground, RGB.BLACK,

DsNheight,       20,

DsNwidth,        20,

DsNx,            10,

DsNy,            10 )

gp3 = create.sub.object( gwin_id, DsCgpLine,

DsNgcBackground, RGB.RED,

DsNxo,           1,

DsNyo,           1,

DsNxn,           1,

DsNyn,           200 )

update.object( mwin_id )

query.object( gwin_id,

 	DsNx,         20,

DsNy,         20,

DsNsubObject, part )

           	| part contains the value of gp2

2	To retrieve the IDs of the subobjects that occur within a particular area of a graphical window.

   long part.list(20)    | max. 20 parts

   long num.parts

   query.object( gwin_id,

                 DsNx,         5,

                 DsNy,         5,

                 DsNsize,      20,        | maximum number of parts

                 DsNwidth,     30,

                 DsNheight,    30,

                 DsNsubObjectArray, part.list, num.parts )

The num.parts argument now contains the number of subobjects that occur within the specified area (in this case, 2). The part.list array contains the IDs of the subobjects (in this example, it contains the IDs of gp1 and gp2).

3	To retrieve the ID of the subobject that in on the top of the subobject stack. If the DsCgwindow object does not contain any parts, 0 is returned.

query.object( gwin_id, DsNfirstSubObject, part )

   | part contains the ID of gp1

4	 To retrieve the ID of the subobject on the bottom of the subobject stack. If the DsCgwindow object does not contain any parts, 0 is returned.

query.object( gwin_id, DsNlastSubObject, part )

   | part contains the ID of gp3

5	To retrieve the ID of the subobject that follows a specified reference subobject in the subobject stack. The stack is built from top to bottom. So the function returns the ID of the subobject below the reference subobject. If the reference subobject is the last subobject in the stack, 0 is returned.

query.object( gwin_id, DsNrefSubObject, gp2, DsNnextSubObject, part )

   | part contains the ID of gp3

6	To retrieve the ID of the subobject that precedes the specified reference subobject in the subobject stack. The stack is built from top to bottom. So the function returns the ID of the subobject above the reference subobject. If the reference subobject is the first subobject in the stack, 0 is returned.

query.object( gwin_id, DsNrefSubObject, gp2, DsNprevSubObject, part )

     | part contains the ID of gp1

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


query.sub.object()

Syntax

long query.sub.object( long object_id, long sub_object_id [, long attribute_in, value_in [, size_in] ] ...  [, long attribute_in, ref value_out [, ref size_out] ] ... )

Description

This retrieves information about a specified subobject, based on specified attribute values. For example, you can query a DsCgpOleSite subobject for data in a specific format.

Arguments

object_id	The ID of the object to which the subobject belongs.
sub_object_id	The ID of the subobject within the specified object.
attribute_in, value_in, size_in	You can use one or more sets of these arguments to specify the input attributes for the query. For each attribute you specify, you must include the attribute type and the attribute value. For attributes of type void data or long array, you must also include the size of the data or array.
attribute_in, value_out, size_out	You can use one or more sets of these arguments to specify the output of the query. For each attribute you specify, you must include the attribute type. The function returns the current value of the attribute. For attributes of type void data or long array, it also returns the size of the data or array.
Return values

TRUE	success
FALSE   	error

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


raise.object()

Syntax

void raise.object( long object_id )

Description

This moves the specified object to the top of the object stack on the workspace.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


set.focus()

Syntax

void set.focus( long object_id )

Description

This moves the keyboard input focus to the specified object. When an object has input focus, all keyboard input within the object's main window is received by that object, regardless of the position of the cursor. When an object has input focus, it is surrounded by a rectangular highlight.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


set.sensitive()

Syntax

void set.sensitive( long object_id, long status )

Description

This sets the sensitivity of a specified object.

Arguments

object_id	The ID of the object.
status	The status that must be set for the object. Possible values are: DSSETSENSITIVE DSSETINSENSITIVE When the status of an object is set to insensitive, the object and its children are disabled.
Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


unmap.object()

Syntax

void unmap.object( long object_id )

Description

This makes the specified object invisible.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


unset.focus()

Syntax

void unset.focus( long object_id )

Description

This removes keyboard input focus from the specified object.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


update.object()

Syntax

void update.object( long object_id )

Description

This (re)draws the specified object. Some changes made to DsCgwindow and DsCbarMenu objects are stored internally and become visible only after an update.object() call. You must also call this function to make new DsCmwindow and DsCgwindow objects visible.

Context

Bshell function.

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCbarMenu

Description

A DsCbarMenu object defines a menu bar and associated drop-down and cascaded menus. The menu bar is displayed across the top of a main window (DsCmwindow), below the title bar.

An application creates the entire menu with a single create.object() call. Subsequently, it can use change.object() to add, remove, change, enable, and disable menu items.

Remember to specify the identification number of the DsCbarMenu object in the DsNbarMenu attribute of the parent window.

Events

A DsCbarMenu object can generate the following event type:

EVTMENUSELECT

Attributes

DsNcommandList          (long array)	[CS]	Use this to set the state of menu items and to remove menu items. The array contains one or more index/attribute pairs. The index is an index into the list created by DsNmenuData. The menu entry identified by each index (1-based) is set to the associated attribute value. Possible attribute values are:             DSMENUNORMAL DSMENUDISABLED DSMENUCHECKED DSMENUREMOVE DSMENURADIOBUTTON You can modify or remove multiple menu items with a single change.object() call.
DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNfunction                  (long)	[CS]	Specifies whether menu items are to be added before or after the point specified by DsNrefCommand. Possible values are: DSMENUINSERT (default) DSMENUAPPEND
DsNmenuData            (void)	[CSG]	This contains the menu data in binary format. The data includes the structure of the menu, menu item names, shortcut and access keys, and the state and ID (return value) of menu items.  The data must start with a header containing the following fields: long   Version number (currently always 1). long   Number of entries to follow. This is followed by multiple entries in the following format: long Menu hierarchy level. long  Unique command identifier. Separators must always  be assigned an ID of -1; cascaded menu entries must  always be assigned an ID of 0. string Null terminated name string (mb). long     State of menu items – possible values are: DSMENUNORMAL DSMENUDISABLED DSMENUCHECKED DSMENUREMOVE DSMENURADIOBUTTON You can use DsNmenuData to create a new menu and also to add items to existing menus.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNrefCommand             (long)	[S]	This contains the index (1-based offset) of the menu position where menu items are to be added or inserted.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
Examples

The following is an example of DsNmenuData data used to create a new menu:

Version	Count
1	12

Level	ID	Name	Flag
1	0	&File	0
2	15	&Save	0
2	-1	-	0
2	23	&Print\tCtrl + P	0
2	-1	-	0
2	37	E&xit\tAlt + F4    	0
1	0	&Edit	0
2	17	&Undo	           	0
2	-1	-	0
2	6	&Find...	0
1	0	&Help	0
2	72	&Contents	0

The following function call creates the menu specified in DsNmenuData:

barmenu.id = create.object(barmenu_id, DsCbarMenu, parentWindow,
DsNmenuData, data, size)

The following is an example of DsNmenuData used to add new entries to the menu:

Version	Count
1	2

Level	ID	Name	Flag
2	90	&Redo	           	0
2	901	&Delete	0

The following function call adds the new entries after the Undo menu item:

change.object(barmenu_id, DsNmenuData, data, size, DsNrefCommand,
8, DsNfunction, DSMENUAPPEND)

The following code disables the Print menu item and removes the Undo menu item:

long commandlist(4)

commandlist(1) = 4	| index of Print menu item

commandlist(2) = DSMENUDISABLE

commandlist(3) = 8	| index of Undo menu item

commandlist(4) = DSMENUREMOVE

change.object(barmenu.id, DsNcommandList, commandlist, 4)

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCcheckBox

Description

A check box represents a choice that has two states (selected or not selected). It appears as a square box with an accompanying label. When the choice is selected, a check mark appears in the box. When the choice is not selected, the box is empty.

Users can toggle a check box on and off with the mouse or keyboard keys. Check boxes are typically used in a group to provide a multiple-choice field. Within a group, they represent independent choices that are not mutually exclusive.

Events

A DsCcheckBox object can generate the following event types:

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

EVTBUTTONSELECT

Attributes

DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNfontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the label text. If this attribute is not set, the Windows default font is used.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNjustify (long)	[CSG]	The alignment of the label text. Possible values are: DSJUSTIFYLEFT (default) DSJUSTIFYRIGHT DSJUSTIFYCENTER
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNset (long)	[CSG]	The state of the check box. Possible values are: TRUE Check box selected. FALSE Check box not selected (default).
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNstring (string)	[CSG]	The label text.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCcolorCell

Description

A color cell is a rectangular child window that displays a color. If possible, a color cell uses only one palette entry and so saves resources. Otherwise, the number of colors used increases with every change.

Events

A DsCcolorCell object does not generate events.

Attributes

DsNbackground (long)	[CSG]	The rgb value that defines the background color of the object. If this attribute is not specified, the object inherits the background color of its parent. If none of the parent objects specify a background color, the resource workAreaBackground is used.
DsNborderWidth (long)	[CSG]	The width of the object's border, in pixels.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCcolormap

Description

A color map defines an array of colors that can be used by a DsCpixmap object. The DsNdata attribute of a pixmap object contains an array of indexes into the color table of a DsCcolormap object.

Events

A DsCcolormap object does not generate events.

Attributes

DsNcolorTable (long array)	[CSG]	An array of rgb values.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCcomBox, DsCdDComBox, DsClistBox, DsCdDListBox

Description

A list box (DsClistBox) displays a list of choices from which the user can select one or more items.

A drop-down list box (DsCdDListBox) also displays a list of choices, but the list is displayed only on demand and the user can select only a single item. Users must open the control to view the list. When the list is closed, the control displays the current value.

A combo box (DsCcomBox) is a combination of a text box and a single-selection list box. Users can type their choice in the text box or select an item from the list.

A drop-down combo box (DsCdDComBox) is a combination of a text box and a drop-down list box. Users can type their choice in the text box or select an item from the list. The list is displayed only on demand – that is, users must open the control to view the list. When the list is closed, the control displays the current value.

For all the above controls, vertical and/or horizontal scroll bars are displayed when the list box is not large enough to display all items in full.

Events

These objects can generate the following events:

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

EVTLISTBOXSELECT

Attributes

DsNallowMultiSelection    (long)	[CG]	DsClistBox objects only. Indicates whether a user can select more than one item. Possible values are:  TRUE Multiselection permitted. FALSE     Multiselection not permitted (default).
DsNcolumns (long)	[CSG]	The width of the list box, in characters. The default is 0. Note that DsNwidth and DsNcolumns are mutually exclusive attributes.
DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNfontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the object's text. If this attribute is not set, the Windows default font is used.
DsNheight (long)	[G]	The height of the object, in pixels.
DsNitemCount (long)	[G]	The total number of items in the list box. This attribute is updated whenever an item is added or removed.
DsNmaxLength (long)	[CSG]	DsCcomBox and DsCdDComBox objects only. The maximum number of input characters in the text field. This can be any value from 0 to 4096. The default is 4096.
DsNmaxWindowSize (long)	[CSG]	The maximum number of items the list box can contain.
DsNminWidth (long)	[CSG]	The minimum width of the list box, in pixels.
DsNminWindowSize (long)	[CSG]	The minimum number of items the window can contain.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNselected    (long)	[CS]	DsClistBox objects only. This determines the state of the items specified by DsNselectedId or DsNselectionArray. Possible values are: TRUE Items are selected. FALSE     Items are unselected. This attribute is valid only when DsNallowMultiSelection is TRUE.
DsNselectedId (long)	[CSG]	The item ID of the currently selected item. An item ID of -1 causes the list box to act in a special way. In a single-selection list, all items are unselected. In a multiselection list, all items are selected or unselected, depending on the value of DsNselected.
DsNselectionArray   (long array)	[CSG]	DsClistBox objects only. The item IDs of all selected items in a multiselection list. The array length is 2 * DsNselectionCount.
DsNselectionCount     (long)	[G]	DsClistBox objects only. The number of items currently selected in a multiselection list.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNstring (string array)	[CSG]	DsCcomBox and DsCdDComBox objects only. The text to be displayed in the text box. You can specify from 0 to 4096 characters. The default is an empty string.
DsNstringArray	[CS]	This contains the text and ID of each item in the list box. The data must be filled as follows: itemstring + idstring + itemstring + idstring ... All strings are null terminated.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCdrawnButton

Description

A DsCdrawnButton object has the same functionality as a DsCpushButton object except that it displays a graphical image instead of a text label.

Events

A DsCdrawnButton object can generate the following events:

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

EVTBUTTONSELECT

Attributes

DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNpixmap (long)	[CSG]	The ID of the DsCpixmap object to be displayed on the button.
DsNreturnValue (long)	[CSG]	The value that will be returned when the button is selected. The return value must be handled as an event. See Events.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCfield

Description

A DsCfield object provides a rectangular child window where the user can enter and edit text. It can be defined to support a single line or multiple lines of text. A DsCfield object provides the same functionality as a Windows text box (also referred to as an edit control).

Events

A DsCfield object can generate the following events:

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

EVTFIELDSELECT

Attributes

DsNcolumns (long)	[CSG]	The width of the text box, in characters. For proportional fonts, the width is based on the widest character of the font.  DsNwidth and DsNcolumns are mutually exclusive attributes. If both are zero, the window width is determined by the length of the string it contains and the font used.
DsNconvertSoftReturn (long)	[CSG]	Specifies whether or not soft returns in a multiline text box must be converted to hard returns. Possible values are: TRUE Soft returns are converted to hard returns (default). FALSE      Soft returns are not converted to hard returns.
DsNeditable (long)	[CSG]	Specifies whether or not users can edit the text string. Possible values are: TRUE User can edit text string (default). FALSE      User cannot edit text string.
DsNeditMode (long)	[CG]	Specifies how the TAB key is handled. Possible values are: DSNORMALEDITMODE TAB generates a change focus event  (default). DSTEXTEDITORMODE TAB is inserted in the text.
DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNfieldData (void)	[CSG]	The contents of the text box. Use this attribute if the string length is greater than 4Kb. Otherwise, use DsNstring. The string must be null terminated.
DsNfontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the object's text. If this attribute is not set, the Windows default font is used.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNjustify (long)	[CG]	Specifies the alignment of text in a multiline window. The possible values are : DSJUSTIFYLEFT (default) DSJUSTIFYRIGHT DSJUSTIFYCENTER
DsNmaxLength (long)	[CSG]	Specifies the maximum length of the text string that a user can enter from the keyboard.
DsNmultiLine (boolean)	[CG]	Specifies whether the text box supports multiple lines of text or only a single line. Possible values are: TRUE Multiline. FALSE    Single line (default). DsNmultiLine and DsNpasswordField are mutually exclusive options.
DsNobjectType               (long)	[G]	The object type.
DsNoffset (long)	[S]	The offset (position) in the text box where the data in DsNstring or DsNfieldData is to be inserted. If this attribute is not specified, the new text overwrites the current text.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNpasswordField (boolean)	[CG]	Specifies a password-type text box. That is, characters entered in the text box are displayed as asterisks. DsNmultiLine and DsNpasswordField are mutually exclusive options.
DsNrows (long)	[CSG]	The number of rows in a multiline text box. DsNheight and DsNrows are mutually exclusive attributes. If both are zero, the window height depends on the settings of the DsNfontSet, DsNstring, and DsNmultiLine attributes.
DsNselectionArray (long array)	[CSG]	The current position of the cursor or selection in the text box. The array contains two longs that represent the start and end position of the selection (zero-based index). When the two values are the same, this represents the position of the cursor.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNsize (long)	[G]	The length of the string in the text box, including the null character at the end of the string.
DsNstring (string)	[CSG]	The contents of the text box. The string can be a maximum of 4Kb. For long strings, use DsNfieldData instead.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNtoolTip (string)	[CSG]	The tooltip string associated with the text box. This is displayed when the user positions the mouse pointer over the window for one second or more. The string can be a maximum of 80 characters.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNwordWrap (long)	[CG]	Specifies whether word wrap is enabled or disabled in a multiline text box. Possible values are: TRUE Word wrap on (default). FALSE     Word wrap off.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCfontSet

Description

A DsCfontSet object defines a set of font attributes that other objects can apply to text strings. Objects indicate the font set to use by specifying the object ID of the font set in their DsNfontSet attribute.

Events

A DsCfontSet object does not generate events.

Attributes

DsNfsBaseline (long)	[G]	The height of the font (in pixels) relative to the baseline. This attribute corresponds to the MS Windows Ascent attribute.
DsNfsHeight (long)	[CG]	The height of the font, in pixels. When creating a font object, the height includes the internal leading. When retrieving information about a font object, the height excludes the internal leading. The default value is 12.
DsNfsMaWidth (long)	[G]	The maximum width of a (multibyte) character in pixels * 10. For nonproportional fonts, this attribute is identical to the DsNfsWidth attribute.
DsNfsPoints (long)	[G]	The height of the font in pixels * 10. This is the same value as returned by DsNfsHeight * 10.
DsNfsSlant  (long)	[CG]	Possible values are: FNTROMAN FNTITALIC
DsNfsSpacing  (long)	[CG]	The type of spacing. Possible values are: FNTFIXED     Fixed spacing. FNTVARIABLE Proportional spacing.
DsNfsTypeface (string)	[CG]	The typeface name. For example,  "Courier" or "MS Sans Serif". The following values have a special meaning: "DefaultFixed" Use a predefined default font with fixed width character spacing. "DefaultVariable"  Use a predefined default font with proportional  character spacing. If this attribute is not specified, or if it contains an empty string, BW uses the first font that matches the other specified attributes.
DsNfsWeight (long)	[CG]	The weight of the font. Possible values are: FNTMEDIUM FNTBOLD FNTNORMAL
DsNfsWidth (long)	[CG]	The average width of the font in pixels * 10. When neither DsNfsWidth nor DsNfsHeight are specified, the default is 8. When DsNfsWidth is not specified but DsNfsHeight is specified, the default width is DsNfsHeight/π.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNstring (string)	[Q]	Use this attribute in a query operation to retrieve the height and width of the specified text string as displayed using the font set. The reply message contains the DsNwidth and DsNheight attributes of the string.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCframe

Description

A DsCframe object places a three-dimensional border around a single child object.

Events

A DsCframe object does not generate events.

Attributes

DsNfontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the title string defined by DsNstring.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNshadowType (long)	[CG]	The frame's border style. Possible values are: DSSHADOWNONE        No shadowed border. DSSHADOWIN                  Frame appears inset. DSSHADOWOUT         Frame appears outset (default). DSSHADOWETCHEDIN    Frame uses the grouping border style. DSSHADOWGROUPBOX Frame uses the grouping border style – this frame style can display a title string (left aligned).
DsNstring (string)	[CSG]	The text string for the frame title. This is visible only when DsNshadowType is DSSHADOWGROUPBOX.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgc

Description

A graphical context object (DsCgc) defines a set of attributes that can be applied to graphical parts (that is, to subobjects of type DsCgpArc, DsCgpLine, DsCgpPie, and so on).

When multiple graphical parts have common attributes, you can define those attributes in a DsCgc object instead of specifying them individually for each graphical part. You can then apply the attributes to a graphical part by specifying the ID of the relevant DsCgc object in the DsNgc attribute of the graphical part. Using this mechanism improves performance because less data needs to be transferred between the bshell and the user interface.

Events

A DsCgc object does not generate events.

Attributes

DsNgcBackground (long)	[CSG]	The rgb value that defines the background color of the graphical part.
DsNgcCapStyle (long)	[CSG]	This controls the appearance of line ends. Possible values are: GCCAPBUTT Lines are square at the endpoint. GCCAPROUND Lines are terminated by a circular arc whose    diameter equals the line width.
DsNgcFillColor (long)	[CSG]	The rgb value that defines the fill color of the graphical part. This is relevant only to polygons, rectangles, and pies.
DsNgcFillStyle (long)	[CSG]	The fill style for a graphical part. Possible values are: GCFILLSOLID Fill solid. GCFILL90 Fill 90 %. GCFILL75 Fill 75 %. GCFILL50 Fill 50 %. GCFILL25 Fill 25 %. GCFILL10 Fill 10 %. GCFILL00 Fill 0 %. GCFILLHOR Fill with horizontal lines. GCFILLVER Fill with vertical lines. GCFILLSLEFT Fill with slant left lines. GCFILLSRIGHT Fill with slant right lines. GCFILLHOLLOW  Do not fill.
DsNgcFontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to text in the graphical part.
DsNgcForeground (long)	[CSG]	The rgb value that defines the foreground color of the graphical part.
DsNgcJoinStyle (long)	[CSG]	Defines how corners are drawn. Possible values are: GCJOINMITER The outer edges of the two lines extend to meet  at an angle. GCJOINROUND Lines are joined by a circular arc whose diameter  equals the line width and which is centered on                       the join point.
DsNgcLineStyle (long)	[CSG]	The line and border style for a graphical part. Possible values are:  GCLINESOLID Normal line. GCLINEDOUBLEDASH Line stippled, using DsNgcForeground and DsNgcBackground colors. GCLINEONOFFDASH Line stippled, using DsNgcForeground and  the window's background color.
DsNgcLineWidth (long)	[CSG]	The width of lines and borders, in pixels.
DsNgcTextStyle (long)	[CSG]	Defines the style of graphical text. Possible values are: TSNORMAL Normal text TSBOLD Bold text TSREVERSE Reverse text TSUNDERLINE Underlined text TSFILLSOLID  Fill with background color
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNtemplate	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgraph

Description

A graph is a rectangular child window that displays a graph. The DsCgraph object is not part of the standard BaanERP Tools object library. It is a third-party OCX control. It can be controlled from 3GL scripts in the same way as standard objects. Several graphs can be displayed simultaneously within the same main window. A wide range of graph types is supported.

Events

A DsCgraph object can generate the following events:

EVTBUTTONPRESS

EVTBUTTONRELEASE

The parameters of these events are as described in Event array parameters, with the following exceptions:

evt.button.x	The graph set selected.

evt.button.y	The graph point selected.

evt.button.rootx	The x-coordinate (Graphic Server units).

evt.button.rooty	The y-coordinate (Graphic Server units).

evt.button.state	0 when a graph set/point is selected
(Shift and Control states are not supported).

Attributes

DsNbackgroundColor (long)	[CSG]	The background color for the graphic object specified by the  DsNbackgroundUse attribute. Possible values are: DSBLACK        Black DSBLUE                   Blue DSGREEN        Green DSCYAN                Cyan DSRED          Red DSMAGENTA      Magenta DSBROWN        Brown DSLGRAY        Light gray (default) DSDGRAY        Dark gray DSLBLUE        Light blue DSLGREEN       Light green DSLCYAN               Light cyan DSLRED                  Light red DSLMAGENTA       Light magenta DSYELLOW       Yellow DSWHITE        White DSAUTOCOLOR Automatic black or white (whichever  provides the greatest contrast)
DsNbackgroundStyle (long)	[CSG]	The background style for the graphic object specified by the DsNbackgroundUse attribute. Possible values are: DSBGSTYLENO         No background (default). DSBGSTYLESHADOW Drop shadow. DSBGSTYLERAISED Sculptured raised. DSBGSTYLELOWERED Sculptured lowered.
DsNbackgroundUse (long)	[CSG]	Specifies the graphic object to which the DsNbackgroundStyle and DsNbackgroundColor attributes apply. Possible values are: DSBGENTIRE Entire graph window (default). DSBGGRAPHAXES Graph and axes. DSBGGRAPHTITLE Top title. DSBGLEFTTITLE Left title. DSBGRIGHTTITLE Right title. DSBGBOTTOMTITLE Bottom title. DSBGLEGEND Legend.
DsNbottomTitle (string)	[CSG]	The text of the graph title positioned at the bottom of the graph window. This can be up to 80 characters long, and can include new-line characters. Use DsNbackgroundStyle and DsNbackgroundUse to change the style of the title.
DsNdrawMode (long)	[CS]	The drawing mode for the graph control. Possible values are: DSDRAWNOACTION          Graph not drawn – reset to     DSDRAWDEFAULT to display the graph. DSDRAWCLEAR                 Graph not drawn but background set to color specified by DsNbackground. DSDRAWDEFAULT Redraws the graph immediately (default). DSDRAWBLIT Graph built in background, then displayed all at once. DSDRAWCOPY Copies the graph image as a bitmap to the clipboard. DSDRAWROTATE Redraws the graph itself without recalculating scales and redrawing titles and legends (True3D graphs only). DSDRAWUPDATE Updates a time series graph with newly added points.
DsNelevation (long)	[CSG]	The vertical viewing angle for true3D graphs. The value can be any angle between -60 degrees and 90 degrees.
DsNextraData (long array)	[CS]	A two-dimensional array that holds additional data for a graph. You fill the array in the same way as you fill the DsNgraphData array. When referencing a single data point, use DsNthisSet and DsNthisPoint to index the data point. Possible values are: Pie charts DSEDNORMAL      Not exploded (default). DSEDEXTRA       Exploded. Line, Lin/log, Log/lin, Log/log, Polar, Scatter (2D), Tape DSEDNORMAL      Point shown (default). DSEDEXTRA      Point not shown. Time series DSEDNORMAL      No statistical lines (default). DSEDEXTRA       Mean line. DSEDSTDDEV      Standard deviation line. DSEDEXTRA and DSEDSTDDEV can be combined.
DsNforegroundColor (long)	[CSG]	The foreground color for the graphic object specified by the DsNforegroundUse attribute. See DsNbackgroundColor for the list of possible values. The default is DSAUTOCOLOR.
DsNforegroundUse (long)	[CSG]	Specifies the graphic object to which the DsNforegroundColor attribute applies. Possible values are: DSFGRAPHTITLE Top title (default) DSFGLEFTTITLE Left title DSFGRIGHTTITLE Right title DSFGBOTTOMTITLE Bottom title DSFGLABELS Labels DSFGLEGEND Legend DSFGAXES Axes DSFGGRIDS Gridlines DSFGMEAN Mean line DSFGMINMAX Min and max lines DSFGSTDDEV Standard deviation lines DSFGBESTFIT Best-fit line DSFGCURVE Fitted curve DSFGDATALABELS Data labels
DsNgraphData (long array)	[CS]	A two-dimensional array that holds the actual data values for a graph. The array is indexed by DsNthisSet and DsNthisPoint.  For a graph with two data sets and three data points per set, the array data is filled as follows: set1_pt1 + set1_pt2 + set1_pt3 + set2_pt1 + set2_pt2 + set2_pt3
DsNgraphStyle (long)	[CSG]	The graph style. This attribute is not relevant for Bubble, Candlestick, Tape, and Time series graph types. Possible values are: Area (2D/3D) DSAREASTACKED Stacked (default). DSAREAABSOLUTE          Absolute. DSAREAPERCENTAGE Stacked percentage. Bar (2D/3D) DSBARVERTICAL Vertical bars (default). DSBARHORIZONTAL Horizontal bars. DSBARSTACKED Stacked. DSBARPERCENT Percentage. DSBARZCLUSTERED  Z-clustered (3D bar only). DSBARFLOATING Stacked floating. DSBARPARETO Pareto. These values can be combined, as appropriate. Box-whisker DSBOXRAWSAMPLES Raw data, samples drawn (default). DSBOXRAWNOSAMPLES Raw data, no samples drawn. DSBOXPARAMETRIC Parametric data. Gantt DSGANTTADJACNTBARS Adjacent bars (default). DSGANTTSPACEDBARS Spaced bars. High-low-close and Open-high-low-close DSHLCOPEN  Open, high, low, and close bars (default). DSHLCNOCLOSE No open or close bars. DSHLCNOHIGHLOW No high or low bars. DSHLCNOBARS No bars. Line, log/lin, lin/log, and log/log           DSLINEONLY Lines only.           DSLINESYMBOLS Symbols.           DSLINESTICKS Sticks between points and y  origin.           DSLINELINES                     Lines.           These values can be combined. Pie (2D/3D) DSPIELINES Lines join labels to graph  (default). DSPIENOLINES No label lines. DSPIECOLORED Colored labels. DSPIEPERCENT Percentage labels. These values can be combined. Polar DSPOLARLINE  Lines only (default). DSPOLARSYMBOLS Symbols. DSPOLARSTICKS Sticks. DSPOLARLINES Lines. These values can be combined. Scatter (2D) DSSCATTER Symbols only (default). DSSCATTERCURVE Curve only. DSSCATTERSYMBOLS Symbols only. These values can be combined. Scatter (3D) DSSCATTER3DSYMBOLS Symbols only (default). DSSCATTER3DSTICKS Symbols and vertical sticks. DSSCATTER3DLINES Symbols and lines between  points. These values can be combined. Surface DSSURFACE Filled panels and boundary lines (default). DSSURFACEBDYONLY Boundary lines only. DSSURFACEPANONLY Filled panels only. DSSURFACEBDYPANWALL  Filled panels, boundary lines,    side wall. DSSURFACEBDYWALL    Boundary lines, side wall. DSSURFACEPANWALL    Filled panels, side wall.
DsNgraphTitle (string)	[CSG]	The text of the graph title positioned at the top of the graph window. This can be up to 80 characters long, and can include new-line characters. Use DsNbackgroundStyle and DsNbackgroundUse to change the style of the title.
DsNgraphType (long)	[CSG]	The graph type. Possible values are: DSNOGRAPH No graph DS2DPIE 2D pie DS3DPIE 3D pie DS2DBAR 2D bar DS3DBAR 3D bar (default) DSGANTT Gantt DSLINE Line DSLIN-LOG Lin/log DSLOG-LIN Log/lin DSLOG-LOG Log/log DS2DAREA 2D area DS3DAREA 3D area DS2DSCATTER 2D scatter DSTRUE3DSCATTER True3D scatter DSTRUE3DSURFACE True3D surface DSHLC High-low-close DSOHLC Open-high-low-close DSBUBBLE Bubble DSTAPE Tape DSBOXWHISKER Box-whisker DSCANDLESTICK Candlestick DSPOLAR Polar DSTIMESERIES Time series
DsNgridLineStyle (long)	[CSG]	The line style applied to gridlines specified by DsNgridStyle. Possible values are: DSGRIDSOLID        Solid lines (default) DSGRIDDASHED Dashed lines DSGRIDDOTTED       Dotted lines DSGRIDDASHDOT      Dash-dot lines DSGRIDDASHDOTDOT   Dash-dot-dot lines DSGRIDNULL         Null
DsNgridStyle (long)	[CSG]	Enables/disables gridlines on a graph. Possible values are: DSGRIDOFF          No gridlines (default). DSGRIDHORIZONTA Y (horizontal) gridlines –  concentric circles in polar graphs. DSGRIDVERTICAL X (vertical) gridlines –  radial lines in polar graphs. DSGRIDBOTH         Both horizontal and vertical gridlines.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNlabels (long)	[CSG]	Enables/disables graph labels. Possible values are: DSDISABLE No labels. DSENABLEBOTH Both X and Y labels (default). DSENABLEX X labels only. DSENABLEY Y labels only.
DsNlabelEvery (long)	[CSG]	The frequency of X axis labels. You can specify any frequency from 1 (every data point is labeled) to 1000 (every 1000th data point is labeled, starting with the first point).
DsNlabelStyle (long)	[CSG]	The orientation of X and Z axes labels. For horizontal bar graphs and gantt graphs, the label style applies to the Y axis rather than the X axis. For other graph types, Y axis labels are always horizontal. Possible values are: DSLABELHORIZONTAL Horizontal (default) DSLABELVERTICAL         Vertical
DsNlabelText (void)	[CS]	A one-dimensional array that holds the text for graph labels.  For graph types with X and Y axes, the labels apply to data points on the independent axis (normally the X axis). For pie charts, the labels apply to each pie slice. The default labels are the numbers of the data points.  The array strings are filled from left to right, separated by null characters. Each string can be up to 80 characters long. To label one particular data point, you can index DsNlabelText using DsNthisPoint.  Use DsNyLabelText and DsNzLabelText to specify label text for the Y and Z axes of a graph.
DsNleftTitle (string)	[CSG]	The text of the graph title positioned on the left side of the graph window. This can be up to 80 characters long, and can include new-line characters.  Use DsNbackgroundStyle and DsNbackgroundUse to change the style of the title.
DsNleftTitleStyle (long)	[CSG]	The orientation of the graph title specified by DsNleftTitle. Possible values are: DSTITLENORMAL Horizontal (default). DSTITLEUP Vertical (read from bottom to top). DSTITLEDOWN Vertical (read from top to bottom).
DsNlegendPos (long)	[CSG]	The position of the legend in the graph window. Possible values are: DSLEGENDRIGHT  Right DSLEGENDTOPRIGHT Top right DSLEGENDTOP Top DSLEGENDTOPLEFT Top left DSLEGENDLEFT Left DSLEGENDBOTTOMLEFT Bottom left DSLEGENDBOTTOM Bottom DSLEGENDBOTTOMRIGHT Bottom right DSLEGENDNO No legend (default)
DsNlegendSize (long)	[CSG]	Specifies the size of the gap between lines in the legend as a percentage of the maximum possible gap. This latter varies depending on the size of the graph window and the number of items in the legend. You can specify any value from 0% to 100% (default).
DsNlegendStyle (long)	[CSG]	Specifies the color for the legend text. Possible values are: DSLEGENDFG Legend text set by DsNforegroundColor. DSLEGENDCOLOR Legend text in same colors as legend markers.
DsNlegendText (long)	[CS]	A one-dimensional array that holds text for the graph legend.  For graph based on a single data set (pie, bubble, and single-set bar graphs), the legends apply to the individual data points. For other graph types, the legends apply to the data sets.  The array strings are filled from left to right, separated by null characters. Each string can be up to 80 characters long.
DsNlineStats (long)	[CSG]	Enables/disables statistical lines and curves. Both lines and curves are available for line, 2D scatter, high-low-close, open-high-low-close, and box-whisker parametric graphs. Only curves are available for candlestick graphs. Possible values are: DSSTATNOLINES No statistical lines (default). DSSTATMEAN Mean (average) line. DSSTATMINMAX     Min/max line. DSSTATSTDDEV Standard deviation line. DSSTATBESTFIT Best-fit line. DSSTATCURVE Curve line. You can combine all the above values.
DsNnumPoints (long)	[CSG]	The number of points in the data sets of a graph. This can be any value between 1 and 6000, provided that the total number of points in a graph does not exceed 128000. That is: DsNnumSets * DsNnumPoints <= 128000
DsNnumSets (long)	[CSG]	The number of data sets in the graph. For most graph types, DsNnumSets can be any value between 1 and 6000. The exceptions are: Pie (2D/3D) 1 set Bubble  2 sets Gantt >=2 sets Surface >=2 sets HLC 3 sets OHLC 4 sets Candlestick 4 sets Box-whisker 7 sets for parametric data (can be higher for raw data) The total number of sets in any graph is limited to 128000. That is: DsNnumSets * DsNnumPoints <= 128000
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNperspective (long)	[CSG]	The degree of perspective foreshortening for true3D graphs that use the perspective projection method. This represents the perceived distance from which the graph is viewed. The value must lie in the range 1 to 100 (default is 50).
DsNrightTitle (string)	[CSG]	The text of the graph title positioned on the right side of the graph window. This can be up to 80 characters long, and can include new-line characters.  Use DsNbackgroundStyle and DsNbackgroundUse to change the style of the title.
DsNrightTitleStyle (long)	[CSG]	The orientation of the graph title specified by DsNrightTitle. Possible values are: DSTITLENORMAL Horizontal (default). DSTITLEUP Vertical (read from bottom to top). DSTITLEDOWN Vertical (read from top to bottom).
DsNrotation (long)	[CSG]	The horizontal viewing angle for true3D graphs. The value can be any angle between -180 degrees and 180 degrees.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNthisPoint  (long)	[CS]	This indexes array-based attributes by data point number. In combination with the DsNthisSet attribute, it indexes individual data points in a data set for direct access. The following example modifies a pie graph, exploding points 3 and 5, and imploding point 4: long   extra_array(10) extra_array(1) = DSEDEXTRA  |* Explode point extra_array(2) = DSEDNORMAL  |* Return point   |* to normal extra_array(3) = DSEDEXTRA   |* Explode point change.object( pie_graph_object, DsNthisSet,    1,    |* Pie graph has only 1 set DsNthisPoint,  3,    |* Start with point 3 DsNextraData, extra_array, 3  |* Do for 3 points )
DsNthisSet (long)	[CS]	This indexes array-based attributes by data set number. In combination with the DsNthisPoint attribute, it indexes individual data points for direct access. DsNthisSet can be used to index the following attributes: DsNextraData, DsNgraphData, DsNlegendText, and DsNzLabelText. The following example changes the value of one data point, using DsNthisSet and DsNthisPoint to index the data point: long data_array(100) data_array(1) = 50 change.object(graph_object, DsNthisSet,  3, DsNthisPoint,  6, DsNgraphData,  data_array, 1 )
DsNtickFrequency (long)	[CSG]	The frequency of ticks on the X axis (or on the Y axis of horizontal bar graphs and gantt graphs). You can specify any frequency from 1 (every data point is labeled) to 1000 (every 1000th data point is labeled, starting with the first point).
DsNtickStyle (long)	[CSG]	Enables/disables tick marks on the graph axes. Possible values are: DSDISABLE No ticks DSENABLEBOTH Both X and Y ticks (default) DSENABLEX X ticks only DSENABLEY Y ticks only
DsNtrue3D (long)	[CSG]	Enables/disables true3D graphing and sets the projection method. Possible values are: DSTRUE3DOFF            No 3D (except for scatter and surface graphs). DSTRUE3DPERSPECTIVE3D Perspective projection (see DsNperspective). DSTRUE3DISOMETRIC3D   Isometric projection. DSTRUE3DOFF is the default when true3D is not available for the graph type. DSTRUE3DPERSPECTIVE is the default when true3D is available for the graph type.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
DsNyLabelText (void)	[CS]	A one-dimensional array that holds the text for Y axis labels. The default labels indicate the numeric scaling of the axis. The array strings are filled from left to right, separated by null characters. Each string can be up to 80 characters long.
DsNzLabelText (void)	[CS]	A one-dimensional array that holds the text for Z axis labels in true3D graphs.  The default labels indicate the numeric scaling of the axis. However, no default labels are supplied for true 3D bar graphs, tape graphs, area graphs, or surface graphs. In these cases, you must set DsNzLabelText if you want to display z axis labels.  The array strings are filled from left to right, separated by null characters. Each string can be up to 80 characters long. You can index DsNlabelText using DsNthisPoint.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgrid

Description

A DsCgrid object is a rectangular child window that displays a spreadsheet grid. Cells in the grid can contain not only data but also controls such as text boxes, list boxes, and check boxes.

Events

A DsCgrid object can generate the following events:

EVTCHANGEFOCUS

EVTGRIDEVENT

EVTKEYPRESS

EVTSETFOCUS

Attributes

DsNbackground (long)	[S]	Specifies the background color (as an rgb value) for selected cells. The possible values are 0 to 16777215. When not specified, the background adopts the Windows standard.
DsNcolHeader (boolean)	[CG]	Specifies whether or not the grid includes column headers. The default is TRUE.
DsNcolumn (long)	[SQ]	Use this to select a column in the grid. The value of the attribute is the column number (0-based index). In combination with DsNrow, this attribute selects an individual cell.
DsNcolumns (long)	[CSG]	The number of columns in the grid. The default is 1.
DsNcolWidth (long array)	[CSQ]	Use this to specify the width of the grid columns. You fill the array with the width values for each column, starting with the first column. If you specify only one value, all columns are set to that width.  If you first use DsNcolumn to select a column, the width specified is applied to the selected column. The width can be any value between 0 and 32768. By default, all columns are the same width, the actual width depending on the width of the grid.
DsNcontrol (long)	[SQ]	Use to create a control object in selected cell(s). Possible values are: DSEDIT        Edit control (text box) (default). DSSTATIC     Static label field. DSDDLISTBOX   Drop-down list box. DSCHECKBOX Check-box. DSZOOMEDIT    Zoom edit field. For an edit control, use DsNmaxLength to specify the maximum number of input characters for the field.  For a drop-down list box, use DsNenum to specify the list box contents.  For a check box, use the values 1 and 0 to select/deselect the control.  For a drop-down list box, select the list box entry to be displayed by specifying its index number in the list.
DsNeditable (boolean)	[SQ]	Specifies whether or not an edit control is read-only. The default is FALSE.
DsNenum (string)	[SQ]	Specifies the contents of a drop-down list box. Separate the individual list items using \n. For example: item1\nitem2\nitem3\n
DsNfontSet (long)	[SQ]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the entire grid or to selected cells. The default font is the Windows default font.
DsNforeground (long)	[S]	Specifies the text color (as an rgb value) for selected cells. The possible values are 0 to 16777215. When not specified, the Windows standard is used.
DsNfreezeColumns (boolean)	[SG]	Use to freeze and unfreeze column(s) selected by the user. The default value is FALSE.
DsNgridEnableSelection (long)	[CG]	Specifies user selection options. Possible values are: DSGRIDSELFULL       All selection actions (default). DSGRIDSELNONE       No selection actions. DSGRIDSELROW        Row selection. DSGRIDSELCOL        column selection. DSGRIDSELTABLE      Grid selection. DSGRIDSELCELL       Cell selection. DSGRIDSELMULTIPLE   Multiple selections. DSGRIDSELSHIFT      Extend selection by pressing SHIFT. DSGRIDSELKEYBOARD   Selection with SHIFT+Arrow Key. You can combine all the above values.
DsNgridFooter (boolean)	[CSG]	Specifies whether or not the last row in the grid has a special style. In this special style, the font and top border are bold and the background color is that defined for 3D objects in the Windows standard color scheme.
DsNgridSetState (long)	[S]	The state of a grid selection. Possible values are: DSGRIDSTATEMARK                 Mark the selection. DSGRIDSTATEUNMARK          Unmark the selection. DSGRIDSTATESETFOCUS        Set focus on the selection (single cell only). DSGRIDSTATESETSENSITIVE    Make the selection sensitive. DSGRIDSTATESETINSENSITIVE Make the selection insensitive. You cannot combine these values.
DsNgridType (long)	[CG]	The grid type. Possible options are: DSGRIDTYPENORMAL      Normal grid functionality (default). DSGRIDTYPEDISPLAY     Read-only functionality. DSGRIDTYPEEDIT        Edit functionality. DSGRIDTYPEVEERTEDIT Vertical edit functionality.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNjustify (long)	[SQ]	Use this to specify the justification for data in selected cells. Possible values are: DSJUSTIFYRIGHT DSJUSTIFYLEFT (default) DSJUSTIFYCENTER
DsNmaxLength (long)	[SQ]	The maximum number of input characters for an edit control field. This can be any value from 0 to 4096. 4096 is the default value.
DsNrange (long array)	[SQ]	Use this to select a range of cells. The array is filled as follows: start_row_num + start_col_num + end_row_num + end _col_num
DsNrow (long)	[SQ]	Use this to select a row in the grid. The value of the attribute is the row number (0-based index). In combination with DsNcolumn, this attribute selects an individual cell.
DsNrowHeader (boolean)	[CG]	Specifies whether or not the grid includes row headers. The default is TRUE.
DsNrowHeight (long array)	[CSQ]	Use this to specify the height of the grid rows. You fill the array with the height values for each row, starting with the first row.  If you specify only one value, all rows are set to that height. If you first use DsNrow to select a row, the height specified is applied to the selected row.  The height can be any value between 0 and 32768. By default, all rows are the same height, the actual height depending on the font size.
DsNrows (long)	[CSG]	The number of rows in the grid. The default is 1 row.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNstringArray (void)	[SQ]	A one-dimensional array that holds data values for selected cell(s). When filling multiple cells, separate the data values with  null characters. The data is filled from left to right and from top to bottom.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgwindow

Description

A graphical window (DsCgwindow) is a window in which applications can draw graphical parts such as lines, rectangles, polygons, and so on. Graphical windows also support user interface controls such as buttons, edit controls, list boxes, and so on.

Note that after changes to graphical parts, the graphical window in not redrawn until DsNsetState is set to DSUPDATE or until the window is repainted by the windows system.

Graphical windows support the following subobjects:

DsCgpArc

DsCgpComposite

DsCgpGroupBox

DsCgpHeader

DsCgpImage

DsCgpLine

DsCgpOleSite

DsCgpPie

DsCgpPolygon

DsCgpPolyline

DsCgpRectangle

DsCgpText

Events

A DsCgwindow can generate the following events:

EVTBUTTONPRESS

EVTBUTTONRELEASE

EVTBUTTONDPRESS

EVTBUTTONMOTION

EVTOLEEVENT

Attributes

DsNbackground (long)	[CSG]	The rgb value that defines the background color of the object. If this attribute is not specified, the object inherits the background color of its parent. If none of the parent objects specify a background color, the resource workAreaBackground is used.
DsNborderColor (long)	[CSG]	The rgb value that defines the color of the object's border.
DsNborderWidth (long)	[CSG]	The width of the object's border, in pixels.
DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNfirstSubObject (long)	[SQ]	The object ID of the subobject that is be drawn above all other subobjects. Setting this attribute changes the drawing order of subobjects.
DsNgridColor (long)	[CSG]	The color of the grid lines in the gwindow. The default is black.
DsNgridHeight (long)	[CSG]	The spacing (in pixels) between horizontal grid lines. If this is not specified, horizontal gridlines are not displayed.
DsNgridWidth (long)	[CSG]	The spacing (in pixels) between vertical grid lines. If this is not specified, vertical gridlines are not displayed.
DsNgridX (long)	[CSG]	The x-coordinate (in pixels) of the first grid line relative to the left border of the window. The default is 0.
DsNgridY (long)	[CSG]	The y-coordinate (in pixels) of the first grid line relative to the top border of the window. The default is 0.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNinferiorPointerCursor (long)	[CSG]	The shape of the inferior mouse pointer when positioned over the gwindow. A child of a gwindow inherits this mouse pointer, unless otherwise specified.  This attribute is overruled by a DsNsuperiorPointerCursor attribute set for the window itself or for ancestor windows. It is also overruled by a DsNinferiorPointerCursor setting in descendant windows. Possible values are: DSCDEFAULT (default) DSCPENCIL DSCARROW DSCQUESTIONARROW DSCCROSSHAIR DSCSPLITHORIZONTAL DSCFLEUR DSCSPLITVERTICAL DSCHAND DSCSPRAYCAN DSCMAGNIFY DSCWATCH DSCAPPSTARTING DSCNODROP
DsNlastSubObject (long)	[SQ]	The object ID of the subobject that is be drawn beneath all other subobjects. Setting this attribute changes the drawing order of subobjects.
DsNnextSubObject  (long)	[SQ]	The object ID of the subobject that is drawn under the subobject specified by DsNrefSubObject. Setting this attribute changes the drawing order of subobjects.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNprevSubObject (long)	[SQ]	The object ID of the subobject that is drawn above the subobject specified by DsNrefSubObject. Setting this attribute changes the drawing order of subobjects.
DsNrefSubObject (long)	[SQ]	The object ID of the subobject used as a reference by  DsNnextSubObject, DsNprevSubObject, and DsNsequence.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNsubObject (long)	[Q]	Use this attribute in a query operation to retrieve information about a subobject of the gwindow.
DsNsubObjectArray (long array)	[Q]	Use this attribute in a query operation to retrieve information about subobjects within a specified area of the gwindow.
DsNsuperiorPointerCursor (long)	[CSG]	The shape of the superior mouse pointer when positioned over the gwindow. A child of a gwindow always inherits this mouse pointer. This attribute overrules any DsNinferiorPointerCursor attribute set for the window and all mouse pointers set for descendant windows. Possible values are: DSCDEFAULT  DSCPENCIL DSCARROW DSCQUESTIONARROW DSCCROSSHAIR DSCSPLITHORIZONTAL DSCFLEUR DSCSPLITVERTICAL DSCHAND DSCSPRAYCAN DSCMAGNIFY DSCWATCH DSCAPPSTARTING DSCNODROP
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsClabel

Description

A DsClabel object provides a text string for labeling other objects.

Events

A DsClabel object does not generate events.

Attributes

DsNfontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to label text The default font is the Windows default font.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNjustify (long)	[CSG]	The alignment of the text string within the label object. Possible values are: DSJUSTIFYLEFT (default) DSJUSTIFYRIGHT DSJUSTIFYCENTER
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNstring (string)	[CSG]	The label string.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCmwindow

Description

A main window (DsCmwindow) acts as the frame window for applications. It is used for starting processes and for creating graphical and character windows. Typically, a main window contains a border, title bar, control menu box, sizing controls, menu bar, toolbar, status bar, work area, and scroll bars.

A main window also acts as the frame window for modal and modeless dialog boxes.

Events

A DsCmwindow object can generate the following events:

EVTKEYPRESS

EVTRESIZEWINDOW

Attributes

DsNbarMenu (long)	[CSG]	The object ID of the DsCbarMenu object to be displayed across the top of a main window, below the title bar. The menu bar becomes visible after this attribute is set.
DsNclose (long)	[CG]	Specifies whether or not the menu of a dialog window includes the Close command. It also controls the processing of ALT+F4. The default is TRUE. This attribute affects the window only if DsNdialog=TRUE.
DsNcmdStateList (long array)	[S]	Use to change the state of toolbar buttons and menu items. The array consists of one or more pairs of values. Each pair consists of the command ID of a toolbar button or menu item and the new state of the item. The possible values for the command state are: DSCMDNORMAL Resets the command/button to its  default state. DSCMDDISABLED Disables the command/button. DSCMDCHECKED Sets the command/button to its  checked state (you can combine this with  either of the other options).
DsNcommandStrings (void data)	[CS]	The status field strings and tooltip strings for commands/buttons defined in DsCbarMenu and DsCtoolBar objects.  The DsNcommandStrings data consists of a header followed by multiple entries that specify the required strings.  The header contains two longs, one specifying the version number (currently always 1), the other specifying the number of following entries.  Each entry consists of a long and two strings. The long contains the unique command ID. The strings contain the status bar text and the tooltip text respectively.
DsNdialog (long)	[CG]	Specifies whether or not the window is a dialog-type window. The default is FALSE. This attribute is often used in combination with DsNmodal.
DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNhelpButton (boolean)	[CG]	Use to specify whether or not a main window of dialog type  (DsNdialog = TRUE) contains a help button in the title bar. This button provides context-sensitive help. The default is TRUE.
DsNiconic (long)	[C]	Specifies whether or not the main window is realized as an icon (that is, minimized). The default is FALSE.
DsNinferiorPointerCursor (long)	[CSG]	The shape of the inferior mouse pointer when positioned over the main window. A child of a main window inherits this mouse pointer, unless otherwise specified.  This attribute is overruled by a DsNsuperiorPointerCursor attribute set for the window itself or for ancestor windows. It is also overruled by a DsNinferiorPointerCursor setting in descendant windows. Possible values are: DSCDEFAULT (default) DSCPENCIL DSCARROW                    DSCQUESTIONARROW DSCCROSSHAIR DSCSPLITHORIZONTAL DSCFLEUR DSCSPLITVERTICAL DSCHAND DSCSPRAYCAN DSCMAGNIFY DSCWATCH DSCAPPSTARTING DSCNODROP
DsNmaxHeight (long)	[CSG]	The maximum height (in pixels) of the main window.
DsNmaxWidth (long)	[CSG]	The maximum width (in pixels) of the main window.
DsNminHeight (long)	[CSG]	The minimum height (in pixels) of the main window.
DsNminWidth (long)	[CSG]	The minimum width (in pixels) of the main window.
DsNmodal (long)	[CG]	This specifies whether the main window is modal or modeless. If TRUE, then the user must complete interaction with the window and close it before continuing with any further interaction outside the window. This attribute is normally used in combination with the DsNdialog attribute. The default is FALSE.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNprocessGroup (long)	[CSG]	The ID of the process group to which events from the main window are sent. See Process groups.
DsNresizeable (long)	[CG]	Indicates whether or not the main window is resizable. The default is TRUE.
DsNsetState                  (long)	[CS]	The state of the object. This can also be set with the corresponding functions. Possible values are: DSMAP                           Makes object visible  (see also map.object()). DSUNMAP              Makes object invisible  (see also unmap.object()). DSUPDATE             (Re)draws the object  (see also update.object()). DSRAISE                           Puts object in the forefront  (see also raise.object()). DSLOWER              Puts object in the background  (see also lower.object()). DSCLEAR              Destroys the gparts on a gwindow. DSSETSENSITIVE     Makes object sensitive – that is the object is enabled (see also  set.sensitive()). DSSETINSENSITIVE  Makes object insensitive – that is  the object is disabled (see also set.sensitive()). DSSETFOCUS Sets keyboard input focus on the object (see set.focus()). DSUNSETFOCUS Moves keyboard input focus to the mwindow (see unset.focus()). Note that you cannot combine these values.
DsNstartHelpMode (boolean)	[S]	This indicates whether or not the window is in context-sensitive help mode (that is, whether or not SHIFT+F1 is enabled).
DsNsuperiorPointerCursor (long)	[CSG]	The shape of the superior mouse pointer when positioned over the main window. A child of a main window always inherits this mouse pointer. DsNsuperiorPointerCursor overrules any inferior mouse pointer (DsNinferiorPointerCursor) set for the window and all mouse pointers set for descendant windows. Possible values are: DSCDEFAULT  DSCPENCIL DSCARROW          DSCQUESTIONARROW DSCCROSSHAIR  DSCSPLITHORIZONTAL DSCFLEUR DSCSPLITVERTICAL DSCHAND DSCSPRAYCAN DSCMAGNIFY DSCWATCH DSCAPPSTARTING DSCNODROP
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNtitle (string)	[CS]	The title displayed in the title bar of the main window and as the caption for the window's icon.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
The following attributes are supported for backward compatibility only. Do not use them in new applications.

DsNcolumns	DsNdata	DsNdisplay	DsNflags
DsNmaxColumns	DsNmaxRows	DsNminRows 	DsNminColumns
DsNmode 	DsNrows	DsNsize	DsNwindow

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCpixmap

Description

A DsCpixmap object defines a graphical image. It consists of a two-dimensional array of pixels, with a specified width, height, and depth (number of planes), but no screen coordinates. A pixmap is a resource that is used by other objects that can display an image. Objects that can use a pixmap include DsCdrawnButton, DsCgpImage and DsCtoolBar objects.

Events

A DsCpixmap object does not generate events.

Attributes

DsNbackgroundMode (long)	[CS]	Specifies the pixmap's background mode. Possible values are: DSTRANSPARENT DSOPAQUE (default)
DsNcolormap (long)	[CS]	The object ID of a DsCcolormap object. The color map defines an array of colors that the pixmap uses when DsNdataType is set to DSPIXMAP8.
DsNdata (long array)	[CS]	An array of indexes into the contents of a .gif file or into the color table of the DsCcolormap object specified by DsNcolormap.
DsNdataType (long)	[CS]	The pixmap type. Possible values are: DSPIXMAP8 DSPIXGIF8
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCpushButton

Description

A pushbutton, also referred to as a command button, represents an action that is carried out when the user selects the button. A pushbutton displays a text label.

A DsCdrawnButton object has the same functionality as a DsCpushButton object except that it displays a graphical image instead of a text label.

Events

A DsCpushButton object can generate the following events:

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

EVTBUTTONSELECT

Attributes

DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNfontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the label on the pushbutton The default font is the Windows default font.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNreturnValue (long)	[CSG]	The value that is returned when the pushbutton is selected. The return value must be handled as an event. See Events.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNshowAsDefault (long)	[CSG]	Indicates whether of not the button is the default button. If TRUE, the button has a thicker border and can be activated with the ENTER key.
DsNstring (string)	[CSG]	The text string for the button's label.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCradioBox

Description

A DsCradioBox object is an instance of DsCrowColumn object that contains radio buttons (also referred to as option buttons).

Events

A DsCradioBox object does not generate events.

Attributes

DsNfixedDimension (long)	[CSG]	Specifies how children are arranged in the radio box. Possible values are:
		DSVERTICAL	Children are arranged vertically, from top to bottom. Use DsNnumRows to specify the maximum number of children that can be displayed vertically.
		DSHORIZONTAL	Children are arranged horizontally, from left to right. Use DsNnumColumns to specify the maximum number of children that can be displayed horizontally.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNnumColumns (long)	[CSG]	The maximum number of children that the object can display horizontally.
DsNnumRows (long)	[CSG]	The maximum number of children that the object can display vertically.
DsNobjectType               (long)	[G]	The object type.
DsNpacking (long)	[CSG]	The method of spacing the radio buttons within the radio box. Possible values are:
		DSPACKTIGHT	The radio box contains cells of equal size, set to the size of the largest child window. Child windows positioned within these cells maintain their minimum dimensions. This is the default value.
		DSPACKEQUAL	The radio box contains cells of equal size, set to the size of the largest child window. All child windows within these cells are displayed at the size of the largest child window.
		DSPACKNONE	Child windows determine their own size and position. The radio box window is sized to accommodate all its children.
		DSPACKSTACKED	All child windows have the same size and position. Only the last created child is visible. All other children are stacked beneath this.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCradioButton

Description

A radio button (also referred to as an option button) represents a single option within a set of mutually exclusive options. It is either set or not set. Within a group of radio buttons, only one option in the group can be set. Selecting one radio button automatically deselects all others in the group. A partially filled in circle indicates the currently selected button. All radio buttons have an associated label.

Events

A DsCradioButton object can generate the following events:

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

EVTBUTTONSELECT

Attributes

DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNfontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the radio button's label. The default font is the Windows default font.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNjustify (long)	[CSG]	The alignment of the text string within the radio button window. Possible values are: DSJUSTIFYLEFT (default) DSJUSTIFYRIGHT DSJUSTIFYCENTER
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNset    (long)	[CSG]	The state of the button (selected or unselected). The default is FALSE.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNstring (string)	[CSG]	The string value for the radio button's label.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCrowColumn

Description

A DsCrowColumn object is a container object that displays its children in rows and columns.

Events

A DsCrowColumn object does not generate events.

Attributes

DsNfixedDimension (long)	[CSG]	Specifies how children are arranged in the object. Possible values are:
		DSVERTICAL	Children are arranged vertically, from top to bottom.  Use DsNnumRows to specify the maximum number of children that can be displayed.
		DSHORIZONTAL	Children are arranged horizontally, from left to right.  Use DsNnumColumns to specify the maximum number of children that can be displayed.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNhspace (long)	[CSG]	The horizontal spacing (in pixels) between child objects and between the edge of the DsCrowColumn object and its nearest child.
DsNinferiorPointerCursor   (long)	[CSG]	The shape of the inferior mouse pointer when positioned over the object. A child of a DsCrowColumn object inherits this mouse pointer, unless otherwise specified.  This attribute is overruled by a DsNsuperiorPointerCursor attribute set for the object itself or for ancestor windows. It is also overruled by a DsNinferiorPointerCursor setting in descendant windows. Possible values are: DSCDEFAULT (default) DSCPENCIL DSCARROW          DSCQUESTIONARROW DSCCROSSHAIR DSCSPLITHORIZONTAL DSCFLEUR DSCSPLITVERTICAL DSCHAND DSCSPRAYCAN DSCMAGNIFY DSCWATCH DSCAPPSTARTING DSCNODROP
DsNjustify (long)	[CSG]	The justification of child windows within the cells of the DsCrowColumn object. This is relevant only when DsNpacking is set to DSPACKTIGHT. The possible values for horizontal justification are: DSJUSTIFY LEFT (default) DSJUSTIFY CENTER DSJUSTIFY RIGHT The possible values for vertical justification are: DSJUSTIFYTOP (default) DSJUSTIFYMIDDEL DSJUSTIFYBOTTOM When setting this attribute, you must combine a horizontal justification option and a vertical justification option.
DsNnumColumns (long)	[CSG]	The maximum number of children that the object can display horizontally.
DsNnumRows (long)	[CSG]	The maximum number of children that the object can display vertically.
DsNobjectType               (long)	[G]	The object type.
DsNpacking (long)	[CSG]	The method of spacing the child objects within the DsCrowColumn object. Possible values are:
		DSPACKTIGHT	The object contains cells of equal size, set to the size of the largest child window. Child windows positioned within these cells maintain their minimum dimensions. This is the default value.
		DSPACKEQUAL	The object contains cells of equal size, set to the size of the largest child window. All child windows within these cells are displayed at the size of the largest child window.
		DSPACKNONE	Child windows determine their own size and position. The DsCrowColumn window is sized to accommodate all its children.
		DSPACKSTACKED	All child windows have the same size and position. Only the last created child is visible. All other children are stacked beneath this.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNsuperiorPointerCursor (long)	[CSG]	The shape of the superior mouse pointer when positioned over the object. A child of a DsCrowColumn object always inherits this mouse pointer. DsNsuperiorPointerCursor overrules any inferior mouse pointer (DsNinferiorPointerCursor) set for the object and all mouse pointers set for descendant windows. Possible values are: DSCDEFAULT  DSCPENCIL DSCARROW        DSCQUESTIONARROW DSCCROSSHAIR  DSCSPLITHORIZONTAL DSCFLEUR DSCSPLITVERTICAL DSCHAND DSCSPRAYCAN DSCMAGNIFY DSCWATCH DSCAPPSTARTING DSCNODROP
DsNvspace    (long)	[CSG]	The vertical spacing (in pixels) between child objects and between the and between the edge of the DsCrowColumn object and its nearest child.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCscrollWindow

Description

A DsCscrollWindow object provides a scrollable view of a child object. It supports a single child object only. Scroll bars enable users to view the data not currently visible in the window. Scroll bars are visible only when the child object is larger than the scroll window.

Events

A DsCscrollWindow object does not generate events.

Attributes

DsNchildPosX (long)	[CSG]	The distance (in pixels) from the left edge of the child object to the left edge of the scroll window.
DsNchildPosY (long)	[CSG]	The distance (in pixels) from the top edge of the child object to the top edge of the scroll window.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCscrollbar

Description

Scroll bars enable users to scroll data that is too large to fit in the viewing window. They can be either horizontal or vertical. A scroll bar consists of the following components:

•	A rectangular shaft (referred to as the scroll region). This represents the full amount of information available to the window.

•	A scroll arrow at either end of the scroll region. Clicking on these scrolls the data by specified increments.

•	A movable slider (also referred to as a scroll box). This indicates the relative position of the currently displayed data within the whole.

To scroll the data, users can click on one of the scroll arrows, click in the scroll region, or drag the slider.

Events

A DsCscrollbar object can generate the following events:

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

EVTSCROLLBARSELECT

Attributes

DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNincrement (long)	[CSG]	The amount the slider value changes when the user moves the slider by one increment. Clicking on one of the scroll arrows moves the slider one increment towards the arrow. If a negative value is specified, the absolute value is used.
DsNmaximum (long)	[CSG]	The maximum value of the slider. This corresponds to the right or bottom position of the slider.
DsNminimum (long)	[CSG]	The minimum value of the slider. This corresponds to the left or top position of the slider. DsNmaximum can be less than DsNminimum.
DsNobjectType               (long)	[G]	The object type.
DsNorientation (long)	[CSG]	The orientation of the scroll bar. Possible values are:  DSHORIZONTAL DSVERTICAL (default)
DsNpageIncrement	[CSG]	The amount the slider value changes when the user moves the slider by one page increment. Clicking in the scroll region moves the slider one page increment in the direction of the click. If a negative value is specified, the absolute value is used.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNsize (long)	[CSG]	The size of the scroll bar control, in pixels. This specifies the width of horizontal scroll bars and the height of vertical scroll bars. The default value is 100.
DsNsliderValue (long)	[CSG]	The value corresponding to one side of the slider.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCslider

Description

A slider object is used to set a value in a continuous range of values (for example, volume or brightness). It consists of a scroll bar that represents the full range of values and a movable slider whose position represents the current value. It also includes labels that indicate the slider's current, maximum, and minimum values. Tick marks are optional.

Events

A DsCslider object can generate the following events:

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

EVTSCROLLBARSELECT

Attributes

DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNfontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the slider's labels. The default font is the Windows default font.
DsNincrement (long)	[CSG]	The amount the slider value changes when the user moves the slider by one increment.
DsNmaximum (long)	[CSG]	The maximum value of the slider. This corresponds to the right or bottom position of the slider.
DsNminimum (long)	[CSG]	The minimum value of the slider. This corresponds to the left or top position of the slider. DsNmaximum can be less than DsNminimum.
DsNobjectType               (long)	[G]	The object type.
DsNorientation (long)	[CSG]	The orientation of the slider object. Possible values are:  DSHORIZONTAL DSVERTICAL (default)
DsNpageIncrement	[CSG]	The amount the slider value changes when the user moves the slider by one page increment. Clicking in the slider bar moves the slider one page increment in the direction of the click. If a negative value is specified, the absolute value is used.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNsize (long)	[CSG]	The size of the slider in pixels. For horizontal sliders, it specifies the width of the slider. For vertical sliders, it specifies the height. The default value is 100.
DsNsliderValue (long)	[CSG]	The value corresponding to one side of the slider.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNtickFrequency (long)	[CSG]	The frequency of tick marks on the slider. This can be any interval from 0 to DsNmaximum - DsNminimum. The default is 0. DsNtickStyle must not be DSNTICKNONE.
DsNtickStyle (long)	[CSG]	The positioning of tick marks on the slider. Possible values are: DSTICKNONE    No tick marks. DSTICKTOP     Tick marks above slider (DSHORIZONTAL). DSTICKBOTTOM  Tick marks below slider (DSHORIZONTAL). DSTICKRIGHT   Tick marks to right of slider  (DSVERTICAL). DSTICKLEFT    Tick marks to left of slider (DSVERTICAL). DSTICKBOTH    Tick marks on both sides of slider (default).
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCstatusBar

Description

A DsCstatusBar object provides a status bar that displays help and status information in a main window (DsCmwindow object). Each main window can include one DsCstatusBar object. The status bar is positioned at the bottom of the window. It occupies part of the client area of the window. When a status bar is added to a main window, the window size is adjusted so that the size of the client area is not affected.

The help and status messages are displayed in one or more panes in the status bar. There are three types of status bar panes:

•	Default text pane. This displays the status field strings and tooltip strings for commands/buttons, as defined in the DsNcommandStrings attribute of the DsCmwindow object. This pane occupies the full width of the status bar not occupied by other status panes.

The application can also write text to this pane using change.object(). Messages defined by the DsNcommandStrings attribute temporarily overwrite this text. But when these disappear, the last message sent to the default pane by the application is restored.

•	Application-defined text panes. The application supplies text for these panes using change.object(). The application must specify the length of the panes when creating the status bar.

•	Indicator panes. These indicate the current status of certain keyboard keys (for example, NUM LOCK and CAPS LOCK). Microsoft Windows supplies the text for the panes. The application must specify the availability of the panes when creating the status bar.

Events

A DsCstatusBar object does not generate events.

Attributes

DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNstatusIndicator (long)	[CG]	This specifies the indicators to be shown on the status bar. You can specify any combination of the following values: DSCAPS Caps Lock indicator. DSNUM Num Lock indicator. DSSCRL Scroll Lock indicator. DSKANA Kana Lock indicator (Japanese systems only). Indicators are displayed on the status bar in the above order.
DsNstatusLength (long array)	[C]	Specifies the length (in characters) of application-defined text panes in the status bar. The number of entries in the array determines the number of application-defined panes displayed.
DsNstatusPane (long)	[SQ]	This selects a status bar text pane for the DsNstatusText attribute. The pane numbers range from 0 to the total number of panes defined by DsNstatusLength. The default text pane is indexed by 0; this is also the default value.
DsNstatusText	[SQ]	The text for the status bar text pane specified by DsNstatusPane. If DsNstatusPane is not set, the text is displayed in the default text pane. To clear a text pane, set this attribute to an empty string.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCtabFrame

Description

A DsCtabFrame object provides a window with one or more form tabs. The tabs can be arranged in a single line or in multiple lines. When tabs are arranged on a single line, scroll buttons are added automatically if the window is not large enough to accommodate all the tabs.

A tab frame object can have multiple children. Children are automatically positioned at the top-left of the tab frame. The size of the tab frame window automatically adjusts to accommodate the largest child.

Events

A DsCtabFrame object can generate the following events:

EVTTABSELECT

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

Attributes

DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNfixedWidth (boolean)	[CG]	Specifies whether or not all tabs have the same width. The default is     FALSE.
DsNfontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to tab titles. The default font is the Windows default font.
DsNheight (long)	[CSG]	The height (in pixels) of the client area of the tab frame window. If this is not specified, the height of the tab frame adjusts to accommodate the largest child window.
DsNmultiLine (boolean)	[CG]	Specifies whether or not the tabs are arranged on multiple lines. The default is FALSE.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNselected (long)	[CSG]	Use to select a particular tab by tab number. The tab numbers range       from 1 to the total number of tabs. The default is 1.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNstring (string)	[CSG]	The text of the tab titles. Separate the text for each tab by \n. The number of title strings entered determines the number of form tabs displayed. This attribute is mandatory when creating a tab frame.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width (in pixels) of the client area of the tab frame window. If this is not specified, the width of the tab frame adjusts to accommodate the largest child window.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCtemplate

Description

A DsCtemplate object defines a set of attributes that can be applied to other objects.

When multiple objects have common attributes, you can define those attributes in a template instead of specifying them individually for each object. You can then apply the attributes to an object by specifying the ID of the relevant template in the object's DsNtemplate attribute. Using this mechanism improves performance because less data needs to be transferred between the bshell and the user interface.

Events

A DsCtemplate object does not generate events.

Attributes

. . .	[CS]	A DsCtemplate object can include any of the attributes available for other objects.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCtoolBar

Description

A DsCtoolBar object defines a toolbar for a main window (DsCmwindow). An application creates the entire toolbar with a single create.object() call. Subsequently, it can use change.object() to add, remove, change, enable, and disable toolbar buttons.

Use the DsNcommandStrings attribute of the main window to specify status field and tooltip text for the toolbar buttons.

Events

A DsCtoolBar object can generate the following event:

EVTBUTTONSELECT

Attributes

DsNbutton (long)	[SQ]	Selects a particular toolbar button. The value specified is an index into the toolbar button list (1 based index) – separators are not counted.
DsNbuttonState (long)	[SQ]	The state of the toolbar button identified by DsNbutton. Possible values are:  DSTBBTNDISABLEDUNCHECKED DSTBBTNDISABLEDCHECKED  (DSCHECK buttons only) DSTBBTNENABLEDUNCHECKED  (default) DSTBBTNENABLEDCHECKED  (DSCHECK buttons only)
DsNcommandList (long array)	[C]	The list of the command identifiers associated with the toolbar buttons. This attribute is mandatory when creating a toolbar. The command identifiers must be in the range 0 to 12287. The number of entries in the DsNcommandList array must equal the number of entries in the DsNimageList array (excluding separator entries). The event generated when a user clicks a toolbar button contains the command ID for the button.
DsNdockable (boolean)	[CG]	Specifies whether a toolbar is dockable or fixed. When this attribute is FALSE, the toolbar is fixed at the top of the main window immediately below the menu bar. When TRUE (default), the toolbar is dockable; DsNgravity specifies its initial position.
DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNgravity (long)	[CG]	The initial position and state of a dockable toolbar. Possible values are: DSTBTOP Docked at top of main window (default). DSTBBOTTOM Docked at bottom of main window. DSTBLEFT Docked at left of main window. DSTBRIGHT Docked at right of main window. DSTBFLOATING Floating toolbar, initially centered in main window. DSTBINVISIBLE Toolbar not visible (not valid in create.object()).
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNimageList (long array)	[CSG]	The list of DsCpixmap objects and separators that the toolbar displays. This is a mandatory attribute for create.object(). A toolbar separator is indicated by a value of -1. All toolbar images must have the same width and height. The recommended size is 16 pixels wide and 15 pixels high.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNstateList (long array)	[CS]	The state of the toolbar buttons. The array consists of one or more pairs of values. The first value in each pair is the button index (1-based index). The second value defines the state of the button. Possible state values are: DSTBBTNDISABLEDUNCHECKED DSTBBTNDISABLEDCHECKED   (DSCHECK buttons only) DSTBBTNENABLEDUNCHECKED  (default) DSTBBTNENABLEDCHECKED    (DSCHECK buttons only)
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNtitle (string)	[CS]	The title of the window of a floating toolbar. The default is an empty string.
DsNtypeList (long array)	[C]	The button types. The array consists of one or more pairs of values. The first value in each pair is the button index (1-based index). The second value defines the button type. Possible values are: DSNORMAL Normal pushbutton (default). DSCHECK A two-state button.
DsNwidth (long)	[CSG]	The width of the object, in pixels.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCtree

Description

A DsCtree object defines a tree view control. Like any tree view control, it displays a list of items as an indented outline that reflects the hierarchical relationship between the items.

Items in a tree control have a parent-child relationship. They can be either nodes or leaves. Nodes represent category headings and can have leaves and other nodes as children. Leaves do not have children. All items, except the root node, have one parent node; the root node is the highest node in the tree.

Each item in a tree control consists of an icon and a text label. If a node has children, it is preceded by a + or - button that enables the user to expand or collapse it respectively.

Each item has a unique ID. An item also has a parent ID; this is the ID of the item's parent node. An item can also have a sibling ID; this is the ID of the item that appears immediately below it within the same parent node. The parent and sibling IDs of an item determine where the item is positioned within the tree structure.

You use the DsNtreeData attribute to define the type, label, ID, image, and parent or sibling ID of a tree control item. You also use DsNtreeData to change the properties of a tree control item, by calling change.object() and defining the new properties in the DsNtreeData attribute.

For example, you can reposition an item within the tree control by specifying a different parent or sibling for the item. You cannot, however, change the parent ID of an item to 0 (because a tree control can have only one root node). Nor can you change an item's parent ID to that of one of the item's descendants or to the item's own ID. You can change a leaf to a node and vice versa – however, if you change a node to a leaf, all children of the node are automatically removed. You cannot change the unique ID of an item directly. To assign a new ID to an item, you must remove the item and then redefine it with the new ID. Note that when an item has been removed, you can reuse its ID for a new item.

Navigation

Users can use the mouse or keyboard keys to navigate through a tree control and to activate items.

Mouse actions

To move to an item with the mouse, click on the item. To activate an item, and to expand and collapse a node, double-click on it.

Keyboard actions

Move between items	A single item at a time
UP ARROW, DOWN ARROW

One scroll page at a time
Pg Up, Pg Dn

To first and last items
HOME, END

To move to next item whose label begins with a particular character
Press key correspoding to the character

Expand/collapse nodes	RIGHT ARROW, LEFT ARROW

Activate a leaf  	   	       	ENTER

All the above mouse and keyboard actions generate an EVTTREESELECT event (see Events). Pressing any key other than those mentioned above generates an EVTKEYPRESS event.

Events

A DsCtree object can generate the following events:

EVTTREESELECT

EVTKEYPRESS

EVTCHANGEFOCUS

EVTSETFOCUS

EVTHELP

Attributes

DsNcommandList          (long array)	[CS]	Use this to set the state of tree control items and to remove tree items. The array contains one or more entries in the following format: long The ID of a tree node or leaf. long The state of the specified node or leaf: DSTREEEXPAND Expands the node by one level. DSTREECOLLAPSE Collapses the node if it is expanded. DSTREEREMOVE Removes the item (if it is a  node, all its children are also removed). DSTREEEXPANDALL Expands the node and all its  children.
DsNeventMask            (long)	[CSG]	Specifies the events that the object can generate. See select.event.input() for a list of possible masks.
DsNeventReasonMask (long)	[CSG]	The EVTTREESELECT event can be generated when a tree item is activated, expanded, collapsed, or selected. The DsNeventReasonMask attribute specifies for which of these actions or reasons the event is generated. If a particular reason is not set in this attribute, then an event is not generated for that reason. Possible values are: EVTTREEREASONACTIVATEMASK EVTTREEREASONEXPANDMASK EVTTREEREASONCOLLAPSEMASK EVTTREEREASONSELECTMASK Use the bitwise OR operator to combine some or all of these flags.
DsNheight (long)	[CSG]	The height of the scroll view window, in pixels. When the tree is longer than the window, a vertical scroll bar is automatically enabled.
DsNmode (long)	[CSG]	The tree mode. Possible values are: DSOPENAGAIN When reopening node, restore previous state. DSOPENNONE When reopening node, collapse all subnodes.
DsNobjectType               (long)	[G]	The object type.
DsNparent                       (long)	[G]	The ID of the parent object.
DsNselectedId	[CSG]	Specifies the ID of the currently selected tree item.
DsNsetState                  (long)	[CS]	The state of the object. See DsCmwindow.
DsNtemplate                  (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNtreeData	[CS]	This contains the tree data. The data consists of the following information: • A header containing the following fields: long   Version number (currently always 1). long   Number of image sets used by the tree images. long Number of items in the tree. • Zero or more entries specifying the image sets used by the tree items. Normally, tree items of the same type use the same icon. This icon can have a different appearance in different situations – for example, when the item is selected, not selected, expanded, collapsed, and so on. An image set is the set of such images for a particular type of item.  For example, on the contents page of a Windows help file, the following icons represent a collapsed book and an expanded book respectively. The two icons represent the image set for book-type items. An image set entry contains the following fields: short The image set ID. long The ID of the image for items not selected and not  expanded.  long The ID of the image for items selected but not  expanded. If this is 0, the default is the ID of the image for images not selected and not expanded. long The ID of the image for nodes expanded but not selected. If this is 0, the default is the ID of the  image for items not selected and not expanded.  This is relevant only to node items. long The ID of the image for nodes selected and expanded. If this is 0, the default is the ID of the image for items selected but not expanded. This  is relevant only to node items. • Zero or more item entries containing the following fields: byte The item type. Possible values are: 0 leaf 1 node 2 sibling leaf 3 sibling node string The text for the item's label. This is a null-terminated string. short The ID of the item's image set. This can be the ID of an image set specified by the current DsNtreeData attribute, or the ID of an image set specified by a previous DsNtreeData attribute. short A unique item ID. short The ID of the item's parent or sibling. If the item type is 0 or 1, the item is inserted as the last item under the specified parent item – the parent ID of the root item is always 0. If the item type is 2 or 3 (that is,  sibling), the item is inserted above the specified  sibling item. The parent or sibling ID must be that  of an existing tree item. When changing the property of a tree item with change.object(), you must specify the full data for that item in the DsNtreeData attribute. In the case of a node, it is not necessary to redefine the node's children.
DsNwidth (long)	[CSG]	The width of the scroll view window, in pixels. When the tree is wider than the window, a horizonotal scroll bar is automatically enabled.
DsNx  (long)	[CSG]	The x-coordinate of the object's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the object's outer top edge, in pixels, relative to the inner top edge of its parent.
Examples

The following is an example of DsNtreeData data used to create a new tree control:

Resulting tree control

DsNtreeData header

Version	Count (image sets)	Count (nodes)
1	2	9

DsNtreeData image set entries

Image set ID	Image ID (not selected,  not expanded)	Image ID (selected,   not expanded)	Image ID (not selected, expanded)	Image ID (selected,  expanded)
ID_FOLDER_SET	ID_FOLDER_1	0	ID_FOLDER_2	0
ID_SESSION_SET	ID_SESSION_1	ID_SESSION_2	0	0
DsNtreeData item entries

Type	Text	Image set ID	   ID	   Parent ID
1	root	ID_FOLDER_SET	   1	   0
0	leaf1	ID_SESSION_SET	   2	   1
0	leaf2	ID_SESSION_SET	   6	   1
1	node1	ID_FOLDER_SET	   86	   1
1	node2	ID_FOLDER_SET	   87	   1
0	leaf7	ID_SESSION_SET	   88	   1
0	leaf8	ID_SESSION_SET	   43	   1
0	leaf9	ID_SESSION_SET	   78	   1
1	node4	ID_FOLDER_SET	   361	   1

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpArc

Description

A DsCgpArc object defines a circular or elliptical arc inside a rectangle. The center of the circle or ellipse is the center of the rectangle. The major and minor axes are specified by the width and height attributes respectively. The parent object is always a graphical window (DsCgwindow).

Events

A DsCgpArc object does not generate events.

Attributes

DsNangle    (long)	[CSG]	Specifies the start of the arc relative to the three-o'clock radial from the center of the arc. Angles are specified in degrees (maximum 360 degrees). Positive values indicate counter-clockwise motion and negative values indicate clockwise motion.
DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                  Detectable and visible. GPUNDETECTABLE         Cannot be detected with query.object(). GPINVISIBLE          Subobject is hidden.
DsNgc (long)	[CS]	The ID of a DsCgc object that contains a set of attributes to be applied to the object.
DsNgcBackground (long)	[CSG]	The rgb value that defines the background color of the subobject.
DsNgcCapStyle (long)	[CSG]	This controls the appearance of line ends. Possible values are: GCCAPBUTT Lines are square at the end point. GCCAPROUND Lines are terminated by a circular arc whose    diameter equals the line width.
DsNgcForeground (long)	[CSG]	The rgb value that defines the foreground color of the subobject.
DsNgcLineStyle (long)	[CSG]	The line and border style for the subobject. Possible values are:  GCLINESOLID Normal line. GCLINEDOUBLEDASH Line stippled, using DsNgcForeground and DsNgcBackground colors. GCLINEONOFFDASH Line stippled, using DsNgcForeground and  the window's background color.
DsNgcLineWidth (long)	[CSG]	The width of lines and borders, in pixels.
DsNheight     (long)	[CSG]	The height of the bounding rectangle, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNrotation (long)	[CSG]	Specifies the angle of the arc relative to the DsNangle value. Angles are specified in degrees (maximum 360 degrees). Positive values indicate counter-clockwise motion and negative values indicate clockwise motion.
DsNsequence (long)	[CS]	The position of the arc relative to the reference object. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNtemplate (long)	[CS]	The ID of a template object that contains a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the bounding rectangle, in pixels.
DsNx (long)	[CSG]	The x-coordinate of the upper-left corner of the bounding rectangle, relative to the upper-left corner of the parent window.
DsNy (long)	[CSG]	The y-coordinate of the upper-left corner of the bounding rectangle, relative to the upper-left corner of the parent window.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpComposite

Description

A DsCgpComposite subobject groups a number of graphical parts so that you can manipulate them as a single unit. The parent object is always a DsCgwindow object.

Events

A DsCgpComposite object does not generate events.

Attributes

DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                   Detectable and visible. GPUNDETECTABLE           Cannot be detected with query.object(). GPINVISIBLE            Subobject is hidden.
DsNheight (long)	[G]	The height of the object, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the composite object relative to the reference object. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNsubObjectArray (long array)	[CSG]	The IDs of the subobjects that the group contains. This attribute takes two values. The first contains the name of the subobject array, the last specifies the number of subobjects the group contains.
DsNtemplate (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the subobject.
DsNwidth (long)	[G]	The width of the subobject, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the subobject's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the subobject's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpGroupBox

Description

A DsCgpGroupBox object defines a frame on the parent window. It can also display a text string at the top of the frame. The parent object is always a DsCgwindow object.

Events

A DsCgpGroupBox object does not generate events.

Attributes

DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                   Detectable and visible. GPUNDETECTABLE         Cannot be detected with query.object(). GPINVISIBLE            Subobject is hidden.
DsNgcBackground (long)	[G]	The rgb value that defines the background color of the graphical part.
DsNgcFontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to title text.
DsNgcForeground (long)	[G]	The rgb value that defines the foreground color of the graphical part.
DsNgc (long)	[CS]	The ID of a DsCgc object that contains a set of attributes to be applied to the object.
DsNheight (long)	[CSG]	The height of the frame, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the composite object relative to the reference object. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNstring (string)	[CSG]	The text string to be displayed at the top of the groupbox.
DsNtemplate	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNgcTextStyle (long)	[CSG]	Defines the style of the text string displayed at the top of the groupbox. Possible values are: TSNORMAL Normal text. TSBOLD Bold text. TSREVERSE Reverse text. TSUNDERLINE Underlined text. TSFILLSOLID  Fill with background color.
DsNwidth (long)	[CSG]	The width of the frame, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the subobject's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the subobject's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpHeader

Description

A DsCgpHeader subobject defines a header line on the parent window. The line can include a centered title string. The parent window is always a DsCgwindow object.

Events

A DsCgpHeader object does not generate events.

Attributes

DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                    Detectable and visible. GPUNDETECTABLE           Cannot be detected with query.object(). GPINVISIBLE            Subobject is hidden.
DsNgcBackground (long)	[G]	The rgb value that defines the background color of the graphical part.
DsNgcFontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to subobject's text string.
DsNgcForeground (long)	[G]	The rgb value that defines the foreground color of the graphical part.
DsNgc (long)	[CS]	The ID of a DsCgc object that contains a set of attributes to be applied to the object.
DsNheight (long)	[G]	The height of the header line, in pixels.
DsNobjectType               (long)	[G]	The subobject type.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the header subobject relative to the reference subobject. Possible values are: GPMKFIRST part is drawn above all other parts GPMKLAST part is drawn under all other parts GPMKNEXT part is drawn under DsNrefSubObject GPMKPREV part is drawn above DsNrefSubObject
DsNstring (string)	[CSG]	The text string to be displayed in the center of the header line.
DsNtemplate	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNgcTextStyle (long)	[CSG]	Defines the style of the text string displayed in the center of the header line. Possible values are: TSNORMAL normal text TSBOLD bold text TSREVERSE reverse text TSUNDERLINE underlined text TSFILLSOLID  fill with background color
DsNwidth (long)	[CSG]	The width of the header line, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the subobject's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the subobject's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpImage

Description

A DsCgpImage object defines a graphical image to be drawn in the parent window. It is linked to a DsCpixmap object, which defines an array of pixels, with a specified width, height, and depth (number of planes), but no screen coordinates. The parent window is always a DsCgwindow object.

Events

A DsCgpImage subobject does not generate events.

Attributes

DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                    Detectable and visible. GPUNDETECTABLE           Cannot be detected with query.object(). GPINVISIBLE            Subobject is hidden.
DsNheight (long)	[G]	The height of the image, in pixels.
DsNobjectType               (long)	[G]	The subobject type.
DsNpixmap (long)	[CS]	The ID of the pixmap to be drawn.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the image relative to the reference subobject. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNtemplate	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth	[G]	The width of the image, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the subobject's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the subobject's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpLine

Description

A DsCgpLine subobject defines a line to be drawn between two specified points in the parent window. The parent window is always a DsCgwindow object.

Events

A DsCgpLine object does not generate events.

Attributes

DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                   Detectable and visible. GPUNDETECTABLE          Cannot be detected with query.object(). GPINVISIBLE           Subobject is hidden.
DsNgcBackground (long)	[CSG]	The rgb value that defines the background color of the graphical part.
DsNgcCapStyle (long)	[CSG]	This controls the appearance of line ends. Possible values are: GCCAPBUTT Lines are square at the end point. GCCAPROUND Lines are terminated by a circular arc whose    diameter equals the line width.
DsNgcForeground (long)	[CSG]	The rgb value that defines the foreground color of the graphical part.
DsNgc (long)	[CS]	The ID of a DsCgc object that contains a set of attributes to be applied to the subobject.
DsNgcLineStyle (long)	[CSG]	The line style for the subobject. Possible values are:  GCLINESOLID Normal line. GCLINEDOUBLEDASH Line stippled, using DsNgcForeground and DsNgcBackground colors. GCLINEONOFFDASH Line stippled, using DsNgcForeground and the window's background color.
DsNgcLineWidth (long)	[CSG]	The width of lines and borders, in pixels.
DsNobjectType               (long)	[G]	The subobject type.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the line relative to the reference subobject. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNtemplate	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNxo, DsNxn, DsNyo, DsNyn (long)	[CSG]	The line is drawn between two points in the parent window. The DsNxo and DsNyo attributes specify the x- and y-coordinates of the start point, relative to the upper-left corner of the parent window. The DsNxn and DsNyn attributes specify the x- and y-coordinates of the end point, relative to the upper-left corner of the parent window.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpOleSite

Description

A DsCgpOleSite subobject defines a rectangle that can embed an OLE object. The parent window is always a DsCgwindow object.

Events

A DsCgpOleSite subobject does not generate events.

Attributes

DsNappName (string)	[CS]	The name of the application in which the OLE object is embedded.
DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                   Detectable and visible. GPUNDETECTABLE          Cannot be detected with query.object(). GPINVISIBLE           Subobject is hidden.
DsNdata (void)	[CSGQ]	Specifies the binary data that contains the OLE object.
DsNdocName (string)	[CS]	The name of the document in which the OLE object is embedded.
DsNerror (long)	[G]	Specifies the error code returned when a change.object() request fails.
DsNformat (long)	[CQ]	The format of the data in DsNdata. Possible values are: DSFORMATNATIVE Native object format defined by server application (default). DSFORMATTEXT               ASCII text format. DSFORMATBITMAP Bitmap format. DSFORMATMETAFILE           Metafile format. DSFORMATDIB                Device independent  bitmap format. DSFORMATWAVE Wave file format. DSFORMATUNICODETEXT        Unicode text format. DSFORMATENHANCEDMETAFILE   Enhanced metafile format. DSFORMATRICHTEXT           RTF format DSFORMATEMBEDSOURCE        Embedded source format. DSFORMATEMBEDDEDOBJECT     Embedded object format. DSFORMATLINKSOURCE Link source format. DSFORMATOBJECTDESCRIPTOR   Object description format. DSFORMATLINKSOURCEDESCRIPTOR Link source description format. DSFORMATOWNERLINK Owner link format. DSFORMATFILENAME File name format.
DsNheight (long)	[CSG]	The height of the object, in pixels.
DsNname (string)	[CS]	The name of the local file that contains the OLE object.
DsNobjectType               (long)	[G]	The subobject type.
DsNprogId (string)	[CS]	OLE objects are registered with a unique program identifier. This attribute specifies that ID.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the object relative to the reference subobject. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject
DsNsize (long)	[GQ]	The size of the data in DsNdata.
DsNtemplate	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNverb (long)	[S]	The action to be performed on the OLE object.
DsNwidth (long)	[CSG]	The width of the subobject, in pixels.
DsNx  (long)	[CSG]	The x-coordinate of the subobject's outer left edge, in pixels, relative to the inner left edge of its parent.
DsNy  (long)	[CSG]	The y-coordinate of the subobject's outer top edge, in pixels, relative to the inner top edge of its parent.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpPie

Description

A DsCgpPie subobject defines a filled circular or elliptical arc, within a bounding rectangle. This subobject is similar to a DsCgpArc subobject, except that it is filled with a color and fill style. The parent object is always a graphical window (DsCgwindow).

Events

A DsCgpPie object does not generate events.

Attributes

DsNangle    (long)	[CSG]	Specifies the start of the pie relative to the three-o'clock radial from the center of the pie. Angles are specified in degrees (maximum 360 degrees). Positive values indicate counter-clockwise motion and negative values indicate clockwise motion.
DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                   Detectable and visible. GPUNDETECTABLE          Cannot be detected with query.object(). GPINVISIBLE           Subobject is hidden.
DsNgcBackground (long)	[CSG]	The rgb value that defines the background color of the subobject.
DsNgcFillColor (long)	[CSG]	The rgb value that defines the fill color of the graphical part.
DsNgcFillStyle (long)	[CSG]	The fill style for a graphical part. Possible values are: GCFILLSOLID Fill solid. GCFILL90 Fill 90 %. GCFILL75 Fill 75 %. GCFILL50 Fill 50 %. GCFILL25 Fill 25 %. GCFILL10 Fill 10 %. GCFILL00 Fill 0 %. GCFILLHOR Fill with horizontal lines. GCFILLVER Fill with vertical lines. GCFILLSLEFT Fill with slant left lines. GCFILLSRIGHT Fill with slant right lines GCFILLHOLLOW  Do not fill.
DsNgcForeground (long)	[CSG]	The rgb value that defines the foreground color of the graphical part.
DsNgc (long)	[CS]	The ID of a DsCgc object that contains a set of attributes to be applied to the object.
DsNgcJoinStyle (long)	[CSG]	Defines how corners are drawn. Possible values are: GCJOINMITER The outer edges of the two lines extend to meet  at an angle. GCJOINROUND Lines are joined by a circular arc whose diameter  equals the line width and which is centered on                       the join point.
DsNgcLineStyle (long)	[CSG]	The line and border style for a graphical part. Possible values are:  GCLINESOLID Normal line. GCLINEDOUBLEDASH Line stippled, using DsNgcForeground and DsNgcBackground colors. GCLINEONOFFDASH Line stippled, using DsNgcForeground and  the window's background color.
DsNgcLineWidth (long)	[CSG]	The width of lines and borders, in pixels.
DsNheight     (long)	[CSG]	The height of the bounding rectangle, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNrotation (long)	[CSG]	Specifies the angle of the pie relative to the DsNangle value. Angles are specified in degrees (maximum 360 degrees). Positive values indicate counter-clockwise motion and negative values indicate clockwise motion.
DsNsequence (long)	[CS]	The position of the pie relative to the reference object. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNtemplate (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNwidth (long)	[CSG]	The width of the bounding rectangle, in pixels.
DsNx (long)	[CSG]	The x-coordinate of the upper-left corner of the bounding rectangle, relative to the upper-left corner of the parent window.
DsNy (long)	[CSG]	The y-coordinate of the upper-left corner of the bounding rectangle, relative to the upper-left corner of the parent window.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpPolygon

Description

A DsCgpPolygon subobject defines a closed figure, bounded by three or more straight sides, which is drawn in the parent window. It is basically a polyline whose first and last points are joined. A polygon subobject can have a fill color and style. The parent window is always a DsCgwindow object.

Events

A DsCgpPolygon subobject does not generate events.

Attributes

DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                   Detectable and visible. GPUNDETECTABLE          Cannot be detected with query.object(). GPINVISIBLE           Subobject is hidden.
DsNgcBackground (long)	[CSG]	The rgb value that defines the background color of the subobject.
DsNgcFillColor (long)	[CSG]	The rgb value that defines the fill color of the graphical part.
DsNgcFillStyle (long)	[CSG]	The fill style for a graphical part. Possible values are: GCFILLSOLID Fill solid. GCFILL90 Fill 90 %. GCFILL75 Fill 75 %. GCFILL50 Fill 50 %. GCFILL25 Fill 25 %. GCFILL10 Fill 10 %. GCFILL00 Fill 0 %. GCFILLHOR Fill with horizontal lines. GCFILLVER Fill with vertical lines. GCFILLSLEFT Fill with slant left lines. GCFILLSRIGHT Fill with slant right lines GCFILLHOLLOW  Do not fill.
DsNgcForeground (long)	[CSG]	The rgb value that defines the foreground color of the graphical part.
DsNgc (long)	[CS]	The ID of a DsCgc object that contains a set of attributes to be applied to the object.
DsNgcJoinStyle (long)	[CSG]	Defines how corners are drawn. Possible values are: GCJOINMITER The outer edges of the two lines extend to meet  at an angle. GCJOINROUND Lines are joined by a circular arc whose diameter  equals the line width and which is centered on                       the join point.
DsNgcLineStyle (long)	[CSG]	The line and border style for a graphical part. Possible values are:  GCLINESOLID Normal line. GCLINEDOUBLEDASH Line stippled, using DsNgcForeground and DsNgcBackground colors. GCLINEONOFFDASH Line stippled, using DsNgcForeground and  the window's background color.
DsNgcLineWidth (long)	[CSG]	The width of lines and borders, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNpointArray (long array)	[CSG]	The array containing the positions of the points. The point array must be filled as follows: • points(1,1) contains the x-coordinate of the first point • points(1,2) contains the y-coordinate of the first point • points(number of points,1) contains the x-coordinate of the last point • points(number of points,2) contains the y-coordinate of the last point All coordinates must be specified in pixels relative to the upper-left corner of the parent window.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the polygon relative to the reference object. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNtemplate (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpPolyline

Description

A DsCgpPolyline subobject defines a line to be drawn between a number of specified points in the parent window. The points are stored in the DsNpointArray attribute. If the first and last points coincide, the lines are joined according to the setting of the DsNgcJoinStyle attribute. The parent window is always a DsCgwindow object.

Events

A DsCgpPolyline object does not generate events.

Attributes

DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                    Detectable and visible. GPUNDETECTABLE          Cannot be detected with query.object(). GPINVISIBLE           Subobject is hidden.
DsNgcBackground (long)	[CSG]	The rgb value that defines the background color of the subobject.
DsNgcCapStyle (long)	[CSG]	This controls the appearance of line ends. Possible values are: GCCAPBUTT Lines are square at the endpoint. GCCAPROUND Lines are terminated by a circular arc whose.    diameter equals the line width
DsNgcForeground (long)	[CSG]	The rgb value that defines the foreground color of the graphical part.
DsNgc (long)	[CS]	The ID of a DsCgc object that contains a set of attributes to be applied to the object.
DsNgcJoinStyle (long)	[CSG]	Defines how corners are drawn. Possible values are: GCJOINMITER The outer edges of the two lines extend to meet  at an angle. GCJOINROUND Lines are joined by a circular arc whose diameter  equals the line width and which is centered on                       the join point.
DsNgcLineStyle (long)	[CSG]	The line and border style for a graphical part. Possible values are:  GCLINESOLID Normal line. GCLINEDOUBLEDASH Line stippled, using DsNgcForeground and DsNgcBackground colors. GCLINEONOFFDASH Line stippled, using DsNgcForeground and  the window's background color.
DsNgcLineWidth (long)	[CSG]	The width of lines and borders, in pixels.
DsNobjectType               (long)	[G]	The subobject type.
DsNpointArray (long array)	[CSG]	The array containing the positions of the points. The point array must be filled as follows: • points(1,1) contains the x-coordinate of the first point • points(1,2) contains the y-coordinate of the first point • points(number of points,1) contains the x-coordinate of the last point • points(number of points,2) contains the y-coordinate of the last point All coordinates must be specified in pixels relative to the upper-left corner of the parent window.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the polyline object relative to the reference object. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNtemplate (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpRectangle

Description

A DsCgpRectangle subobject defines a rectangle within the parent window. The parent window is always a DsCgwindow object.

Events

A DsCgpRectangle subobject does not generate events.

Attributes

DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                   Detectable and visible. GPUNDETECTABLE          Cannot be detected with query.object(). GPINVISIBLE            Subobject is hidden.
DsNgcBackground (long)	[CSG]	The rgb value that defines the background color of the subobject.
DsNgcFillColor (long)	[CSG]	The rgb value that defines the fill color of the graphical part.
DsNgcFillStyle (long)	[CSG]	The fill style for a graphical part. Possible values are: GCFILLSOLID Fill solid. GCFILL90 Fill 90 %. GCFILL75 Fill 75 %. GCFILL50 Fill 50 %. GCFILL25 Fill 25 %. GCFILL10 Fill 10 %. GCFILL00 Fill 0 %. GCFILLHOR Fill with horizontal lines. GCFILLVER Fill with vertical lines. GCFILLSLEFT Fill with slant left lines. GCFILLSRIGHT Fill with slant right lines GCFILLHOLLOW  Do not fill.
DsNgcForeground (long)	[CSG]	The rgb value that defines the foreground color of the graphical part.
DsNgc (long)	[CS]	The ID of a DsCgc object that contains a set of attributes to be applied to the object.
DsNgcJoinStyle (long)	[CSG]	Defines how corners are drawn. Possible values are: GCJOINMITER The outer edges of the two lines extend to meet  at an angle. GCJOINROUND Lines are joined by a circular arc whose diameter  equals the line width and which is centered on                       the join point.
DsNgcLineStyle (long)	[CSG]	The line and border style for a graphical part. Possible values are:  GCLINESOLID Normal line. GCLINEDOUBLEDASH Line stippled, using DsNgcForeground and DsNgcBackground colors. GCLINEONOFFDASH Line stippled, using DsNgcForeground and  the window's background color.
DsNgcLineWidth (long)	[CSG]	The width of lines and borders, in pixels.
DsNheight (long)	[CSG]	The height of the rectangle, in pixels.
DsNobjectType            (long)	[G]	The subobject type.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the subobject relative to the reference object. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn under DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNwidth (long)	[CSG]	The width of the rectangle, in pixels.
DsNtemplate (long)	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNx (long)	[CSG]	The x-coordinate of the upper-left corner of the rectangle, in pixels, relative to the upper-left corner of the parent window.
DsNy (long)	[CSG]	The y-coordinate of the upper-left corner of the rectangle, in pixels, relative to the upper-left corner of the parent window.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


DsCgpText

Description

A DsCgpText subobject defines a text string to be drawn as a graphical part in the parent window. The parent window is always a DsCgwindow object.

Events

A DsCgpText subobject does not generate events.

Attributes

DsNattribute (long)	[CSG]	The status of the subobject. Possible values are: GPNORMAL                   Detectable and visible. GPUNDETECTABLE          Cannot be detected with query.object(). GPINVISIBLE            Subobject is hidden.
DsNgcBackground (long)	[CSG]	The rgb value that defines the background color of the graphical part.
DsNgcFontSet (long)	[CSG]	The ID of a DsCfontSet object. The font object defines the font attributes to be applied to the text.
DsNgcForeground (long)	[CSG]	The rgb value that defines the foreground color of the graphical part.
DsNgc (long)	[CS]	The ID of a DsCgc object that contains a set of attributes to be applied to the object.
DsNheight (long)	[G]	The height of the text string, in pixels.
DsNobjectType               (long)	[G]	The object type.
DsNrefSubObject   (long)	[CS]	The ID of the subobject used as a reference by DsNsequence.
DsNsequence (long)	[CS]	The position of the text object relative to the reference object. Possible values are: GPMKFIRST Part is drawn above all other parts. GPMKLAST Part is drawn under all other parts. GPMKNEXT Part is drawn below DsNrefSubObject. GPMKPREV Part is drawn above DsNrefSubObject.
DsNstring (string)	[CSG]	The text string to display as graphical text.
DsNtemplate	[CS]	The ID of a template object that defines a set of attributes to be applied to the object.
DsNgcTextStyle (long)	[CSG]	Defines the style of the graphical text. Possible values are: TSNORMAL Normal text. TSBOLD Bold text. TSREVERSE Reverse text. TSUNDERLINE Underlined text. TSFILLSOLID  Fill with background color.
DsNwidth (long)	[G]	The width of the text string, in pixels.
DsNx (long)	[CSG]	The x-coordinate of the baseline starting position for the string, in pixels, relative to the upper-left corner of the parent window.
DsNy (long)	[CSG]	The y-coordinate of the baseline starting position for the string, in pixels, relative to the upper-left corner of the parent window.
Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects
    UI objects:  example


User interface objects: example

#define     COMMAND.ABORT      10

#define     COMMAND.EXIT       11

#define     COMMAND.FIRST      20

#define     COMMAND.LAST       21

#define     COMMAND.PREV       22

#define     COMMAND.NEXT       23

long     toplevel, gwin, image, combox, combox_id

function main()

{

      image = 0

      combox_id = 1

      show.mwindow()

      fill.work.area()

      update.gwindow()

      handle.event.loop()

}

function long create.pulldown.menu(long mwin)

{

      long barmenu, size

      string menudata(1) based

      alloc.mem(menudata, 3000)

      size = 1

      | write header info to buffer

      store.long(1, menudata(size))      | version is 1

      size = size + 4

      store.long(8, menudata(size))      | menu contains 8 entries

      size = size + 4

      | create the File submenu

      write.menu.entry(menudata, size, 1, 0, "&File", 0)

      write.menu.entry(menudata, size, 2, COMMAND.ABORT, "Abort", 0)

      write.menu.entry(menudata, size, 2, COMMAND.EXIT, "E&xit  Alt+F4", 0)

      | create the View submenu

      write.menu.entry(menudata, size, 1, 0, "&View", 0)

      write.menu.entry(menudata, size, 2, COMMAND.FIRST, "First", 0)

      write.menu.entry(menudata, size, 2, COMMAND.LAST, "Last", 0)

      write.menu.entry(menudata, size, 2, -1, "-", 0)      | separator

      write.menu.entry(menudata, size, 2, COMMAND.PREV, "Prev", 0)

      write.menu.entry(menudata, size, 2, COMMAND.NEXT, "Next", 0)

      barmenu = create.object(DsCbarMenu, mwin,

                  DsNmenuData,   menudata, size-1,

                  DsNsetState,   DSRAISE)

       return(barmenu)

}

function write.menu.entry(ref string menudata(), ref long size,

      long level, long id, const string name(), long flags)

{

      store.long(level, menudata(size))

      size = size + 4

      store.long(id, menudata(size))

      size = size + 4

      menudata(size) = name

      size = size + len(name)

      store.byte(0, menudata(size))   | terminate string with 0 char.

      size = size + 1

      store.long(flags, menudata(size))

      size = size + 4

}

function show.mwindow()

{

      long barmenu

      toplevel = create.object( DsCmwindow, 0,

                  DsNtitle,         "MWindow",

                  DsNprocessgroup,  get.pgrp(pid),

                  DsNminWidth,      300,

                  DsNmaxWidth,      600,

                  DsNminHeight,     200,

                  DsNmaxHeight,     400)

      barmenu = create.pulldown.menu(toplevel)

      change.object( toplevel, DsNbarMenu, barmenu )

      update.object(toplevel)

}

function fill.work.area()

{

      long        rowcol

      string      listitems(300)

      rowcol = create.object(DsCrowColumn, toplevel,

                  DsNvspace,        10,

                  DsNhspace,        10,

                  DsNnumColumns,     3,

                  DsNfixedDimension, DSHORIZONTAL )

      create.object(DsClabel,  rowcol,

                    DsNstring, "Article:" )

      |            12345678901234567890123456789012345678901234567890

      listitems = "article -1-printers-2-graph   -3-books   -4-logo-5"

      store.byte(0, listitems(9))

      store.byte(0, listitems(11))

      store.byte(0, listitems(20))

      store.byte(0, listitems(22))

      store.byte(0, listitems(31))

      store.byte(0, listitems(33))

      store.byte(0, listitems(42))

      store.byte(0, listitems(44))

      store.byte(0, listitems(49))

      combox = create.object(DsCdDComBox, rowcol,

                  DsNminWidth,      80,

                  DsNmaxWindowSize, 25,

                  DsNx,             80,

                  DsNy,             40,

                  DsNstringArray,   listitems, 54)

      gwin = create.object(DsCgwindow, rowcol,

                  DsNwidth,         100,

                  DsNheight,        100,

                  DsNpointerCursor, DSCHAND)

      create.sub.object(gwin, DsCgpRectangle,

                  DsNx,             0,

                  DsNy,             0,

                  DsNwidth,         100,

                  DsNheight,        100 )

      create.object(DsCpushButton,  rowcol,

                  DsNstring,        "Abort",

                  DsNreturnValue,   COMMAND.ABORT)

      create.object(DsCpushButton,  rowcol,

                  DsNstring,        "Exit",

                  DsNreturnValue,   COMMAND.EXIT)

      update.object(toplevel)

      update.object(gwin)

}

function update.gwindow()

{

      string file(128)

      string bufr(1)  based

      long buflen, fp, idp

      change.object(combox, DsNselectedId, combox_id)

      on case combox_id

      case 1:

            file = "${BSE}/gif/desktop.gif/tools1"

            break

      case 2:

            file = "${BSE}/gif/desktop.gif/printer1"

            break

      case 3:

            file = "${BSE}/gif/desktop.gif/graph1"

            break

      case 4:

            file = "${BSE}/gif/desktop.gif/display1"

            break

      case 5:

            file = "${BSE}/gif/desktop.gif/baanlogo"

            break

      default:

            return

      endcase

      fp = seq.open(file, "r")

      buflen = seq.seek(0, 2, fp)

      alloc.mem(bufr, buflen)

      seq.rewind(fp)

      seq.read(bufr, buflen, fp)

      seq.close(fp)

      idp = create.object(DsCpixmap, 0,

    	DsNdata, bufr, buflen,

    	DsNdataType, DSPIXGIF8 )

      if image <> 0 then

            destroy.sub.object(gwin, image)

      endif

      image = create.sub.object(gwin, DsCgpImage,

    	   DsNpixmap, idp,

    	   DsNx,      3,

    	   DsNy,      3 )

      update.object(gwin)

      free.mem(bufr)

}

function handle.event.loop()

{

      long event(EVTMAXSIZE)

      while TRUE

            next.event(event)

            on case evt.type(event)

            case EVTMENUSELECT:

                  on case evt.menu.return(event)

                  case COMMAND.ABORT:

                  case COMMAND.EXIT:

                        return

                  case COMMAND.FIRST:

                        combox_id = 1

                        update.gwindow()

                        break

                  case COMMAND.LAST:

                        combox_id = 5

                        update.gwindow()

                        break

                  case COMMAND.PREV:

                        if combox_id > 1 then

    	combox_id = combox_id - 1

    	update.gwindow()

                        endif

                        break

                  case COMMAND.NEXT:

                        if combox_id < 5 then

    	combox_id = combox_id + 1

   	update.gwindow()

                        endif

                        break

                  endcase

                  break

            case EVTPUSHBUTTON:

                  if ( evt.button.return(event) = COMMAND.ABORT OR

                       evt.button.return(event) = COMMAND.EXIT ) then

                         return

                  endif

                  break

            case EVTLISTBOXSELECT:

                  combox_id = evt.listbox.item_id(event)

                  update.gwindow()

                  break

            default:

                  break

            endcase

      endwhile

}

Related help topics

    UI objects:  overview
    UI objects:  synopsis
    UI objects:  objects and subobjects


Predefined variables

The following is a list of the predefined variables available to programmers. Variables specific to a particular function or group of functions are listed with those functions.

4 = 4GL only; R = Read-only

Type              Name                                                    Description

long	actual.occ	4R	Occurrence currently selected on form.
string	attr.adju(1)	4	"l"  align left "r" align right "c" align center
long	attr.bitset.mask	4	The available values for a bitset field (see also enum functions).
long	attr.changed	4R	Indicates if the current field has changed.
string	attr.conv(1)	4	"u" convert to upper case "l" convert to lower case
string	attr.currency$(3)	4R	Current currency (see set.currencies()).
long	attr.currkey	4R	Number of the current key. Or 0 if the current field is not a key field.
long	attr.dbase	4R	1 current field is database field 0 current field is not a database field
long	attr.dbmaxlen	4R	Maximum length of database field.
string	attr.deflt$(100)	4R	Default value of current field.
string	attr.descr$(60)	4	Description of current field.
long	attr.diga	4	Number of digits after decimal sign. For strings, this is the maximum input length.
long	attr.digv	4	Number of digits before decimal sign.
long	attr.divf	4	Division factor. (For entering numeric values without a decimal point.)
string	attr.domain$(16)	4R	Domain of the current field.
string	attr.domm$(14)	4	Domain message code of current field.
long	attr.dorp	4	Fill field with default or previous value: 1 default 0 previous
long	attr.echo	4	1 display value after input 0 do not display value after input This variable is supported for backward compatibility only. In preference, use the inputfield.visible(), inputfield.invisible() and inputfield.password() functions.
long	attr.element	4	Current array index (if field is an array element).
string	attr.enum.mask$(128)	4	The values available for an enumerate field. Also the enumerate values available for the ask.enum() function. See also set.enum.values.for.field() function.
string	attr.format.addition$(3)	4	Currency to be used for an amount format. Language to be used for a date format.
string	attr.helpfile$(10)		Help file of current field.
string	attr.ille$(30)	4	Illegal characters.
long	attr.imax	4	Maximum input length.
long	attr.inpfld	4R	0     display field 1     input field 2     input only     3     display only
long	attr.input	4	0     input disabled   1     input enabled This variable is supported for backward compatibility only. In preference, use disable.fields() and enable.fields() functions.
string	attr.lega$(30)	4	Legal characters.
long	attr.mandatory	4R	Mandatory input.
long	attr.maxlen	4	Maximum display length of current field.
string	attr.message$(132)		Message to be displayed when a field is filled after a before.input event.
long	attr.minlen	4	Minimum length of current field.
long	attr.multioccur	4R	1 multioccurrence field 0 not multioccurrence field
string	attr.nowait$(30)	4R	Characters that start a field command. This variable is supported for backward compatibility only. In BaanERP, field command functionality is replaced by form commands.
string	attr.oformat$(30)	4	Output format of field.
long	attr.permission	4R	Permissions for current field: NO.PERMISSION 1 PERM.READ 2 PERM.MODIFY 4 PERM.WRITE 8 PERM.DELETE 16 NO.RESTRICTION 30 PERM.UNKNOWN 32 NO.PERM.DEFINED 64 See also db.permission() function.
string	attr.previous$(30)	4R	Previous value of field.
long	attr.rang	4R	Compiled expression ID for attr.rang$.
string	attr.rang$(100)	4R	Defines a range; values are automatically checked against this range.
long	attr.reallen	4R	Real database length of field.
string	attr.refpath(100)	4	Reference path.
long	attr.rndm	4	Rounding method (see also round() function).
long	attr.rotate	4	Current index in currency table (see set.currencies() function).
long	attr.sttp	4	Start position in current field.
string	attr.textfield$(17)	4	Name of the text field. Used by the Text Manager.
string	attr.textkw1$(17) to attr.textkw4$(17)	4	Keywords of text. Used by the Text Manager.
string	attr.textlang$(1)	4	Language for text editing. Used by the Text Manager.
long	attr.textmaxlines	4	Maximum number of lines in the text editor. Used by the Text Manager.
long	attr.textmode	4	1 display mode 3 read/write mode Used by the Text Manager.
string	attr.textopt$(25)	4	Name of default option for editor window options. Used by the Text Manager.
long	attr.textstart	4	1 When new text is created, start text manager  directly (default). 0 When new text is created, fill keywords first. Used by the Text Manager.
string	attr.textzoomsession$(18)	4	Session zoomed to by text editor zoom command. The default is "Display Texts" session. Used by the Text Manager.
long	attr.type	4R	Database type (DB.ENUM, DB.STRING, DB.TIME, DB.DATE, and so on)
long	attr.zoomcode	4	Field zoomcode. Possible values are:  0 (no zoom) Z.SESSION Z.MENU
string	attr.zoomreturn$(18)	4	Name of return field of zoom session on current field.
string	attr.zoomsession$(18)	4	Session zoomed to from field.
long	auto.nextform	4	1 0	When modifying form data, automatically display next form when all occurrences on current form have been filled. When modifying form data, do not automatically display next form when all occurrences on current form have been filled (default).
			It is not good GUI practice to use this variable.
long	background	R	1 current session is modal 0 current session is modeless
long	before.update.check	4R	0 field is checked during input 1 field is checked during update Valid only in subsection check.input.
long	break.view	4	When searching for records in type 3 forms, break to next view when no records found and group fields match with old values.
long	chartgrp		Current chart group.
string	chm.name(128)	4	Name of the current chart.
string	chm.owner(14)	4	Owner/creator of current chart.
string	chm.title(128)	4	Description of current chart.
string	chm.user(14)	4	Name of user of current chart.
long	choice	4	Command ID of active command.
long	curr.key	4R	Current key number of main table.
string	curr.pacc$(8)	R	Current package combination.
long	date	R	Number of days since 01-01-0001 (local time).
string	date$(6)	R	Current system date (DDMMYY).
long	e	R	Error code of last file action.
long	error.bypass	4	Indicates which database errors can be detected in your program script, see the database functions for a detailed description.
string	exit.val$(80)	R	String returned to the called program at the end of the process.
string	fattr.currfld$(30)	4R	Name of current field.
string	fattr.descr$(60)	4	Description of current form.
long	fattr.ftype	4R	Type of current form (1, 2, 3, or 4).
string	fattr.helpfile$(14)	4	Name of help file for current form.
long	fattr.horizontal	4R	True for horizontal occurrences.
long	fattr.init	4R	Indicates if the form has been initialized.
long	fattr.nrtabs	4R	Number of tabs on current form (dynamic forms only).
long	fattr.occurnr	4R	Number of occurrences on current form.
long	fattr.seqno	4R	Sequence number of current field in form.
long	fattr.step	4R	Step size in horizontal grid.
long	fattr.toplines	4	The number of lines above the multioccurrence fields (default: 3). Set in the before.program section.
long	fattr.total.line	4	If set in before.program section, this indicates that a total line must be displayed in the grid (see also display.total.fields()).
string	filename$(16)	R	Name of most-recently accessed table.
long	filled.occ	4R	Number of filled occurrences.
string	firstweek$(6)	R	Date of the first day in the first week of the current year.
long	form.curr	4R	Current form number.
long	form.next	4R	Next form number. -1 if no next form
long	form.prev	4R	Previous form number. -1if no previous form
long	graphical.mode	4	Indicates whether the 3GL program runs in graphical mode (true) or in character mode (false). Default is false.
long	ignore.first.event	4	Indicates whether the start command of the current session must be skipped. The start command is defined in the session data.
long	in.ret	4R	Integer value of key pressed on input field. Cursor keys and zoom keys cannot be detected. Valid only in on.input, after.input, and after.field sections.
long	initial.resize	4	Indicates automatic resize while starting a session.
string	job.device(14)	4	Default device used by job process.
long	job.device.requested	4	Indicates whether an output device must be specified when in job mode.
long	job.process	4R	Indicates if process is started by a job.
string	job.report(15)	4	Report code of report to be used when in job mode.
long	job.skip.date.question	4	Indicates if the question "Consider the difference between entered date and system date?" must be skipped.
string	language$(1)	R	Current language code.
long	lattr.*		See Report scripts.
string	logname$(16)	R	Current login name.
string	main.table$(9)	4R	Name of current main table.
long	mark.table()	4R	This array indicates which records are marked. The size of this array is set to fattr.occurnr. For example, if records 3 and 8 are marked, then: mark.table(3) = 1 mark.table(8) = 1 and other elements in the array are 0 (false).
long	marked	4R	Indicates if there are marked records.
long	max.formtabs	4	Defines the maximum number of form tabs to be displayed. Set in the before.program section.
double	maxdouble	R	Maximum value of a double.
long	modify.prim.key	4	1 Primary key can be modified during  modify. Set in programs of type 1, 2, and 3. 0 Primary key cannot be modified.
long	number.forms	4R	Number of forms within current session.
long	parent	R	Identification number of parent process.
long	pid	R	Identification number of current process.
long	previous.choice	4R	Possible values:  0 add.set        dupl.occur  global.copy    modify.set  mark.delete    global.delete Valid only in field sections and main.table.io.
string	procesinfo$(200)		Information passed to program at startup.
string	prog.name$(16)	R	Name of current session.
string	query.extension(512)	4	A condition that is added to the WHERE clause of a query to be parsed by the standard program (using AND operator). Set in before.program section. In preference, use the query.extend functions.
string	report$	4	Current report code.
long	reportgrp	4	Current report group.
long	reportno	R	Report number within group.
string	sattr.descr$(80)	4R	Description of the session.
long	select.only.fields.on.form		true all reference tables are read (default) false only reference tables of fields on form are  read Use in before.program section.
long	shell.type	R	Exec_perm from user file.
	spool.*		See spool.open().
long	start.by.wfc	4R	Session was started by workflow.
long	stp.abort.error	4R	Boolean indicating if the function abort.io() has been called.
long	stp.check.input.error	4R	Boolean indicating if the function set.input.error() has been called.  Valid only in check.input section.
long	stp.skip.error	4R	Boolean indicating if the function skip.io() has been called.
long	synchronized.reason	4R	This indicates the command that started the dialog synchronization.
long	update.status	4R	0 no update ADD.SET during add MODIFY.SET during modify MARK.DELETE during delete
string	user.locale$(14)	R	Locale from user file.
long	user.timer	R	Timer from user file.
string	user.type$(1)	4R	Current type of user. Possible values are: S super user N normal user
long	win.*	4R	See get.window.attrs().
string	zoomfield$(18)	4R	Variable set in the zoom session, indicating which field in the parent session was zoomed from.
string	zoomreturn$(18)	4R	Variable set in the zoom session, indicating which field's value is to be returned. In the parent session, the variable attr.zoomreturn$ has the same value.


Copyright notice

© 1998 Baan Development B.V. All rights reserved.

The information in this document is subject to change without notice. No part of this document may be reproduced, stored, or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Baan Development B.V.

Baan Development B.V. assumes no liability for any damages incurred, directly or indirectly, from any errors, omissions, or discrepancies between the software and the information contained in this document.


New

The following new modules have been implemented in the programmers guide for Corelli (BaanERP 5.2):

Byte arrays: overview

Application Response Time Measurement (ARTM): overview

Generic Browser Framework (GBF): overview

BaanERP Audit Management: overview

BaanERP eMessage Connector: overview


Application Response Time Measurement (ARTM): overview

The ARTM functions can be used by the application developer to monitor the performance of transactions. The actual monitoring is done by an external application.

ARTM is designed for system administrators to monitor the overall user response time of the whole BaanERP system, as well as to monitor specific functionality within a specific application. The data can be analyzed later on.

ARTM helps the IT manager to meet their service level agreement and helps the system administrator to detect slow responses to users and find the bottlenecks in an installed Baan system.

ARTM is not a tracing system that generates huge amounts of data. The information provided by ARTM must be kept to a minimum to give the system administrator a quick overview about the responsiveness of the system.

This implies that transactions should be implemented on a high level, starting when a user action begins, and ending when the user action is finished.

Transactions can be implemented in 4GL UI-script, the DAL script as well as 3GL applications. They may be nested.

For more details, see the Application Response Measurement API guide, located at http://www.cmg.org/regions/cmgarmw/marcarm.html

Related Help topics

Application Response Time Measurement (ARTM): synopsis

Application Response Time Measurement (ARTM): error codes

Application Response Time Measurement (ARTM): debugging

Application Response Time Measurement (ARTM): examples


Application Response Time Measurement (ARTM): synopsis

long	artm.define.transaction.class	(string tran.name(128), string tran.detail(128), [long metric.type, string metric.name(44)] … )
long	artm.redefine.transaction.class	(long artm.transaction.id, long tran.status,[long metric.type, (type depends on metric type) metric.value] … )
long	artm.begin.transaction	(long artm.transaction.class.id, [long metric.type, (type depends on metric type) metric.value] … )
long	artm.update.transaction	(long artm.transaction.id, [long metric.type, (type depends on metric type) metric.value] … )
long	artm.end.transaction	(long artm.transaction.id, long tran.status,[long metric.type, (type depends on metric type) metric.value] … )
Related Help topics

Application Response Time Measurement (ARTM): overview

Application Response Time Measurement (ARTM): error codes

Application Response Time Measurement (ARTM): debugging

Application Response Time Measurement (ARTM): examples


Application Response Time Measurement (ARTM): error codes

-1000	ARTM is not active or a non existing level is passed in the function artm.define.transaction.class()
-1001	One of the following occurred: • An invalid metric type is passed in the metric list • ARTM.SKIP.METRIC is passed in artm.define.transaction.class() • An invalid transaction status is passed.
-1002	Too many metrics have been passed.
-1003	A metric type has been defined, but the name or the value is missing.
Related Help topics

Application Response Time Measurement (ARTM): overview

Application Response Time Measurement (ARTM): synopsis

Application Response Time Measurement (ARTM): debugging

Application Response Time Measurement (ARTM): examples


Application Response Time Measurement (ARTM): debugging

The Bshell environment variable BAAN_ART_TRACE can be set for debugging the ARTM code in the application scripts.

0	Tracing disabled.
1	Basic tracing. Transactions are shown.
5	Advanced tracing. Also binary blocks sent to the ARTM agent are shown.

The trace information is send to the file $BSE/tmp/bshell.pid.

Related Help topics

Application Response Time Measurement (ARTM): overview

Application Response Time Measurement (ARTM): synopsis

Application Response Time Measurement (ARTM): error codes

Application Response Time Measurement (ARTM): examples


Application Response Time Measurement (ARTM): examples

Example 1

function extern start.mrprun()

{

long	tra.class.id

long	tra.id

| Define the MRP transaction class

tra.class.id = artm.define.transaction.class(

"MRP run",

"This is a logistic MRP run within BaanERP.",

ART.CODE, "State",

ART.GAUGE, "Memory" )

| Start the MRP run

session.tra.id = artm.begin.transaction(

tra.class.id,

ART.CODE, "Starting",

ART.GAUGE, get.mem() )

while not end,of.run()

process.next.mrp.item()

| Give feedback about the status

artm.update.transaction(

session.tra.id,

ART.CODE, "In progress",

ART.GAUGE, get.mem() )

endwhile

| Run was successfull.

artm.end.transaction(

tra.id,

ART.TRANSACTION.SUCCESS,

ART.CODE, "Finished",

ART.GAUGE, get.mem() )

}

Example 2:

Update of the metrics of a predefined session transaction class at the beginning of a session.

before.program:

| Redefine the transaction belonging to form command "Process orders"

redefined.tra.class.id = artm.redefine.transaction.class(

"process.orders",

ART.COUNTER, "Order count",

ART.CODE, "Customer code" )

functions:

function extern process.orders()	| Attached to form command

{

long	tra.id

| User has started order processing. Start the transaction

tra.id = artm.begin.transaction(

redefined.tra.class.id,

ART.COUNTER, 0,

ART.CODE, "" )

for i = 1 to order.count

process.order()

| Give feedback about the order processed

artm.update.transaction(

tra.id,

ART.COUNTER, i,

ART.CODE, cust.code )

endfor

| All orders are processed. End transaction.

artm.end.transaction(

tra.id,

ART.TRANSACTION.SUCCESS,

ART.COUNTER, order.count,

ART.CODE, "" )

}

Related Help topics

Application Response Time Measurement (ARTM): overview

Application Response Time Measurement (ARTM): synopsis

Application Response Time Measurement (ARTM): debugging

Application Response Time Measurement (ARTM): error codes


artm.define.transaction.class()

Syntax

long artm.define.transaction.class(string tran.name(128), string tran.detail(128), [long metric.type, string metric.name(44)] … )

Description

Assigns a unique identifier to a transaction class, and optionally to describe the format of additional data passed on by artm.begin.transaction (), artm.update.transaction(), and the artm.end.transaction() calls. This is normally done during the initialization of the specified application. The value returned by artm.define.transaction.class() is passed as a parameter in artm.begin.transaction() calls to identify which class of transaction is starting.

A transaction class is a description of a unit of work, such as Check Account Balance. Any number of transaction classes can be defined within each application.

Arguments

tran.name	The unique name of a transaction class. It is defined for each transaction class by the application developer. It must be unique within the application.
tran.detail	Additional information about a transaction class. If no tran.detail is associated with this transaction, the string must be empty.
metric.type, metric.name	It is possible to pass several metrics to ARTM. These metrics give information about the status of a transaction. Artm.define.transaction.class() is used to define the metrics to be used in the transaction class. Each metric consists of an id, which determines the type of metric, and a descriptive name. Five metrics can be passed at a maximum. These metrics may be chosen arbitrarily from the following list: • ARTM.COUNTER (long) A counter must be used when it makes sense to add up the values over an interval. Examples are bytes printed and records written. • ARTM.GAUGE (long) A gauge must be used instead of a counter when it is not meaningful to add up the values over an interval. An example is the amount of memory used. • ARTM.NUMERIC (long) A numeric id is simply a numeric value that is used as an identifier, and not as a measurement value. Examples are message numbers and error codes. • ARTM.CODE (string(8)) A measurement agent should process a string in the same way as a numeric id. As with numeric ids it is not meaningful to do arithmetic operations on a string value.
Return values

>= 0	The unique transaction class id. This id has to be passed to function artm.begin.transaction() for each transaction of this class.
< 0	The registering of the class failed.
Related Help topics

Application Response Time Measurement (ARTM): overview

Application Response Time Measurement (ARTM): synopsis

Application Response Time Measurement (ARTM): error codes

Application Response Time Measurement (ARTM): debugging

Application Response Time Measurement (ARTM): examples


artm.redefine.transaction.class()

Syntax

long artm.redefine.transaction.class(string tran.name(128), [long metric.type, string metric.name(44)] … )

Description

Updates the metrics of a predefined session transaction class at the beginning of a session.

The 4GL-Engine normally defines a transaction class (without metrics) on session startup for each form command to be measured. If the 4GL-developer wants to do an update on this transaction with specific metrics, they must redefine the transaction class themselves.

Call this function in section before.program.

Note: if you redefine an existing form command transaction class, you must also handle the start and stop of the transaction yourself. The 4GL-Engine will not take care of this anymore.

Implement begin.transaction() in the begin and end.transaction() in the end of the function that is attached to the form command.

Arguments

tran.name	The name of the form command function.  It must be unique within the application. The 4GL-Engine determines through this name which transaction you want to redefine. Therefore, it must match the function’s name exactly.
metric.type, metric.name	It is possible to pass several metrics to ARTM. These metrics give information about the status of a transaction. Artm.define.transaction.class() is used to define the metrics to be used in the transaction class. Each metric consists of an id, which determines the type of metric, and a descriptive name. Five metrics can be passed at a maximum. These metrics may be chosen arbitrarily from the following list: • ARTM.COUNTER (long) A counter must be used when it makes sense to add up the values over an interval. Examples are bytes printed and records written. • ARTM.GAUGE (long) A gauge must be used instead of a counter when it is not meaningful to add up the values over an interval. An example is the amount of memory used. • ARTM.NUMERIC (long) A numeric id is simply a numeric value that is used as an identifier, and not as a measurement value. Examples are message numbers and error codes. • ARTM.CODE (string(8)) A measurement agent should process a string in the same way as a numeric id. As with numeric ids it is not meaningful to do arithmetic operations on a string value.
Return values

>= 0	The unique transaction class id. This id has to be passed to function artm.begin.transaction() for each transaction of this class.
< 0	The registering of the class failed.
Related Help topics

Application Response Time Measurement (ARTM): overview

Application Response Time Measurement (ARTM): synopsis

Application Response Time Measurement (ARTM): error codes

Application Response Time Measurement (ARTM): debugging

Application Response Time Measurement (ARTM): examples


artm.begin.transaction()

Syntax

long artm.begin.transaction(long artm.transaction.class.id, [long metric.type, (type depends on metric type) metric.value] … )

Description

Marks the beginning of a transaction. Each time a transaction starts, artm.begin.transaction() must be called at the beginning of each transaction instance the user wants to monitor.

Input

artm.transaction.class.id	The unique identifier assigned to the transaction class.  This is the id generated by artm.define.transaction.class(). If the tran.id is less than zero, this artm.begin.transaction() call will be treated as a NULL operation, and a negative transaction id is returned.
metric.type, metric.value	The metrics, as defined in artm.define.transaction.class(), can be initialized here. Each metric consists of an id, which determines the type of metric, and its initial value. The value must be of the correct type. See artm.define.transaction.class() for the types. The amount of metrics must not exceed the amount as defined in artm.define.transaction.class(). The metrics must also be passed in the same sequence. It is possible to skip the metrics you don’t want to pass. In that case, pass ARTM.METRIC.SKIP as the metric type, and omit the metric value. If the last metrics are of this type, you don’t need to pass them at all.
Return value

>= 0	The transaction id. This id has to be passed to functions artm.update.transaction() and artm.end.transaction().
< 0	An error occurred in communicating with the measurement agent, or ARTM is switched off. The most likely cause is passing an invalid value for artm.transaction.class.id.
Related Help topics

Application Response Time Measurement (ARTM): overview

Application Response Time Measurement (ARTM): synopsis

Application Response Time Measurement (ARTM): error codes

Application Response Time Measurement (ARTM): debugging

Application Response Time Measurement (ARTM): examples


artm.update.transaction()

Syntax

long artm.update.transaction(long artm.transaction.id, [long metric.type, (type depends on metric type) metric.value] … )

Description

This function is not required, and can thus be omitted if not needed. It can be used for two purposes, namely:

1.	To show the progress of a long transaction
Put the artm.update.transaction() call into the application program after artm.begin.transaction() and before artm.end.transaction() each time “heartbeat” must be sent to indicate that the transaction instance is still running. This would typically be done after fixed interval time. There can be any number of artm.update.transaction() calls between artm.begin.transaction() and artm.end.transaction() pair. This call is most useful for long-running transactions that take minutes or hours to complete. Another way to capture data about the steps within a long transaction is to use component transactions.

2.	To provide extra information about a transaction
Place artm.update.transaction() into the application program after artm.begin.transaction() and before artm.end.transaction() each time special information about a transaction instance should be provided. If there is no additional information to be provided, don’t pass any metrics. There are several types of additional information that may be useful: information about the size of the transaction, information about the state of the application, and diagnostic information.

Arguments

artm.transaction.id	The unique identifier assigned to the transaction. This is the id generated by artm.begin.transaction(). Artm.transaction.id must be passed in each artm.update.transaction() call. Many transaction instances may be carried out at the same time from this and other applications, so this handle is essential for the measurement agent to identify which transaction instance is updated. If artm.transaction.id is less than zero, this artm.update.transaction () call will be treated as a NULL operation, and a negative value is returned.
metric.type, metric.value	It is possible to skip the metrics you don’t want to pass. In that case, pass ARTM.METRIC.SKIP as the metric type, and omit the metric value. If the last metrics are of this type, you don’t need to pass them at all. It is possible to skip the metrics you don’t want to pass. In that case, pass ARTM.METRIC.SKIP as the metric type, and omit the metric value. If the last metrics are of this type, you don’t need to pass them at all.
Return values

>= 0	Success
< 0	An error occurred in communicating with the measurement agent, or ARTM is switched off. The most likely cause is passing an invalid value for artm.transaction.id.
Related Help topics

Application Response Time Measurement (ARTM): overview

Application Response Time Measurement (ARTM): synopsis

Application Response Time Measurement (ARTM): error codes

Application Response Time Measurement (ARTM): debugging

Application Response Time Measurement (ARTM): examples


artm.end.transaction()

Syntax

Function long artm.end.transaction(long artm.transaction.id, long tran.status,[long metric.type, (type depends on metric type) metric.value] … )

Description

Marks the end of a transaction instance that was started with artm.begin.transaction(). artm.end.transaction () should be called from the application program just after each transaction instance ends.

Input

artm.transaction.id	The unique handle from the artm.begin.transaction () call that marked the start of this transaction instance. Artm.transaction.id must be passed in each artm.end.transaction() call. Many transaction instances may be carried out at the same time from this and other applications, so this handle is essential for the measurement agent to identify which transaction instance is stopping. If artm.transaction.id is less than zero, this artm.end.transaction () call will be treated as a NULL operation, and a negative value is returned.
tran.status	The completion code of the transaction, as determined by the application: • ARTM.TRANSACTION.SUCCESS Use this value when the operation is completed normally and as expected. • ARTM.TRANSACTION.ABORTED Use this value when there was a fundamental failure in the system. • ARTM.TRANSACTION.FAILED Use this value in application where the transaction worked properly, but no result was generated.
metric.type, metric.value	The metrics, as defined in artm.define.transaction.class(), can be updated here. Each metric consists of an id, which determines the type of metric, and its current value. The value must be of the correct type. See artm.define.transaction.class() for the types. The amount of metrics must not exceed the amount as defined in artm.define.transaction.class(). The metrics must also be passed in the same sequence. It is possible to skip the metrics you don’t want to pass. In that case, pass ARTM.METRIC.SKIP as the metric type, and omit the metric value. If the last metrics are of this type, you don’t need to pass them at all.
Return value

>= 0	Success
< 0	An error occurred in communicating with the measurement agent, or ARTM is switched off. The most likely cause is passing an invalid value for artm.transaction.id.
Related Help topics

Application Response Time Measurement (ARTM): overview

Application Response Time Measurement (ARTM): synopsis

Application Response Time Measurement (ARTM): error codes

Application Response Time Measurement (ARTM): debugging

Application Response Time Measurement (ARTM): examples


BaanERP Audit Management:
overview

To hide the internal structure of the audit trail, the BaanERP Audit Management provides the developer with a set of high level functions. These high level functions provide access to the transaction notification table and provide ways to read the transaction information without having to deal with the audit info and sequence files.

Related Help topics

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


BaanERP Audit Management:
synopsis

For a good overview of the relations between the BaanERP audit management functions see the flow diagram.

Functions for selecting transaction and action data:

long	aud.select.transactions	(const string selection.criteria, ref long selection.id)
long	aud.get.next.transaction  (Beta version, use with care the arguments number.of.retries and retry.interval still needs to be tested)	(long selection.id, long number.of.retries, long retry.interval, ref string transaction.id, ref long commit.time, ref string session, ref string user)
long	aud.get.next.action	(long selection.id, ref long table.id, ref long company, ref string table.code, ref bool meta.data.changed, ref long current.action.number, ref string action.type)
Functions on handling meta data:

long	aud.get.number.of.fields	(long selection.id, long table.id, ref long number.of.fields)
long	aud.get.field.list	(long selection.id, long table.id, ref string field.names(,))
long	aud.get.field.ids	(long selection.id, long table.id, long number.of.fields, const string field.names(,), ref long field.ids())
void	aud.get.field.info	(long selection.id, long table.id, long field.id, ref long field.depht, ref long field.type, ref long field.length)
Functions on getting field information for a database action:

string	aud.get.field.status	(long selection.id, long table.id, long field.id)
void	aud.put.old.field.value	(long pid, string variable.name, long selection.id, long table.id, long field.id, long element [, bool endian] )
void	aud.put.new.field.value	(long pid, string variable.name, long selection.id, long table.id, long field.id, long element [, bool endian] )
Function for closing the selection of transaction data:

long	aud.close.selection	(long selection.id)

Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: examples


BaanERP Audit Management:
examples

This section contains some examples of the BaanERP Audit Management. The examples are given in pseudo code. To keep the examples clear, error handling is not included. Note the examples demonstrate a metaphorical usage of the audit trail functions.

Batch-oriented replication

To obtain the changes on table tuxch001 in company 800 that occurred on 10-10-1998:

NrFields = n

MyFields(1) = “cxch”

MyFields(2) = “dsca”

…

MyFields(n) = “fldn”

RangeStr = “#COMPANY# = 800 and #TABLE# = “tuxch001” and #COMMITTIME# between 10-10-1998 00:00:00 and 10-10-1998 23:59:59”

IF aud.select.transactions (RangeStr, SelectionId) = OK THEN

WHILE aud.get.next.transaction(SelectionId, 0, 0, TransactionId, CommitTime, SessionCode, UserId) = OK

process.transaction.header(TransactionId, CommitTime, SessionCode, UserId)

WHILE aud.get.next.action(SelectionId, TableId, Company, TableName, MetaChanged,

ActionNum, ActionType) = OK

process.action.header(Company, TableName, Company, ActionNum, ActionType)

IF MetaChanged THEN

IF aud.get.field.ids(SelectionId, TableId, NrFields, MyFields, FieldIds) = OK

process.meta.data(NrFields, MyFields, FieldIds)

| This function uses aud.get.field.info

END IF

END IF

FOR FieldNr = 1 to NrFields

      IF aud.get.field.status(Pid, MyFields(i),

SelectionId, TableId, FieldIds(NrFields)) <> “X” THEN

IF ActionType = ‘D’ or ActionType = ‘U’ THEN

        aud.put.old.field.value(Pid, MyFields(FieldNr), SelectionId,

TableId, FieldIds(FieldNr))

        process.old.value(MyFields(FieldNr))

END IF

IF ActionType = ‘I’ or ActionType = ‘U’ THEN

        aud.put.new.field.value(Pid, MyFields(FieldNr), SelectionId,

TableId, FieldIds(FieldNr))

        process.new.value(MyFields(FieldNr))

END IF

      END IF

END FOR

END WHILE

END WHILE

aud.close.selection(SelectionId)

END IF

Event-driven replication

(Beta version, use with care the arguments number.of.retries and retry.interval of the aud.get.next.transaction function still needs to be tested)

To react on changes on table tuxch001 in company 800:

NrFields = n

MyFields(1) = “cxch”

MyFields(2) = “dsca”

…

MyFields(n) = “fldn”

StartOfInterval = get.commit.time.of.previously.processed.transaction()

RangeStr = “#COMPANY# = 800 and #TABLE# = “tuxch001” and #COMMITTIME# > “ & StartOfInterval

IF aud.select.transactions (RangeStr, SelectionId) = OK

REPEAT

RetVal = aud.get.next.transaction(SelectionId, 100, 10000, TransactionId, CommitTime,

SessionCode, UserId)

IF RetVal = OK

process.transaction.header(TransactionId, CommitTime, SessionCode, UserId)

WHILE aud.get.next.action(SelectionId, TableId, Company, TableName, MetaChanged,

ActionNum, ActionType) = OK

| See previous example on how to process action information

END WHILE

END IF

UNTIL RetVal = FAIL or process.stopped.by.user()

aud.close.selection(SelectionId)

StartOfInterval = CommitTime

END IF

Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: examples


aud.select.transactions()

Syntax

long	aud.select.transactions(const string selection.criteria, ref long selection.id)

Description

Before transactional data can be read from the audit trail the developer has to select the transactions. This function selects transactions from the audit trail using a selection criteria. The selection criterion is given in a SQL ‘where’ like fashion and is used to filter the desired transactions from the transaction notifications.

Restrictions

None.

Arguments

selection.criteria	A string that holds the where clause for the selection.
selection.id	Id of the prepared selection of transactions.
How to specify the selection criteria

The selection.criteria string is an expression that is used to create the ‘where’ clause of an SQL statement. Instead of using table fields in the expression the user must use predefined identifiers.

The following identifiers are available for the user:

#TRANSID#	The transaction id.
#COMMITTIME#	The commit time of the transaction. Note that the date/time is represented in UTC format.
#SESSION#	The session in which the transaction has been done.
#USER#	The Baan user that has performed the update.
#COMPANY#	The BaanERP company in which the transaction has occurred.
#TABLE#	The table that is involved in the transaction.

Using these identifiers the developer can construct any expression that complies with the constraints of a ‘where’ condition of Baan SQL.

Constraints

Operator limitations	Since it is not possible to select data over a range of BaanERP companies, no range constructions may be used for companies (identifier #COMPANY#). So operators such as >=, >, <=, <, <>, not, inrange, between are prohibited. Only =, in, are allowed.
Number of tables and companies	Although there are no limitations on the number of tables, it must be taken into account that the number of tables determines the performance of the BaanERP audit management.
Joins	A join with other tables is not possible because aud.select.transactions creates an SQL statement with the transaction notification table in the from list. The function returns an error if other tables are used in the selection criteria.
Case-sensitive identifiers	When the selection criteria string is parsed, the identifiers (such as #COMPANY#) are searched and the table field equivalent will be substituted for the identifier. The search and replace process is case-sensitive so only the identifiers as described above will be replaced. Other versions of the identifiers such as #Company# or #company# are left unchanged and will present errors during the selection process.
Time ranges	Note that with a time range the end time is included in the selection. To specify a time range of one hour use 08:00:00 - 08:59:59 and not 08:00:00 - 09:00:00. The time range must be specified in UTC time, which is independent of the current time zone.
Example of a selection.criteria string

#COMPANY# = 100 and #TABLE# between tuxch010 and tuxch025 and #USER# in {“John”, “Mary”}

Return Values

AUD_OK	Success

AUD_FAIL	The selection.criteria is not valid.

Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


aud.get.next.transaction

Syntax

long	aud.get.next.transaction(long selection.id, long number.of.retries, long retry.interval, ref string transaction.id, ref long commit.time, ref string session, ref string user)

Description

After the transactions to be selected have been specified using aud.select.transactions, the next step is to retrieve the audit data from the audit trail. The retrieved audit data can be processed in combination with the acquired meta data. The aud.get.next.transaction function fetches the next transaction data based on the selection defined with the aud.select.transactions function. When a transaction is read successfully, the function returns the transaction header, consisting of transaction.id, commit.time, session and user.

Restrictions

Aud.select.transactions has to be called successfully prior to this function. The selection.id must be equal to the selection.id returned by aud.select.transactions().

Arguments

selection.id	Id of the selected transactions returned by aud.select.transactions().
number.of.retries (Beta version, use with care the argument still needs to be tested)	Number of retries for retrieving the transaction. In some situations the required transaction notification is not yet written into the database (this is the case when checking for new transaction notifications). In this case the selection should not contain an end commit time or end transaction id. For these purposes the number.of.retries and retry.interval parameters can be used. The number.of.retries specifies the number of retries that the function has to do before aborting the function and returning an error. The number.of.retries can be 0 which means no retry will be done, or a number larger than 0 specifying the number of retries. Note that if number.of.retries is 10 the function will have performed 11 read attemps before returning a NO_MORE_TRANSACTIONS value. If any data is read, the function will return the OK value, without doing any more retries.
retry.interval (Beta version, use with care the argument still needs to be tested)	Number of milliseconds to wait before doing a retry to retrieve the data.
transaction.id	Id of the transaction, as read from the audit trail.
commit.time	The commit date and time of the next transaction (UTC format).
session	The code of the session that is responsible for the transaction.
user	The BaanERP user code of the user who is responsible for the transaction.
Return Values

AUD_OK	Next transaction could be determined and transaction header data is retrieved successfully
AUD_FAIL	An error occured when trying to retrieve the transaction data
AUD_NO_MORE_TRANSACTIONS	If there are no more transactions that meet the selection criteria defined, using function aud.select.transactions, the function returns NO_MORE_TRANSACTIONS.
Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


aud.get.next.action

Syntax

long	aud.get.next.action(long selection.id, ref long table.id, ref long company, ref string table.code, ref bool meta.data.changed, ref long current.action.number, ref string action.type)

Description

Determines and reads the next action from the list of tables that was constructed by the aud.get.next.transaction function.

The action header is returned, which consists of the current.action.number and the action.type. Furthermore, an indication is given on whether the meta data is changed. If this is the case, the number of fields, the type, or the length of one or more fields has changed, which means the meta data functions aud.get.field.ids and aud.get.field.info  must be used to handle the meta data.

The other information on the action (for each field the status, the old value and the new value) is kept internally and can be retrieved using function aud.get.field.status , aud.put.old.field.value and aud.put.new.field.value .

The action.type specifies if the action is a table operation (create table, clear table and drop table) or a row operation (insert row, delete row and update row).

If the maximum number of opened files has been reached, the function uses the action numbers to determine the last action in the list. The sequence file of this action is closed before opening a new sequence file.

Restrictions

The function aud.get.next.transaction has to be called successfully prior to this function.

State

If meta.data.changed  is true, the internal meta data information on the fields have been refreshed. This information must be retrieved using functions aud.get.field.ids and aud.get.field.info.

If action.type is ‘I’, ‘U’ or ‘D’ then the row information on the action is available for retrieval using functions aud.get.field.status , aud.put.old.field.value and aud.put.new.field.value. See the following table:

Action type	aud.get. field.status	aud.get.old.field.value	aud.get. new.field.value
‘C’ (Create table)	no	no	no
‘L’ (Clear table)	no	no	no
‘R’ (Drop table)	no	no	no
‘I’ (Insert row)	yes	no	yes
‘D’ (Delete row)	yes	yes	no
‘U’ (Update row)	yes	yes	yes

Note: The old and new field value is not available if the status shows the field is not logged in the audit trail. See aud.get.field.status() .

Arguments

selection.id	Id of the selection, as provided by aud.select.transactions.
table.id	Id of the table on which the action occurred that is used to retrieve the detailed action data using functions aud.get.field.status , aud.put.old.field.value and aud.put.new.field.value. This id is also used to get the meta data information, in case it has been changed.
company	BaanERP company that contains the table on which the database action was done.
table.code	The code of the updated database table
meta.data.changed	The status of the meta data. If true the application has to use the meta data functions (like aud.get.field.ids) to obtain the meta data that is required to retrieve the field values of the database action.  Note that when reading an action on a specific database table for the first time for a selection, meta.data.changed  will be set.
current.action.number	Sequence number of the action within the transaction.
action.type	A character that specifies the type of action retrieved. The string contains an ‘I’ for inserting a row, ‘U’ for updating a row and a ‘D’ for deleting a row. For table operations the string contains a ‘C’ for creating a table, ‘L’ for clearing a table and ‘R’ for dropping a table.
Return values

AUD_OK	Next transaction in the selection is determined and transaction header data is retrieved
AUD_FAIL	The transaction data could not be retrieved
AUD_NO_MORE_ACTIONS	There are no more transactions in the selection
Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


aud.get.number.of.fields

Syntax

long	aud.get.number.of.fields(long selection.id, long table.id, ref long number.of.fields)

Description

Use this function to determine the number of fields, read from the data dictionary, that are stored in the sequence files. This function is especially useful if the user is not aware or interested in the table fields but simply needs to pick up the value of all fields. In this situation the user uses this function together with the aud.get.field.list to read all the information of all fields.

Restrictions

The function aud.get.next.action has to be called prior to this function so that the fields list contains the dictionary information stored in the audit file.

Arguments

selection.id	Id of the selection, as provided by aud.select.transactions
table.id	Id of the table on which the action occurred as provided by the aud.get.next.action function. The table.id  is used to retrieve the detailed action data using function aud.get.field.status , aud.put.old.field.value and aud.put.new.field.value . This id is also used to get the meta data information, in case it has been changed.
number.of.fields	The number of fields logged in the audit trail for the specified table. This can be used to run the function aud.get.field.list .
Return Values

AUD_INCORRECT_SELECTION_ID	Selection.id is invalid
AUD_INCORRECT_TABLE_ID	Table.Id is invalid
AUD_OK	The number of fields can be retrieved
Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


aud.get.field.list

Syntax

long aud.get.field.list(long selection.id, long table.id, ref string field.names(,))

Description

Use this function to get the field names of all fields logged for a database table in the audit trail. This function is especially useful if the user is not aware or interested in the table fields but simply needs the names of all fields. In this case the user uses the aud.get.number.of.fields to determine how many fields are available and also uses aud.get.field.list to obtain the field ids for each field. The information of these two function can be used to further retrieve field info as well as the value of the field using the functions: aud.get.field.info , aud.get.field.status and aud.put.old.field.value and aud.put.new.field.value.

Restrictions

The function aud.get.next.action has to be called prior to this function so that the fields list contains the dictionary information stored in the audit file.

Arguments

selection.id	Id of the selection, as provided by aud.select.transactions
table.id	Id of the table on which the action occurred, as provided by the aud.get.next.action function. The table.id is used to retrieve the detailed action data using function aud.get.field.status , aud.put.old.field.value and aud.put.new.field.value . This id is also used to get the meta data information, in case it has been changed.
field.names	An array that contains the fields of the table. Note: the number of elements in this array is equal to the number.of.fields returned by function aud.get.number.of.fields .
Return values

AUD_INCORRECT_SELECTION_ID	Selection.id is invalid
AUD_INCORRECT_TABLE_ID	Table.id is invalid
AUD_OK	Names of all fields can be determined
Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


aud.get.field.ids

Syntax

long	aud.get.field.ids(long selection.id, long table.id, long number.of.fields, const string field.names(,), ref long field.ids())

Description

Aud.get.next.action stores the contents of the action row internally: old value, new value and status of each field. To retrieve this information, the application needs to have a reference for each field. These references are called field ids. Only when the meta data is changed do the field ids change, so only in such a case does this function have to be used. This function also enables the user to filter only those fields that are relevant to the application by means of a field.names array. This array contains the field names for which an id has to be retrieved.

Restrictions

The aud.get.next.action must be run before this function. This function returns the table.id for which the new meta data needs to be retrieved. Note that it is not necessary (although not forbidden) to run aud.get.field.ids if the aud.get.next.action did not indicate that the meta data has changed.

Arguments

selection.id	Id of the selection, as provided by aud.select.transactions
table.id	Id of the table on which the action occurred, which is used to retrieve the detailed action data using function aud.get.field.status , aud.put.old.field.value and aud.put.new.field.value . This id is also used to get the meta data information, in case it has been changed.
number.of.fields	The number of fields specified in the field.names array.
field.names	An array that contains one or more fields of the table.
field.ids	An array that contains an index for each field in the field.names array. If the field is not in the audit trail data, the index is 0. These ids can be used in function aud.get.field.info , aud.get.field.status, aud.put.old.field.value and aud.put.new.field.value.
Return values

AUD_INCORRECT_SELECTION_ID	Selection.id is invalid:
AUD_INCORRECT_TABLE_ID	Table.id is invalid
AUD_OK	The meta data information was retrieved successfully. Note: if one or more field.ids are 0, this function will still return.
AUD_FAIL	The meta data information could not be found.
Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


aud.get.field.info

Syntax

void	aud.get.field.info(long selection.id, long table.id, long field.id, ref long field.depht, ref long field.type, ref long field.length)

Description

Returns the format of the field at the time it was audited. The information consists of the type, the depth and the size of the field. This function will not check the input, because of performance reasons. Instead the combination selection.id, table.id, field.id is assumed to refer to an existing field, as returned by aud.get.field.ids. This means that if the input parameters are not valid, an error message will be presented to the end user.

Restrictions

It is assumed that the field.id is retrieved using function aud.get.field.ids and has a valid value (greater than 0). So this is not checked in the function.

Arguments

selection.id	Id of the selection, as provided by aud.select.transactions.
table.id	Id of the table on which the action occurred, which is used to retrieve the detailed action data using the functions aud.get.field.status , aud.put.old.field.value and aud.put.new.field.value . This id is also used to get the meta data information, in case it has been changed.
field.id	Identifier for a field, as retrieved using the functions aud.get.field.ids or aud.get.field.list . Precondition: field.id should not be 0: for not existing fields no field information can be retrieved.
field.depth	Depth of the field: • 1 for non-array fields • > 1 for array fields
field.type	Data type of the field, for example db.long, db.double, db.string, db.multibyte and so on.
field.length	Length of the field in the action row string. The field.length specifies the number of characters to be extracted from the old value or the new value string.
Return values

None

Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


aud.get.field.status

Syntax

string	aud.get.field.status(long selection.id, long table.id, long field.id)

Description

Retrieves the status of a field in a database action (insert, update or delete).

The status can be one of the following values:

X	Not available (insert, update or delete) This either means the field does not exist, or it was not logged because this was specified in the data model, or (in case of an update) it was not logged because it has not changed
Y (changed)	Depending on Action Type: old value available (delete), new value available (insert), both old and new value available, value has changed (update)
N (not changed)	Value has not changed, yet both old and new values are available (update).
The following table shows the status in all cases that might occur:

Action Type	Field in Audit DD	Field Changed	Field Logged	Status
I	Yes	Yes	Yes	Y
I	No	-	-	X
D	Yes	Yes	Yes	Y
D	No	-	-	X
U	Yes	Yes	Yes	Y
U	Yes	No	Yes	N
U	Yes	No	No	X
U	No	-	-	X
Restrictions

This function will not check the input, because of performance reasons. Instead the combination of selection.id, table.id, field.id is assumed to refer to an existing field, as returned by aud.get.field.ids. This means that if the arguments are not valid, an error message will be presented to the end user.

During the last aud.get.next.action for this selection, an action.type must have been returned that is ‘I’, ‘U’ or ‘D’. If the action is a table operation (‘C’, ‘L’ or ‘R’) the status of a field has no meaning and therefore this function cannot be used.

Arguments

selection.id	Id of the selection, as provided by aud.select.transactions
table.id	Id of the table on which the action occurred, which is used to retrieve the detailed action data using function aud.get.field.status , aud.put.old.field.value and aud.put.new.field.value . This id is also used to get the meta data information, in case it has been changed.
field.id	Identifier for a field, as retrieved using function aud.get.field.ids. Note: if field.id = 0 (the field does not exist) status “X” is returned.
Return values

See description.

Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


aud.put.old.field.value(), aud.put.new.field.value()

Syntax

•	void  aud.put.old.field.value(long pid, string variable.name, long selection.id, long table.id, long field.id, long element [, bool endian] )

•	void  aud.put.new.field.value(long pid, string variable.name, long selection.id, long table.id, long field.id, long element [, bool endian] )

Description

Use aud.put.old.field.value (and aud.put.new.field.value) to retrieve the value of a field from the old (new) value string. The retrieved value is put into the variable supplied by the application.

If the action is a table operation the old value and new value have no meaning and therefore this function cannot be used in that case. Depending on the status of a field the old value and/or new value can be retrieved.

Insert row	The value part of the action row contains all the field values of the inserted row. This part is copied to the new.value string.
Delete row	The value part of the action row contains all the field values of the deleted row. This part is copied to the new.value string.
Update row	The value part of the action row contains both old and new values but not for all fields. Only those fields that have been changed or are part of the key or specified in the audit_set file are stored in the action row. Unchanged field entries in the action row consist of only two parts: the status that is ‘N’, meaning unchanged, and the old value. Changed field entries in the action row consist of three parts: the status which is ‘Y’, meaning that the field has changed, and both old value and new value. The function reads each field entry in the action row and, depending on the status, copies the values to the old.value or the new.value string. If the field is unchanged, the status string will have an ‘N’ for this field entry otherwise an ‘Y’.

The following table shows whether the functions can be used, depending on action type and status:

Action Type	Status	Field in OldValues	Field in  NewValues
I	Y	No	Yes
I	X	No	No
D	Y	Yes	No
D	X	No	No
U	Y	Yes	Yes
U	N	Yes	Yes
U	X	No	No
U	X	No	No
Restrictions

This function will not check the input, because of performance reasons. Instead the combination selection.id, table.id, field.id is assumed to refer to an existing field, as returned by aud.get.field.ids. This means that if the input parameters are not valid, an error message will be presented to the end user.

During the last aud.get.next.action for this selection, an action.type must have been returned that is ‘I’, ‘U’ or ‘D’. The last execution of aud.get.field.status for this action must have indicated a status <> “X”.

The combination of action.type and status for the field must be one of the following:

•	for aud.put.old.field.values: Status <> “X” and (action.type = “U” or action.type = “D”)

•	for aud.put.new.field.values: Status <> “X” and (action.type = “I” or action.type = “U”)

In all other cases the value of a field has no meaning and therefore this function cannot be used in those cases.

Arguments

pid	Id of the current process. This must be filled in the same manner as the BaanERP function put.var().
variable.name	The name of the variable that will contain the extracted field value.
selection.id	Id of the selection, as provided by aud.select.transactions
table.id	Id of the table on which the action occurred, which is used to retrieve the detailed action data using function aud.get.field.status, aud.put.old.field.value and aud.put.new.field.value. This id is also used to get the meta data information, in case it has been changed.company: the company that holds the updated table.
field.id	Identification of the field as retrieved using function aud.get.field.ids. Precondition: field.id must not be 0: for not existing fields no field information can be retrieved.  Precondition for aud.put.old.field.value: (action.type = ‘D’ and FieldStatus = ‘A’) or (action.type = ‘U’ and FieldStatus = (‘Y’ or ‘N’)).  Precondition for aud.put.new.field.value: (action.type = ‘I’   and FieldStatus = ‘A’) or (action.type = ‘U’ and FieldStatus = (‘Y’ or ‘N’)).
element	The value requested. For function aud.put.old.field.value this is the value of the field directly before the database action (‘before image’). For function aud.put.new.field.value this is the value of the field directly after the database action (‘after image’).
endian	Defines how the data in element must be interpreted. It is assumed that data is stored in big endian order (highest byte first) . If little endian order is required set this optional argument to 1.
Return values

None

Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


aud.close.selection

Syntax

long	aud.close.selection(long selection.id)

Description

The opening of the audit trail is not done explicitly in comparison to the low-level audit library functions. To close the opened files again, the developer must use the aud.close.selection. During the invocation of aud.select.transactions and all functions beginning with aud.get.next, each file that is opened but not closed will be registered within the BaanERP Audit Management. The function aud.close.selection will use this information to close the files that are registered as being open. The function also closes the selection of transactions that have been created using the aud.select.transactions function.

State

The internal state on the selection.id is removed, so after running this function selection.id cannot be used anymore.

Restrictions

The function aud.select.transactions has to be called prior to this function. After executing aud.close.selection, the selection.id cannot be used anymore in any other BaanERP Audit Management functions.

Arguments

selection.id	Id of the selection, as provided by aud.select.transactions .
Return values

AUD_OK	All files are closed successfully and the dynamic SQL selection is also closed successfully
AUD_INCORRECT_SELECTION_ID	Selection.id is not valid.
AUD_FAIL	Not all files could be closed or the dynamic SQL statement is not closed successfully.
Related Help topics

BaanERP Audit Management: overview

BaanERP Audit Management: synopsis

BaanERP Audit Management: examples


Byte arrays: overview

There are two types of byte arrays:

•	Fixed Byte Arrays (FBA)

•	Variable Byte Arrays (VBA)

Fixed Byte Arrays

This type of array has a fixed size, and memory must be allocated by the application developer.

ims.openfba()

Variable Byte Arrays

This type of array has a variable size that can grow as the program script runs. The growth is in a fixed number of bytes that can be set by the application developer. The memory allocation is done by the Bshell.

ims.openvba()

Related help topics

Byte arrays: synopsis


Byte arrays: synopsis

long	ims.clearerr	(long bytearray)
long	ims.eof	(long bytearray)
long	ims.error	(long bytearray)
long	ims.close	(long bytearray)
long	ims.rewind	(long bytearray)
long	ims.tell	(long bytearray)
long	ims.read	(ref string buffer(1024), long nrBytes, long bytearray)
long	ims.write	(string buffer(1024), long nrBytes, long bytearray)
string	ims.getc$	(long bytearray)
string	ims.putc$	(string char, long bytearray)
long	ims.skip	(long nrbytes, long bytearray)
long	ims.seek	(long offset, long opt, long bytearray)
long	ims.gets	(ref string line(80), long size, long opt, long bytearray, [long skip.mode, long there.was.more])
long	ims.puts	(string line, long bytearray)
long	ims.r.long	(long bytearray)
long	ims.w.long	(long value, long bytearray)
long	ims.r.short	(long bytearray)
long	ims.w.short	(long value, long bytearray)
long	ims.spool.line	(ref string line(), long bytearray)
long	ims.openfba	(string buffer, long size, string type(2))
long	ims.openvba	(string type, [long initialSize, long increment])
long	ims.getproperties	(long bytearray, ref string buffer(), [ref long size])
long	ims.setvbaproperties	(long bytearray, long increment)
Related help topics

Byte arrays: overview


ims.clearerr()

Syntax

long	ims.clearerr(long bytearray)

Description

Resets the error and end-of-byte-array indicator.

Arguments

bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearray is not a valid stream

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.eof()

Syntax

long	ims.eof(long bytearray)

Description

Detects if the end of the byte array is reached.

Arguments

bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearray is not a valid stream

0	Not at the end of the byte array

>0	The end of the byte array is detected

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.error()

Syntax

long	ims.error(long bytearray)

Description

Detects if an error has occurred while reading from or writing to the byte array.

Arguments

bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearray is not a valid stream

0	No errors

>0	An error occurred

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.close()

Syntax

long	ims.close(long bytearray)

Description

Closes the byte array. This is done automaticallly when you leave your process.

For a variable byte array (VBA), the claimed memory will be freed.

For a fixed byte array (FBA), the used memory buffer has to be freed manually (or is freed automatically when you leave your process).

Arguments

bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearray is not a valid stream

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.rewind()

Syntax

long	ims.rewind(long bytearray)

Description

Sets the position in byte array to the beginning.

Same as ims.seek(0, 0, bytearray).

Arguments

bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.tell()

Syntax

long	ims.tell(long bytearray)

Description

Returns the current offset within the byte array relative to the begin of the byte array.

Arguments

byetarray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream

>=0	Offset, in number of bytes, within the byte array

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.read()

Syntax

long	ims.read(ref string buffer(1024), long nrBytes, long bytearray)

Description

Reads a number of bytes from the byte array into a buffer.

Arguments

buffer	The buffer that stores the bytes read from the byte array.
nrBytes	The number of bytes to read from the byte array into the buffer.
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream

0	End-of-byte-array

>0	Number of bytes actually read.

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.write()

Syntax

long	ims.write(string buffer(1024), long nrBytes, long bytearray)

Description

Appends a given number of bytes from the buffer into the byte array, beginning at the current position in the byte array.

Arguments

buffer	The buffer that contains the bytes to write into the byte array relative to the current position in the byte array.
nrBytes	The number of bytes to write from the buffer into the byte array.
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream

0	End-of-byte-array

>0	Number of bytes actually written.

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.getc$()

Syntax

string	ims.getc$(long bytearray)

Description

Returns the next character from the byte array.

Arguments

bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

If an empty string is returned, an error has occurred.

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.putc$()

Syntax

string	ims.putc$(string char, long bytearray)

Description

Writes a character to the current position in the byte array.

Arguments

char	The character to write to the byte array.
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

If no error occurs, the written character is returned. Otherwise, an empty string is returned.

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.skip()

Syntax

long	ims.skip(long nrbytes, long bytearray)

Description

Skips forward a number of bytes in the byte array.

Restrictions

Can only be used in read mode.

Arguments

nrbytes	The number of bytes to skip in the byte array
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.seek()

Syntax

long	ims.seek(long offset, long opt, long bytearray)

Description

Changes the current position within the byte array.

Arguments

offset	The number of bytes
opt	Can be set to the following values: 0 New position is set offset bytes from the beginning of the bytearray. 1 New position is set offset bytes from the current position. 2 New position is set offset bytes from the end of the bytearray.
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream

>=0	New offset position from beginning of the byte array

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.gets()

Syntax

long	ims.gets(ref string line(80), long size, long opt, long bytearray, [long skip.mode, long there.was.more])

Description

Reads characters from the byte array into a buffer (line).

Arguments

line	Stores the retrieved characters.
size	The maximum number of bytes to be read. Note that the function stops retrieving characters when a new line character is read or when the end-of-file is reached.  The maximum number of characters that can be read is 2048 bytes.
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
skip.mode	If skip.mode is set to: 0: read until a new-line character 1: read until size or until end-of-byte-array is reached.
there.was.more	There are more characters in the byte array than there were read.
Return values

-1	Error, most probably bytearrray is not a valid stream or end-of-file was already reached.

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.puts()

Syntax

long	ims.puts(string line, long bytearray)

Description

Writes a line (and a new-line character) to the byte array.

Arguments

line	The line to write to the byte array.
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream.

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.r.long()

Syntax

long	ims.r.long(long bytearray)

Description

Reads a long value from the byte array.

Arguments

bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream, or end-of-byte-array reached.

>=0	Value read from byte array.

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.w.long()

Syntax

long	ims.w.long(long value, long bytearray)

Description

Writes a value of data type long into the byte array.

Arguments

value	The value to write into the byte array.
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream.

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.r.short()

Syntax

long	ims.r.short(long bytearray)

Description

Reads a short value from the byte array.

Arguments

bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearray is not a valid stream, or end-of-byte-array reached.

>=0	Value read from byte array.

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.w.short()

Syntax

long	ims.w.short(long value, long bytearray)

Description

Writes a value of data type short into the byte array.

Arguments

value	The value to write into the byte array
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream.

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.spool.line()

Syntax

long	ims.spool.line(ref string line(), long bytearray)

Description

Spools a line and writes it to the byte array. The characters in the line are copied to the byte array until the last non-white character in the line is encountered. After that, the contents of the line is cleared.

Arguments

line	The line to spool to the byte array.
bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
Return values

-1	Error, most probably bytearrray is not a valid stream or the byte array is full.

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.openfba()

Syntax

long	ims.openfba(string buffer, long size, string type(2))

Description

Opens a Fixed Byte Array (FBA).

The following code fragment shows an example of how to create an FBA:

string	buffer(1)	based

long	size

long	stream.id

size = 1024

alloc.mem(buffer, size)

stream.id = ims.openFBA(buffer, size, "rw")

Important

Do not reallocate buffer when it is already in use by an FBA. This will cause the Bshell to crash. In the code above, do not call an alloc.mem(buffer, newSize) after the FBA has been opened.

Arguments

buffer	Stores the byte array. It may already contain information before the start of this function.
size	Size of the buffer.
type	The mode in which the byte array must be opened. This can be one of the following options: • "r":  Open for reading. The current position is placed at the start of the byte array. • "w": Open for writing. The byte array is created if it does not already exist. The current position is placed at the start of the byte array. • "a": Open for writing. The byte array is created if it does not already exist. The current position is placed at the end of the byte array. • "x": Open for writing. This is the same as "w", except that the function fails if the byte array already exists.  • "r+": Same as "r", but it can also be written to. • "w+": Same as "w", but it can also be read.  • "a+": Same as "a", but it can also be read. • "x+": Same as "x", but it can also be read.
Return values

-1	Error, most probably bytearrray is not a valid stream or the byte array is full.

>0	Ims.openfba succeeded, a byte array identifier was returned.

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.openvba()

Syntax

long	ims.openvba(string type, [long initialSize, long increment])

Description

Opens a Variable Byte Array (VBA).

Arguments

type	The mode in which the byte array must be opened. This can be one of the following options: • "r":  Open for reading. The current position is placed at the start of the byte array. • "w": Open for writing. The byte array is created if it does not already exist. The current position is placed at the start of the byte array. • "a": Open for writing. The byte array is created if it does not already exist. The current position is placed at the end of the byte array. • "x": Open for writing. This is the same as "w", except that the function fails if the byte array already exists.  • "r+": Same as "r", but it can also be written to. • "w+": Same as "w", but it can also be read.  • "a+": Same as "a", but it can also be read. • "x+": Same as "x", but it can also be read.
initialSize	The initial buffer size for the VBA. If not specified, the initial buffer size is 4096 bytes.
increment	Specifies the number of bytes to increment the VBA with, in case the VBA is full. If not specified, the buffer will be doubled in size.
Return values

-1	Error, most probably bytearrray is not a valid stream or the byte array is full.

>0	Ims.openvba succeeded, a byte array identifier was returned.

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.getproperties()

Syntax

long	ims.getproperties(long bytearray, ref string buffer(), [ref long size])

Description

Returns the properties of the byte array.

Arguments

bytearray	The byte array identifier that is returned by ims.openvba or ims.openfba.
buffer	The contents of the byte array
size	The number of bytes in the byte array, if specified.
Return values

-1	Error, most probably bytearrray is not a valid stream

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


ims.setvbaproperties()

Syntax

long	ims.setvbaproperties(long bytearray, long increment)

Description

Sets the properties of the Variable Byte Array (VBA).

Arguments

bytearray	The byte array identifier that is returned by ims.openvba.
increment	The number of bytes to increase the VBA with when needed.
Return values

-1	Error, most probably bytearrray is not a variable byte array

0	Success

Context

3GL function

Related help topics

Byte arrays: overview

Byte arrays: synopsis


Baan eMessage Connector:
overview

The Baan eMessage Connector provides a developer with a set of functions that can be used in application scripts to enable:

•	A Baan user to send a message (email, fax, SMS, telex) with the help of a mail client(e.g. Microsoft Outlook, Lotus Notes or other MAPI compliant mail clients).

•	A Baan Application to send a message without any user assistance.

•	A Baan Application to process an incoming message without any user assistance. The environment should enable processing of incoming EDI style messages.

The Baan eMessage Connector is defined between a Baan messaging-enabled application and one or more providers. A provider is a third party software package or another Baan Virtual Machine that can process messages. The Baan eMessage Connector environment  is depicted in the figure shown above.

The Baan eMessage Connector relies on the following Baan products:

•	Baan Virtual Machine (Bshell)

•	Baan User Interfaces (BW and BI).

•	Baan 4GL Development tools

The Baan eMessage Connector has a relationship with the underlying provider. Examples of providers which could be supported are:

•	Fenestrae Faxination for Baan

•	Microsoft Exchange

•	SMTP  based provider

•	Lotus Notes

•	IBM MQSeries

The Baan eMessage Connector has a relationship with external messaging clients. Examples of external messaging clients are:

•	Microsoft Outlook

•	Lotus Notes client

•	DEM workflow modeler

Architecture

Component descriptions

4GL Process

The 4GL process represents any Baan 4GL process which needs to communicate with another process which is not located in the same Baan Virtual Machine (BVM). This external process can be another Baan process running on a separate BVM or third party messaging based software (eg. Microsoft Outlook). This 4GL process can be sending messages to an external process, processing incoming messages or both.

Baan eMessage Connector DLL

The Baan eMessage Connector DLL is a 4GL DLL which can be used by any Baan process to create, send and receive message objects. Baan processes wishing to use the Baan eMessage Connector must utilize this DLL. The DLL contains functions for the creation, examination and transport of message objects. The Baan eMessage Connector DLL accesses the Baan eMessage Connector Repository to determine the available message types and connectors to handle those message types. When a Baan process wishes to send a message, the Baan eMessage Connector DLL examines the repository to determine the appropriate connector needed to handle the message and starts it.

This dll can be linked to a script by adding the following line:

#include <bic_cmf>

Baan eMessage Connector

The Baan eMessage Connector connector acts as the intermediary between the 4GL process and the provider. When started it examines the Baan eMessage Connector Repository to determine how to connect to the external provider and establishes a connection. From then on it handles the transport of the message objects between the 4GL process and the external provider. It also performs message logging. All messages passing through the connector are logged to the Baan eMessage Connector Repository log table and the individual message parts are stored in the file system. This ensures traceability. The storage of message objects as files is also important for Baan 4GL applications. The Baan 4GL does not allow the allocation of large memory areas for processing BLOBs (Binary Large Objects) and other large objects. The message log therefore allows the Baan applications to digest these large files in smaller chunks (by reading them from the file system in small pieces).

Baan eMessage Connector Repository

The repository stores several types of information about the Baan eMessage Connector environment.

•	Baan eMessage Connector services which are supported (email, fax, EDI, SMS, Baan, etc)

•	Message types supported per service (SMTP, SMS, fax, telex, etc)

•	Baan eMessage Connector Service providers (Fenestrae, Microsoft Exchange, Lotus Notes, etc)

•	Message Logs

Outbound Message Handling

A number of steps must be executed in order for a Baan process to send a message to a provider. First, the Baan process creates the message using the Baan eMessage Connector DLL functions. Next the Baan process instructs the Baan eMessage Connector DLL to send the message using a particular service. A Baan eMessage Connector Service is associated with a connector which provides the actual service. The Baan eMessage Connector DLL accesses the Baan eMessage Connector repository to determine the appropriate connector to be used to process the message object. This connector is then started and the message object passed to it. The connector accesses the Baan eMessage Connector repository to determine the appropriate parameters to be used to connect to the provider. Connection is established to the provider and the message sent. The appropriate message logging is also performed.

Inbound Message Handling

Inbound message handling involves invoking the appropriate connector and having it wait for messages with a particular address. The startup parameters specify the messages the connector should handle. The connector is always started by a 4GL message enabled application. Command line invocation can be achieved by using the 4GL application as a parameter to the bshell on startup. Incoming messages are sent via BMS to the 4GL process which started the connector. The connector can also be started in inbound message handling mode from a currently running BVM.  It is not necessary (but seems more practical) to start it from the OS command line.

Note: Inbound message handling is not yet implemented, except for notifications (i.e. is the message delivered or not)

Related Help topics

Synopsis

Examples


Baan eMessage Connector:
synopsis

Functions are categorized into the following:

Message object general functions

Message object identification functions

Message object delivery settings functions

Message object recipient functions

Message object attachment functions

Task object functions

Appointment object functions

Miscellaneous

Baan eMessage Connector API extensions for the Address Book

Message object general functions

long	cmf.create	( )
long	cmf.destroy	(long mid)
long	cmf.send	(long mid, string service(15))
long	cmf.receive	(ref long mid, domain ttcmf.prov service, long block)
long	cmf.startService	(string service(15), long mode, [string address(13)])
long	cmf.stopService	(string service(15), long mode)
long	cmf.addObjectToMessage	(long oid, long mid, string class(100))
Message object identification functions

long	cmf.setClass	(long mid, string class)
long	cmf.getClass	(long mid, ref string class)
long	cmf.setMessageId	(long mid, string messageId)
long	cmf.getMessageId	(long mid, ref string messageId)
long	cmf.getCreateTime	(long mid, ref domain ttutc createtime)
long	cmf.setSubject	(long mid, string subject)
long	cmf.getSubject	(long mid, ref string subject)
long	cmf.setTemplate	(long mid, string template)
long	cmf.getTemplate	(long mid, ref string template)
long	cmf.setChargeCode	(long mid, string chargecode)
long	cmf.getChargeCode	(long mid, ref string chargecode)
long	cmf.setCategories	(long mid, string categories)
long	cmf.getCategories	(long mid, ref string categories)
Message object delivery functions

long	cmf.setPriority	(long mid, enum priority)
long	cmf.getPriority	(long mid, ref enum priority)
long	cmf.setSensitivity	(long mid, enum sensitivity)
long	cmf.getSensitivity	(long mid, ref enum sensitivity)
long	cmf.setStartTime	(long mid, domain ttutc starttime)
long	cmf.getStartTime	(long mid, ref domain ttutc starttime)
long	cmf.setExpiry	(long mid, domain ttutc expiry)
long	cmf.getExpiry	(long mid, ref domain ttutc expiry)
long	cmf.setNotification	(long mid, enum notification)
long	cmf.getNotification	(long mid, ref enum notification)
long	cmf.setDisplay	(long mid, enum display)
long	cmf.getDisplay	(long mid, ref enum display)
Message object recipient functions

long	cmf.createRecipient	(long mid, enum role)
long	cmf.getNextRecipient	(long mid, ref enum role, long previous)
long	cmf.destroyRecipient	(long recipient)
long	cmf.setRecipientName	(long recipient, string name)
long	cmf.getRecipientName	(long recipient, ref string name)
long	cmf.setRecipientAddress	(long recipient, string address)
long	cmf.getRecipientAddress	(long recipient, ref string address)
long	cmf.setRecipientType	(long recipient, string type)
long	cmf.getRecipientType	(long recipient, ref string type)
long	cmf.setRecipientResponsibility	(long recipient, string responsibility)
long	cmf.getRecipientResponsibility	(long recipient, ref string responsibility)
long	cmf.setRecipientReasoncode	(long recipient, long reasoncode)
long	cmf.getRecipientReasoncode	(long recipient, ref long reasoncode)
long	cmf.setRecipientReasonstring	(long recipient, string reasonstring(100))
long	cmf.getRecipientReasonstring	(long recipient, ref string reasonstring)
Message object attachment functions

long	cmf.createAttachment	(long mid)
long	cmf.getNextAttachment	(long mid, long previous)
long	cmf.destroyAttachment	(long attachment)
long	cmf.copyAttachment	(long attachment.id, oid)
long	cmf.setAttachmentBody	(long attachment, enum body)
long	cmf.getAttachmentBody	(long attachment, enum ttyeno body)
long	cmf.setAttachmentMIME	(long attachment, string mime)
long	cmf.getAttachmentMime	(long attachment, ref string mime)
long	cmf.setAttachmentFilename	(long attachment, string filename [, string displayname])
long	cmf.getAttachmentFilename	(long attachment, ref string filename, ref string displayname)
long	cmf.setAttachmentPosition	(long attachment, string position(10))
long	cmf.getAttachmentPosition	(long attachment, ref string position)
Task object functions

long	cmf.createTask	( )
long	cmf.destroyTask	(long tid)
long	cmf.setTaskSubject	(long tid, string subject)
long	cmf.getTaskSubject	(long tid, ref string subject)
long	cmf.setTaskPriority	(long tid, enum priority)
long	cmf.getTaskPriority	(long tid, ref enum priority)
long	cmf.setTaskStartdate	(long tid, domain ttutc startdate)
long	cmf.getTaskStartdate	(long tid, ref domain ttutc startdate)
long	cmf.setTaskDuedate	(long tid, domain ttutc duedate)
long	cmf.getTaskDuedate	(long tid, ref domain ttutc duedate)
long	cmf.setTaskReminderTime	(long tid, domain ttutc remindertime)
long	cmf.getTaskReminderTime	(long tid, ref domain ttutc remindertime)
long	cmf.setTaskTotalwork	(long tid, string totalwork)
long	cmf.getTaskTotalwork	(long tid, ref string totalwork)
Appointment object functions

long	cmf.createAppointment	( )
long	cmf.destroyAppointment	(long apid)
long	cmf.setAppointmentSubject	(long apid, string subject)
long	cmf.getAppointmentSubject	(long apid, ref string subject)
long	cmf.setAppointmentMeeting	(long apid, enum meeting)
long	cmf.getAppointmentMeeting	(long apid, ref enum meeting)
long	cmf.setAppointmentAlldayevent	(long apid, enum alldayevent)
long	cmf.getAppointmentAlldayevent	(long apid, ref enum alldayevent)
long	cmf.setAppointmentStarttime	(long apid, domain ttutc starttime)
long	cmf.getAppointmentStarttime	(long apid, ref domain ttutc starttime)
long	cmf.setAppointmentEndtime	(long apid, domain ttutc endtime)
long	cmf.getAppointmentEndtime	(long apid, ref domain ttutc endtime)
long	cmf.setAppointmentAlarm	(long apid, domain ttutc alarm)
long	cmf.getAppointmentAlarm	(long apid, ref domain ttutc alarm)
long	cmf.setAppointmentBusystatus	(long apid, enum busystatus)
long	cmf.getAppointmentBusystatus	(long apid, ref string busystatus)
long	cmf.setAppointmentLocation	(long apid, string location)
long	cmf.getAppointmentLocation	(long apid, ref string location)
Miscellaneous

long	cmf.messageDialog	(long mode, long show, [long show.message])
long	cmf.getId	(domain ttcmf.cmes messageId, string service, domain ttcmf.mdir message.direction, ref string error_string())
long	cmf.isServiceEnabled	(domain ttcmf.prov service)
long	cmf.enableService	(domain ttcmf.prov service, long enable)
long	cmf.resolveAddress	(ref domain ttcmf.catg category, ref domain ttcmf.catg key, ref domain ttcmf.defa addresstype, ref string address(), ref string message.str, [string name(100) mb, long use.default])
Address List Object Functions

long	cmf.createAddressList	()
long	cmf.addAddressEntry	(long aid, string role, string name, string address, string addresstype, [domain ttcmf.catg key, domain ttcmf.catg category])
long	cmf.getNextAddress	(long aid, long previous)
long	cmf.getAddressDetails	(long entry_id, ref string category, ref string key, ref string role, ref string name, ref string address, ref string addresstype, ref long errorcode)
long	cmf.getAddressBookKey	(long entry.id,  ref string key,  ref string category)
long	cmf.updateAddressStatus	(long entry_id, long errorcode)
long	cmf.destroyAddressEntry	(long entry_id)
long	cmf.getService	(enum addresstype, enum user_interaction, enum resolve, ref string service)
long	cmf.sendToPerson	(long mid, long aid, long display, long show.progress, ref string message_string() [,long convert, string filename1, string filename2, …])
void	cmf.stopAllServices	()
Related Help topics

Overview

Examples


Baan eMessage Connector:
examples

You can choose of the following examples:

How to use the Baan eMessage Connector API to construct and send a message

How to use function cmf.sendToPerson

How to use the message dialog

Tip: Maximize the help window for a good view of the examples.

How to use the eMessage Connector API to construct and send a message

In this example function cmf.send is used to send the message. The main difference with cmf.sendToPerson (see next section for an example) is that when using cmf.send only the message id is suplied as an argument, while cmf.sendToPerson needs both a message- and an addresslist id. This means cmf.send sends the message to the recipients in the message object, while cmf.sendToPerson sends the message to the recipients in the addresslist object.

|******************************************************************************

|* CMF Sample Code

|******************************************************************************

|* Script Type: 0

|******************************************************************************

dllusage

Desc:	This code sample demonstrates the use of some of the Baan eMessage Connector commands

described in the CMF 4GL Functional Design. It accepts a filename (which points to an RTF

document), Baan eMessage Connector service name, recipient name and recipient address

 (SMTP only) as input arguments. It then uses the Baan eMessage Connector commands to

construct a message then send it to the indicated recipients.

Pre:	None.

Post:	The file is sent to the appropriate Baan eMessage Connector service.

In:	The four program arguments accepted are:

sourcefile:	The name of the file (RTF format) to be sent.

service:	This is the name of the service that will be used to send the message.

This must be name of a valid Baan eMessage Connector service

name:	This is the (human readable) name of the recipient.

address:	This the address where the file should be sent. This could be an email address,

a fax number, etc.

Out:	None.

enddllusage

string recipient.address(80)	|Recipient address

string recipient.name(80)	|Human readable name of the recipient

string sourcefile(256)	|Filename of the source file

function main()

{

domain ttcmf.prov service	|Baan eMessage Connector service for transporting messages

long stat	|Variable to hold return values

long mid	|CMF message id

|Switch to company 0

compnr.check(0)

|Get program arguments

sourcefile = strip$(argv$(1))

service = strip$(argv$(2))

recipient.name = strip$(argv$(3))

recipient.address = strip$(argv$(4))

|Build message XML header

mid = create.xml.header()

|Send message

if mid <>0 then

stat = cmf.startService(service,2)

if stat<>0 then

message("Message could not be sent (Baan eMessage Connector service did not start)")

exit()

endif

stat = cmf.send(mid,service)

if stat<>0 then

message("Message could not be sent (Baan eMessage Connector service refused message)")

cmf.stopService(service,2)

exit()

endif

stat = cmf.stopService(service,2)

endif

}

function long create.xml.header()

{

long 	message.ID

long	from.ID

long 	to.ID

long	attachment.ID

long 	ret

message.ID = cmf.create()

ret = cmf.setClass(message.ID, "CMF.NOTE")

ret = cmf.setSubject(message.ID, "Sample CMF Message")

|Set FROM recipient

from.ID = cmf.createRecipient(message.ID, ttcmf.role.from)

ret = cmf.setRecipientName(from.ID, "John Doe")

ret = cmf.setRecipientAddress(from.ID,"jdoe@baan.com")

ret = cmf.setRecipientType(from.ID, "SMTP")

|In reality of course the from address could be filled from the

|Address book.

|Set TO recipient

to.ID = cmf.createRecipient(message.ID, ttcmf.role.to)

ret = cmf.setRecipientName(to.ID, recipient.name)

ret = cmf.setRecipientAddress(to.ID, recipient.address)

ret = cmf.setRecipientType(to.ID, "SMTP")

ret = cmf.setRecipientResponsibility(to.ID, "TRUE")

|Set attachment

attachment.ID = cmf.createAttachment(message.ID)

ret = cmf.setAttachmentBody(attachment.ID, "TRUE")

ret = cmf.setAttachmentMIME(attachment.ID, "application/rtf")

ret = cmf.setAttachmentFileName(attachment.ID,sourcefile,

"Sample Attachment")

return(message.ID)

}

How to use function cmf.sendToPerson

Use cmf.sendToPerson if the same message has to be send to multiple recipients and when using the Message Dialog to construct message- and addresslist objects. As arguments a message-id of a message object and an addresslist-id of an addresslist object (among others) have to be supplied. Cmf.sendToPerson delivers the message to all recipients on the addresslist. Message- and addresslist objects can be constructed in two ways:

1.	With user interface: use the Message Dialog. Using this session the user can determine some message characteristics and construct an addresslist. After exiting the Message Dialog, the id’s of the message- and addresslist objects are available in the variables cmf.MessageObject and cmf.AddressList (defined in global include file bic_global).

1.	Without user interface: use the eMessage Connector API to build a message- and addresslist object (see example in section 10.1). But watch out: using cmf.sendToPerson the message will solely be delivered to recipients in the addresslist object. Any recipients in the message object will NOT be reached.

|******************************************************************************

|* Example of usage of cmf.sendToPerson

|******************************************************************************

|* Script Type: 0

|******************************************************************************

table	tttcmf200	|Address Book

table	tttaad200	|User Data

#include "ittadv0001"

function main()

{

set.compnr.0()

sendMessage()

}

function sendMessage()

{

long	ret	|return value of various functions

long	show.progress	|if true, progress indicator will be

|shown to user. If false, no indicator

|is shown

string 	message.str(250)	|success or error message set by

|cmf.sendToPerson.

string	addresstype(30)	|string representation of message type

|used to send message

string	role.str(6)	|string representaton of role of

|recipient

string	address(80) mb	|address of recipient

domain	ttaad.user user	|key of table ttaad200 User Data

domain	ttcmf.catg catg	|category of a recipient in Address Book

|(for example: BAAN USER, EMPLOYEE etc.)

domain	ttcmf.catg akey	|key of recipient: must uniquely

|identify entry in Address Book within

|a category

domain	ttcmf.role role	|role of a recipient (from/to etc.)

show.progress	= 0

message.str	= ""

addresstype	= ""

catg	= ""

akey	= ""

role.str	= ""

user	= ""

role 	= empty

|create message- and addresslist objects

cmf.MessageObject = cmf.create()

cmf.AddressList = cmf.createAddressList()

      |fill addresslist with data from Address Book: first select baan users

      |from User Data table (ttaad200), then select for each user their

      |address data from the Address Book (ttcmf200). Then add user as entry

      |to the addressslist object

      |NOTE: in this example only one user is selected from the User Data

      |table. Also, role of recipient is always "to".

      |NOTE: in this example the default addresstype is used to resolve the

      |address.

      role = ttcmf.role.to

      user = "skalma"

select ttaad200.user

from ttaad200

where ttaad200._index1 = {:user}

as set with 1 rows

selectdo

catg = "BAAN USER"

akey = toupper$(strip$(ttaad200.user))

select ttcmf200.*

from ttcmf200

where ttcmf200._index1 = {:catg, :akey}

as set with 1 rows

selectdo

ret = convert.enum.to.string.role(	role,

role.str)

|ttdllcmf

ret = convert.enum.to.string.addresstype(ttcmf200.defa,

ttcmf200.type,

addresstype)

|ttdllcmf

ret = cmf.resolveAddress(	catg,

akey,

ttcmf200.defa,

address,

ttcmf200.name,

true)

|ttdllcmf

ret = cmf.addAddressEntry(	cmf.AddressList,

role.str,	|role

ttcmf200.name,	|name

ttcmf200.mail,	|address

addresstype)	|message type

|ttdllcmf

endselect

endselect

|set identification attributes

ret = cmf.setClass(cmf.MessageObject, "CMF.NOTE")

ret = cmf.setSubject(cmf.MessageObject, "Message to” & strip$(ttcmf200.name))

|set delivery attributes

ret = cmf.setPriority(cmf.MessageObject, ttcmf.prio.high)

ret = cmf.setSensitivity(cmf.MessageObject, ttcmf.sens.secret)

ret = cmf.setNotification(cmf.MessageObject, ttcmf.noti.nondelivery)

|set cmf.ShowMessage: indicates whether cmf.sendToPerson must try to start up a user

     	|interface based service (for example Outlook) to send this message: 1 means yes, 0

     	|means no.

     	cmf.ShowMessage = 1

     	|set show.progress to false: no indicator shown to user

     	show.progress = false

|send message

ret = cmf.sendToPerson(	cmf.MessageObject,

cmf.AddressList,

cmf.ShowMessage,

show.progress,

message.str)

|show message.str

if not isspace(message.str) then

if ret < 0 then

mess("ttcmf01303", 1, message.str)

|* %s (warning)

else

mess("ttstpsplclose2", 1, message.str)

|* %s (information)

endif

endif

|stop all started services that were started by cmf.sendToPerson

cmf.stopAllServices()

|destroy objects

ret = cmf.destroy(cmf.MessageObject)

ret = cmf.destroy(cmf.AddressList)

}

How to use the message dialog

Here one report is created and send to multiple recipients using cmf.sendToPerson. The message dialog is used to construct the message and addresslist objects.

|******************************************************************************

|* Send Same Report to Multiple Recipients

|******************************************************************************

|* Script Type: 0

|******************************************************************************

|tables

table	tttadv002	| Baan Tools Parameters

table	tttaad100	| Companies

table	tttaad110	| Languages

table	tttaad120	| Packages

table	tttaad200	| User Data

table	tttadv111	| Package VRC's

table	tttadv360	| Menus

table	tttams200	| Role Data

table	tttaad121	| Package Combinations Packages

|includes

#include "ittadv0001"   |compnr. and last-used functions

|defines

#define	OK	0

#define	NOT.FOUND	1

#define	EXPIRED 	2

function main()

{

|form variables

extern	domain	ttaad.user	user.f  fixed	|on form: from Baan user

extern	domain	ttaad.user	user.t  fixed	|on form: to Baan user

extern	domain	ttdsca	pacc.desc	|package combination

|description

extern	domain	ttdsca	comp.desc	|company description

extern	domain	ttdsca	lang.desc	|language description

extern	domain	ttdesc60	stmn.desc

extern	domain	ttdsca	role.desc	|role description

extern	domain	ttams.crol	role	|role of user

|report variable

extern	domain	ttst30 docu.id	|used to determine which parts of report

|will be written to the report file

set.compnr.0()

send.user.data()

}

function send.user.data()

{

long	ret	|return vales of various functions

long	brp_id	|id of report

domain	ttdesc200 message.str	|contains error message. set by

|cmf.sendToPerson

ret	= 0

brp_id	= 0

message.str	= ""

|open spooler and activate report without user interface

spool.fileout = "${BSE}/tmp/user_data_report"

brp_id = brp.open("rttams140111000", "ASCIF", 0)

on case brp_id

case 0:

|Error in opening report

return

case -1:

|Printing cancelled

return

endcase

|user.f and user.t normally set on form

user.f	= "gmurre"

user.t	= "gmurre"

| data in range is send to opened report

select ttaad200.user

from ttaad200

where ttaad200.user inrange :user.f and :user.t

selectdo

| send User

docu.id = "user"

brp.ready(brp_id)

| send system-data

docu.id = "sysd.header"

brp.ready(brp_id)

systemdata.to.report( ttaad200.user, brp_id)

docu.id = "sysd.footer"

brp.ready(brp_id)

| send defaults

docu.id = "def.header"

brp.ready(brp_id)

defaults.to.report( ttaad200.user, brp_id)

docu.id = "def.footer"

brp.ready(brp_id)

| send authorizations

docu.id = "auth.header"

brp.ready(brp_id)

auth.to.report( ttaad200.user, brp_id)

docu.id = "auth.footer"

brp.ready(brp_id)

| send empty line

docu.id = "empty"

brp.ready(brp_id)

endselect

| stops report writer for the report

brp.close(brp_id)

|activate Message Dialog with only Message Formtab: user can set some

|message characteristics and construct a recipient list

ret = cmf.messageDialog(2, CMF.MESSAGE)

on case ret

case -1:

|error launcing Message Dialog

return

case -2:

|invalid argument values

return

endcase

|send message: after Message Dialog is closed, message object- and

|addresslist object id's are available in variables cmf.MessageObject

|and cmf.AddressList. Also, the user can determine if a user interface

|based service has to be started by checking the checkbox 'Show Message

|before Sending (if possible)'. If checked, cmf.ShowMessage will be 1,

|else 0.

ret = cmf.sendToPerson(	cmf.MessageObject, cmf.AddressList,

cmf.ShowMessage, true, message.str, true,

spool.fileout)

|display message

if not isspace(message.str) then

if ret < 0 then

|error message

mess("ttcmf01303", 1, message.str)

|* %s (warning)

else

|succes message

mess("ttstpsplclose2", 1, message.str)

|* %s (information)

endif

endif

|stop all the services started up by cmf.sendToPerson

cmf.stopAllServices()

|delete xml-objects

if cmf.MessageObject <> 0 then

ret = xml.deleteNode(cmf.MessageObject)

endif

if cmf.AddressList <> 0 then

ret = xml.deleteNode(cmf.AddressList)

endif

}

Related Help topics

Overview

Synopsis

Examples


cmf.create( )

Synopsis

long cmf.create( )

Description

Creates a new Baan eMessage Connector message object.

Arguments

None.

Return

<>0	(Bshell wide) unique Baan eMessage Connector message object id.

0	Message object creation error.

Related Help topics

Overview

Synopsis

Examples


cmf.destroy()

Synopsis

long cmf.destroy(long mid)

Description

Destroys the Baan eMessage Connector message object identified by mid.

Arguments

mid	Message object identification.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.send()

Synopsis

long cmf.send(long mid, string service(15))

Description

Sends the Baan eMessage Connector message object identified by mid using the service specified by service. The message class is set to the service name.

Arguments

mid	Message object identification.
service(15)	Service offered by a provider, for example, Fax or Email.
Return

0	Success.

-1	Error sending message

-2	Service not started

Related Help topics

Overview

Synopsis

Examples


cmf.receive()

Synopsis

long cmf.receive(ref long mid, domain ttcmf.prov service, long block)

Description

Receives a Baan eMessage Connector message object and returns the object id in mid. The appropriate connector must have been previously started prior to calling this function using cmf.startService() .

Arguments

mid	Message object identification.
service	Service offered by a provider, for example, Fax or Email.
block	Flag indicating whether cmf.receive will wait for a message  (blocking) or simply return if there is no message waiting  (nonblocking).
Return

0	Success

-1	Error receiving message

-2	Service not started

Related Help topics

Overview

Synopsis

Examples


cmf.startService()

Synopsis

long cmf.startService(string service(15), long mode, [string address(13)])

Description

Starts the Baan eMessage Connector service.

Arguments

service	The service offered by a provider, for example, Fax or Email.
mode	Message direction in respect to the BVM: 1=inbound 2=outbound
address(13)	Alternate name to the default that the connector uses to connect to the external service. The default format of the address is : <sessioncode>.<company-nr>@<HOSTNAME>. The argument address replaces the session code in the address e.g. <address>.000@SATURN.
Return

0	Success.

-1	Service not present

-2	Service could not be started.

-3	Service not enabled

Related Help topics

Overview

Synopsis

Examples


cmf.stopService()

Synopsis

long cmf.stopService(string service(15), long mode)

Description

Stops the currently running Baan eMessage Connector service named service which is running in mode mode.

Arguments

service	The service offered by a provider, for example, Fax or  e-mail.
mode	Message direction in respect to the BVM: 1=inbound 2=outbound
Return

0	Success.

-1	No service running

-2	Service could not be stopped normally

Related Help topics

Overview

Synopsis

Examples


cmf.addObjectToMessage()

Synopsis

long cmf.addObjectToMessage(long oid, long mid, string class(100))

Description

The object identified by oid is added to the message object identified by mid. The class of this message is set to the string class (mandatory attribute for a message: for example CMF.TASK for tasks, CMF.APPOINTMENT for appointments and so on). The object is written to a temporary file with extension .xml, which is placed in the current working directory. This file is added as an attachment to the message object. The body attribute of this attachment is set to true, the mimetype is set to application/xml and the delete attribute is set to true. All attachments currently attached to the task are also attached to the message object. Finally the object identified by oid is deleted (because changes in this object are not reflected anymore in the message object).

Note: If an error is returned, the object identified by oid is not deleted

Arguments

oid	Object identification.
mid	Message object identification.
class(100)	Mandatory attribute for a message: for example CMF.TASK for tasks, CMF.APPOINTMENT for appointments and so on. For more information see cmf.setClass .
Return

0	Success.

-1	General error (check logfiles)

-2	Oid or mid are not valid xml object id's

-3	Class argument empty

-4	Object could not be written to file

Related Help topics

Overview

Synopsis

Examples


cmf.setClass()

Synopsis

long cmf.setClass(long mid, string class)

Description

Sets the message class of the message identified by mid to the value class.

Arguments

mid	Message object identification.
class	Mandatory attribute for a message, identifying the meaning of a message: for example CMF.TASK for tasks, CMF.APPOINTMENT for appointments and so on.
CLASS	Description
CMF.NOTE	Common note message
CMF.NOTE.EMAIL	E-mail message message
CMF.NOTE.FAX	Fax message
CMF.NOTE.TELEX	Telex message
CMF.NOTE.SMS	SMS message
CMF.NOTE.SITA	SITA message
CMF.TASK	TASK message, task specific information is in the attachment.
CMF.APPOINTMENT	APPOINTMENT message, appointment specific information is in the attachment.
Return

0	Success

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getClass()

Synopsis

long cmf.getClass(long mid, ref string class)

Description

Gets the message class of the message identified by mid and returns string into class.

Arguments

mid	Message object identification.
class	Mandatory attribute for a message, identifying the meaning of a message: for example CMF.TASK for tasks, CMF.APPOINTMENT for appointments and so on.
Return

0	Success.

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.setMessageId()

Synopsis

long cmf.setMessageId(long mid, string messageId)

Description

Sets the message ID of the message identified by mid and returns string into messageId. The messageId is a string that uniquely identifies a message within Baan eMessage Connector. The application using Baan eMessage Connector need not to call this function as Baan eMessage Connector will take care of this automatically.

Arguments

mid	Message object identification.
messageId	The unique message id of the message in the Baan system.  It corresponds to the directory name where the serialized message components are stored. The message id is a 40 character string max. The first 10 characters represent the UTC date and time (number of seconds since Jan 1, 1970 converted to a string) followed by a “.”.  The next five characters represent the bshell pid (mod 99999) followed by a “.”.  The next three characters represent the Bshell process id (mod 999) followed by a “.”.  The next three characters represent a counter in case of multiple transactions per second (max 999) followed by a “.”. The last characters represent the first few characters of the machine’s hostname.
Return

0	Success.

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.getMessageId()

Synopsis

long cmf.getMessageId(long mid, ref string messageId)

Description

Gets the message id of the message identified by mid and return string into messageId.

Arguments

mid	Message object identification.
messageId	Unique identification of a message within Baan eMessage Connector.
Return

0	Success.

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.getCreateTime()

Synopsis

long cmf.getCreateTime(long mid, ref domain ttutc createtime)

Description

Gets the message creation time of the message identified by mid and returns it into utc date createtime.

Arguments

mid	Message object identification.
createtime	UTC date the message was created.
Return

0	Success.

-1	Error (most likely invalid object id or element not present).

-2 	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.setSubject()

Synopsis

long cmf.setSubject(long mid, string subject)

Description

Sets the message subject line of the message identified by mid to the value subject. This is a mandatory property for a Baan eMessage Connector message.

Arguments

mid	Message object identification.
subject	Message subject line.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getSubject()

Synopsis

long cmf.getSubject(long mid, ref string subject)

Description

Gets the message subject of the message identified by mid and return string into subject.

Arguments

mid	Message object identification.
subject	Message subject line.
Return

0	Success

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.setTemplate()

Synopsis

long cmf.setTemplate(long mid, string template)

Description

Sets the message template identification of the message identified by mid to the value template.

Arguments

mid	Message object identification.
template	Message template identification.
Return

0	Success

-1	 	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getTemplate()

Synopsis

long cmf.getTemplate(long mid, ref string template)

Description

Gets the message template of the message identified by mid and return string into template.

Arguments

mid	Message object identification.
template	Message template identification.
Return

0	Success

-1	Error (most likely invalid object id or element not present)

Related Help topics

Overview

Synopsis

Examples


cmf.setChargeCode()

Synopsis

long cmf.setChargeCode(long mid, string chargecode)

Description

Sets the message charge code of the message identified by mid to the value chargecode. Chargecodes are used to determine who will be charged for sending/receiving this message.

Arguments

mid	Message object identification.
chargecode	Message charge code.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getChargeCode()

Synopsis

long cmf.getChargeCode(long mid, ref string chargecode)

Description

Gets the message charge code of the message identified by mid and returns string into chargecode.

Arguments

mid	Message object identification.
chargecode	Message charge code.
Return

0	Success.

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.setCategories()

Synopsis

long cmf.setCategories(long mid, string categories)

Description

Sets the categories of the message identified by mid to the value categories. Categories are supplied in a comma delimited list.  Mail clients such as Microsoft Outlook make use of categories and all categories used in Outlook can be used here.

Arguments

mid	Message object identification.
categories	Message category.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getCategories()

Synopsis

long cmf.getCategories(long mid, ref string categories)

Description

Gets the categories of the message identified by mid and returns string into categories.

Arguments

mid	Message object identification.
categories	Message category.
Return

0	Success.

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.setPriority()

Synopsis

long cmf.setPriority(long mid, enum priority)

Description

Sets the priority of the message identified by mid to the value priority.

Arguments

mid	Message object identification.
priority	Message priority. “LOW” | “NORMAL” | “HIGH”
Return

0	Success.

-1	Invalid cmf object.

Related Help topics

Overview

Synopsis

Examples


cmf.getPriority()

Synopsis

long cmf.getPriority(long mid, ref enum priority)

Description

Gets the priority of the message identified by mid and returns it in the enum priority.

Arguments

mid	Message object identification.
priority	Message priority. “LOW” | “NORMAL” | “HIGH”
Return

0	Success.

-1	Invalid cmf object or element not present.

Related Help topics

Overview

Synopsis

Examples


cmf.setSensitivity()

Synopsis

long cmf.setSensitivity(long mid, enum sensitivity)

Description

Sets the sensitivity of the message identified by mid to the value sensitivity.

Arguments

mid	Message object identification.
sensitivity	Message sensitivity. “NORMAL” | “PERSONAL” | “PRIVATE” | “CONFIDENTIAL” | “SECRET”
Return

0	Success

-1	Invalid cmf object.

Related Help topics

Overview

Synopsis

Examples


cmf.getSensitivity()

Synopsis

long cmf.getSensitivity((long mid, ref enum sensitivity)

Description

Gets the sensitivity of the message identified by mid and returns it in the enum sensitivity.

Arguments

mid	Message object identification.
sensitivity	Message sensitivity. “NORMAL” | “PERSONAL” | “PRIVATE” | “CONFIDENTIAL” | “SECRET”
Return

0	Success.

-1	Invalid cmf object or element not present.

Related Help topics

Overview

Synopsis

Examples


cmf.setStartTime()

Synopsis

long cmf.setStartTime(long mid, domain ttutc starttime)

Description

Sets the delivery start time of the message identified by mid to the value starttime.

Arguments

mid	Message object identification.
starttime	Start time when the message must be delivered.
Return

0	Success

-1	Invalid cmf object

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.getStartTime()

Synopsis

long cmf.getStartTime(long mid, ref domain ttutc starttime)

Description

Gets the delivery start time of the message identified by mid and return in the utc date starttime.

Arguments

mid	Message object identification.
starttime	Start time when the message must be delivered.
Return

0	Success

-1	Invalid cmf object or element not present.

Related Help topics

Overview

Synopsis

Examples


cmf.setExpiry()

Synopsis

long cmf.setExpiry(long mid, domain ttutc expiry)

Description

Sets the expiry time of the message identified by mid to the value expiry.

Arguments

mid	Message object identification.
expiry	Message expiry time.
Return

0	Success

-1	Invalid cmf object

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.getExpiry()

Synopsis

long cmf.getExpiry(long mid, ref domain ttutc expiry)

Description

Gets the expiry time of the message identified by mid and returns it in the utc date expiry.

Arguments

mid	Message object identification.
expiry	Message expiry time.
Return

0	Success

-1	Invalid cmf object or element not present.

Related Help topics

Overview

Synopsis

Examples


cmf.setNotification()

Synopsis

long cmf.setNotification(long mid, enum notification)

Description

Sets the notification required of the message identified by mid to the value notification.

Arguments

mid	Message object identification.
notification	Message notification.  “ALWAYS” | “DELIVERY” | “NON-DELIVERY” | “NEVER”
Return

0	Success

-1	Invalid cmf object

Related Help topics

Overview

Synopsis

Examples


cmf.getNotification()

Synopsis

long cmf.getNotification(long mid, ref enum notification)

Description

Gets the notification required of the message identified by mid and returns it in the enum notification.

Arguments

mid	Message object identification.
notification	Message notification.  “ALWAYS” | “DELIVERY” | “NON-DELIVERY” | “NEVER”
Return

0	Success

1	Invalid cmf object

Related Help topics

Overview

Synopsis

Examples


cmf.setDisplay()

Synopsis

long cmf.setDisplay(long mid, enum display)

Description

Sets the display option of this message identified by mid to the value display.

Arguments

mid	Message object identification.
display	"TRUE": message will be shown before sending it. User interface based service will be started. "FALSE": message will be send without showing it first. UI-based and non ui-based service(s) can be started
Return

0	Success

-1	Invalid cmf object

Related Help topics

Overview

Synopsis

Examples


cmf.getDisplay()

Synopsis

long cmf.getDisplay(long mid, ref enum display)

Description

Gets the display option of this message identified by mid and put it in the variable display.

Arguments

mid	Message object identification.
display	"TRUE": message shows before sending. User interface based service will be started. "FALSE": message is send without showing it first. UI-based and non ui-based service(s) can be started
Return

0	Success

-1	Invalid cmf object

Related Help topics

Overview

Synopsis

Examples


cmf.createRecipient()

Synopsis

long cmf.createRecipient(long mid, enum role)

Description

Creates a recipient entry of type role in the message identified by mid and returns the identification of the recipient object.

Arguments

mid	Message object identification.
role	The recipient's role: “FROM” | “TO” | “CC” | “BCC” | “OBO” | “NOTIFY”
Return

<>0	Recipient Id

=0	Invalid object id

Related Help topics

Overview

Synopsis

Examples


cmf.getNextRecipient()

Synopsis

long cmf.getNextRecipient(long mid, ref enum role, long previous)

Description

Retrieves the recipient entry in the message identified by the combination of role and the id of the previous recipient listed in the XML document. It returns the id of the recipient object. If previous is 0 (zero), the id of the first recipient listed in the XML document is returned.

Arguments

mid	Message object identification.
role	The recipient's role: “FROM” | “TO” | “CC” | “BCC” | “OBO” | “NOTIFY”
Return

<>0	Recipient Id

=0	No (next) recipient found or invalid object id.

Related Help topics

Overview

Synopsis

Examples


cmf.destroyRecipient()

Synopsis

long cmf.destroyRecipient(long recipient)

Description

Destroys the recipient identified by recipient.

Arguments

recipient	The recipient identification that must be removed from the recipient list.
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.setRecipientName()

Synopsis

long cmf.setRecipientName(long recipient, string name)

Description

Sets the (human-readable) name of the recipient identified by recipient to the value name.

Arguments

recipient	The recipient identification.
name	The name of the recipient.
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.getRecipientName()

Synopsis

long cmf.getRecipientName(long recipient, ref string name)

Description

Gets the name of the recipient identified by recipient and returns it in the string name.

Arguments

recipient	The recipient identification.
name	The name of the recipient.
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.setRecipientAddress()

Synopsis

long cmf.setRecipientAddress(long recipient, string address)

Description

Sets the address of the recipient identified by recipient to the value address.  An address could be a fax number, SMTP address, SMS number, and so on)

Arguments

recipient	The recipient identification.
address	The address of the recipient.
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.getRecipientAddress()

Synopsis

long cmf.getRecipientAddress(long recipient, ref string address)

Description

Gets the address of the recipient identified by recipient and returns it in the string address.

Arguments

recipient	The recipient identification.
address	The address of the recipient.
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.setRecipientType()

Synopsis

long cmf.setRecipientType(long recipient, string type)

Description

Sets the type of the recipient identified by recipient to the value type. The listed types are only examples and new types can be introduced at any time.

Arguments

recipient	The recipient identification.
type	The type of the recipient: “FAX” | “TELEX” | “SMTP” | “SMS “ | “SITA” | “BAAN” | …
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.getRecipientType()

Synopsis

long cmf.getRecipientType(long recipient, ref string type)

Description

Gets the type of the recipient identified by recipient and returns it in the string type.

Arguments

recipient	The recipient identification.
type	The type of the recipient: “FAX” | “TELEX” | “SMTP” | “SMS “ | “SITA” | “BAAN” | …
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.setRecipientResponsibility()

Synopsis

long cmf.setRecipientResponsibility(long recipient, string responsibility)

Description

Sets the responsibility of the recipient identified by recipient to the value responsibility.

Arguments

recipient	The recipient identification.
responsibility	The responsibility of the recipient: “TRUE” | “FALSE”
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.getRecipientResponsibility()

Synopsis

long cmf.getRecipientResponsibility(long recipient, ref string responsibility)

Description

Gets the responsibility of the recipient identified by recipient and returns it in the string responsibility.

Arguments

recipient	The recipient identification.
responsibility	The responsibility of the recipient: “TRUE” | “FALSE”
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.setRecipientReasoncode()

Synopsis

long cmf.setRecipientReasoncode(long recipient, long reasoncode)

Description

Sets the reason code of the recipient identified by recipient to the value reasoncode. The reason code is used only in case of a non-delivery of a message to a recipient.

Arguments

recipient	The recipient identification.
reasoncode	The code of the reason why the message could not be delivered.
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.getRecipientReasoncode()

Synopsis

long cmf.getRecipientReasoncode(long recipient, ref long reasoncode)

Description

Gets the reason code of the recipient identified by recipient and returns it in the string reasoncode.

Arguments

recipient	The recipient identification.
reasoncode	The code of the reason why the message could not be delivered.
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.setRecipientReasonstring()

Synopsis

long cmf.setRecipientReasonstring(long recipient, string reasonstring(100))

Description

Sets the (human-readable) reason string of the recipient identified by recipient to the value reasonstring. The reason string is used only in case of a non-delivery of a message to a recipient.

Arguments

recipient	The recipient identification.
reasonstring	The description of the reason  why the message could not be delivered.
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.getRecipientReasonstring()

Synopsis

long cmf.getRecipientReasonstring(long recipient, ref string reasonstring)

Description

Gets the reason string of the recipient identified by recipient and returns it in the string reasonstring.

Arguments

recipient	The recipient identification.
reasonstring	The description of the reason  why the message could not be delivered.
Return

0	Success

-1	Invalid recipient id

Related Help topics

Overview

Synopsis

Examples


cmf.createAttachment()

Synopsis

long cmf.createAttachment(long mid)

Description

Creates an attachment entry in the message identified by mid and returns the identification of the attachment.

Arguments

mid	Message object identification.
Return

<>0	Attachment Identification

=0	Attachment could not be created (most likely invalid cmf object)

Related Help topics

Overview

Synopsis

Examples


cmf.getNextAttachment()

Synopsis

long cmf.getNextAttachment(long mid, long previous)

Description

Gets an attachment entry in the message identified by mid and returns the identification of the attachment. If previous is 0 (no valid object id), then the first attachment is returned.  If previous is a valid object id (not 0) then the attachment id of the attachment that follows the attachment identified by previous is returned.  Subsequent calls to this function return succeeding attachments. The current attachment pointer can be reset by setting previous to 0 again.

Arguments

mid	Message object identification.
previous	The identification of the attachment. If previous is 0 (no valid object id), then the first attachment is returned.  If previous is a valid object id (not 0) then the attachment id of the attachment that follows the attachment identified by previous is returned.
Return

<>0	Attachment Identification

=0	Attachment could not be found (most likely end of attachment list)

Related Help topics

Overview

Synopsis

Examples


cmf.destroyAttachment()

Synopsis

long cmf.destroyAttachment(long attachment)

Description

Destroys the attachment identified by attachment.  Any files associated with the attachment are not removed.

Arguments

attachment	The attachment identification.
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.copyAttachment()

Synopsis

long cmf.copyAttachment(long attachment.id, oid)

Description

Copies the attachment identified by attachment.id from the object identified by id1 to the object identified by id2. All attributes and their values are also copied

Arguments

attachment.id	Identification of the source attachment.
oid	Identification of the destination attachment.
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.setAttachmentBody()

Synopsis

long cmf.setAttachmentBody(long attachment, enum body)

Description

Sets the type of the attachment identified by attachment to the value body. If body is “YES”, then the attachment is considered to be the bodytext.  Only one body attachment is allowed for each message object, although this is NOT enforced by the Baan eMessage Connector.

Arguments

attachment	The attachment identification.
body	Is attachment the bodytext: "YES" | "NO" Only one attachment for each message can be the body.
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.getAttachmentBody()

Synopsis

long cmf.getAttachmentBody(long attachment, enum ttyeno body)

Description

Gets the type of the attachment identified by attachment and returns it in the enum body.

Arguments

attachment	The attachment identification.
body	Is attachment the bodytext: "YES" | "NO" Only one attachment for each message can be the body.
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.setAttachmentMIME()

Synopsis

long cmf.setAttachmentMIME(long attachment, string mime)

Description

Sets the mime type of the attachment identified by attachment to the value mime.

Arguments

attachment	The attachment identification.
mime	The mime type: “image/tiff “ | “text/rtf” | “text/plain” | …
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.getAttachmentMime()

Synopsis

long cmf.getAttachmentMime(long attachment, ref string mime)

Description

Gets the mime type of the attachment identified by attachment and returns it in the string mime.

Arguments

attachment	The attachment identification.
mime	The mime type: “image/tiff “ | “text/rtf” | “text/plain” | …
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.setAttachmentFilename()

Synopsis

long cmf.setAttachmentFilename(long attachment, string filename [, string displayname])

Description

Sets the physical filename of the attachment identified by attachment to the value filename.  Sets the human-readable filename to displayname.  If displayname is not supplied, then the readable filename is set to the physical filename.

Arguments

attachment	The attachment identification.
filename	The physical filename.
displayname	The name of the file that is displayed. If displayname is not supplied, then the physical filename is used.
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.getAttachmentFilename()

Synopsis

long cmf.getAttachmentFilename(long attachment, ref string filename, ref string displayname)

Description

Gets the filename and display name of the attachment identified by attachment and return them in the strings  filename and displayname.

Arguments

attachment	The attachment identification.
filename	The physical filename.
displayname	The name of the file that is displayed. If displayname is not supplied, then the physical filename is used.
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.setAttachmentPosition()

Synopsis

long cmf.setAttachmentPosition (long attachment, string position(10))

Description

Sets the position of the attachment identified as attachment to the value position. Position determines the number of characters (of the bodytext) after which the attachment-icon will be placed. By default the attachment-icon is positioned at the end of the bodytext.

Arguments

attachment	The attachment identification.
position(10)	The attachment position determines the number of characters (of the bodytext) after which the attachment-icon will be placed.
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.getAttachmentPosition()

Synopsis

long cmf.getAttachmentPosition(long attachment, ref string position)

Description

Gets the position of the attachment identified by attachment and returns it in the string position.

Arguments

attachment	The attachment identification.
position(10)	The attachment position determines the number of characters (of the bodytext) after which the attachment-icon will be placed.
Return

0	Success

-1	Invalid attachment identification

Related Help topics

Overview

Synopsis

Examples


cmf.createTask( )

Synopsis

long cmf.createTask( )

Description

Creates a new Baan eMessage Connector task object.

Arguments

None.

Return

<>0	 (Bshell wide) unique Baan eMessage Connector task object id.

=0 	Task object creation error.

Related Help topics

Overview

Synopsis

Examples


cmf.destroyTask()

Synopsis

long cmf.destroyTask(long tid)

Description

Destroys the Baan eMessage Connector task object identified by tid.

Arguments

tid	The Baan eMessage Connector task object identification.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.setTaskSubject()

Synopsis

long cmf.setTaskSubject(long tid, string subject)

Description

Sets the task subject of the task identified by tid to the value subject. This is a mandatory property for a Baan eMessage Connector task.

Arguments

tid	The Baan eMessage Connector task object identification.
subject	The task subject.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getTaskSubject()

Synopsis

long cmf.getTaskSubject(long tid, ref string subject)

Description

Gets the task subject of the task identified by tid and return string into subject.

Arguments

tid	The Baan eMessage Connector task object identification.
subject	The task subject.
Return

0	Success

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.setTaskPriority()

Synopsis

long cmf.setTaskPriority(long tid, enum priority)

Description

Sets the task priority of the task identified by tid to the value priority. This is a mandatory property for a Baan eMessage Connector task.

Arguments

tid	The Baan eMessage Connector task object identification.
priority	The task priority: "LOW" | "NORMAL" | "HIGH"
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getTaskPriority()

Synopsis

long cmf.getTaskPriority(long tid, ref enum priority)

Description

Gets the task priority of the task identified by tid and returns string into priority.

Arguments

tid	The Baan eMessage Connector task object identification.
priority	The task priority: "LOW" | "NORMAL" | "HIGH"
Return

0	Success

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.setTaskStartdate()

Synopsis

long cmf.setTaskStartdate(long tid, domain ttutc startdate)

Description

Sets the task startdate of the task identified by tid to the value startdate.

Arguments

tid	The Baan eMessage Connector task object identification.
startdate	Start date of the task.
Return

0	Success

-1	Invalid cmf object

-2	Invalid value for startdate

Related Help topics

Overview

Synopsis

Examples


cmf.getTaskStartdate()

Synopsis

long cmf.getTaskStartdate(long tid, ref domain ttutc startdate)

Description

Gets the task startdate of the task identified by tid and returns it in the string startdate.

Arguments

tid	The Baan eMessage Connector task object identification.
startdate	Start date of the task.
Return

0	Success

-1	Invalid cmf object or element not present.

-2	date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.setTaskDuedate()

Synopsis

long cmf.setTaskDuedate(long tid, domain ttutc duedate)

Description

Sets the task duedate of the task identified by tid to the value duedate.

Arguments

tid	The Baan eMessage Connector task object identification.
duedate	The date by which the task must be finished.
Return

0	Success

-1	Invalid cmf object

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.getTaskDuedate()

Synopsis

long cmf.getTaskDuedate(long tid, ref domain ttutc duedate)

Description

Gets the task duedate of the task identified by tid and return it in the utc date duedate.

Arguments

tid	The Baan eMessage Connector task object identification.
duedate	The date by which the task must be finished.
Return

0	Success

-1	Invalid cmf object or element not present.

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.setTaskReminderTime()

Synopsis

long cmf.setTaskReminderTime(long tid, domain ttutc remindertime)

Description

Sets the task remindertime of the task identified by tid to the value remindertime.

Arguments

tid	The Baan eMessage Connector task object identification.
remindertime	The task reminder time.
Return

0	Success

-1	Invalid cmf object

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.getTaskReminderTime()

Synopsis

long cmf.getTaskReminderTime(long tid, ref domain ttutc remindertime)

Description

Gets the task remindertime of the task identified by tid and returns it in the utc date remindertime.

Arguments

tid	The Baan eMessage Connector task object identification.
remindertime	The task reminder time.
Return

0	Success

-1	Invalid cmf object or element not present.

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.setTaskTotalwork()

Synopsis

long cmf.setTaskTotalwork(long tid, string totalwork)

Description

Sets the task totalwork of the task identified by tid to the value totalwork.

Arguments

tid	The Baan eMessage Connector task object identification.
totalwork	The total work for the task.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getTaskTotalwork()

Synopsis

long cmf.getTaskTotalwork(long tid, ref string totalwork)

Description

Gets the totalwork of the task identified by tid and return string into totalwork.

Arguments

tid	The Baan eMessage Connector task object identification.
totalwork	The total work for the task.
To create a Task Attachment

Use cmf.createAttachment with task id as argument.

To get the next Task Attachment

Use cmf.getNextAttachment

To destroy a Task Attachment

Use cmf.destroyAttachment

To set and get Task Attachment Attributes

To manipulate attributes of task attachments, the regular attachment functions can be used: cmf.set /get AttachmentBody, cmf.set /get AttachmentMime, cmf.set /get AttachmentFilename and cmf.set /get AttachmentPosition.

Return

0	Success

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.createAppointment( )

Synopsis

long cmf.createAppointment( )

Description

Creates a new Baan eMessage Connector appointment object.

Arguments

None.

Return

<>0	 (Bshell wide) unique Baan eMessage Connector appointment object id.

=0 	Appointment object creation error.

Related Help topics

Overview

Synopsis

Examples


cmf.destroyAppointment()

Synopsis

long cmf.destroyAppointment(long apid)

Description

Destroys the Baan eMessage Connector appointment object identified by apid.

Arguments

apid	The appointment identification.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.setAppointmentSubject()

Synopsis

long cmf.setAppointmentSubject(long apid, string subject)

Description

Sets the appointment subject of the appointment identified by apid to the value subject.

Arguments

apid	The appointment identification.
subject	The subject of the appointment.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getAppointmentSubject()

Synopsis

long cmf.getAppointmentSubject(long apid, ref string subject)

Description

Gets the appointment subject of the appointment identified by apid and returns string into subject.

Arguments

apid	The appointment identification.
subject	The subject of the appointment.
Return

0	Success

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.setAppointmentMeeting()

Synopsis

long cmf.setAppointmentMeeting(long apid, enum meeting)

Description

Sets the meeting flag of the appointment identified by apid to the value meeting.

Arguments

apid	The appointment identification.
meeting	Appointment meeting: "YES" | "NO"
Return

0	Success

-1	Invalid cmf object

Related Help topics

Overview

Synopsis

Examples


cmf.getAppointmentMeeting()

Synopsis

long cmf.getAppointmentMeeting(long apid, ref enum meeting)

Description

Gets the meeting flag of the appointment identified by apid and returns it in the string meeting.

Arguments

apid	The appointment identification.
meeting	Appointment meeting: "YES" | "NO"
Return

0	Success

-1	Invalid cmf object or element not present.

Related Help topics

Overview

Synopsis

Examples


cmf.setAppointmentAlldayevent()

Synopsis

long cmf.setAppointmentAlldayevent(long apid, enum alldayevent)

Description

Sets the alldayevent flag of the appointment identified by apid to the value alldayevent.

Arguments

apid	The appointment identification.
alldayevent	All day event appointment: "YES" | "NO"
Return

0	Success

-1	Invalid cmf object

Related Help topics

Overview

Synopsis

Examples


cmf.getAppointmentAlldayevent()

Synopsis

long cmf.getAppointmentAlldayevent(long apid, ref enum alldayevent)

Description

Gets the alldayevent flag of the appointment identified by apid and returns it in the string alldayevent.

Arguments

apid	The appointment identification.
alldayevent	All day event appointment: "YES" | "NO"
Return

0	Success

-1	Invalid cmf object or element not present.

Related Help topics

Overview

Synopsis

Examples


cmf.setAppointmentStarttime()

Synopsis

long cmf.setAppointmentStarttime(long apid, domain ttutc starttime)

Description

Sets the appointment starttime of the appointment identified by apid to the value starttime.

Arguments

apid	The appointment identification.
starttime	The start time of the appointment.
Return

0	Success

-1	Invalid cmf object

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.getAppointmentStarttime()

Synopsis

long cmf.getAppointmentStarttime(long apid, ref domain ttutc starttime)

Description

Gets the starttime of the appointment identified by apid and returns it in the utc date starttime.

Arguments

apid	The appointment identification.
starttime	The start time of the appointment.
Return

0	Success

-1	Invalid cmf object or element not present.

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.setAppointmentEndtime()

Synopsis

long cmf.setAppointmentEndtime(long apid, domain ttutc endtime)

Description

Sets the endtime of the appointment identified by apid to the value endtime.

Arguments

apid	The appointment identification.
endtime	The end time of the appointment.
Return

0	Success

-1	Invalid cmf object

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.getAppointmentEndtime()

Synopsis

long cmf.getAppointmentEndtime(long apid, ref domain ttutc endtime)

Description

Gets the endtime of the appointment identified by apid and returns it in the utc date endtime.

Arguments

apid	The appointment identification.
endtime	The end time of the appointment.
Return

0	Success

-1	Invalid cmf object or element not present.

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.setAppointmentAlarm()

Synopsis

long cmf.setAppointmentAlarm(long apid, domain ttutc alarm)

Description

Sets the alarm of the appointment identified by apid to the value alarm.

Arguments

apid	The appointment identification.
alarm	The alarm time for the appointment.
Return

0	Success

-1	Invalid cmf object

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.getAppointmentAlarm()

Synopsis

long cmf.getAppointmentAlarm(long apid, ref domain ttutc alarm)

Description

Gets the alarm of the appointment identified by apid and returns it in the utc date alarm.

Arguments

apid	The appointment identification.
alarm	The alarm time for the appointment.
Return

0	Success

-1	Invalid cmf object or element not present.

-2	Date conversion error

Related Help topics

Overview

Synopsis

Examples


cmf.setAppointmentBusystatus()

Synopsis

long cmf.setAppointmentBusystatus(long apid, enum busystatus)

Description

Sets the busystatus of the appointment identified by apid to the value busystatus.

Arguments

apid	The appointment identification.
busystatus	The busy status of the appointment. "BUSY" | "FREE" | "OUTOFOFFICE" | "TENTATIVE"
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getAppointmentBusystatus()

Synopsis

long cmf.getAppointmentBusystatus(long apid, ref string busystatus)

Description

Gets the busystatus of the appointment identified by apid and return string into busystatus.

Arguments

apid	The appointment identification.
busystatus	The busy status of the appointment. "BUSY" | "FREE" | "OUTOFOFFICE" | "TENTATIVE"
Return

0	Success

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.setAppointmentLocation()

Synopsis

long cmf.setAppointmentLocation(long apid, string location)

Description

Sets the appointment location of the appointment identified by apid to the value location.

Arguments

apid	The appointment identification.
location	The location of the appointment.
Return

0	Success.

-1	Error (most likely invalid object id).

Related Help topics

Overview

Synopsis

Examples


cmf.getAppointmentLocation()

Synopsis

long cmf.getAppointmentLocation(long apid, ref string location)

Description

Gets the appointment location of the appointment identified by apid and return string into location.

Arguments

apid	The appointment identification.
location	The location of the appointment.
To create an Appointment Attachment

Use cmf.createAttachment with task id as argument.

To get the next Appointment Attachment

Use cmf.getNextAttachment

To destroy an Appointment Attachment

Use cmf.destroyAttachment

To set and get Appointment Attachment Attributes

To manipulate attributes of appointment attachments, the regular attachment functions can be used: cmf.set /get AttachmentBody, cmf.set /get AttachmentMime, cmf.set /get AttachmentFilename and cmf.set /get AttachmentPosition.

Return

0	Success

-1	Error (most likely invalid object id or element not present).

Related Help topics

Overview

Synopsis

Examples


cmf.messageDialog()

Synopsis

long cmf.messageDialog(long mode, long show, [long show.message])

Defined as global variables in include bic_global:

long cmf.MessageObject: contains id of an XML message object

long cmf.AddressList: contains id of an XML address list object

Description

Launches a Message dialog box.

Arguments

mode	The mode argument determines the way the Message dialog box will operate. Possible values: 1. When the continue button is pressed, the message will be sent to the recipients on the address list. 2. When the continue button is pressed, the message- and addresslist objects id's (cmf.MessageObject and cmf.AddressList) are exported to the calling session, which has to take care of sending the message itself using cmf.sendToPerson or option 3. 3. The Message dialog sends the message to the recipients on the address list using cmf.sendToPerson with display argument default set to 0 (no user interface). It then stops all started services and exits immediately (without showing itself to the user).
show	The show argument determines which form-tabs will be shown to the user. Possible values:         • CMF.MESSAGE: only message formtab will be shown • CMF.TASK: only task formtab will be shown • CMF.APPOINTMENT: only appointment formtab will be shown Note: Any combination of the three (for example: CMF.MESSAGE + CMF.TASK) will start up a combination of the selected formtabs.
show.message	If the optional show.message argument is set to 1, cmf.sendToPerson  will start up a user interface based service (if available) for each message type found in the addresslist object.
Return

0	Success

-1	Error launching the Message Dialog

-2 	Error: invalid argument value(s)

Related Help topics

Overview

Synopsis

Examples


cmf.getId()

Synopsis

long cmf.getId(domain ttcmf.cmes messageId, string service, domain ttcmf.mdir message.direction, ref string error_string())

Description

Creates a path to the header.xml file, which consists of the message storage path in the Services (ttcmf030) table and inbox or outbox (depending on message direction) and header.xml. This file is opened in read mode and then parsed with function xml.read which returns the bshell-wide unique object ID of the message object, which is often needed to call other functions in this library.

Arguments

messageld	Unique identification of a message within Baan eMessage Connector.
service	Service offered by a provider, for example, Fax or Email.
message.direction	This is an enumerated field that indicates whether the message was inbound (to the Bshell) or outbound (from the Bshell).  This field also indicates whether the message is stored in the inbox or outbox subdirectories of the message storage directory.  The possible values are: "ttcmf.mdir.inbound|ttcmf.mdir.outbound".
error_string()	Detailed error information.
Return

<> 0	mid = Bshell-wide unique message ID

=  0	mid = no valid object id error_string contains detailed error information

Related Help topics

Overview

Synopsis

Examples


cmf.isServiceEnabled()

Synopsis

long cmf.isServiceEnabled(domain ttcmf.prov service)

Description

Checks in the Services (ttcmf030) table if service	is enabled (ttcmf030.enab = yes) or not.

Arguments

service	The service identification.
Return

1 	true	: service is enabled

0	false	: service is disabled

-1	service not found in table Services (ttcmf030)

Related Help topics

Overview

Synopsis

Examples


cmf.enableService()

Synopsis

long cmf.enableService(domain ttcmf.prov service, long enable)

Description

Checks in the Services (ttcmf030) table if service is enabled (ttcmf030.enab = yes) or not. If not, and enable is true, then service is enabled. If yes, and enable is false, then service is disabled. In the other (two) cases nothing happens.

Arguments

service	The service identification.
enable	Enable service:: "TRUE" | "FALSE"
Return

2	service is enabled

1 	service is disabled

0	nothing changed

-1	service not found in table Services (ttcmf030)

Related Help topics

Overview

Synopsis

Examples


cmf.resolveAddress()

Synopsis

long cmf.resolveAddress(ref domain ttcmf.catg category, ref domain ttcmf.catg key, ref domain ttcmf.defa addresstype, ref string address(), ref string message.str, [string name(100) mb, long use.default])

Description

Selects address data of recipient identified by key and category from Address Book and sets address depending on value of addresstype. Address data is selected from Tools Address Book (table ttcmf200) if current company is 0 and from BaanERP Address Book (table tccom130/131) if current company is not 0.

•	If key and category arguments are  empty, it is possible to search the Tools Address Book using the optional argument name. If more than one record is found, an error is returned. The BaanERP Address Book cannot be searched using just a name. In this case a RECIPIENT_NOT_FOUND (-2) error is returned.

•	If the argument use.default is set to true and addresstype is empty, the address is resolved using the default address type specified in the Address Book. If the addresstype argument is empty and use.default is not set to true, the address is not resolved.

•	If the key and category arguments are both filled and also a name argument is supplied, then it is checked if they match. If they do not match, the category and key arguments are made empty and the Tools Address Book is searched for an entry with name = <name>. If exactly one entry is found the category, key and address argument  are filled with the found values.
Note: the BaanERP Address Book cannot be searched with just a name argument. So in this case a RECIPIENT_NOT_FOUND (-2) error is returned

•	If category is ‘Distribution List’, the function stops immediately after the above check and returns SUCCESS (0). If the category and key arguments are empty and the name argument filled, the Tools Address Book (ttcmf200) is searched to determine if this name represents a distribution list, if so, the key argument is filled with the name of the list (ttcmf210.list) and the category argument is set to ‘Distribution List’.

Arguments

category	Recipient's category.
key	Recipient's key.
addresstype	Recipient type of address (fax, telex, smtp and so on.)
address()	Recipient's actual address depending on the address type.
message.str
name(100)	The name of the recipient.
use.default	If true, the default address type for the recipient is used.
Return

0	succes

-1	error: no address specified for addresstype in Address Book

-2	error: recipient not found in Address Book

-3	error: more than one record found in Address Book

-4	error: dll tcintdlltccom not found on server

-5	error: function tcint.dlltccom.start.addresses not found in dll tcintdlltccom.

-6	error: key field must be filled if category is Business Contact

-7	error: table tccom130 and/or tccom131 not found

-8	error: something went wrong in execution of function tcint.dlltccom.start.addresses in DLL tcintdlltccom

Related Help topics

Overview

Synopsis

Examples


cmf.createAddressList()

Synopsis

long cmf.createAddressList()

Description

Creates an address list object.

Arguments

None.

Return values

<> 0	Id of root-element of address list

=0	Error creating object

Related Help topics

Overview

Synopsis

Examples


cmf.addAddressEntry()

Synopsis

long cmf.addAddressEntry(long aid, string role, string name, string address, string addresstype, [domain ttcmf.catg key, domain ttcmf.catg category])

Description

Creates an address child node in the address list aid. The attributes of the node are provided by the parameters of the function.

Note: If an argument is left empty and the attribute is currently present in the message object, it will be removed completely.

Arguments

aid	Identification of the address list.
role	The recipient role: “FROM” | “TO” | “CC” | “BCC” | “OBO” | “NOTIFY”
name	Recipient name
address	Recipient address
addresstype	Recipient type of address (fax, telex, smtp and so on.)
key, category	The key and the category of the recipient (that make a primary key) to easily find the address entry of this recipient in the address book.
Return

<>0 	Object id of addresslist entry

=0	Error creating entry (most likely invalid address list id)

Related Help topics

Overview

Synopsis

Examples


cmf.getNextAddress()

Synopsis

long  cmf.getNextAddress(long aid, long previous)

Description

Retrieves the next address child element in the address list root element identified by aid. If previous is 0 (zero) the id of the first entry on the addresslist is returned with type element. Else, the entry following the entry identified by previous is returned.

Arguments

aid	Identification of the address list.
previous	Index in the address list.
Return values

<>0	Id of address list child element

0	End of child elements reached or invalid address list id supplied.

Related Help topics

Overview

Synopsis

Examples


cmf.getAddressDetails()

Synopsis

long cmf.getAddressDetails(long entry_id, ref string category, ref string key, ref string role, ref string name, ref string address, ref string addresstype, ref long errorcode)

Description

Retrieves the details of an address entry specified by entry_id. Entry_id is obtained from the function cmf.getNextAddress() or cmf.addAddressEntry() . The attribute values for the object identified by entry_id are copied to the appropriate parameter variables.

Arguments

entry_id	The address list entry identification.
category	The recipient category.
key	The recipient key.
role	The recipient role: “FROM” | “TO” | “CC” | “BCC” | “OBO” | “NOTIFY”
name	The recipient name.
address	The recipient address.
addresstype	The recipient addresstype.
errorcode	See cmf.updateAddressStatus() for the error codes.
Return values

0	Success

-1	Error retrieving details (most probably invalid address entry id)

Related Help topics

Overview

Synopsis

Examples


cmf.getAddressBookKey()

Synopsis

long cmf.getAddressBookKey(long entry.id,  ref string key,  ref string category)

Description

Gets the two key fields of the Address Book (ttcmf200) of the recipient identified by entry.id and returns them in the strings key and category.

Note:

•	With these two values it's very easy to retrieve data from the Address Book about a recipient

•	Category and key are set using cmf.addAddressEntry

Arguments

entry.id	The address list entry identification.
key	The recipient key.
category	The recipient category.
Return values

0	Success

-1	Error retrieving category and key: probably invalid recipient id.

Related Help topics

Overview

Synopsis

Examples


cmf.updateAddressStatus()

Synopsis

long cmf.updateAddressStatus(long entry_id, long errorcode)

Description

Updates the error status of an address entry. Entry_id is obtained from the function cmf.getNextAddress(). The possible values of errorcode are subdivided into two categories: errors which can  also occur when the addresslist object is empty (global error variables used) and errors which only occur when the addresslist object is filled with one or more recipients: then the errorcode of the recipient is set to indicate the nature of the error. Possible values:

Errors indicated by global variables

0	OK	No errors for this recipient
-1	SERVICE_NOT_STARTED	Service could not be started: cmf.startService returned error
-2	SEND_ERROR	Cmf.send returned error
-3	SERVICE_DISABLED	Service for current address type disabled in the Services (ttcmf030) table
Errors indicated by errorcode

-10	ADDRTYPE_NOT_SUPPORTED	Current addresstype not supported by any service.
-11	NO_SITA_SENDER_ADDRESS	From-recipient has no SITA-address in Address Book (ttcmf200), so all recipients with addresstype SITA could not be reached.
-12	MORE_SENDERS_FOUND	More than one from-recipient found. Message not send to all recipients
-13	NO_ADDRESS	No address found or set for this recipient. Message not sent to the intended recipient.
-14	LIST_MEMBER_NOT_ADDED	A member of a distribution list could not be added to the addresslist object.
Arguments

entry_id	The address list entry identification.
errorcode	See tables above.
Return values

0	Success

-1	Error updating entry (most likely invalid address entry id)

Related Help topics

Overview

Synopsis

Examples


cmf.destroyAddressEntry()

Synopsis

long cmf.destroyAddressEntry(long entry_id)

Description

Destroys the address list entry referenced by entry_id.

Arguments

entry_id	The address list entry identification.
Return values

0	Success

-1	Error removing address entry (most probably invalid value for entry_id)

Related Help topics

Overview

Synopsis

Examples


cmf.getService()

Synopsis

long cmf.getService(enum addresstype, enum user_interaction, enum resolve, ref string service)

Description

Returns the name of the service that supports the addresstype specified by the variables addresstype, user_interaction and resolve.  The enum variables use the same enum types as their respective fields in the Baan eMessage Connector Address Types by Service table.

Arguments

addresstype	Specify the Baan eMessage Connector address type, for example, smtp, fax, telex and so on.
user_interaction	Specify if the service must allow user interaction before completion of the message transfer. "YES"|"NO"
resolve	Specify if the service should have resolve capability when given a name and address type.
service	Returns the service identification that supports given parameters.
Return values

0	Success.

-1	No matching service found.  The value of service is undefined in this case.

Related Help topics

Overview

Synopsis

Examples


cmf.sendToPerson()

Synopsis

long cmf.sendToPerson(long mid, long aid, long display, long show.progress, ref string message_string() [,long convert, string filename1, string filename2, …])

Description

Takes the message object and sends it to the recipients in the addresslist object that is identified by aid.

Recipients are separated into groups by address type (fax, SMTP, telex, SITA, and so on). For each group a separate message object is built with the recipients in that group attached to it. The Baan eMessage Connector service for that address type is started and the message sent to it.

If no sender information is available, it will automatically be added. This holds also for the notify recipient (who, for example, gets the delivery reports). Also it's checked that the addresslist object contains only one sender (from-recipient).

Any errors encountered are stored for each recipient in the addresslist object. Baan eMessage Connector services opened by this function are not stopped. This is for efficiency purposes. It is expensive to start and stop services. This allows applications to make multiple calls to cmf.sendToPerson without incurring the overhead of service startup and shutdown. Instead another function will be provided to stop all services opened by this function (cmf.stopAllServices).

Note:

•	Object id's can be negative

•	The calling application is responsible for deleting message and address list object after this function has finished.

Arguments

mid	Message object identification.
aid	Identification of the address list.
display	Display = 1: message will be shown before sending it. User interface based service will be started. Display = 0: message will be sent without showing it first. UI-based and non ui-based service(s) can be started
show.progress	If true, a progress indicator will be shown tracking the progress of the message sending process. If false, no indicator is shown.
message_string()	Constructed error message which contains the number of recipients that could not be reached, and the error details. If no errors, message_string contains a success message
convert	Optional list of arguments: first optional argument in this list is the flag convert; the arguments following this flag are filenames to be converted to the default format specified for the service used to send the message depending on the value of convert. There are three cases: 1 Convert is set to true and there are one or more file arguments specified: the files are converted and added as attachments to the message object.  2 Convert is set to false and there are one or more file arguments specified: the files will be added as attachments to the message object, but they won't be converted.  3 Convert is set to true, but there are no files specified: all attachments found in the message object are converted to the default format of the current service.
filename1 filenamen
Return values

0	Success for all recipients

-1	Failure for some or all recipients (Check recipient list object)

Related Help topics

Overview

Synopsis

Examples


cmf.stopAllServices()

Synopsis

void cmf.stopAllServices()

Description

Stops all Baan eMessage Connector services started by cmf.sendToPerson() .

Arguments

None.

Return values

None.

Related Help topics

Overview

Synopsis

Examples


Generic Browser Framework (GBF):
overview

The Generic Browser Framework (GBF) provides the developer with a set of functions to easily set up a browser for all kinds of purposes. The browser is capable of displaying a parent-child hierarchy and is based upon the menu browser functionality.

The window created and displayed will look like this:

The default size of the whole window is (width × height) 640 × 480 pixels, excluding the title bar and status bar. The minimum width of the window is 300 × 200 pixels. The five labels in the status bar at the bottom will proportionally increase/decrease in size when the whole window is enlarged/shrunken in horizontal direction. For Baan V the status bar will also contain the latched key indicators (CAPS, NUM, SCRL and KANA).

Related Help topics

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


Generic Browser Framework:
synopsis

long	gbf.add.header	(const string object.key(), const string object.description() mb, long object.value)
long	gbf.add.interior	(const string object.key(), const string object.description() mb, long object.value)
long	gbf.add.leaf	(const string object.key(), const string object.description() mb, long object.value)
long	gfb.add.object	(const string object.key(), const string object.description() mb, longobject.value, long obj.type, [long icon.set, long default.function.id, long help.function.id, long drop.function.id, long menumask, long text.color, long line.style, long context.menu.id])
string	gbf.current.library	()
long	gbf.create.context.menu	()
long	gbf.delete.object	(long obj.id)
string	gbf.error.string	(long error)
string	gbf.file.to.library	(const string filename())
long	gbf.get.current.parent	()
long	gbf.get.cutcopy	(long index, ref string obj.key(), ref string obj.desc() mb, ref long obj.value)
long	gbf.get.cutcopy.nr	()
long	gbf.get.description	( long obj.id, ref string description() mb)
long	gbf.get.first.child	( long obj.id, long force.read, ref long child.id, ref string child.key(), ref long child.value, ref long child.type)
long	gbf.get.key.desc.length	(ref long key.length, ref long desc.length)
long	gbf.get.next	( long  obj.id, ref long next.id, ref string next.key(), ref long next.value, ref long next.type)
long	gbf.get.object.info	( long  obj.id, ref string key(), ref string description(), ref long value, ref long type)
long	gbf.get.open.depth	(ref long open.depth)
long	gbf.get.open.strategy	(ref long open.type)
long	gbf.get.parent	( long obj.id, ref long parent.id, ref string parent.key(), ref long parent.value)
long	gbf.get.previous	( long  obj.id, ref long prev.id, ref string prev.key(), ref long prev.value, ref long prev.type)
long	gbf.get.print.options	(ref long print.options)
long	gbf.get.read.levels	( ref long read.levels, [ref long show.levels])
long	gbf.get.refresh.strategy	( ref long refresh.rate, ref long refresh.type)
long	gbf.get.resource	( long resource.type, ref <type> resource.value,  …)
long	gbf.get.search.strategy	(ref long search.strategy)
long	gbf.get.selected	( long index, ref long obj.id, ref string obj.key(), ref long obj.value, ref long obj.type)
long	gbf.get.selected.nr	()
long	gbf.get.sort.strategy	(ref long sort.strategy)
long	gbf.init	(const string library(), const string title(), [long default.menu, long default.button, long default.options, long standard.button, long default.context])
long	gbf.is.displayed	(const long obj.id)
long	gbf.set.button	( const string button.group(), const string normal.button(), const string selected.button(), const string insensitive.button(), const string button.name(), long menu.item, long add.space)
long	gbf.set.child.function	(const string dll_id(), const string child.function.name(), long is.default)
long	gbf.set.buttonstate	(  long button.id, long button.state)
long	gbf.set.color	(long color, const string color.desc())
long	gbf.set.desc.length	(long desc.length)
long	gbf.set.drop.function	(const string dll_id(), const string drop.function.name(), long is.default)
long	gbf.set.header.icon	(const string icon.group(), const string icon(), long is.default, [const string icon.desc()]
long	gbf.set.help.function	(const string dll_id(), const string help.function.name(), long is.default)
long	gbf.set.interior.icon	(const string icon.group(), const string unselected.closed(), const string unselected.open(), const string selected.closed(), const string unselected.open(), long is.default, [const string icon.desc(), long context.menu]
long	gbf.set.key.desc.length	(long key.length, long desc.length)
long	gbf.set.key.length	(long key.length)
long	gbf.set.label	(const string label1(), const string label2(), const string label3(), const string label4(), const string label5())
long	gbf.set.label1	(const string label())
long	gbf.set.label2	(const string label())
long	gbf.set.label3	(const string label())
long	gbf.set.label4	(const string label())
long	gbf.set.label5	(const string label())
long	gbf.set.leaf.icon	(const string icon.group(),const string unselected(),const string selected(), long is.default,[const string icon.desc(), long context.menu]
long	gbf.set.menu.checked	(long item.id)
long	gbf.set.menu.disabled	(long item.id)
long	gbf.set.menu.enabled	(long item.id)
long	gbf.set.menu.function	(const string dll_id(), const string  menu.function.id(), long is.default)
long	gbf.set.menu.head	(string menu.text, [long maskbit, long multi.mask])
long	gbf.set.menu.item	( long menu.id, const string menu.text(), const string keystroke(), [ long is.default, long menu.function.id, long maskbit, long multi.mask, long std.button])
long	gbf.set.menu.not.checked	(long item.id)
long	gbf.set.menu.not.radio	(long item.id)
long	gbf.set.menu.radio	(long item.id)
long	gbf.set.menu.separator	(long menu.id)
long	gbf.set.menu.state	(long menu.id, long item.id, long disable, long checked, [long radio])
long	gbf.set.open.child	(long open.strategy)
long	gbf.set.open.depth	(long open.depth)
long	gbf.set.open.read	(long open.strategy)
long	gbf.set.open.strategy	(long open.strategy)
long	gbf.set.open.what	(long open.strategy)
long	gbf.set.print.options	(long print.options)
long	gbf.set.read.levels	(long read.levels, [ long show.levels])
long	gbf.set.refresh.strategy	(long refresh.rate, long refresh.type)
long	gbf.set.resource	(long resource.type, <type> resource.value, …)
long	gbf.set.search.headers	(long search.strategy)
long	gbf.set.search.sensitive	(long search.strategy)
long	gbf.set.search.set	(long search.strategy)
long	gbf.set.search.strategy	(long search.strategy)
long	gbf.set.search.what	(long search.strategy)
long	gbf.set.sort.strategy	(long sort.strategy)
long	gbf.set.std.menu	(long menu.pattern, long disable, long checked)
	gbf.set.tree.report.subtitle	(const string sub.title(80) mb)
long	gbf.start	([long read.levels, long show.levels])
long	gbf.update.deffunc	( long obj.id,  long default.function.id)
long	gbf.update.desc	( long obj.id, const string object.description() mb)
long	gbf.update.dropfunc	( long obj.id,  long drop.function.id)
long	gbf.update.icon	( long obj.id,  long icon.set)
long	gbf.update.menumask	( long obj.id,  long menumask)

The following is a list of functions called by the Generic Browser Framework that must be defined within the application. The return values as described in the Generic Browser Framework: error codes and return values, must be used otherwise the GBF may stop the application.

long	gbf.bms.received	( long sender.id, const string mask(), const string mss(), long length)
long	gbf.drag.drop	( long drag.obj, const string drag.key(), long drag.value, long drag.type, long drop.obj, const string drop.key(), long drop.value, long drop.type, long button.mode)
long	gbf.get.children	( const string object.key(), long object.value, long cur.level)
long	gbf.get.top.level	()
void	gbf.help.selected	( long obj.id, const string object.key(), long object.value, long help.value)
long	gbf.menu.selected	( long obj.id, const string object.key(), long object.value, long menu.option)
void	gbf.on.selection	( long obj.id, long obj.type, long transition)
long	gbf.save	( long obj.id, const string object.key(), long object.value, long save.type)
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


Generic Browser Framework:
error codes and return values

The GBF error codes must be interpreted as follows:

>= 0	Successful completion If the function at hand has a meaningful nonzero return value, for example, an object identification (usually given as obj.id), or  count of objects, then that number will be returned. If the function only returns a status, for example, update successful, then 0 will be returned.
< 0	Unsuccessful completion The actual returned number indicates a more precise reason of the failure. See also the function gbf.error.string() which translates any of these error codes and return values into its mnemonic string.

Possible successful completion return values (thus all >= 0) and their meaning:

Mnemonic	Meaning
0	Generic successful completion return value
GBF.CYCLE	Cycles detected
GBF.NO.CHILDREN	Given object by its obj.id does not have any children
GBF.NO.READ.CHILDREN	Children of obj.id are not yet read
GBF.LAST	Returned next object is last sibling
GBF.TOP.LEVEL	Returned parent is top (root) level

Possible error return values (thus all < 0) and their meaning is:

Mnemonic	Meaning
GBF.ARG.ERROR	Cannot store value in given argument
GBF.CHILD.ABORT	Application requested GBF termination
GBF.CHILD.EXIT	Application requested GBF exiting
GBF.DRAW.ERROR	Drawing failed: bitmap, line, shadow
GBF.EXPR.ERROR	Search expression error
GBF.ICON.EMPTY	Given icon string is empty
GBF.ICON.LOAD.ERROR	Icon could not be found and/or loaded
GBF.ILL.BITMAP	Illegal bitmap given
GBF.ILL.BUTTON	The given button is illegal.
GBF.ILL.DLL	Given DLL is unknown
GBF.ILL.FUNCTION	Given function is unknown
GBF.ILL.ICON	Given icon identification is unknown
GBF.ILL.LENGTH	Illegal key or description length
GBF.ILL.LEVEL	illegal level specified in gbf.start()
GBF.ILL.MENU.ID	Given menu.id is unknown
GBF.ILL.OBJECT	Unknown object reference given
GBF.ILL.OPEN.TYPE	Illegal open type given
GBF.ILL.REFRESH.RATE	Given refresh rate is illegal
GBF.ILL.REFRESH.TYPE	Illegal refresh type given
GBF.ILL.RESOURCE.TYPE	Unknown resource type specified
GBF.ILL.RESOURCE.VALUE	Invalid value for this resource type
GBF.ILL.SEARCH.TYPE	Illegal search type given
GBF.ILL.SORT.TYPE	Illegal sort type given
GBF.ILL.STATE	Illegal GBF state for this function
GBF.INTERNAL.ERROR	Internal error of the GBF
GBF.MAX.MENU	Too many menus or submenus defined
GBF.MENU.EMPTY	Given menu string is empty
GBF.NO.BUTTONS	The specified button does not exist
GBF.NO.DEFAULT.ICONS	GBF could not load all default icons
GBF.NO.GRAPHICS	GBF cannot run on an ASCII display
GBF.NO.LABEL	GBF configured without this label
GBF.NO.MEMORY	Not enough memory
GBF.NO.MENU	Not enough memory for menu
GBF.NO.MORE.RESOURCES	No more (free) resources available
GBF.NOT.EXPECTED	GBF did not expect this function call
GBF.NOT.INTERIOR	Given object is not an interior object
GBF.SEQ.IO.ERROR	Errors with sequential file I/O
GBF.STOP.READING	Reading stop on user request

There is no general recipe about what to do with these errors. Some errors are typically development errors, such as: GBF.ILL.RESOURCE.TYPE, GBF.ILL.LENGTH, whereas others are typically run time errors when running at the customer site, such as: GBF.NO.MEMORY or GBF.SEQ.IO.ERROR. If an error occurs on a user action (if the user pushed a button, selected a menu item and so on.) a generic message should be given which tells the user that the operation failed. Since (in general) the user is unaware of the details there should be no detailed message given. In all cases it is advised to log these errors. The GBF will log some of these errors into a persistent log file. This log file is: $BSE/log.<kk><mmm>, where the <kk> is the package name of the current session and <mmm> the module name of the current session (or in other words: the first 5 characters of the current session name), where the session name is the current value of the global: prog.name$.

Sample code could be:

long	retval

retval = gbf.SomeGBFFunction(arg1, arg2, …)

if retval < 0 then

mess(“operation failed”, 1)

LogError(“gbf.SomeGBFFunction(%s, %d) failed: %s (%d)”,

arg1, arg2, gbf.error.string(retval), retval)

return (0)	| or: return (GBF.DO.EXIT)

endif

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


Generic Browser Framework:
example

The following main application example displays all defined icons by icongroup in the current installation.

|************************************************************************

|* Framework test

|************************************************************************

|* Script Type: 0

|************************************************************************

|	Type	    : 3GL Main program

|************************************************************************

table	tttdsk900	| Icon groups

table	tttdsk903	| Icons

|************************************************************************

| Includes

|************************************************************************

#include	"ittgbfdefs"	| GBF defines

|************************************************************************

| Main entry point for the menu browser driver

| It initializes the browser display program and sends all menu options

|************************************************************************

function main()

{

long	retval	|to test return values

retval = gbf.init(gbf.current.library(), "",

GBF.MENU.ALL + GBF.MENU.FILE.OPEN + GBF.MENU.FILE.READ))

if retval < 0 then

exit(retval)

endif

exit(gbf.start())	|Show and read the first level

}

|************************************************************************

|* functions to read a tables with parent child relations

|* here this will be ttdsk900 and ttdsk903

|************************************************************************

function extern long gbf.get.children(const string Icongroup(), long object.value, long level)

{

long	retval

select ttdsk903.*

from ttdsk903

where ttdsk903.icgp = :Icongroup and ttdsk903._compnr = 0

selectdo

| add the just found icon as leaf icon

| in case of an error, use the default leaf icon

retval = gbf.set.leaf.icon( congroup,

  ttdsk903.icon,

  ttdsk903.icon,

FALSE)

if retval < 0 then

retval = 0	| indicates default leaf icon

endif

| add the icon description as new object to the tree,

| with itself as display icon, and use default functions

| there is no help function so application specific help

| options are insensitive

if gbf.add.object(ttdsk903.icon, ttdsk903.desc, 0, GBF.LEAF, retval) < 0

then

return (GBF.DO.EXIT)

endif

endselect

return (0)

}

function extern long gbf.get.top.level()

{

select ttdsk900.*

from ttdsk900

where ttdsk900._compnr = 0

selectdo

| set icongroups with default icons and functions

if gbf.add.interior(ttdsk900.icgp, ttdsk900.desc, 0) < 0

then

return (GBF.DO.EXIT)

endif

endselect

return (0)

}

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


Generic Browser Framework:
allowed functions

The Generic Browser Framework (GBF) goes through several states during its lifecycle from the start till the end of a session.

State	Description
GBF chaos (Yellow)	This state indicates that the main session has started, but no actions to the GBF have been done yet, hence the state of the GBF is undetermined and no functions, except gbf.init() should be used.
GBF initialized (Blue)	This state indicates that a gbf.init() has been received, which means that the GBF is initializing itself, and waiting for a gbf.start(). In this state the main session is still in control.
GBF running (Green)	This state indicates that now the GBF is in control, due to a gbf.start() . The GBF will be in control until it is told to terminate.
GBF terminated (Red)	This state indicates that the GBF just has relinquished control and handed it back to the main session. In this state some settings can still be retrieved from the GBF. The GBF waits for session termination or for a new gbf.init().

The next table lists in which state  the GBF functions are allowed to be used:

	State:
Function	Yellow	Blue	Green	Red
gbf.add.object			yes: 3, 4
gbf.current.library	yes	yes	yes	yes
gbf.create.context.menu		yes
gbf.error.string	yes	yes	yes	yes
gbf.delete.object			yes: 5
gbf.drag.drop			yes
gbf.get.cutcopy			yes	yes
gbf.get.cutcopy.nr			yes	yes
gbf.file.to.library	yes	yes	yes	yes
gbf.get.description			yes	yes
gbf.get.current.parent			yes: 1, 3, 4
gbf.get.first.child			yes: 1, 2, 5, 6, 7	yes
gbf.get.icon		yes	yes	yes
gbf.get.key.desc.length		yes	yes	yes
gbf.get.next			yes: 1, 2, 5, 6, 7	yes
gbf.get.object.info			yes	yes
gbf.get.next			yes: 1, 2, 5, 6, 7	yes
gbf.get.open.depth		yes	yes	yes
gbf.get.open.strategy		yes	yes	yes
gbf.get.parent			yes: 1, 2, 5, 6, 7	yes
gbf.get.print.options		yes	yes	yes
gbf.get.read.levels			yes	yes
gbf.get.refresh.strategy		yes	yes	yes
gbf.get.resource		yes	yes	yes
gbf.get.search.strategy		yes	yes	yes
gbf.get.selected			yes: 1, 2, 5, 6, 7	yes
gbf.get.selected.nr			yes	yes
gbf.get.sort.strategy		yes	yes	yes
gbf.get.children			yes
gbf.get.top.level			yes
gbf.help.selected			yes
gbf.init	yes	yes		yes
gbf.is.displayed		yes	yes	yes
gbf.menu.selected			yes
gbf.save			yes
gbf.set.button		yes	yes
gbf.set.buttonstate		yes	yes
gbf.set.color		yes	yes
gbf.set.child.function		yes	yes
gbf.set.drop.function		yes	yes
gbf.set.help.function		yes	yes
gbf.set.header.icon		yes	yes
gbf.set.interior.icon		yes	yes
gbf.set.key.desc.length		yes
gbf.set.label		yes	yes
gbf.set.leaf.icon		yes	yes
gbf.set.menu.function		yes	yes
gbf.set.menu.head		yes
gbf.set.menu.item		yes
gbf.set.menu.separator		yes
gbf.set.menu.state		yes	yes
gbf.set.open.depth
gbf.set.open.strategy and so on.		yes	yes
gbf.set.print.options		yes	yes	yes
gbf.set.read.levels			yes
gbf.set.refresh.strategy		yes	yes
gbf.set.resource		yes	yes
gbf.set.search.strategy etc		yes	yes
gbf.set.sort.strategy		yes	yes
gbf.set.std.menu		yes	yes
gbf.start		yes
gbf.set.tree.report.subtitle	yes	yes	yes	yes
gbf.update.object			yes: 1, 2, 5, 6, 7

In the GBF running state there are further restrictions if the yes is followed by a sequence of numbers. These numbers refer to:

1.	gbf.bms.received()

2.	gbf.drag.drop()

3.	gbf.get.children()

4.	gbf.get.top.level()

5.	gbf.menu.selected()

6.	gbf.help.selected()

7.	gbf.save()

It can be that this is not enforced by the GBF, so for example a gbf.get.first.child() call during a gbf.get.top.level() can be run without an error.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


Generic Browser Framework:
standard menu items and function keys

Standard menu items

The GBF allows to define a set of standard menu items, see gbf.init() .

Menu	Sub- menu	Key	Description
File	New	Ctrl+N	Insert a new object, implemented by the application
	Open all	Ctrl+O	Open all interior nodes whose children have already been read before (so do not read what is not yet there, see read all)
	Read all	Ctrl+R	Read the whole tree into memory (but do not show it, see open all)
	Refresh	F5	Refresh the current contents using the current refresh strategy
	Font…		Start change font dialog.
	Save	Ctrl+S	Save the given object or whole tree
	Save + Exit	Ctrl+Q	Save the given object or whole tree and exit the GBF
	Print Options…		Set some print options, which will be used when the GBF starts printing
	Print	Ctrl+P	Print the whole object tree as it is currently displayed
	Exit	Alt+F4	Exit the GBF
Edit	Undo	Ctrl+Z	Undo, implemented by application
	Cut	Ctrl+X	Cut, implemented by application
	Copy	Ctrl+C	Copy, implemented by application
	Paste	Ctrl+V	Paste, implemented by application
	Delete	Delete	Delete, implemented by application
	Text	Ctrl+T	Text, implemented by application
Find	By description…	Ctrl+F	Start searching for objects where the given pattern matches parts of the object description.  Note: the Ctrl+F starts the last search which is either a “By description…” or a “By code…” search.
	By code…		Start searching for objects where the given pattern matches parts of the object key. Note: the Ctrl+F starts the last search which is either a “By description…” or a “By code…” search.
	First		Set focus on the first found object, only enabled if there are found objects. If object not shown on the screen then display it including all its parents
	Next	Ctrl+G	Set focus on the next found object. If the current object is already the last found object, then leave the focus on this last object. Only enabled when there are found objects. If object not shown on the screen then display it including all its parents.
	Previous	Ctrl+ Shift+G	Set focus on the previous found object. If the current object is already the first object, then leave the focus on this first object. Only enabled when there are found objects. If object not shown on the screen then display it including all its parents.
	Last		Set focus on the last object only enabled when there are found objects. If object not shown on the screen then display it including all its parents.
	Search in current set		Only what is currently in GBF memory will be searched through.
	Read before search		Before the search is started, everything which is NOT yet known to the GBF is asked (see gbf.get.children ) from the main application, that is the whole set is used to search in  this is the GBF.SEARCH.ALL search strategy (see gbf.set.search.strategy() ).
	Match case		Do not ignore case differences this is the GBF.SEARCH.SENSITIVE search strategy (see gbf.set.search.strategy()).
Sort	None		Do not sort the objects and keep the order in which they are handed over by the main application.
	By description		Sort the objects using their description.
	By code		Sort the objects using their key.
	Ascending		Sort in ascending mode. Only enabled when sort option is not none
	Descending		Sort in descending mode. Only enabled when sort option is not none.
	Match case		Do not ignore case differences. Only enabled when sort option is not none.
Group	New	Ctrl+ Shift+N	Insert a new group object, Implemented by the application.
	First		Go to the oldest brother of the current selected item, which is the first child object of the parent of the current selected object.
	Previous		Go to the previous brother of the current selected object.
	Next		Go to the next brother of the current selected object.
	Last		Goto the last brother of the current selected item, which is the last child object of the parent of the current selected object.
Help	Contents		Give a table of contents of all available Help within the current session that is using the GBF.
	What’s This?	Shift + F1	Starts the context sensitive Help, which gives detailed Help on the next selected item (including menu items, buttons, keystrokes and so on).
	Color Descriptions…		Starts the  special Color Descriptions (ttgbf1310m000) session that shows all used text colors in the GBF when at least one text.color has been used, see also gbf.set.color().
	Icon Descriptions…		Starts the Icon Descriptions (ttgbf1320m000) session that shows all used icons, with a description of what these icons mean. See also icon.desc of gbf.set.interior.icon() and gbf.set.leaf.icon() .
	Using Browser	F2	Gives Help on how to use the GBF at runtime.
	Using Session	F1	Gives help on how to use the current session which is build using the GBF. Starts the help associated with the current session, which is identified by the global: prog.name$.
	About…		Show the About box of the GBF.
Standard key strokes

Key	Restriction	Description
Alt+F4		Shortcut for menu: File exit
Alt+F4	during read	Asks to stop for further reading.
Ctrl+C	during read	Asks to stop for further reading.
Ctrl+C	normal operation	Shortcut for menu: Edit copy
Ctrl+F		Shortcut for menu: Find by description
Ctrl+G		Shortcut for menu: Find next
Ctrl+Shift+G		Shortcut for menu: Find previous
Ctrl+N		Shortcut for menu: File new
Ctrl+Shift+N		Shortcut for menu: Group new
Ctrl+O		Shortcut for menu: File open all
Ctrl+P		Shortcut for menu: File print
Ctrl+Q		Shortcut for menu: File save + exit
Ctrl+R		Shortcut for menu: File read all
Ctrl+S		Shortcut for menu: File save
Ctrl+T		Shortcut for menu: Edit text
Ctrl+V		Shortcut for menu: Edit paste
Ctrl+X		Shortcut for menu: Edit cut
Ctrl+Z		Shortcut for menu: Edit undo
ESCAPE	during read	asks to stop for further reading.
Delete		Shortcut for menu: Edit Delete.
F1		Shortcut for menu: Help using session .
Shift+F1		Shortcut for menu: Help what’s this ? (context sensitive help).
F2		Shortcut for menu: Help using browser.
F5		Shortcut for menu: File refresh.
- or Shift -	on open interior node	Close this interior node.
+ or Shift +	on closed interior node	Open this interior node.
Backspace	not on top level node	Go to parent.
Left Arrow	not on top level node	Go to parent.
Shift+Left Arrow	open interior node	Close node and go to parent.
Ctrl+Left Arrow		Go to the ancestor to which the cycle line goes, or if not in a cycle go to the parent.
Right Arrow	interior node is open and has children	Go to first child.
Shift+Right Arrow	closed interior node	Open node (get the children) and go to first child.
Ctrl+Right Arrow	on interior node	Go to the first or next (great-…-grand) child which has a cycle line to the current selected object. So the first time a Ctrl+Right Arrow is given focus is set to the first cycle child, the next Ctrl+Right Arrow goes to the next child which has the same cycle ancestor If no cycle then go to the first child.
Up Arrow		Go to previous object, in other words the object above this one.
Ctrl+Up Arrow	not on first object of parent	Go to previous brother.
Down Arrow		Go to next object, in other words the object beneath this one
Ctrl+Down Arrow	not on last object of parent	Go to next brother
Home		Set focus on top object
Ctrl+Home	one object selected	Go to oldest brother, in other words first child of parent of object
Ctrl+Home	no record selected	Go to top object.
End		Set focus on last object in tree.
Ctrl+End	one object selected	Go to youngest brother, in other words last child of parent of obj.
Ctrl+End	no object selected	go to last object in tree.
Page Down	one object selected	Set focus on last visible object on screen.
Page Down	no object selected	Set focus on last object in tree.
Page Up	one object selected	Set focus on an object above the current selected object such that this old current object is just visible after the operation.
Page Up	no object selected	Set focus on top object.
When the restriction is not met, for example right arrow on a leaf node, no action is taken.

Special Key Strokes during Read

When the GBF is reading (that is: it is currently busy with a lot of gbf.get.children()’s then this may be a lengthy process, which can make the impression that the application ‘hangs’. After each gbf.get.children() function it is checked to see whether the end user wants to stop this lengthy operation. The way to stop this is by pressing any button, or by hitting the ESCAPE key, CTRL+C or Alt+F4. If this is the case then a question is asked whether or not the reading should really be stopped or not. Note that the number of objects currently in memory of the GBF is also shown, so one can monitor the progress.

When the progress bar is used (see option GBF.OPT.PROGRESS in gbf.init() ) then also the current number of total items is displayed. When the STOP button is pressed still the above mentioned question will be asked.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: messages and questions


Generic Browser Framework:
messages and questions

The standard messages used by the GBF are all located in the tt package.

Message id	Message text	Meaning or used for
gbfk0001	Alt	Pattern to match and recognize the Alt key.
gbfk0002	Ctrl	Pattern to match and recognize the Control key.
gbfk0003	Shift	Pattern to match and recognize the Shift key.
gbfk0005		Keystroke for: Print Options…
gbfk0007		Keystroke for: Help Contents
gbfk0008	Ctrl+P	Keystroke for: File Print
gbfk0009	Alt+F4	Keystroke for: File Exit
gbfk0011	Ctrl+F	Keystroke for: Find by description
gbfk0012	Shift+Ctrl+F	Keystroke for: Find by code
gbfk0013		Keystroke for: Find first
gbfk0014		Keystroke for: Find last
gbfk0015	Ctrl+G	Keystroke for: Find next
gbfk0017	Shift+Ctrl+G	Keystroke for: Find previous
gbfk0019	Shift+F1	Keystroke for: Help What’s This?
gbfk0020	F2	Keystroke for: Help Using Browser
gbfk0021	Ctrl+O	Keystroke for: File Open All
gbfk0022	Ctrl+R	Keystroke for: File Read All
gbfk0023	F1	Keystroke for: Help Using Session
gbfk0024	Ctrl+S	Keystroke for: File Save
gbfk0025	Ctrl+Q	Keystroke for: File Save + Exit
gbfk0026		Keystroke for: Help About
gbfk0027		Keystroke for Find: Search in current set
gbfk0028		Keystroke for Find: Read before search
gbfk0029		Keystroke for Find: Match case
gbfk0031	F5	Keystroke for: File Refresh
gbfk0033		Keystroke for: Sort none
gbfk0034		Keystroke for: Sort by description
gbfk0035		Keystroke for: Sort by code
gbfk0036		Keystroke for: Sort ascending
gbfk0037		Keystroke for: Sort descending
gbfk0039		Keystroke for: Sort match case
gbfk0043		Keystroke for: Help Color Descriptions…
gbfk0044		Keystroke for: Help Icon Descriptions…
gbfk0050	Tab	Keystroke for: TAB key
gbfk0051	INS	Denotation of the: INSERT key
gbfk0052	DEL	Denotation of the:DEL key, but see message gbfk0095
gbfk0054	HOME	Denotation of the: HOME key
gbfk0054	END	Denotation of the: END key
gbfk0055	ESC	Denotation of the: ESCAPE key
gbfk0056	PgUp	Denotation of the: PAGEUP key
gbfk0057	PgDn	Denotation of the: PAGEDOWN key
gbfk0058	Return	Denotation of the: RETURN key
gbfk0059	Enter	alternative denotation of the: RETURN key
gbfk0060	Space	Denotation of the: Space bar or space key
gbfk0061	Backspace	Denotation of the: Backspace key
gbfk0071	Ctrl+Shift+N	Keystroke for: Group new
gbfk0072		Keystroke for: Group first
gbfk0073		Keystroke for: Group previous
gbfk0074		Keystroke for: Group next
gbfk0075		Keystroke for: Group last
gbfk0080	Backtab	Denotation of special vt220 key: BACKTAB key
gbfk0081	Do	Denotation of special vt220 key: DO key
gbfk0082	Find	Denotation of special vt220 key: FIND key
gbfk0083	Help	Denotation of special vt220 key: HELP key
gbfk0084	Lang	Denotation of special vt220 key: LANG key (mb)
gbfk0085	Print	Denotation of special vt220 key: PRINT key
gbfk0086	Push	Denotation of special vt220 key: PUSH key (bidi, mb)
gbfk0087	Remove	Denotation of special vt220 key: REMOVE key
gbfk0088	Reverse	Denotation of special vt220 key: REVERSE key (bidi)
gbfk0089	Select	Denotation of special vt220 key: SELECT key
gbfk0091	Ctrl+Z	Keystroke for: Edit undo
gbfk0092	Ctrl+X	Keystroke for: Edit cut
gbfk0093	Ctrl+C	Keystroke for: Edit copy
gbfk0094	Ctrl+V	Keystroke for Edit paste
gbfk0095	Delete	Keystroke for Edit delete
gbfk0096	Ctrl+T	Keystroke for: Edit text
gbfk0097	Ctrl+N	Keystroke for: File new
gbfk0098		Keystroke for: File fonts…
gbfl0000	OK	Text on button in About box to close this About box.
gbfl0002	Debug info: %s	Used for display internal debugging information.
gbfl0005	Print Option&s…	Submenu of File: Print Options…
gbfl0006	&File	Header of File menu on menu bar
gbfl0007	&Contents	Submenu of Help: Contents
gbfl0008	&Print	Submenu of File: Print
gbfl0009	E&xit	Submenu of File: Exit
gbfl0010	F&ind	Header of Find menu on menu bar
gbfl0011	By &description…	Submenu of Find: By description…
gbfl0012	By &code…	Submenu of Find: By code…
gbfl0013	&First	Submenu of Find: First
gbfl0014	&Last	Submenu of Find: Last
gbfl0015	&Next	Submenu of Find: Next
gbfl0017	&Previous	Submenu of Find: Previous
gbfl0018	&Help	Header of Help menu on menu bar
gbfl0019	What’s &This?	Submenu of Help: What is This ?
gbfl0020	Using &Browser	Submenu of Help: Using Browser
gbfl0021	&Open All	Submenu of File: Open All
gbfl0022	Read &All	Submenu of File: Read All
gbfl0023	&Using session	Submenu of Help: Using Session
gbfl0024	&Save	Submenu of File: Save
gbfl0025	Save + &Exit	Submenu of File: Save + Exit
gbfl0026	&About…	Submenu of Help: About
gbfl0027	&Search in current set	Submenu of Find: Search in current set
gbfl0028	&Read before search	Submenu of Find: Read before search
gbfl0029	&Match case	Submenu of Find: Match case
gbfl0030	Cannot find %s	Error text when searching for object which does not exists
gbfl0031	&Refresh	Submenu of File: refresh
gbfl0032	S&ort	Header of Sort menu on menu bar
gbfl0033	&None	Submenu of Sort: None
gbfl0034	By &description	Submenu of Sort: by description
gbfl0035	By &code	Submenu of Sort: by code
gbfl0036	&Ascending	Submenu of Sort: Ascending
gbfl0037	De&scending	Submenu of Sort: Descending
gbfl0038	Sorting	Action text when sorting is executing
gbfl0039	&Match case	Submenu of Sort: Match case
gbfl0040	Dragging	Action text when dragging and dropping
gbfl0041	Opening	Action text when opening of all levels is executing
gbfl0042	Reading	Action text when reading of all levels is executing
gbfl0043	Color &Descriptions…	Submenu of Help: Color Descriptions
gbfl0044	&Icon Descriptions…	Submenu of Help: Icon descriptions
gbfl0045	%s [User: %s]	Default title when user has NO session code in titlebar
gbfl0046	%s : %s [User: %s]	Default title when user wants session code in titlebar
gbfl0047	Refreshing	Action text when refreshing is executing
gbfl0048	Displaying	Action text when opening an interior object
gbfl0049	Loading	Action text when initial loading of objects is executing
gbfl0050	Searching	Action text when searching is executing
gbfl0051	Search for	Text on search pop-up
gbfl0053	Company	Prefix for label3 in status box
gbfl0054	Date	Prefix for label5 in status box
gbfl0055	No top level function defined	Error message when gbf.get.top.level() function was not found, which will leave the GBF blank
gbfl0056	No child function defined	Error message when no Gbf.get.children()(or any other child retrieval function) defined in the main application This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfl0057	No help function defined	Error message when no Gbf.help.selected() (or any other help function) defined in the main application This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfl0058	No save function defined	Error message when no gbf.menu.selected() defined in the main application This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfl0059	No drag&drop function defined	Error message when no gbf.drag.drop() (or any other drag & drop function) defined in the main application This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfl0060	No menu function defined	Error message when no gbf.menu.selected() (or any other menu function) defined in the main application This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfl0064	<untitled>	Initial value for label2 in status box
gbfl0070	&Group	Header of Group menu on menubar
gbfl0071	&New	Submenu of Group: new
gbfl0072	&First	Submenu of Group: first
gbfl0073	&Previous	Submenu of Group: previous
gbfl0074	&Next	Submenu of Group: next
gbfl0075	&Last	Submenu of Group: last
gbfl0090	&Edit	Header of Edit menu on menubar
gbfl0091	&Undo	Submenu of Edit: undo
gbfl0092	Cu&t	Submenu of Edit: cut
gbfl0093	&Copy	Submenu of Edit: copy
gbfl0094	&Paste	Submenu of Edit: paste
gbfl0095	&Delete	Submenu of Edit: delete
gbfl0096	&Text	Submenu of Edit: text
gbfl0097	&New	Submenu of File: new
gbfl0098	&Font…	Submenu of File: font
gbfl2000	gbf	Index in ttdsk900, default icon group for leaf icons
gbfl2001	leaf.normal	Index in ttdsk903, unselected leaf icon
gbfl2002	leaf.select	Index in ttdsk903, selected leaf icon
gbfl2005	leaf	Icon description of leaf icon
gbfl3000	gbf	Index in ttdsk900, default icon group for leaf icons
gbfl3001	header.gif	Index in ttdsk903, header icon
gbfl3005	header	Icon description of header icon
gbfl4000	gbf	Index in ttdsk900, default icon group for interior icons
gbfl4001	intcl.normal	Index in ttdsk903, closed and unselected interior icon
gbfl4002	intop.normal	Index in ttdsk903, open and unselected interior icon
gbfl4003	intcl.select	Index in ttdsk903, closed and selected interior icon
gbfl4004	intop.select	Index in ttdsk903, open and selected interior icon
gbfl4005	node	Icon description of interior node
gbfl6000	gbf	Index in ttdsk900, default icon group for all buttons
gbfl6001	end1.gif	Index in ttdsk903, unselected GBF.BUTTON.FILE.QUIT button icon
gbfl6002	end2.gif	Index in ttdsk903, selected GBF.BUTTON.FILE.QUIT button icon
gbfl6003	end3.gif	Index in ttdsk903, insensitive GBF.BUTTON.FILE.QUIT button icon
gbfl6011	abort1.gif	Index in ttdsk903, unselected GBF.BUTTON.FILE.EXIT button icon
gbfl6012	abort2.gif	Index in ttdsk903, selected GBF.BUTTON.FILE.EXIT button icon
gbfl6013	abort3.gif	Index in ttdsk903, insensitive GBF.BUTTON.FILE.EXIT button icon
gbfl6021	print1.gif	Index in ttdsk903, unselected GBF.BUTTON.FILE.PRINT button icon
gbfl6022	print2.gif	Index in ttdsk903, selected GBF.BUTTON.FILE.PRINT button icon
gbfl6023	print3.gif	Index in ttdsk903, insensitive GBF.BUTTON.FILE.PRINT button icon
gbfl6031	save1.gif	Index in ttdsk903, unselected GBF.BUTTON.FILE.SAVE button icon
gbfl6032	save2.gif	Index in ttdsk903, selected GBF.BUTTON.FILE.SAVE button icon
gbfl6033	save3.gif	Index in ttdsk903, insensitive GBF.BUTTON.FILE.SAVE button icon
gbfl6041	firstr1.gif	Index in ttdsk903, unselected GBF.BUTTON.FRST button icon
gbfl6042	firstr2.gif	Index in ttdsk903, selected GBF.BUTTON.FRST button icon
gbfl6043	firstr3.gif	Index in ttdsk903, insensitive GBF.BUTTON.FRST button icon
gbfl6044	top	button name
gbfl6051	prevr1.gif	Index in ttdsk903, unselected GBF.BUTTON.PREV button icon
gbfl6052	prevr2.gif	Index in ttdsk903, selected GBF.BUTTON.PREV button icon
gbfl6053	prevr3.gif	Index in ttdsk903, insensitive GBF.BUTTON.PREV button icon
gbfl6054	page up	button name
gbfl6061	nextr1.gif	Index in ttdsk903, unselected GBF.BUTTON.NEXT button icon
gbfl6062	nextr2.gif	Index in ttdsk903, selected GBF.BUTTON.NEXT button icon
gbfl6063	nextr3.gif	Index in ttdsk903, insensitive GBF.BUTTON.NEXT button icon
gbfl6064	page down	button name
gbfl6071	lastr1.gif	Index in ttdsk903, unselected GBF.BUTTON.LAST button icon
gbfl6072	lastr2.gif	Index in ttdsk903, selected GBF.BUTTON.LAST button icon
gbfl6073	lastr3.gif	Index in ttdsk903, insensitive GBF.BUTTON.LAST button icon
gbfl6074	bottom	button name
gbfl6081	fhelp1.gif	Index in ttdsk903, unselected GBF.MENU.HELP button icon
gbfl6082	fhelp2.gif	Index in ttdsk903, selected GBF.MENU.HELP button icon
gbfl6083	fhelp3.gif	Index in ttdsk903, insensitive GBF.MENU.HELP button icon
gbfl6091	find1.gif	Index in ttdsk903, unselected GBF.BUTTON.SRCH.DESC button icon
gbfl6092	find2.gif	Index in ttdsk903, selected GBF.BUTTON.SRCH.DESC button icon
gbfl6093	find3.gif	Index in ttdsk903, insensitive GBF.BUTTON.SRCH.DESC button icon
gbfl6101	undo1.gif	Index in ttdsk903, unselected GBF.BUTTON.UNDO button icon
gbfl6102	undo2.gif	Index in ttdsk903, selected GBF.BUTTON.UNDO button icon
gbfl6103	undo3.gif	Index in ttdsk903, insensitive GBF.BUTTON.UNDO button icon
gbfl6104	undo	button name
gbfl6111	addr1.gif	Index in ttdsk903, unselected GBF.BUTTON.INSERT button icon
gbfl6112	addr2.gif	Index in ttdsk903, selected GBF.BUTTON.INSERT button icon
gbfl6113	addr3.gif	Index in ttdsk903, insensitive GBF.BUTTON.INSERT button icon
gbfl6114	insert	button name
gbfl6121	copy1.gif	Index in ttdsk903, unselected GBF.BUTTON.COPY button icon
gbfl6122	copy2.gif	Index in ttdsk903, selected GBF.BUTTON.COPY button icon
gbfl6123	copy3.gif	Index in ttdsk903, insensitive GBF.BUTTON.COPY button icon
gbfl6124	copy	button name
gbfl6131	delete1.gif	Index in ttdsk903, unselected GBF.BUTTON.DELETE button icon
gbfl6132	delete2.gif	Index in ttdsk903, selected GBF.BUTTON.DELETE button icon
gbfl6133	delete3.gif	Index in ttdsk903, insensitive GBF.BUTTON.DELETE button icon
gbfl6134	delete	button name
gbfl6141	gotog1.gif	Index in ttdsk903, unselected GBF.BUTTON.GRP.NEW button icon
gbfl6142	gotog2.gif	Index in ttdsk903, selected GBF.BUTTON.GRP.NEW button icon
gbfl6143	gotog3.gif	Index in ttdsk903, insensitive GBF.BUTTON.GRP.NEW button icon
gbfl6144	new group	button name
gbfl6151	firstg1.gif	Index in ttdsk903, unselected GBF.BUTTON.GRP.FRST button icon
gbfl6152	firstg2.gif	Index in ttdsk903, selected GBF.BUTTON.GRP.FRST button icon
gbfl6153	firstg3.gif	Index in ttdsk903, insensitive GBF.BUTTON.GRP.FRST button icon
gbfl6154	first group	button name
gbfl6161	prevg1.gif	Index in ttdsk903, unselected GBF.BUTTON.GRP.PREV button icon
gbfl6162	prevg2.gif	Index in ttdsk903, selected GBF.BUTTON.GRP.PREV button icon
gbfl6163	prevg3.gif	Index in ttdsk903, insensitive GBF.BUTTON.GRP.PREV button icon
gbfl6164	previous group	button name
gbfl6171	nextg1.gif	Index in ttdsk903, unselected GBF.BUTTON.GRP.NEXT button icon
gbfl6172	nextg2.gif	Index in ttdsk903, selected GBF.BUTTON.GRP.NEXT button icon
gbfl6173	nextg3.gif	Index in ttdsk903, insensitive GBF.BUTTON.GRP.NEXT button icon
gbfl6174	next group	button name
gbfl6181	lastg1.gif	Index in ttdsk903, unselected GBF.BUTTON.GRP.LAST button icon
gbfl6182	lastg2.gif	Index in ttdsk903, selected GBF.BUTTON.GRP.LAST button icon
gbfl6183	lastg3.gif	Index in ttdsk903, insensitive GBF.BUTTON.GRP.LAST button icon
gbfl6184	last group	button name
gbfl6191	text1.gif	Index in ttdsk903, unselected GBF.BUTTON.TEXT button icon
gbfl6192	text2.gif	Index in ttdsk903, selected GBF.BUTTON.TEXT button icon
gbfl6193	text3.gif	Index in ttdsk903, insensitive GBF.BUTTON.TEXT button icon
gbfl6194	text	button name
gbfl6201	cut1.gif	Index in ttdsk903, unselected GBF.BUTTON.CUT button icon
gbfl6202	cut2.gif	Index in ttdsk903, selected GBF.BUTTON.CUT button icon
gbfl6203	cut3.gif	Index in ttdsk903, insensitive GBF.BUTTON.CUT button icon
gbfl6204	Cut	button name
gbfl6211	paste1.gif	Index in ttdsk903, unselected GBF.BUTTON.PASTE button icon
gbfl6212	paste2.gif	Index in ttdsk903, selected GBF.BUTTON.PASTE button icon
gbfl6213	paste3.gif	Index in ttdsk903, insensitive GBF.BUTTON.PASTE button icon
gbfl6214	Paste	Button name
gbfreport 001	(%s)	Default subtitle format for print report, see also gbf.set.tree.report.subtitle().
gbfreport 002	The report could not be printed	Error message when GBF could not finish the printing for some reason
gbfs0001	Icon %s of icongroup %s is not a valid picture in GIF format, actual file: %s	The given icon in the given icongroup is not a valid GIF file, so it cannot be used as icon or button in the GBF
gbfs0010	%s	Message used to show the error messages set via a dal.set.error.message(), that is errors coming from the DAL.
gbfs0013		Default name for extra Root element added by the GBF when running on BI and using Tree Control.
gbfs0020	Ascii server does not support graphics	Error message when GBF is started on BA (Baan ASCII)
gbfs0021	No more memory	Error message when GBF runs out of memory
gbfs0022	Icon %s not in icongroup %s	Error message when GBF cannot find specified icon
gbfs0023	Unknown keystroke: %s	Error message when asking context sensitive help on a keystroke which has no help or is not supported by the GBF or application. Note that some of the standard GBF keystrokes are explained in the Help: Using Browser.
gbfs0024	Objects do not fit in window anymore: %s (key: %s)	Error message when too many or too large objects are put into the browser window. The object shown by its description and key is the first which is outside the browser window.
gbfs0025	Debug: unexpected error from exec_function %s: %d	Error message used when a call back from GBF to the main application fails, where the error number is the return value from the exec_function. This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfs0026	Debug: return value from %s: %s (%d)	Error message used when the main application returns on a call back function a value which indicates that the GBF should stop further processing, that is GBF.DO.ABORT or GBF.DO.EXIT. This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfs0027	Debug: current state %s does not allow to call %s	Error message used when a GBF function is called while it's in the wrong state. This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfs0028	Debug: illegal %s length: %d max = %d, value = %s	Error message when the key or description is too long to fit in the incore GBF data structures. This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfs0029	key	Used in message: gbfs0028 to denote the key is too long
gbfs0030	description	Used in message: gbfs0028 to denote the description is too long.
gbfs0031	Debug: keystroke: %s mapped to %s	Error message used when a keystroke is mapped onto another key combination when the given one cannot be dealt with by the GBF. For example: ‘Shift+A’ to ‘A’. This message will only be given when the GBF.OPT.DEBUG is set during gbf.init.
gbfs0032	Debug: cannot find DLL: %s or function: %s	Error message when adding a function using gbf.set.child.function(), gbf.set.drop.function(), gbf.set.help.function(), or gbf.set.menu.function() and that function or DLL, in which the function is supposed to be in, cannot be found.  This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfs0033	Debug: Button %s: %s too large: %d x %d (max: %d x %d)	Error message when adding buttons, indicating that the picture is too large to fit in the button. This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfs0034	Debug: not a standard GBF button %d: (0x%8.8x) for menu item: %s, keystroke: %s	Error message when adding menu items and associating them with a not allowed or wrong standard GBF button (see function: gbf.set.menu.item()). This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfs0035	Debug: too many different colors defined (max = %d)	Error message when adding a new object or updating an existing object with a non default color but there are already too many colors in use (see functions:gbf.add.object() and gbf.update.object()). Note that at run time the default color will be used. This message will only be given when the GBF.OPT.DEBUG is set during gbf.init()
gbfs0036	Debug: illegal child function: %d (max: %d), drag&drop function: %d (max: %d) or help function: %d (max: %d)	Error message when adding a new object or updating an existing object with one or more non default use (see functions:gbf.add.object() and gbf.update.object()). This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfs0037	Debug: illegal icon set: %d (max: %d)	Error message when adding a new object or updating an existing object with a new icon set, but the given icon set is invalid. This message will only be given when the GBF.OPT.DEBUG is set during gbf.init().
gbfs0040	Selected object “%s” (key: %s) is outside the window	Warning message when the selected object is outside the possible range that the GBF can show (cannot be draw on the Gwindow)
gbfs0050	Version: %s, BSE Env: %s, Host: %s	String in the about box to display the VRC, BSE environment and current host name
gbfs0051	Open: %s, %s, %s, levels: %d	String in the about box to display the open strategy, see gbf.get.open.strategy(),and open depth, see gbf.get.open.depth().
gbfs0052	Search: %s, %s, %s	String in the about box to display the current search strategy, see gbf.get.search.strategy().
gbfs0053	Sort: %s, %s, %s	String in the about box to display the current sort strategy, see gbf.get.sort.strategy().
gbfs0054	Refresh: %s, %d msec.	String in the about box to display the current refresh strategy, see gbf.get.refresh.strategy().
gbfs0055	Nr.objs: %s, current: %d, nr.sel %d, nr.cut: %d	String in the about box to display the total number of objects in GBF, the current selected object, the number of current selected objects and the number of objects in the Cut&Copy buffers
gbfs0056	Menu  : %s	String in the about box, displays the original standard GBF menu. See default.menu in gbf.init().
gbfs0057	Button: %s, supported: %s	String in the about box, displays the original standard GBF buttons. See default.button and standard.button in gbf.init().
gbfs0058	Option: %s	String in the about box, displays the original standard GBF options. See default.options in gbf.init().
gbfs0070	Unselected	Text for description text in grid of unselect item color, see the Color Descriptions (ttgbf1310m000) session.
gbfs0071	Selected	Text for description text in grid of selected item color.
gbfs0072	Default text color	Color description of default text color of GBF in grid.
gbfs0073	Color description	Heading text in grid of color descriptions column.
gbfs0074	(no description given)	Text used when no real color description has been given for this particular color, see gbf.set.color and the Color Descriptions (ttgbf1310m000) session.
gbfs0075	Cannot activate session: %s (%s)	Error message when GBF cannot start one of its own subsessions.
gbfs0080	Leaf icon: unselected	Icon is used for an unselected leaf object, see the Icon Descriptions (ttgbf1320m000) session.
gbfs0081	Leaf icon: selected	Icon is used for a selected leaf object.
gbfs0082	Interior node: closed, unselected	Icon is used for a closed and unselected interior node object.
gbfs0083	Interior node: closed, selected	Icon is used for a closed but selected interior node object.
gbfs0084	Interior node: open, unselected	Icon is used for an open but unselected interior node object.
gbfs0085	Interior node: open, selected	Icon is used for an open and selected interior node object.
gbfs0086	Header icon	Icon is used as a header icon.
gbfreport001	(%s)	Format used for default heading in print report
gbfreport002	The report could not be printed…	Error message when the printing of the GBF failed.
Question id	Question text	Meaning or used for
gbf0001	Currently %d objects. Do you want to stop further reading ?	Used when end user aborts lengthy read operations. A Yes will stop further reading, a No will continue as if nothing has happened.
gbf0002	Do you want to print all open objects or only the subtree below the selected node?	Used when printing is started and currently at least one object in the tree is selected.
Some remarks:

1.	The prefix gbfk means: keystrokes, gbfs means session errors and gbfl is used for all other texts such as: labels, initial label fields (at bottom of window), standard menu labels, default icon names, and so on.

2.	When changing one of more of gbfk0001, gbfk0002 and/or gbfk0003 all other keystroke definitions should also be changed using this new definition, since these messages are used to recognize the keystrokes (see gbf.set.menu.item()).

3.	The special keys are defined by the messages gbfk0050 -  gbfk0061 (see gbf.set.menu.item()).

4.	If gbfl<nr> is a submenu item, then gbfk<nr> (for the same nr of course) is the associated keystroke.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys


Generic Browser Framework:
typical usage

This topic describes the typical usage of the GBF.

Initialization

The browser should be initialized with a function call. The application has to call the function gbf.init() of the framework.

The developer has the possibility to define the menu structure they want to use. There he can specify which action can be taken on an object. The menu structure should be specified in the function gbf.set.menu.head() and gbf.set.menu.item() in the application. It is also possible to set a default icon for possible parents, open and closed, selected and not selected and children, selected and not selected. This can be done with the functions gbf.set.interior.icon() and gbf.set.resource() in the application.

The initialization phase ends with a gbf.start() function call which puts the GBF in control.

Filling the top level of the data structure

The browser asks for information on the top level to be displayed. This is done with a call of a function with a fixed name: the function gbf.get.top.level(). In that function the application must store the required data in the data structure of the browser with a function of the framework. This must be done with gbf.add.object() . The developer must indicate within this call whether the object can have children. This is necessary for the browser to determine which actions should be taken at which time. The developer can also specify the icon and description of the object. This gives many possibilities to the developer to give the desired look to the browser. When no icon is specified the default icon is used. This way the data structure of the framework is filed.

Actions

To change the (number of) objects

The actions that follow are dependent of the actions of the user and the type of the object. When an object is a possible parent, the children must be displayed in case of a double click or a comparable event. The framework then calls the function gbf.get.children() in the application. This function must give the children of the parent object and store them in the data structure with the function gbf.add.object() of the framework. When an action is required on a possible parent object, the object has to be selected and the required action taken from the menu. When an object can only be a child, the double click or comparable event should perform the required default action.

The developer can use the function gbf.update.object() to change the icon or description of an object. To remove an object from the browser the function gbf.set.drop.function() of the framework can be used. To insert an object the function gbf.add.object() of the framework can be used.

Refresh

There are three possible ways to refresh the displayed objects:

1.	The developer can use the function gbf.set.refresh.strategy() of the framework to get a time based refresh

2.	A refresh can be performed as the result of a return value of a user function, see for example gbf.menu.selected()

3.	A refresh can be done via a menu item and/or keystroke, see also gbf.init()

The refresh will execute gbf.get.top.level() and then gbf.get.children() of all open parents. Now not-existing objects will be removed from the browser and new objects will be displayed. This will keep the browser up to date with the database. Note that objects are matched ONLY by their object.key (see gbf.add.object()), as all other attributes of the object, such as object.description, object.value and obj.type, may have changed since this attribute change may have been what caused this refresh in the first place. The functions gbf.get.first.child() and gbf.get.next() should be avoided during a refresh, since that would lead to unpredictable results.

User actions

When a menu option is chosen the framework calls the function gbf.menu.selected() in the application. The frameworks gives the code of the option and the object(s) that was/were marked so the application can execute the required function. The return value of gbf.menu.selected() is an indication for the framework which action should be performed (for example a refresh or a gbf.get.children() on the object).

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


Generic Browser Framework:
getting started

This topic gives the first few steps to build a main application from scratch all the way up to a full application. The focus of the chapter is to get a script running. For readibility reasons the checking of return values and error handling is removed from the examples. It is advised to use the Generic Browser Framework: example as a reference while reading this section.

Minimal script:

1.	In the include section of the main application, add the following:

#include “ittgbfdefs”	| all GBF defines

2.	In the main function (or where appropriate) add:

gbf.init(gbf.current.library(), “”, GBF.MENU.ALL, GBF.BUTTON.ALL, GBF.OPT.DEFAULT + GBF.OPT.DEBUG)

3.	After this add:

gbf.start()

4.	Be sure to add the GBF library to the application in the Maintain Sessions (ttadv2100m000) session. In this session go to form 2 and click on Scripts, which should start the Maintain Program Scripts/Libraries (ttadv2130s000) session.
Now click on Libraries and add the “ttgbfsrvlib” library.

5.	Now the application can be compiled and run. There may be an error popup: “No top level function defined”, but that is OK for this moment.

Basic Script

1.	Add the function gbf.get.top.level() to the main application. Be sure to return 0. A compile and run of the program should now work without the previous described error popup.

2.	Next fill the body of gbf.get.top.level(), by telling the GBF which are the top level objects. See also the manual page for gbf.add.interior().

function extern long gbf.get.top.level()
{
gbf.add.interior(“top key”, “top description”, 0)
return (0)
}

3.	Compile and run the application and see what happens. In general the body of this function will contain a more elaborate SELECT statement.

Normal Script

Now more objects have to be added to the script, which can be done using the function: gbf.get.children() . See also gbf.add.leaf() and gbf.add.object() .

Example:

function extern long gbf.get.children(const string key(), long value, long level)

{

gbf.add.leaf(“leaf key 1”, “leaf description 1”, 0)

gbf.add.leaf(“leaf key 2”, “leaf description 2”, 0)

gbf.add.leaf(“leaf key 3”, “leaf description 3”, 0)

return (0)

}

Compile and run the application and see what happens. In general the body of this function will contain a more elaborate SELECT statement.

Full Script

Now the essential frame work of how to use the GBF is complete. More and more features may now be added. Do not forget to remove the GBF.OPT.DEBUG flag. The next table lists the functions and options that you can use to implement a feature.

Feature	Functions and options to implement the feature
buttons	gbf.init() and use the GBF.BUTTON options, gbf.set.button(),gbf.set.menu.item(), gbf.get.resource(), gbf.set.resource()
debugging	gbf.init(), and use the GBF.OPT.DEBUG / GBF.OPT.POP.UP options
cut, copy & paste	gbf.init(), gbf.menu.selected(), gbf.get.cutcopy(), gbf.get.cutcopynr()
drag and drop	gbf.init() and use the GBF.OPT.DRAG.DROP option, gbf.set.drop.function(),gbf.drag.drop()
help	gbf.init(), gbf.set.help.function(), gbf.add.object(), gbf.help.selected()
icons	gbf.init() and use the GBF.OPT.SHADOWS option gbf.set.interior.icon(), gbf.set.leaf.icon(), gbf.add.object(), gbf.update.object()
initialization	gbf.file.to.library(), gbf.current.library(),gbf.init(), gbf.start()
labels	gbf.init() and use the GBF.OPT.NO.LABELS/GBF.OPT.<nr>.LABELS options, gbf.add.object()
menus	gbf.init() and use the GBF.MENU options, gbf.set.menu.function(), gbf.set.menu.head(), gbf.set.menu.item(), gbf.set.menu.seperator(), gbf.set.menu.state(), gbf.set.std.menu()
multiple select	gbf.init() and use the GBF.OPT.MULTIPLE option, gbf.get.selected(), gbf.drag.drop(), gbf.menu.selected()
object management	gbf.add.header(), gbf.add.interior(), gbf.add.leaf(),gbf.add.object(), gbf.get.description(), gbf.set.drop.function(), gbf.update.object(), gbf.get.key.desc.length(), gbf.set.key.desc.length() see also the return values of: gbf.drag.drop() and gbf.menu.selected()
open and close of nodes	gbf.init() and use the GBF.MENU.FILE.READ/OPEN options, gbf.get.open.depth(), gbf.get.open.strategy(), gbf.set.open.depth(), gbf.set.open.strategy()
printing	gbf.init(),gbf.set.tree.report.subtitle()
saving	gbf.init(), gbf.menu.selected()
selecting	gbf.init() and use the GBF.OPT.UNSELECT / GBF.OPT.NO.UNSELECT options
searching	gbf.get.search.startegy(), gbf.set.search.startegy(), gbf.set.search.sensitive(), gbf.set.search.set(), gbf.set.search.what()
sorting	gbf.get.sort.startegy(), gbf.set.sort.startegy()
tree walking	gbf.get.current.parent(), gbf.get.first.child(), gbf.get.next(), gbf.get.parent(), gbf.is.displayed()
window configuration	gbf.init() and use the GBF.OPT.1.WINDOW/GBF.OPT.2.WINDOWS, GBF.OPT.FORCE.SHADOW, GBF.OPT.<nr>.LABELS, GBF.OPT.FONT options, but see also gbf.get.resource(), gbf.set.resource(), gbf.add.object()
Fan Out

In some (very large) applications you may need to fan out to different functions on the same action. For example selecting a menu item on an object will (if nothing has been changed) call gbf.menu.selected(). However, if the main application has different kinds of leaf nodes, it must call the right function, so the code in the main application will look like:

function extern long gbf.menu.selected(long obj.id,

const string object.key(),

long object.value,

long menu.option)

{

long	retval

on case menu.option

case this.menu:	| note: this.menu must be

| defined using gbf.set.menu.item()

if <some condition 1> then

retval = do.menu.1(obj.id, object.key,object.value, menu.option)

else	if <some condition 2> then

retval = do.menu.2(obj.id, object.key,object.value, menu.option)

else	if <some condition 3> then

retval = do.menu.3(obj.id, object.key,object.value, menu.option)

…

endif

endif

endif

break

case …:

…

break

endcase

return (…)

}

In other words the fan out to the different functions is done in the main application itself.

Another solution to this problem is that the GBF will do the fan out. This can be accomplished by setting the default function for the object during the gbf.add.object() to a value which was returned from a preceding gbf.set.child.function(). Now this function will be called instead of gbf.menu.selected(). In other words the fan out is done by the GBF.

This mechanism can also be applied for:

Fan out on	Function to set the fan out function	Add to object
children (for interior nodes)	gbf.set.child.function	gbf.add.object
drag and drop	gbf.set.drag.drop	gbf.add.object
help	gbf.set.help.function	gbf.add.object
menu	gbf.set.menu.function, gbf.set.menu.item	gbf.add.object
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.add.header()

Syntax

long gbf.add.header(const string object.key(), const string object.description() mb, long object.value)

Restriction

This function may only be called by the application when the GBF issues a gbf.get.top.level() or a gbf.get.children() call.

Description

Adds a header to the object tree.

Same as: gbf.add.object(key, desc, value, GBF.HEADER)

Arguments

object.key()	The key of the object by which it is known in the application.
object.description()	The text that is displayed in the browser to describe the object.
object.value	The object.value can be used to further identify this object, which may be needed in case the object appears more than once in the tree. This object.value will be returned on subsequent function calls, such as gbf.get.children() or gbf.menu.selected(). Note that a value of 0 means something special, see gbf.update.object().
Return values

>= 0	Successful completion, returned value is the new obj.id
GBF.NO.MEMORY	Not enough memory
GBF.ILL.ICON	Illegal icon.set identification
GBF.ILL.FUNCTION	Illegal default.function.id, help.function.id or drop.function.id identification
GBF.ILL.LENGTH	Length of object.key exceeds the stored key length in GBF
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.NOT.EXPECTED	Function called when GBF did not expect this
Related Help topics

gbf.add.interior()

gbf.add.leaf()

gbf.add.object()

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.add.interior()

Syntax

long gbf.add.interior(const string object.key(), const string object.description() mb, long object.value)

Restriction

This function may only be called by the application when the GBF issues a gbf.get.top.level() or a gbf.get.children() call.

Description

Adds an interior node to the object tree.

Same as: gbf.add.object(key, desc, value, GBF.INTERIOR)

Arguments

object.key()	The key of the object by which it is known in the application.
object.description()	The text that is displayed in the browser to describe the object.
object.value	The object.value can be used to further identify this object, which may be needed in case the object appears more than once in the tree. This object.value will be returned on subsequent function calls, such as gbf.get.children() or gbf.menu.selected(). Note that a value of 0 means something special, see gbf.update.object().
Return values

>= 0	Successful completion, returned value is the new obj.id
GBF.NO.MEMORY	Not enough memory
GBF.ILL.ICON	Illegal icon.set identification
GBF.ILL.FUNCTION	Illegal default.function.id, help.function.id or drop.function.id identification
GBF.ILL.LENGTH	Length of object.key exceeds the stored key length in GBF
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.NOT.EXPECTED	Function called when GBF did not expect this
Related Help topics

gbf.add.header()

gbf.add.leaf()

gbf.add.object()

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.add.leaf()

Syntax

long gbf.add.leaf(const string object.key(), const string object.description() mb, long

object.value)

Restriction

This function may only be called by the application when the GBF issues a gbf.get.top.level() or a gbf.get.children() call.

Description

Adds a leaf node to the object tree.

Same as: gbf.add.object(key, desc, value, GBF.LEAF)

Arguments

object.key()	The key of the object by which it is known in the application.
object.description()	The text that is displayed in the browser to describe the object.
object.value	The object.value can be used to further identify this object, which may be needed in case the object appears more than once in the tree. This object.value will be returned on subsequent function calls, such as gbf.get.children() or gbf.menu.selected(). Note that a value of 0 means something special, see gbf.update.object().
Return values

>= 0	Successful completion, returned value is the new obj.id
GBF.NO.MEMORY	Not enough memory
GBF.ILL.ICON	Illegal icon.set identification
GBF.ILL.FUNCTION	Illegal default.function.id, help.function.id or drop.function.id identification
GBF.ILL.LENGTH	Length of object.key exceeds the stored key length in GBF
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.NOT.EXPECTED	Function called when GBF did not expect this
Related Help topics

gbf.add.header()

gbf.add.interior()

gbf.add.object()

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.add.object()

Syntax

long gbf.add.object(const string object.key(), const string object.description() mb, long

object.value, long obj.type, [long icon.set, long default.function.id, long help.function.id, long

drop.function.id, long menumask, long text.color, long line.style, long context.menu.id])

Restriction

This function may only be called by the application when the GBF issues a gbf.get.top.level() or a gbf.get.children() call.

Description

Adds a header, interior, or leaf node to the object tree.

Arguments

object.key()	The key of the object by which it is known in the application.
object.description()	The text that is displayed in the browser to describe the object.
object.value	The object.value can be used to further identify this object, which may be needed in case the object appears more than once in the tree. This object.value will be returned on subsequent function calls, such as gbf.get.children() or gbf.menu.selected(). Note that a value of 0 means something special, see gbf.update.object().
obj.type	Specify the object type by choosing one of the following: GBF.HEADER GBF.INTERIOR GBF.LEAF
icon.set	The value returned by a function depending on the obj.type: GBF.HEADER or GBF.LEAF: gbf.set.leaf.icon() GBF.INTERIOR: gbf.set.interior.icon()
default.function.id	The default.function.id  is an overloaded function identification. The actual function depends on whether or not this object is a leaf object. See Table default.function.id.
help.function.id	The help.function.id, if given and > 0, is the function to be called when help is asked and this object is currently selected. The value of help.function.id must be a value returned by a preceding gbf.set.help.function() call. When this help.function.id has an illegal value an error will be returned, and when GBF.OPT.DEBUG has been set then a debug error message will be given.
drop.function.id	The drop.function.id, if given and > 0, is the function to be called when other objects are dragged and dropped on this object. The value of drop.function.id must be a value returned by a preceding gbf.set.help.function() call. When this drop.function.id has an illegal value an error will be returned and when GBF.OPT.DEBUG has been set then a debug error message will be given.
menumask	The menumask is a bitmask to indicate which menu options should be disabled. Which bit disables which option is defined by setting a maskbit with gbf.set.menu.item().
text.color	The text.color, if given and <> 0 is the color with which the object.description will be written in the tree. The value must be given as an RGB (red-green-blue) value. The standard defines are RGB.RED, RGB.GREEN, RGB.YELLOW, RGB.CYAN, RGB.MAGENTA, RGB.BLUE, RGB.WHITE RGB.GRAY, RGB.DGRAY. There is a limited number of colors possible, so that when this limit is exceeded the standard colors will be used. Note that the RGB.BLACK happens to be 0, so that value is mapped onto the standard foreground color of the GBF (see also: gbf.get.resource() and  gbf.set.resource()) which by default is black. All used colors must have a description so in case the end user asks for Help on Colors they will get a short explanation of these colors, see also gbf.set.color().
line.style	The line.style, if given and <> GBF.LINE.SOLID (which is defined as: 0), indicates that the linestyle to the parent node must be used rather than a solid line. Currently only GBF.LINE.DASHED must be used, which draws dashed lines. Note that this information is not used when this gbf.add.object() call is made during a gbf.get.top.level() function call.
context.menu.id	The context.menu.id is used to couple a context menu to this specific object. The context menu and its context should be known before the call to gbf.start() . The context.menu.id is aquired through the function gbf.create.context.menu(). When used properly the end user can right-click on an item which makes a context menu appear for this specific node. When the option GBF.OPT.TREE.CONTROL is used, i.e. microsoft treeview, the functions gbf.set.leaf.icon() and gbf.set.interior.icon() have to be used to add the context menu. This is because the Microsoft Treeview couples the context menus to the icon groups.
Table - default.function.id

obj.type	default function.id	description
(any)	< 0	GBF.ILL.FUNCTION is returned If GBF.OPT.DEBUG is set a debug error message is given.
GBF.HEADER, GBF.LEAF	= 0	Default.function.id is ignored, and the default gbf.get.children() function is called when this object is opened
GBF.HEADER, GBF.LEAF	>  0	Default.function.id is the function to be called when the children of this object are asked for. The value of default.function.id must be a value returned by a preceding gbf.set.child.function() call.
GBF.INTERIOR	= 0	Default.function.id is ignored,  and the default gbf.menu.selected() function is called when this object is executed
GBF.INTERIOR	>  0	Default.function.id is the function to be called when this object is double clicked or selected and Return is hit. The value of default.function.id must be a value returned by a preceding gbf.set.menu.function() call.
When the return value is less than 0, the object is not added to the tree. The GBF however will not give any visible feedback, that is, there will be no popup generated, unless the GBF.OPT.DEBUG has been specified during gbf.init(). Also the GBF will continue working normally. It is the application responsibility to end the gbf.get.top.level(), or gbf.get.children() function with a non-zero value in these error cases.

When the object.description is too long, then only a debug error message is given (when GBF.OPT.DEBUG has been set), since this affects only the output on the screen.

When the object.key is too long then not only a debug error message is given (when GBF.OPT.DEBUG has been set) but also the error GBF.ILL.LENGTH is returned avoiding problems with truncated database keys.

Return values

>= 0	Successful completion, returned value is the new obj.id
GBF.NO.MEMORY	Not enough memory
GBF.ILL.ICON	Illegal icon.set identification
GBF.ILL.FUNCTION	Illegal default.function.id, help.function.id or drop.function.id identification
GBF.ILL.LENGTH	Length of object.key exceeds the stored key length in GBF
GBF.ILL.STATE	GBF is not in the correct state to deal with this function
GBF.NOT.EXPECTED	Function called when GBF did not expect this
Related Help topics

gbf.add.header()

gbf.add.interior()

gbf.add.leaf()

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.create.context.menu()

Syntax

long gbf.create.context.menu()

Description

This function creates a popup menu that is activated when the user clicks on the right mouse button and the mouse cursor is on a node. The popup menu is initially completely empty. The programmer has to add the popup menu items with the function gbf.set.menu.item(). After that, the developer has to bind this context menu to a certain object through a call to gbf.add.object() which has an argument context.menu.id for this so at the same time the node is created the context menu is assigned to it. Thus each node can have its own specific context menu.

The behaviour of each menu item is determined by the programmer who binds a function to the entry with the function gbf.set.menu.function().

The function gbf.create.context.menu() has to be called before the call to gbf.start().

Arguments

None.

Return values

>=0	Successful completion, returned value is the new popup menu.id
GBF.NO.MEMORY	Not enough memory
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.NOT.EXPECTED	Function called when GBF did not expect it
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.object.info()

Syntax

long gbf.get.object.info( long  obj.id, ref string key(), ref string description(), ref long value, ref long type)

Description

This function returns the information of the object obj.id. The returned information is the information set at the call to gbf.add.object().

Arguments

object.id	The unique object identification.
key()	The key of the object by which it is known in the application.
description()	The text that is displayed in the browser to describe the object.
value	The value of the object that is used to further identify this object (in case the object appears more than once in the tree). Note that a value of 0 means something special, see gbf.update.object() .
type	Specify the object type by choosing one of the following: • GBF.HEADER • GBF.INTERIOR • GBF.LEAF
Return values

0	Successful completion
GBF.ILL.OBJECT	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.delete.object()

Syntax

long gbf.delete.object(long obj.id)

Description

Deletes the given object, identified by obj.id, including all its child objects. When obj.id is GBF.ROOT.OBJECT then all child objects will be deleted.Note that in most cases a return value from gbf.menu.selected() will do better than using this function. The object identified by obj.id is deleted from the object tree, including all its children. Deleting obj.id in case when it is part of a multiple selection has some complications. If the obj.id is in the list of current selected objects, then it will also be removed from that list, which implies that the list is now at least one element shorter than it used to be and all elements that follow this element now have a smaller index. For example, if this obj.id used to have an index of 3 (see gbf.get.selected()) then the object which used to have index 4 will now have index 3, object 5 will now be object 4 and so on. Take care that when this to be deleted obj.id, has child objects that are also in the current selection, then these will be removed to. So that the list will get even shorter and the indices of the remaining objects may have changed more than just with 1.

Arguments

obj.id	The unique object identification.
Return values

0	Successful completion
GBF.ILL.OBJECT	Illegal obj.id given
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.error.string()

Syntax

string gbf.error.string(long error)

Description

Returns the string which represents the given error. This error should be a return value from any other GBF function call. This function translates such an (error) return value into its defined format.

For example:

sprintf$(“The error is: %s.”, gbf.error.string(GBF.NO.MEMORY))

will build the following string:

The error is: GBF.NO.MEMORY.

Arguments

error	The error return value.
Return value

String holding the mnemonic value (or define).

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.file.to.library()

Syntax

string gbf.file.to.library(const string filename())

Description

Uses the given filename to guess the object name of the session. It replaces the first “p" (of program file) in the file name with an “o” (of object file) and removes the trailing digit (usually a 0, but in fact the variant number). This macro can be used when all session functions, such as gbf.get.top.level(), gbf.get.children(), gbf.menu.selected() and so on, reside in the source file name filename. When these functions gbf.get.top.level() and so on reside in the current file, gbf.current.library() should be used.

Arguments

filename()	The program file name.
Return values

The run time object name of the object file.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.current.library()

Syntax

string gbf.current.library()

Description

The gbf.current.library() is a macro, which is defined as: gbf.file.to.library(__FILE__). It makes an educated guess based on the current filename what the object name is.

Arguments

None

Return values

The run time object name of the object file.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.current.parent()

Syntax

long gbf.get.current.parent()

Description

Returns the object identification (obj.id) of the current parent, which is the parent for which the children are now asked for by the GBF. In other words, the current parent is the parent to which objects will be added with the gbf.add.object() function. This function can thus only be called during a call back to gbf.get.top.level() (in which case the return value will be the special value: GBF.ROOT.OBJECT), or during a gbf.get.children(). Unlike with gbf.get.parent() function the parents key and value are not returned by this gbf.get.current.parent() function, since that information has already been supplied with the original (gbf.get.top.level() and) gbf.get.children() function call. In case the GBF has added a special extra parent then this extra node will not be returned by this function.

Note that since this function is available while the GBF is reading children, it may very well be that the tree is different than you would expect it to be. For example, not all children are already present, no deeper children are available and so on.

Arguments

None

Return values

other	Object id of current object, function called during gbf.get.children()
GBF.ROOT.OBJECT	Successful completion, no parent (or root is parent), function called during gbf.get.top.level()
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.cutcopy()

Syntax

long gbf.get.cutcopy(long index, ref string obj.key(), ref string obj.desc() mb, ref long obj.value)

Description

This function must only be used when a call back to the main application indicates that there are one or more objects in the cut, copy and paste buffers (see gbf.get.cutcopynr()). A further use of this function is immediately after the GBF has stopped (in other words the gbf.start() function call has completed) to get the current cut or copy objects, so in this case the GBF can be used as a zoom session to pick a specific object. This function then allows you to retrieve all the cut or copy objects one by one as it returns the cut or copy object at the given index. The object is identified by the obj.key, obj.desc and obj.value, which have been given to the GBF on a gbf.add.object() call.

Note that the internal GBF obj.id is not returned, since the object may no longer be present in the GBF, for example typically after the cut operation.

In case the application does not support multiple selection, this gbf.get.cutcopy() function can only be called with index set to 1.

Arguments

index	The index in the cut, copy and paste buffer. To retrieve the number of objects within the buffer, use the gbf.get.cutcopy.nr() function.
obj.key()	A reference to the key of the object by which it is known in the application.
obj.description()	A reference to the text that is displayed in the browser to describe the object.
obj.value	A reference to the value of the object that is used to further identify this object (in case the object is in the tree more than once). Note that a value of 0 means something special, see gbf.update.object().
Return values

0	Successful completion
GBF.ILL.OBJECT	Illegal index given
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related topics

gbf.get.cutcopy.nr()

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.cutcopy.nr()

Syntax

long gbf.get.cutcopy.nr()

Description

This function returns the number of objects that have been pasted into the so-called cut, copy and paste buffers. You can use the following user actions to fill the cut, copy and paste buffers:

•	The menu commands Edit->Cut and Edit->Copy

•	The keystrokes Ctrl+X and Ctrl+C

•	The buttons Cut and Paste

•	And all user defined menu commands that return a GBF.DO.CUTCOPY.INSERT (see gbf.menu.selected())

Arguments

None

Return values

= 0	Successful completion, but cut, copy & paste buffers are empty
> 0	Successful completion, returned value is number of objects in cut, copy & paste buffers
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related topics

gbf.get.cutcopy()

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.description()

Syntax

long gbf.get.description( long obj.id, ref string description() mb)

Description

This function returns the description of the given object. In other words the description with which the object has been created (gbf.add.object()) or last updated (gbf.update.object()).

Arguments

obj.id	The unique object identification.
description()	A reference to the description of the object.
Return values

0	Successful completion, description is valid
GBF.ILL.OBJECT	Illegal obj.id given, description is invalid
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.first.child()

Syntax

long gbf.get.first.child( long obj.id, long force.read, ref long child.id, ref string child.key(), ref long child.value, ref long child.type)

Description

This function returns the first child of the given object if the children are read by the GBF (see below). The returned child.id is the GBF child identification, to be used on subsequent gbf.get.parent(), gbf.get.first.child(), gbf.get.next() and gbf.update.object() function calls. The child is further identified by the child.key and child.value, which have been given to the GBF on a preceding gbf.add.object() call.

If the obj.id has no children at all, then GBF.NO.CHILDREN will be returned (and of course the other return values, such as child.id and so on. will not contain any valid information).

The force.read tells the GBF what to do when the children are not yet read:

Force.read	Description
true	First the children are read, using the gbf.get.children() function call, and the first read child is returned by this gbf.get.first.child() call as described above. That is, in this case it does not matter whether or not the children are already read before the main application issued this call (except for the GBF.NO.MEMORY return call).
false	The special return value GBF.NO.READ.CHILDREN is returned, and of course the child.id, child.key, child.value and obj.type are all invalid and should not be used

A very special value of obj.id may be used to indicate that the first child of the root object should be used. This special value is: GBF.ROOT.OBJECT. In this case an object which has been given to the GBF on the preceding gbf.add.object() from within the gbf.get.top.level() will be returned. The special successful completion return value GBF.LAST indicates that the child.id object returned is the only child object, which means that this child object has no further brothers, or in other words child.id cannot be used in a subsequent gbf.get.next() function call.

Warning

This function should not be used during a refresh, so not during a gbf.get.top.level() or a gbf.get.children() since that may lead to unpredictable results when, for example, using this function to get the children of the object for which the gbf.get.children() was started in the first place. Not refreshed children (in other words the dirty children) will not be returned.

Arguments

obj.id	The unique object identification.
force.read	Tells the GBF what to do when the children are not yet read. See table above with an explanation.
child.id	Returns the unique child (object) identification.
child.key	Returns the key of the child (object) by which it is known in the application.
child.value	Returns the value of the child (object) that is used to further identify this object (in case the object is more than once in the tree). Note that a value of 0 means something special, see gbf.update.object().
child.type	The type of node child.id:  • GBF.HEADER the returned child.id is a header node • GBF.INTERIOR the returned child.id is an interior node. • GBF.LEAF the returned child.id is a leaf node
Return values

0	Successful completion
GBF.CYCLE	Successful completion, but child.id reflects the same object as obj.id in this subtree due to a cycle.
GBF.LAST	Successful completion, and child.id is the only child
GBF.NO.CHILDREN	Successful completion, but obj.id does not have any children
GBF.NO.READ.CHILDREN	Successful completion, but the children of obj.id are not yet read
GBF.ILL.OBJECT	Illegal obj.id given
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.NO.MEMORY	Not enough memory to store all children
GBF.NOT.INTERIOR	Given obj.id is not an interior node, so it has no children
Related topics

gbf.get.next()

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.next()

Syntax

long gbf.get.next( long  obj.id, ref long next.id, ref string next.key(), ref long next.value, ref long next.type)

Description

Returns the next brother object of the given object. The returned next.id is the GBF identification, to be used on subsequent gbf.get.parent(), gbf.get.first.child(), gbf.get.next() and gbf.update.object() function calls. The next brother is further identified by the next.key and next.value, which have been given to the GBF on a preceding gbf.add.object() call.

The special successful completion return value GBF.LAST indicates that the next.id object returned is the last object, which means that this next.id cannot be used in a subsequent gbf.get.next() function call. If this is attempted, that is a gbf.get.next() on this last brother, then GBF.ILL.OBJECT will be returned.

Warning

This function should not be used during a refresh. In other words, not during a gbf.get.top.level() or a gbf.get.children() since that may lead to unpredictable results when, for example, you use this function to get the children of the object for which the gbf.get.children() was started in the first place. Not refreshed children (in other words the dirty children) will not be returned.

Arguments

obj.id	The unique object identification.
next.id	Returns the unique child (object) identification.
next.key()	Returns the key of the child (object) by which it is known in the application.
next.value	Returns the value of the child (object) that is used to further identify this object (in case the object appears more than once in the tree). Note that a value of 0 means something special, see gbf.update.object().
next.type	The type of node child.id:  • GBF.HEADER the returned child.id is a header node • GBF.INTERIOR the returned child.id is an interior node. • GBF.LEAF the returned child.id is a leaf node
Return values

0	Successful completion
GBF.LAST	Successful completion, and next.id is the last brother
GBF.ILL.OBJECT	Illegal obj.id given, or obj.id has no further brothers
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related topics

gbf.get.first.child()

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.key.desc.length()

Syntax

long gbf.get.key.desc.length(ref long key.length, ref long desc.length)

Description

Returns the length of the key of the object and the length of the description of the object. The default length for the object key is 64 and for the object description 60.

Arguments

key.length	Returns the length of the object key.
desc.length	Returns the length of the object description.
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.open.depth()

Syntax

long gbf.get.open.depth(ref long open.depth)

Description

Returns the current open and read depth. This open.depth is the number of levels the GBF will display when opening an interior node. When not all of these levels have been read yet, the GBF will read the necessary levels. The default value for open.depth  is 1.

This function may be used after the GBF run has finished to get the setting for this specific user, and restore them at the next run.

Arguments

open.depth	Returns the current open and read depth.
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.open.strategy()

Syntax

long gbf.get.open.strategy(ref long open.type)

Description

Returns the current automatic open and close schema.

This function may be used after the GBF run has finished to get the setting for this specific user, and restore them at the next run.

Arguments

open.type	Returns the current automatic open and close schema.
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.parent()

Syntax

long gbf.get.parent( long obj.id, ref long parent.id, ref string parent.key(), ref long parent.value)

Description

Returns the parent of the given object. The returned parent.id is the GBF parent identification, to be used on subsequent gbf.get.parent(), gbf.get.first.child(), gbf.get.next() and gbf.update.object() function calls. The parent is further identified by the parent.key and parent.value, which have been given to the GBF on a preceding gbf.add.object() call.

The special successful completion return value GBF.TOP.LEVEL indicates that the parent.id object returned resides at the top level, which means that this parent.id cannot be used in a subsequent gbf.get.parent() function call. In this case the parent.id, parent.key and the parent.value are not valid for the main application, since there is no parent of a top level object. Note that in case the GBF has added a special extra parent then this extra node will NOT be returned by this function.

Arguments

obj.id	The unique object identification.
parent.id	Returns the parent object identification.
parent.key()	Returns the parent object key.
parent.value	Returns the parent object value.
Return values

0	Successful completion
GBF.TOP.LEVEL	Successful completion, and parent.id is at top level
GBF.ILL.OBJECT	Illegal obj.id given
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related topics

gbf.get.current.parent()

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.previous()

Syntax

long gbf.get.previous( long  obj.id, ref long prev.id, ref string prev.key(), ref long prev.value, ref long prev.type)

Description

This function returns the previous brother object of the given object. The returned prev.id is the GBF identification, to be used on subsequent gbf.get.parent() , gbf.get.first.child() , gbf.get.next() and gbf.update.object() function call. The previous brother is further identified by the prev.key and prev.value, which have been given to the GBF on a preceding gbf.add.object() call.

The special successful completion return value GBF.LAST indicates that the prev.id object returned is the last object, which means that this prev.id cannot be used in a subsequent gbf.get.next() function call. If this is attempted, that is a gbf.get.previous() on this last brother, then GBF.ILL.OBJECT will be returned.

Warning

This function should not be used during a refresh, so not during a gbf.get.top.level() or a gbf.get.children() since that may lead to unpredictable results when for example using this function to get the children of the object for which the gbf.get.children() was started in the first place. Not refreshed children (in other words the dirty children) will not be returned.

Arguments

obj.id	The unique object identification.
prev.id	Returns the unique previous (object) identification.
prev.key	Returns the key of the previous (object) by which it is known in the application.
prev.value	Returns the value of the previous (object) that is used to further identify this object (in case the object is more than once in the tree). Note that a value of 0 means something special, see gbf.update.object().
prev.type	The type of node prev.id:  • GBF.HEADER the returned prev.id is a header node • GBF.INTERIOR the returned prev.id is an interior node. • GBF.LEAF the returned prev.id is a leaf node
Return values

0	Successful completion
GBF.LAST	Successful completion, and prev.id is the first previous brother
GBF.ILL.OBJECT	Illegal obj.id given, or obj.id has no further brothers
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.print.options()

Syntax

#include “ittgbfdefs”

long gbf.get.print.options(ref long print.options)

Description

Returns the current print options in print.options. For more details about the print.options see function gbf.set.print.options().

This function may be used after the GBF run has finished to get the setting for this specific user, and restore them at the next run.

Arguments

print.options	Returns the current print options.
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.read.levels()

Syntax

long gbf.get.read.levels( ref long read.levels, [ref long show.levels])

Description

Returns the current number of levels that will be read (and shown) when an application returns one of the restart return values (see: gbf.menu.selected(): for example the GBF.DO.RESTART.TREE). Initially these values are set to the values as supplied with the gbf.start() function call and can be changed using: gbf.set.read.level().

This function may be used after the GBF run has finished to get the setting for this specific user, and restore them at the next run.

Arguments

read.levels	Returns the current number of levels that will be read.
show.levels	Returns the current number of levels that will be shown.
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.refresh.strategy()

Syntax

long gbf.get.refresh.strategy( ref long refresh.rate, ref long refresh.type)

Description

Returns the current automatic refreshing schema. The two arguments will be used to store the values. If refresh.rate  is 0, then the refresh.type  may not be a valid type (see also gbf.set.refresh.strategy()).

This function may be used after the GBF run has finished to get the setting for this specific user, and restore them at the next run.

Arguments

refresh.rate	Retuns the refresh rate.
refresh.type	Returns the refresh type.
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.resource()

Syntax

#include “ittgbfdefs”

long gbf.get.resource( long resource.type, ref <type> resource.value,  …)

Description

Returns the current value for the given resource types. The arguments are given in name value pairs. For the possible resources see gbf.set.resource(). In almost all cases the <type> will be long (or a domain of basic type int, long, enumerate, bitset and so on.), except when the resource.type is DsNtitle, since in this case the <type> must be multi-byte string.

This function may be used after the GBF run has finished to get the setting for this specific user, and restore them at the next run.

Note

When the Tree Control is used, it may very well be that the actual requested resources are NOT supported by this Tree Control. Nevertheless in these cases no error will be returned.

Arguments

resource.type	The resource type that is used to get the value. For a list of resource types see gbf.set.resource().
resource.value	Returns the current value of the resource type.
Return values

0	Successful completion
GBF.ARG.ERROR	One or more of the given resource.value references is wrong
GBF.ILL.RESOURCE. TYPE	Unknown resource type specified
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related topics

gbf.set.resource()

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.search.strategy()

Syntax

long gbf.get.search.strategy(ref long search.strategy)

Description

Returns the current search strategy. The argument will be used to store the value. For more details about the search.strategy see function gbf.set.search.strategy().

This function may be used after the GBF run has finished, to get the setting for this specific user, and to restore the search.strategy at the next run.

Arguments

search.strategy	The current search strategy. For a list of search strategies, see gbf.set.search.strategy().
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.selected()

Syntax

long gbf.get.selected( long index, ref long obj.id, ref string obj.key(), ref long obj.value, ref long obj.type)

Description

This function must only be used when a call back to the main application indicates that there is one or more currently selected objects (see gbf.init(), gbf.menu.selected(), gbf.drag.drop() and so on). The function gbf.get.selected.nr() can be used to get the current number of selected objects. A further use of this function is immediately after the GBF has stopped (in other words the gbf.start() function call has completed) to get the current selected objects, so in this case the GBF can be used as zoom session to pick a specific object. This function then allows you to retrieve all the selected objects one by one as it returns the selected object at the given index. The returned obj.id is the GBF identification, to be used on subsequent gbf.get.parent(), gbf.get.first.child(), gbf.get.next() and gbf.update.object() function call. The object is further identified by the obj.key and obj.value, which have been given to the GBF on a preceding gbf.add.object() call.

The obj.type flag indicates the type of node obj.id:

GBF.LEAF	Returned obj.id is a leaf node
GBF.HEADER	Returned obj.id is a header node
GBF.INTERIOR	Returned obj.id is an interior node.
In case the functions gbf.menu.selected(), gbf.drag.drop(), and so on. indicate that there is only one object selected (in other words obj.id in those functions is greater than 0) then this gbf.get.selected() function may only be called with index set to 1.

Note that the order of objects, as well as the maximum valid index, changes when objects are deleted from the list using gbf.delete.object().

Arguments

index	The index in the range of selected objects
obj.id	Returns the object identification
obj.key()	Returns the object key
obj.value	Returns the object value
obj.type	Returns the object type
Return values

0	Successful completion
GBF.ILL.OBJECT	Illegal index given
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.selected.nr()

Syntax

long gbf.get.selected.nr()

Description

This function returns the current number of selected objects. It can be used to obtain the maximum allowed index for gbf.get.selected().

Arguments

None

Return values

> 0	Successful completion, the actual number of selected objects is returned
= 0	Successful completion, but currently no objects are selected
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.sort.strategy()

Syntax

long gbf.get.sort.strategy(ref long sort.strategy)

Description

This function returns the current sort strategy in sort.strategy. For more details about the sort.strategy see function gbf.set.sort.strategy().

This function may be used after the GBF run has finished to get the setting for this specific user, and restore them at the next run.

Arguments

sort.strategy	Returns the current sort strategy. For more information on the sort strategies see the gbf.set.sort.strategy() call.
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related topics

gbf.get.sort.strategy()

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.init()

Syntax

#include “ittgbfdefs”

long gbf.init(const string library(), const string title(), [long default.menu, long default.button, long default.options, long standard.button, long default.context])

Description

This function must be the first to be called, it initializes the global data structures of the GBF. It is not forbidden to reactivate a new run of the GBF in a session after a previous run of the GBF has terminated, the GBF has to clear its global variables again. This cleaning of the global variables cannot be done when leaving the GBF as at that point in time it must still be possible to get some information about the settings in order for the application to save and restore some user preferences, see for example gbf.get.refresh.strategy() and gbf.get.sort.strategy().

Arguments

library()	See Library
title()	See Title
default.menu	See Default.menu
default.button	See Default.button
default.options	See Default.option
standard.button	See Standard.button
default.context	See Default.context
Library

The library should be the name of the library, in general this is the application itself, which may or should contain the following call back functions (see gbf.current.library() and gbf.file.to.library() for an easy way to retrieve the library name):

Function	Mandatory or optional
gbf.drag.drop	Optional, but if not present, no drag and drop will be available
gbf.get.top.level	Mandatory
gbf.get.children	Optional, but then another function should be set with gbf.set.child.function()
gbf.help.selected	Optional, and another function may be set with gbf.set.help.function()
gbf.menu.selected	Optional, but then another function must be set with gbf.set.menu.function()
Title

The title will be the title of the window. It may be empty, in which case the window will have the following title:

<session.desc> [User: <user.name>]

or:

<prog.name>: <session.desc> [User: <user.name>]

where

prog.name	The program name as given by the global variable prog.name$ but this field will only be shown when the user has enabled the displaying of session codes in the titlebar
session.desc	The description of the program or session as obtained by the function call: tt.session.desc(prog.name$, …)
user.name	The name of the current user, as given by the global variable logname$
Default.menu

The flag default.menu specifies which of the following standard menus the browser will have (the words in italic are the actual menu text, taken from the message catalogue)

main menu flag	submenu flag	description
GBF.MENU.NONE		No default menu, not even a menu bar is created, so no custom menu headings or items can be added. Only keystrokes can be added.
GBF.MENU.BAR.ONLY		Create only an empty menu bar, so no standard menu is added, but allow for custom menu headings and items and keystrokes
GBF.MENU.FILE		file menu on menu bar
	GBF.MENU.FILE.RFSH	refresh in submenu
	GBF.MENU.FILE.OPEN	open all in submenu
	GBF.MENU.FILE.READ	read all in submenu
	GBF.MENU.FILE.PRNT	print options…and print in submenu
	GBF.MENU.FILE.SAVE	save in submenu
	GBF.MENU.FILE.QUIT	save + exit in submenu
	GBF.MENU.FILE.EXIT	exit program in submenu
	GBF.MENU.FILE.ALL	same as: GBF.MENU.FILE + GBF.MENU.FILE.RFSH + GBF.MENU.FILE.PRNT + GBF.MENU.FILE.EXIT
GBF.MENU.SRCH		find menu on menu title bar
	GBF.MENU.SRCH.DESC	Search by description… in submenu
	GBF.MENU.SRCH.CODE	Search by code… in submenu
	GBF.MENU.SRCH.FRST	Search for first in submenu
	GBF.MENU.SRCH.NEXT	Search for next in submenu
	GBF.MENU.SRCH.PREV	Search for previous in submenu
	GBF.MENU.SRCH.LAST	Search for last in submenu
	GBF.MENU.SRCH.CURR	Search in current set submenu, which is the same as GBF.SEARCH.CURRENT search strategy (see gbf.set.search.strategy())
	GBF.MENU.SRCH.READ	Read before search submenu item, which is the same as GBF.SEARCH.ALL search strategy (see gbf.set.search.strategy())
	GBF.MENU.SRCH.INS	Match case submenu item.
	GBF.MENU.SRCH.ALL	Same as: GBF.MENU.SRCH + GBF.MENU.SRCH.DESC + GBF.MENU.SRCH.CODE + GBF.MENU.SRCH.FRST + GBF.MENU.SRCH.NEXT + GBF.MENU.SRCH.PREV + GBF.MENU.SRCH.LAST + GBF.MENU.SRCH.CURR + GBF.MENU.SRCH.READ + GBF.MENU.SRCH.INS
GBF.MENU.SORT		sort menu on menu title bar
	GBF.MENU.SORT.NONE	none sorting in submenu
	GBF.MENU.SORT.DESC	sort by description in submenu
	GBF.MENU.SORT.CODE	sort by code in submenu
	GBF.MENU.SORT.ASC	sort ascending in submenu
	GBF.MENU.SORT.DSC	sort descending in submenu
	GBF.MENU.SORT.ALL	same as: GBF.MENU.SORT + GBF.MENU.SORT.NONE + GBF.MENU.SORT.DESC + GBF.MENU.SORT.CODE + GBF.MENU.SORT.ASC + GBF.MENU.SORT.DSC
GBF.MENU.HELP		help menu on menu bar
	GBF.MENU.HELP.CONT	help on contents in submenu
	GBF.MENU.HELP.SRCH	what’s this ? in submenu
	GBF.MENU.HELP.GBF	Color Descriptions…, Icon Descriptions… and using browser in submenu
	GBF.MENU.HELP.SESS	using session in submenu
	GBF.MENU.HELP.ABOUT	about…  in submenu
	GBF.MENU.HELP.ALL	same as: GBF.MENU.HELP + GBF.MENU.HELP.CONT + GBF.MENU.HELP.SRCH + GBF.MENU.HELP.GBF + GBF.MENU.HELP.SESS + GBF.MENU.HELP.ABOUT
GBF.MENU.ALL		same as: GBF.MENU.FILE.ALL + GBF.MENU.SRCH.ALL + GBF.MENU.SORT.ALL + GBF.MENU.HELP.ALL
Note that when the flag standard.button is given, then some more menu items may be added.

When no default.menu is given (so the gbf.init() is called with only 2 arguments) then the GBF.MENU.ALL flag is used as the current value for default.menu. It is required to have the main menu flag (once) as well as all submenu flags for those options that are wanted. When only specifying the submenu, it will not show up. It is advised to use the GBF.MENU.ALL flag as default.menu. Disabling of submenu items can also easily be accomplished by subtracting them from this default. For example if no printing is wanted then the default.menu could be given as: GBF.MENU.ALL – GBF.MENU.FILE.PRINT.

Also a whole menu can be disabled in this way. For example suppose sorting is not wanted, then give as the default.menu: GBF.MENU.ALL – GBF.MENU.SORT or GBF.MENU.ALL – GBF.MENU.SORT.ALL.

The original idea of the GBF was to have an object browser, which means more or less a read-only view on the objects. Updates on the object tree can only be done by the main application that is called on a menu selection or keystroke. This means that these updates, for example creating new objects or deleting old objects, should be done by the main application before the function gbf.menu.selected() returns from the main application back to the GBF. This mechanism ensures that the GBF always displays the information as it is in the database, that is, there is no need for a special save function. Nevertheless, it is possible to have Save and Save+Quit menus under the File menu heading. However, they must be specially be enabled, since they do not add up to the GBF.MENU.FILE.ALL or GBF.MENU.ALL, so the default.menu should be given as: GBF.MENU.ALL + GBF.MENU.FILE.SAVE + GBF.MENU.FILE.QUIT.

These Save and Save+Quit menu items will be insensitive (‘white’) when the save function gbf.menu.selected() could not be found in the given library.

Also the original idea of the GBF was to have a lazy read strategy, that is read only what needs to be shown (see also gbf.start() and gbf.set.search.strategy()). Nevertheless there are two non-standard menu entries:

Menu identification	Menu text	Keystroke	Description
GBF.MENU.FILE.READ	Read All	Ctrl+R	read the whole object tree, do not change view
GBF.MENU.FILE.OPEN	Open All	Ctrl+O	open all interior nodes whose children have already been read
By default, that is with the GBF.MENU.ALL or GBF.MENU.FILE.ALL these two options are excluded, so if they are wanted, they should be explicitly be included, so the default.menu should be given as: GBF.MENU.ALL + GBF.MENU.FILE.OPEN + GBF.MENU.FILE.READ

Note that when the open strategy (see: gbf.get.open.strategy()/gbf.set.open.strategy()) contains the GBF.OPEN.READALL option then it is advised to NOT use the GBF.MENU.FILE.READ.

The GBF.MENU.FILE.RFSH menu allows to refresh the contents of the GBF using the current refresh strategy as has been set by gbf.set.refresh.strategy(). Also the sort menu will reflect the current sorting strategy as has been set by gbf.set.sort.strategy() as well as the current selected sort strategy by the end user via the menu can be retrieved by the application using gbf.get.sort.strategy().

If the library does not contain the gbf.help.selected() function, then the help menu entries identified by GBF.MENU.HELP.CONT and GBF.MENU.HELP.SRCH will be insensitive (‘white’). When an help function is defined later on (see gbf.set.help.function()) these menu items will become selectable (‘black’).

Default.button

The flag default.button specifies which of the following standard buttons the browser will have:

Button flag	Description (see also: submenu flag column in menu flag table above)
GBF.BUTTON.NONE	no button bar will be created
GBF.BUTTON.BAR.ONLY	create only an empty button bar, so no standard buttons are added, but allow for custom buttons
GBF.BUTTON.FILE.QUIT	same as: GBF.MENU.FILE.QUIT
GBF.BUTTON.FILE.EXIT	same as: GBF.MENU.FILE.EXIT
GBF.BUTTON.FILE.PRNT	same as: GBF.MENU.FILE.PRNT
GBF.BUTTON.FILE.SAVE	same as: GBF.MENU.FILE.SAVE
GBF.BUTTON.CUT	application defined CUT button
GBF.BUTTON.UNDO	application defined UNDO button
GBF.BUTTON.INSERT	application defined INSERT button
GBF.BUTTON.COPY	application defined COPY button
GBF.BUTTON.PASTE	application defined PASTE button
GBF.BUTTON.DELETE	application defined DELETE button
GBF.BUTTON.SRCH.DESC	same as: GBF.MENU.SRCH.DESC
GBF.BUTTON.FRST	same as: keystroke HOME
GBF.BUTTON.PREV	same as: keystroke PageDown
GBF.BUTTON.NEXT	same as: keystroke PageUp
GBF.BUTTON.LAST	same as: keystroke END
GBF.BUTTON.GRP.NEW	application defined NEW GROUP button
GBF.BUTTON.GRP.FRST	go to oldest brother of selected object
GBF.BUTTON.GRP.PREV	same as: Ctrl+UpArrow
GBF.BUTTON.GRP.NEXT	same as: Ctrl+DownArrow
GBF.BUTTON.GRP.LAST	go to youngest brother of selected object
GBF.BUTTON.TEXT	application defined TEXT button
GBF.BUTTON.HELP	same as: GBF.MENU.HELP
GBF.BUTTON.ALL	same as: GBF.BUTTON.FILE.PRNT + GBF.BUTTON.FILE.SAVE + GBF.BUTTON.UNDO + GBF.BUTTON.INSERT + GBF.BUTTON.COPY + GBF.BUTTON.DELETE + GBF.BUTTON.SRCH.DESC+ GBF.BUTTON.FRST + GBF.BUTTON.PREV +  GBF.BUTTON.NEXT + GBF.BUTTON.LAST + GBF.BUTTON.GRP.NEW + GBF.BUTTON.GRP.FRST + GBF.BUTTON.GRP.PREV + GBF.BUTTON.GRP.NEXT + GBF.BUTTON.GRP.LAST + GBF.BUTTON.TEXT + GBF.BUTTON.HELP
Note that if the flag standard.button is given, then that value is first added (actually: bitwise ‘or’-ed) to this default.button flag to get all the buttons displayed.

When no default.button is given (so the gbf.init() is called with only 2 or 3 arguments) then the GBF.BUTTON.ALL flag is used as the current value for the default.button

The position of the button bar in the GBF window is taken from the User Data (table ttaad200, session ttaad2500m000). The order of the buttons is hard coded in the GBF, but will follow as far as possible the standard Baan order of buttons. When a button in the above table is marked as: application defined, then the application can use this button on his own behalf. The GBF will create these buttons (if specified of course) and makes them insensitive, since the GBF does not handle these buttons. The application should connect these buttons to a menu item, that can be done via the function gbf.set.menu.item() and setting the button mnemonic. This association will also enable the button.

It is recommended to use the following initial values for default.button:

GBF.BUTTON.ALL	when a button bar is wanted

GBF.BUTTON.NONE	when no button bar is wanted

Default.options

The flag default.options specifies further configuration of the Generic Browser Framework:

Option flag	Description
GBF.OPT.1.WINDOW	have one window
GBF.OPT.2.WINDOWS	Have 2 windows: left one for interior objects in tree format right one for leaf nodes in free format
GBF.OPT.NO.TREE.CONTROL	Use standard server based GBF drawing techniques
GBF.OPT.TREE.CONTROL	Use local windows Tree Control for drawing the actual tree
GBF.OPT.FONT.USER	Use default font of current user for object descriptions
GBF.OPT.FONT.FIXED	Use default FixedFont for object descriptions
GBF.OPT.FONT.VARIABLE	Use default VariableFont for object descriptions
GBF.OPT.FONT.RUNTIME	Allow dynamic font changes, so add Font… menu entry to standard GBF File menu
GBF.OPT.NO.LABELS	Do not have the status bar at the bottom of the browser
GBF.OPT.1.LABEL	Have only 1 label in the status bar
GBF.OPT.2.LABELS	Have only 2 labels in the status bar
GBF.OPT.3.LABELS	Have only 3 labels in the status bar
GBF.OPT.4.LABELS	Have only 4 labels in the status bar
GBF.OPT.5.LABELS	Have all 5 labels in the status bar
GBF.OPT.CYCLE	Display cycles (with a red line) on the window
GBF.OPT.DRAG.DROP	Main application supports drag and drop (see gbf.drag.drop())
GBF.OPT.MULTIPLE	Main application supports multiple select (see gbf.menu.selected())
GBF.OPT.PROGRESS	When doing a lot of nested reads (e.g. due to a “Read before search”, “Read All” or “Open All”) then a progress bar (or progress indicator) will be used to display the progress. This progress bar will have a STOP button allowing you to stop further reading. See also Special keystrokes during read.
GBF.OPT.NO.PROGRESS	No progress bar will ever be displayed
GBF.OPT.SHADOWS (Baan IV)	Draw shadow lines around the icons in the window, which make them look more like buttons.
GBF.OPT.FORCE.SHADOW  (Baan V)
GBF.OPT.UNSELECT	Unselect item when it is selected again. If not specified, the tree will behave as in the Microsoft tree.
GBF.OPT.NO.UNSELECT	Keep item selected when it is selected again.
GBF.OPT.NO.POP.UP	GBF should not generate error pop-ups on some problems: 1. memory shortage 2. icons not found in icon groups
GBF.OPT.POP.UP	GBF should always generate error pop-ups on problems
GBF.OPT.DEBUG	GBF now gives some more debugging information, such as 1. Unrecognized keystrokes are displayed in label1 2. Popup when calling a GBF function when it is not allowed (GBF is in wrong state) 3. Popup and same text in label1 when trying to call an unimplemented call back function, that is gbf.drag.drop(), gbf.get.top.level(), gbf.get.children(), gbf.help.selected(), or gbf.menu.selected() 4. Popup on unexpected failures when issuing a main application call back 5. Popup when a main application function requests termination of the GBF (in general always directly followed by the next popup) 6. Popup when actually terminating the GBF on user request (in general always directly after the previous pop up) 7. Popup when adding a menu item with a keystroke which is handled differently by GBF (see gbf.set.menu.item()) and ‘shift’ problem description). 8. Popup when gbf.add.object() is called with an illegal function identification, icon set or a too long description 9. The main window is immediately displayed when leaving this gbf.init() function. Otherwise displaying of the main window is postponed until the subsequent gbf.start()  function call. Use this option only when developing the main application
GBF.OPT.NO.DEBUG	GBF does not give developing debug popups
GBF.OPT.DEFAULT	GBF.OPT.1.WINDOW + GBF.OPT.SHADOWS + GBF.OPT.CYCLE + GBF.OPT.5.LABELS + GBF.OPT.UNSELECT + GBF.OPT.POP.UP + GBF.OPT.FONT.USER + GBF.OPT.PROGRESS + GBF.NO.TREE.CONTROL + GBF.OPT.NO.DEBUG
It is recommended to use the GBF.OPT.DEFAULT value for default.options flag.

When no default.options is given (so the gbf.init() is called with at most 4 arguments) then the GBF.OPT.DEFAULT flag is used as the current value for default.options.

Note that the GBF does not start running yet. This means that  the control still lies within the main application. The idea is that now other configuration functions are called by the application, such as:

•	adding new icons sets, see gbf.set.resource() and gbf.set.interior.icon()

•	add menus and keystrokes, see gbf.set.menu.function(), gbf.add.menu.head() and gbf.set.menu.item().

•	add new strategies to get child nodes, see gbf.add.child.function()

•	set the refresh policy, see gbf.set.refresh.strategy()

Standard.buttons

The standard.button indicate which standard GBF buttons and menu items are further handled by the application. This means that the GBF will create menu items and buttons for these buttons, and call the application to perform the actual operation, see gbf.menu.selected(). When no standard.button is given (so the gbf.init() is called with at most 5 arguments) then 0 is used as the current value for standard.button.

These buttons are:

Button flag	Menu heading	Menu item	Description
GBF.BUTTON.COPY	Edit	Copy	Copy the current selected object(s)
GBF.BUTTON.CUT	Edit	Cut	Cut (delete) the current selected object(s)
GBF.BUTTON.DELETE	Edit	Delete	Delete the current selected object(s)
GBF.BUTTON.GRP.NEW	Group	New	Insert a new group object
GBF.BUTTON.INSERT	File	New	Insert a new object
GBF.BUTTON.PASTE	Edit	Paste	Paste the contents of the cut/copy buffers into the current selected object
GBF.BUTTON.TEXT	Edit	Text	Start the text editor for the current selected object(s)
GBF.BUTTON.UNDO	Edit	Undo	Undo the last operation
For the Cut and Copy operation the GBF will put the current selected object into the so called cutcopy buffers and the application can use this buffered information, see also gbf.get.cutcopy.nr() and gbf.get.cutcopy(). Note that on a Delete and Cut the application still has to tell the GBF that these objects should be deleted.

Default.context

With this option a default context menu can be defined. The context menu behaves like the standard buttons and the standard menu. Again, these menu items are coupled with the item in the menu.bar and the toolbar. The following options can be used for the context menu:

context.menu flag	menu heading	menu item	description
GBF.BUTTON.COPY	Edit	Copy	Copy the current selected object(s)
GBF.BUTTON.CUT	Edit	Cut	Cut (delete) the current selected object(s)
GBF.BUTTON.DELETE	Edit	Delete	Delete the current selected object(s)
GBF.BUTTON.GRP.NEW	Group	New	Insert a new group object
GBF.BUTTON.INSERT	File	New	Insert a new object
GBF.BUTTON.PASTE	Edit	Paste	Paste the contents of the cut/copy buffers into the current selected object
GBF.BUTTON.TEXT	Edit	Text	Start the text editor for the current selected object(s)

The GBF will not take over control. This means that the browser will not be started, until the subsequent gbf.start() function call.

Return values

0	Success
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.NO.GRAPHICS	GBF can only run on graphical displays, not on ASCII only displays
GBF.NO.MEMORY	Not enough memory
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.is.displayed()

Syntax

long gbf.is.displayed(const long obj.id)

Description

Returns whether or not the given object is currently displayed. That is whether the obj.id can be seen and is not hidden because its parent is closed. This function can be used when walking through the object tree (see gbf.get.first.child(), gbf.get.next(),gbf.get.parent() and so on.). It is only checked whether the Generic Browser Framework has drawn the object on the virtual window, but note that it may not actually be visible (on the physical window) because the current view is currently displaying another part of that virtual window.

Arguments

obj.id	The object identification.
Return values

true	Successful completion, obj.id is currently displayed
false	Successful completion, obj.id is currently not displayed
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.button()

Syntax

long gbf.set.button( const string button.group(), const string normal.button(), const string selected.button(), const string insensitive.button(), const string button.name(), long menu.item, long add.space)

Description

Adds a button to the button bar.

A button needs three icons. These icons are all in the group identified by  button.group.

For Baan IV these three icons are for when the button is in the normal state (normal.button), when it is pushed (selected.button) and when it is currently not selectable (button.insensitive). When one or more of these icons do not exist, then another will be used instead. When no icon is available then an empty button will be used. The icons should be 20 x 20 pixels.

For Baan V only the normal.button icon is used, since the GUI will take care of creating a selected icon and an insensitive icon based on this normal.button. For compatibility reasons with older versions of the GBF the arguments selected.button and insensitive.button should nevertheless be given, but may of course be empty (in other words: “”) or the same as the normal.button. The normal.button icons should be 16 x 15 pixels. When it is larger all buttons on the button bar will have this larger size.

The menu.item is the menu item that will be used when the button is pushed. This menu.item should be a valid value from a preceding call to the function: gbf.set.menu.item().

In general the message used to get the menu.text for that function should be used as button.name for this function. The button has a name, identified by the message button.name. Note that the Help associated with this button.name message will be given as help when topic Help is asked for this button and this button is not associated to a menu item, in other words menu.item is 0 in this function call. In case help is asked for the button which is associated to a menu item, then the Help of that menu item will be activated rather than the Help for this button. When the button is pushed the value of the message button.name will be shown in the left-most message box and the function gbf.menu.selected() is called with this menu.item as identification. So for the application there is no difference whether the menu item is selected or this button is pushed.

Arguments

button.group()	A group name for the normal, selected and insensitive icon.
normal.button()	Baan(IV) The icon(20x20) to represent a button in its normal state Baan (V) The icon (16x15) to represent all states.
selected.button()	Baan(IV) The icon(20x20) to represent a button in its selected state Baan(V) -
insensitive.button()	Baan(IV) The icon(20x20) to represent a button in its insensitive (not selectable) state Baan (V) -
button.name()	The name of the button that is shown when the cursor is above this button or when help is asked on this button and No menu item is associated with this button.
menu.item	The associated menu command. This menu.item should be a valid value from a preceding call to the function: gbf.set.menu.item().
add.space	When the add.space is TRUE, then some extra white space is added before the button. When the add.space is FALSE then no extra white space is added before this new button.
Return values

> 0	Successful completion, actual button identification is returned
0	Should never happen
GBF.NO.MEMORY	Not enough memory
GBF.ILL.MENU.ID	Illegal menu.item value given
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.buttonstate()

Syntax

long gbf.set.buttonstate (  long button.id, long button.state )

Description

This function regulates the state of the standard buttons. This function can only be used if the default.button mask in the function gbf.init() is set with the standard buttons that need to be controlled. The old behavour of this option was that all the standard buttons were shown but disabled. This is still the case but now it is possible to enable or disable these buttons. When, however, the standard.button mask is used then it is not possible to adjust the standard buttons using this function. The GBF will then take over controll of these buttons. This is also default behaviour. To improve the accessibility to the buttons the application function gbf.on.selection() can be used. This function is called whenever a selection is made. It is clear that the user of this function is fully responsible for the behaviour of the buttons. The following table gives the buttons that can be manipulated through this function:

Button.id	Description
GBF.BUTTON.COPY	Copy the current selected object(s)
GBF.BUTTON.CUT	Cut (delete) the current selected object(s)
GBF.BUTTON.DELETE	Delete the current selected object(s)
GBF.BUTTON.GRP.NEW	Insert a new group object
GBF.BUTTON.INSERT	Insert a new object
GBF.BUTTON.PASTE	Paste the contents of the cut/copy buffers into the current selected object
GBF.BUTTON.TEXT	Start the text editor for the current selected object(s)
GBF.BUTTON.UNDO	Undo the last operation
Arguments

button.id	The identification of the button. See the list above.
button.state	The state of the buttons or button.state can be either GBF.DISABLED or GBF.ENABLED.
Return values

0	Success
GBF.NO.BUTTON	The requested button does not exist
GBF.ILL.BUTTON	The given button is illegal or not supported yet
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.color()

Syntax

long gbf.set.color(long color, const string color.desc())

Description

Adds a description to the given color. This color.desc should be a message, which will be displayed when the Help on colors (Help -> Color Descriptions…) is activated. These colors are the colors with which the actual object have been added to the GBF. See the text.color argument of the gbf.add.object() function. When using the same color then only the last color.description of this color will be remembered, even when this color.description is empty when a preceding color.description was not empty.

Arguments

color	The color RGB value
color.desc()	The description for this color
Return values

0	Success
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.child.function()

Syntax

long gbf.set.child.function(const string dll_id(), const string child.function.name(), long is.default)

Description

Adds a function to get children, to the set of all get children functions. If the child.function.name resides in the same source file as in which the call to this gbf.set.child.function() is made, then the function gbf.current.library() can be used, so use: gbf.set.child.function(gbf.current.library(), …).

Note that the child.function.name function must be defined as:

function extern long child.function.name(const string object.key(), long obj.value, long cur.level)

The dll_id  is tried to be loaded with the load_dll() function call, without overload. The value, if positive, which is returned by gbf.set.child.function() may be used in subsequent gbf.add.object() and/or gbf.update.object() calls to identify this child function.

Arguments

dll_id()	The name of the DLL.
child.function.name()	The name of the child function to find in the DLL.
is.default	If set to true this child function is set as the default child function. Only if it is successfully added.
Return values

> 1	The identification of this child function
= 1	Should never be returned, as 1 is the GBF default
GBF.ILL.DLL	llegal DLL specified
GBF.ILL.FUNCTION	Illegal function specified, or function not known in given DLL
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.NO.MEMORY	Not enough memory
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.drop.function()

Syntax

long gbf.set.drop.function(const string dll_id(), const string drop.function.name(), long is.default)

Description

Adds a new drag and drop function to the drag and drop functions. If the drop.function.name resides in the same source file as in which the call to this gbf.set.drop.function() is made, then the function gbf.current.library() can be used, so use: gbf.set.drop.function(gbf.current.library(), …). Note that the drop.function.name function must be defined as:

function extern long drop.function.name(long drag.obj, const string drag.key(), long drag.value, long drag.leaf, long drop.obj, const string drop.key(), long drop.value, long drop.leaf, long button.mode)

The dll_id  is tried to be loaded with the load_dll() function call, without overload. The value, if non negative, which is returned by gbf.set.drop.function() may be used in subsequent gbf.add.object() and/or gbf.update.object() calls to identify this special drag and drop function.

Arguments

dll_id()	The name of the DLL.
drop.function.name()	The name of the drag and drop function to find in the DLL.
is.default	If set to true this drag and drop function is used as the default, instead of a previous defined default drag and drop function or the standard gbf.drag.drop() function.
Return values

> 1	The identification of this drag and drop function
= 1	Should never be returned, as 1 is the GBF default
GBF.ILL.DLL	Illegal DLL specified
GBF.ILL.FUNCTION	Illegal function specified, or function not known in given DLL
GBF.NO.MEMORY	Not enough memory
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.header.icon()

Syntax

long gbf.set.header.icon(const string icon.group(), const string icon(), long is.default, [const string icon.desc()]

Description

Adds a header node icon to the set of header node icons. The value, if non negative, which is returned must be used in subsequent calls to identify this icon set. Empty icons, in other words empty strings, are not allowed.

Arguments

icon.group()	The icon.group must be a valid icon group as defined in table ttdsk900 Icon Groups using session ttdsk9100m000 Icon Groups.
icon()	Also the icon should be a valid icon as defined in table ttdsk903 Icons using session ttdsk9103m000 Icons.
is.default	If set to true this icon is used as the default header icon and the previous default header icon is overruled.
icon.desc()	The icon.desc should be a message containing the description of the icon. This icon.desc will be used when the GBF tree is printed. If not given or the message is empty then nothing will be printed. Also this text will be shown when help on icons is asked for via the Help -> Icon Descriptions.
Return values

> 1	The identification of this new icon set
= 1	Should never be returned, as 1 is the GBF default
GBF.NO.MEMORY	Not enough memory
GBF.ICON.EMPTY	Empty icon strings are not allowed
GBF.ICON.LOAD.ERROR	Could not load the icon
GBF.ILL.BITMAP	Illegal bitmap for icon (not a GIF file)
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.help.function()

Syntax

long gbf.set.help.function(const string dll_id(), const string help.function.name(), long is.default)

Description

This function adds a new help function to the help functions. If the help.function.name resides in the same source file as in which the call to this gbf.set.help.function() is made, then the function gbf.current.library() can be used, so use: gbf.set.help.function(gbf.current.library(), …). Note that the help.function.name function must be defined as:

function extern help.function.name(long obj.id, const string object.key(), long obj.value, long help.value)

The dll_id  is tried to be loaded with the load_dll() function call, without overload. The value, if positive, which is returned by gbf.set.help.function() may be used in subsequent gbf.add.object() calls to identify this special help function.

Arguments

dll_id()	The name of the DLL.
help.function.name()	The name of the help function to find in the DLL.
is.default	If set to true the function is used as the default help function instead of a previous defined default or the standard gbf.help.selected() function.
Return values

> 1	The identification of this help function
= 1	Should never be returned, as 1 is the GBF default
GBF.ILL.DLL	Illegal DLL specified
GBF.ILL.FUNCTION	Illegal function specified, or function not known in given DLL
GBF.NO.MEMORY	Not enough memory
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.interior.icon()

Syntax

long gbf.set.interior.icon(const string icon.group(), const string unselected.closed(), const string unselected.open(), const string selected.closed(), const string unselected.open(), long is.default, [const string icon.desc(), long context.menu]

Description

This function adds an interior node icon to the set of interior node icons. The return value, if non negative, must be used in subsequent gbf.add.object() calls to identify this icon set. Empty icons, in other words empty strings, are not allowed. It is not checked whether the icons are different, so for example it is allowed to have the same icon for both selected.open and selected.closed.

Note that when using the Tree Control this default icon will also be used as dummy unique root icon.

Arguments

icon.group()	The icon.group must be a valid icon group as defined in table ttdsk900 Icon Groups using session ttdsk9100m000 Icon Groups.
unselected.closed()	The unselected.closed, unselected.open, selected.closed, unselected.open should be valid icons as defined in table ttdsk903 Icons using session ttdsk9103m000 Icons.
unselected.open()
selected.closed()
unselected.open()
is.default	If set to true this icon is used as the default interior node icon and the previous default interior node icon is overruled.
icon.desc()	The icon.desc should be a message that contains the description of the icon. This icon.desc will be used when the GBF tree is printed. If not given or the message is empty then nothing will be printed. Also this text will be shown when help on icons is asked for via the Help -> Icon Descriptions.
context.menu	The context.menu argument is used when the user wants to couple a context menu to the icon (see gbf.create.context.menu() ). Every icon can have it’s own context.menu. This option will be overruled by the context menu given by gbf.add.object()
Return values

> 1	The identification of this new icon set
= 1	Should never be returned, as 1 is the GBF default
GBF.NO.MEMORY	Not enough memory
GBF.ICON.EMPTY	Empty icon strings are not allowed
GBF.ICON.LOAD.ERROR	Could not load the icon
GBF.ILL.BITMAP	Illegal bitmap for icon (not a GIF file)
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.desc.length()

Syntax

#include “ittgbfdefs”

long gbf.set.desc.length(long desc.length)

Description

The following functions are actually defines and they are defined as:

gbf.set.desc.length(desc.length) : gbf.set.key.desc.length(0, desc.length)

The gbf.set.key.desc.length() function adjusts the length of the key of an object and/or the length of the description of the object. The default length for the object key is 64 and for the object description is 60. A new value of 0 means that the associated length is not changed. So, for example, gbf.set.key.desc.length(100, 0) will increase the key length to 100 and leave the description length at 64 (see also the two macros defined at the top of this description).

All objects will use the same key length and description length. That is regardless of the object, for example: top level, interior, leaf object, the key length will always be the same. The same holds for the object description.

Note the bigger these lengths are made, the more memory is needed to store the objects. This means that making these too big will lead to memory problems further on. So, this function should also be used to shrink these lengths if they are too large for the current application. For example, if it is known that the key will never exceed 10 characters, then a gbf.set.key.length(10) should be made.

This function can only be called before any object has been created, so once a gbf.start()  has been given, this function will always return an error.

Arguments

desc.lentgh	The new description length.
Return values

0	Successful completion
GBF.ILL.LENGTH	Key.length and/or desc.length < not enough memory
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.key.length()

Syntax

#include “ittgbfdefs”

long gbf.set.key.length(long key.length)

Description

The following functions are actually defines and they are defined as:

gbf.set.key.length(key.length) : gbf.set.key.desc.length(key.length, 0)

The gbf.set.key.desc.length() function adjusts the length of the key of an object and/or the length of the description of the object. The default length for the object key is 64 and for the object description is 60. A new value of 0 means that the associated length is not changed. So, for example, gbf.set.key.desc.length(100, 0) will increase the key length to 100 and leave the description length at 64 (see also the two macros defined at the top of this description).

All objects will use the same key length and description length. That is regardless of the object, for example: top level, interior, leaf object, the key length will always be the same. The same holds for the object description.

Note the bigger these lengths are made, the more memory is needed to store the objects. This means that making these too big will lead to memory problems further on. So, this function should also be used to shrink these lengths if they are too large for the current application. For example, if it is known that the key will never exceed 10 characters, then a gbf.set.key.length(10) should be made.

This function can only be called before any object has been created, so once a gbf.start()  has been given, this function will always return an error.

Arguments

key.length	The new key length.
Return values

0	Successful completion
GBF.ILL.LENGTH	Key.length and/or desc.length < not enough memory
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.key.desc.length()

Syntax

#include “ittgbfdefs”

long gbf.set.key.desc.length(long key.length, long desc.length)

Description

This function is used to define:

gbf.set.desc.length(desc.length)

gbf.set.key.length(key.length)

The gbf.set.key.desc.length() function adjusts the length of the key of an object and/or the length of the description of the object. The default length for the object key is 64 and for the object description is 60. A new value of 0 means that the associated length is not changed. So for example gbf.set.key.desc.length(100, 0) will increase the key length to 100 and leave the description length at 64 (see also the two macros defined at the top of this description).

All objects will use the same key length and description length. That is regardless of the object, for example: top level, interior, leaf object, the key length will always be the same. The same holds for the object description.

Note the bigger these lengths are made the more memory is needed to store the objects. This means that making these too big will lead to memory problems further on. So, this function should also be used to shrink these lengths if they are too large for the current application. For example if it is known that the key will never exceed 10 characters, then a gbf.set.key.length(10) should be made.

This function can only be called before any object has been created, so once a gbf.start()  has been given, this function will always return an error.

Arguments

key.length	The new key length. If 0 nothing happens.
desc.length	The new description length. If 0 nothing happens.
Return values

0	Successful completion
GBF.ILL.LENGTH	Key.length and/or desc.length < not enough memory
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.label(), gbf.set.label1(), gbf.set.label2(), gbf.set.label3(), gbf.set.label4(), gbf.set.label5()

Syntax

#include “ittgbfdefs”

long gbf.set.label(const string label1(), const string label2(), const string label3(), const string label4(), const string label5())

long gbf.set.label1(const string label())

long gbf.set.label2(const string label())

long gbf.set.label3(const string label())

long gbf.set.label4(const string label())

long gbf.set.label5(const string label())

Description

The gbf.set.label<nr>() functions are actually defines and they are defined as:

gbf.set.label1(label)	gbf.set.label(label, “”, “”, “”, “”)
gbf.set.label2(label)	gbf.set.label( “”, label, “”, “”, “”)
gbf.set.label3(label)	gbf.set.label( “”, “”, label, “”, “”)
gbf.set.label4(label)	gbf.set.label( “”, “”, “”, label, “”)
gbf.set.label5(label)	gbf.set.label( “”, “”, “”, “”, label)
The gbf.set.label() function will write the labels to the browser window and will display them in the bottom of this window in a status bar box. Note that  the GBF will set and use these five labels for:

label id	description	dynamically changed by GBF
label1	current action, like searching…, loading… and so on.	yes
label2	key of the current selected item	yes
label3	company number	no
label4	company description	no
label5	current date	no
As can be seen from this table label1 and label2 are changed dynamically by the GBF:

•	when an action is started this action will be displayed in label1

•	when another object becomes selected the key of the selected object will be displayed in label2

The others are only set in gbf.init() and left unchanged by the GBF, hence an overwrite using this gbf.set.label() will be permanent.

Note that with gbf.init() it can be customized to have no labels or less than the default 5 labels, which implies that this function will return an error when trying to change a non existing label.

A value of “” for a label means that that label is not changed, where as any other value for which isspace() returns true (like “ ”), that label will be cleared on the screen.

Arguments gbf.set.label

label1()	The current action, like searching…, loading… and so on.
label2()	The key of the current selected item
label3()	The company number
label4()	The company description
label5()	The current date
Arguments gbf.set.labeln (n=1..5)

label()	For n: 1. The current action, like searching…and so on. 2. The key of the current selected item 3. The company number 4. The company description 5. The current date
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.NO.LABEL	Trying to change a non existing label
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.leaf.icon()

Syntax

long gbf.set.leaf.icon(const string icon.group(),const string unselected(),const string selected(), long is.default,[const string icon.desc(), long context.menu]

Description

Adds a leaf node icon to the set of leaf node icons. The return value, if positive, must be used in subsequent calls to identify this icon set. Empty icons, that is empty strings, are not allowed. It is not checked whether the icons are different, so for example it is allowed to have the same icon for both selected and unselected.

Note that when using the Tree Control this default icon will also be used as the dummy icon for the next level, to enable the displaying of the ‘+’.

Arguments

icon.group()	The icon.group must be a valid icon group as defined in table ttdsk900 Icon Groups using session ttdsk9100m000 Icon Groups.
unselected()	The unselected and selected should be valid icons as defined in table ttdsk903 Icons using session ttdsk9103m000 Icons.
selected()
is.default	Indicates whether (if the value is true) or not (if the value is false) to use this icon set (if it could successfully be added) as the default leaf node icon set. If is.default is true then the previous default icon set is overruled.
icon.desc()	A message that contains the description of the icon. This icon.desc will be used when the GBF tree is printed. If not given or the message is empty then nothing will be printed. Also this text will be shown when help on icons is asked for via the Help -> Icon Descriptions.
context.menu	The context.menu is used when the user wants to couple a context menu to the icon (see gbf.create.context.menu() ). Every icon can have it’s own context.menu. This option will be overruled by the context menu given by gbf.add.object().
Return values

> 1	The identification of this new icon set
= 1	Should never be returned, as 1 is the GBF default
GBF.NO.MEMORY	Not enough memory
GBF.ICON.EMPTY	Empty icon strings are not allowed
GBF.ICON.LOAD. ERROR	Could not load the icon
GBF.ILL.BITMAP	Illegal bitmap for icon (not a GIF file)
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.menu.function()

Syntax

long gbf.set.menu.function(const string dll_id(), const string  menu.function.id(), long is.default)

Description

This functions adds a function to the menu functions. For more information about dll_id and menu.function.id see the standard dll manual page in the programmers manual. The dll_id  is tried to be loaded with the load_dll() function call, without overload. The return value, if positive,  may be used in subsequent gbf.set.menu.item() calls to identify this special menu function.

dll_id()	The name of the DLL.
menu.function.id()	The menu function to find in the DLL.
is.default	Indicates whether (if the value is true) or not (if the value is false) to use this menu function (if it could successfully be added) as the default menu function instead of a previous defined default or the standard gbf.menu.selected() function.
Return values

> 1	The identification of this menu function
= 1	Should never be returned, as 1 is the GBF default
GBF.ILL.DLL	Illegal DLL specified
GBF.ILL.FUNCTION	Illegal function specified, or function not known in given DLL
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.NO.MEMORY	Not enough memory
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.menu.head()

Syntax

#include “ittgbfdefs”

long gbf.set.menu.head(string menu.text, [long maskbit, long multi.mask])

Description

Adds a menu header to the menu bar.

The value returned is to be used in subsequent gbf.set.menu.item() functions calls to add new menu items to this menu.

The number of menus is limited, currently fixed to 10. Note that the default menus are included (see gbf.init()) if they must be generated.

Arguments

menu.text	The menu.text should be a message. In this case the message is first translated to its actual value. So for example when menu.text is “ttgbfl0006” then this value will be: “File”. See also: gbf.set.menu.item(). The rest of this section keeps using the menu.text as if this is the actual menu header text.
maskbit	The maskbit can be used to disable a menu head depending on the menumask set with gbf.add.object(). The default value is 0.
multi.mask	The multi.mask is used to indicate what should happen when zero or more than one objects are selected. The least significant bit (lsb) is used to indicate whether the menu head should be disabled when no objects are selected. The second bit is used to indicate whether the menu head should be disabled when more than one objects are selected. The default value is GBF.ZERO.ENABLE + GBF.MULTI.ENABLE. The following defines should be used: • GBF.ZERO.ENABLE menu head is enabled  when zero objects are selected • GBF.ZERO.DISABLE menu head is disabled when zero objects are selected • GBF.MULTI.ENABLE menu head is enabled  when more than one object is selected • GBF.MULTI.DISABLE menu head is disabled when more than one object is selected
Return values

≥ 0	The identification of this new menu head
GBF.NO.MEMORY	Not enough memory
GBF.MENU.EMPTY	Empty menu text is not allowed
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.MAX.MENU	Too many menus defined
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.menu.item()

Syntax

long gbf.set.menu.item( long menu.id, const string menu.text(), const string keystroke(), [ long is.default, long menu.function.id, long maskbit, long multi.mask, long std.button])

Description

Adds a menu item to the set of menu items under the heading as identified by menu.id, as well as it allows to assign a keystroke combination (such as <Ctrl>+A and so on.) and connect it to a standard GBF button which the GBF does not service itself.

Arguments

menu.id

The menu identification.

menu.text() and keystroke()

Both menu.text and keystroke should be messages. In this case the message is first translated to its actual value. So for example when menu.text is “ttgbfl0006” then this value will be: “File”. The reason why messages are preferred over (hard coded) text is that help associated to that message will be called when the context help is asked for for this menu or keystroke. The rest of this section keeps using the menu.text and keystroke as if these are the actual menu texts and keystrokes.

At least menu.text or keystroke must be specified:

•	If the menu.text is “---” (3 minutes) then only a menu separator line is drawn in the menu which can never be selected and will generate a 0 return value. Note that the keystroke  should be empty in this case. Also only BW supports these menu separator lines, but no error is generated when using this under BX.
Note that for these menu separator also the function gbf.set.menu.seperator() should be used.

•	If the menu.text is non empty then the menu.id must be a value returned by a preceding gbf.set.menu.head() call. The keystroke may be empty, in which case no special keystroke recognition is done for this menu item. The keystroke  will be added to the menu on the right hand side of the menu entry.
The first character in the menu.id which is preceded by an ‘&’ will become underscored which allows you to select that menu item by typing that underscored character at the moment the menu is dropped down. This however is not considered to be a keystroke in this manual.

•	If the menu.text is empty, then the keystroke is added to an anonymous menu (menu.id is ignored in this case).

The return value of this function (if > 0) will be the value which is used when the menu is activated or the keystroke is recognized. The GBF does not check whether this keystroke is already in use (when the specified keystroke is not empty), and it is left undetermined which value will be given when the keystroke is recognized, in this ambiguous case.

The format of the keystroke is:

[Ctrl+][Shift+][Alt+](<single char>|F<nr>|<special key>)

where:

Ctrl	indicates that the Control key should be pressed
Shift	indicates that the Shift key should be pressed
Alt	indicates that the Alt key should be pressed
<single char>	is the single character to be pressed
F<nr>	denominates the function key with number <nr>, where 1 <= nr <= 12 on most keyboards.
<special key>	indicates a special key on the keyboard

So to make a Keystroke for <control><shift>F1 use: Ctrl+Shift+F1.

Note that the Shift should only be used for special keys or in combination with other modifiers, for example: Ctrl+F<nr> and Ctrl+Shift+A, not with single characters, as for example GBF cannot differentiate between ‘A’ and ‘Shift+A’ (but of course GBF differentiates between ‘a’ and ‘A’). These ‘Shift+a’ and ‘Shift+A’ are both converted to ‘A’. In debug mode (see gbf.init(), using GBF.OPT.DEBUG) these changes will be noted with a debug pop-up message.

The supported special keys are:

Special key	Key on keyboard	Needs modifier
Backspace	Backspace	yes
DEL or Delete	DEL or Delete	no
END	END	yes
ESC	ESC or ESCAPE	no
HOME	HOME	yes
INS	INS or Insert	no
PgDn	Page Down	yes
PgUp	Page Up	yes
Return or Enter	Return or Enter	yes
Space	space bar	no
TAB	Tab	no

The last column of the above table tells whether this key can be used by itself, for example ESC, or whether it needs a modifier, for example PgDn, since the standard key is already defined by the GBF. These modifiers are Ctrl, Shift, Alt or any combination of these. The denotations ‘Return’ and ‘Enter’ are two different names for the same key.

The is.default argument indicates whether (if the value is true) or not (if the value is false) to use this menu item as the default action. That is when double clicking on a leaf node or selecting and <Enter> (if it could successfully be added) as the default leaf node icon set. The default value is false.

When a menu item is selected or the keystroke is recognized, the following application function will be called by default:

gbf.menu.selected(string object.key, long object.value, long menu.option)

Where menu.option is the return value from the gbf.set.menu.item() function call. For further details about this function see gbf.menu.selected(). When another function has been defined to be called, that function will be called instead, but the arguments will be the same.

menu.function.id

The menu.function.id indicates, if > 0, the function to be called when the menu item is selected or keystroke is recognized, instead of the default function. This menu.function.id must be a value returned by a preceding gbf.set.menu.function() call. The default value is 0.

maskbit

If the maskbit is used in the menumask of the currently selected item the menu item will be disabled. The default value is 0.

multi.mask

The multi.mask is used to indicate what should happen when zero or more than one objects are selected. The lsb is used to indicate whether the menu item should be disabled when no objects are selected. The second bit is used to indicate whether the menu item should be disabled when more than one objects are selected. The default value is GBF.ZERO.ENABLE + GBF.MULTI.ENABLE. The following defines should be used:

GBF.ZERO.ENABLE	menu item is enabled  when zero objects are selected
GBF.ZERO.DISABLE	menu item is disabled when zero objects are selected
GBF.MULTI.ENABLE	menu item is enabled  when more than one object is selected
GBF.MULTI.DISABLE	menu item is disabled when more than one object is selected

std.button

The optional argument std.button should no longer be used. It is only here for compatibility reasons with older versions of the GBF. It is strongly advised to use the new mechanism (see flag standard.button of gbf.init()):

GBF mnemonic	GBF menu text	GBF keystroke
GBF.BUTTON.UNDO	Undo or Redo	Ctrl+Z
GBF.BUTTON.INSERT	Insert	Insert
GBF.BUTTON.COPY	Copy	Ctrl+C
GBF.BUTTON.DELETE	Delete	Delete
GBF.BUTTON.TEXT	Text	Ctrl+T
GBF.BUTTON.GRP.NEW		Ctrl+Shift+N

The number of submenus per menu is limited, currently fixed to 10.

Return value

> 1	The identification of this new menu entry
= 1	Should never be returned, as 1 is the GBF default
0	Menu separator line added
GBF.NO.MEMORY	Not enough memory
GBF.MENU.EMPTY	Empty menu text is not allowed
GBF.ILL.MENU.ID	Illegal menu.id value
GBF.ILL.FUNCTION	Illegal menu.function.id value
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.MAX.MENU	Too many submenus for this menu defined
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.menu.separator()

Syntax

long gbf.set.menu.separator(long menu.id)

Description

This function (actually: define) adds a separator to the given menu. A menu separator line is drawn in the menu which can never be selected and will generate a 0 return value. Also only BW supports these menu separator lines, but no error is generated when using this under BX.

Arguments

menu.id	The menu identification.
Return values

0	Menu separator line added
GBF.NO.MEMORY	Not enough memory
GBF.MENU.EMPTY	Empty menu text is not allowed
GBF.ILL.MENU.ID	Illegal menu.id value
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.MAX.MENU	Too many submenus for this menu defined
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.menu.start(), gbf.set.menu.checked(), gbf.set.menu.disabled(), gbf.set.menu.enabled(), gbf.set.menu.not.checked(), gbf
gbf.set.menu.start(), gbf.set.menu.checked(), gbf.set.menu.disabled(), gbf.set.menu.enabled(), gbf.set.menu.not.checked(), gbf.set.menu.not.radio(), gbf.set.menu.radio()

Syntax

long gbf.set.menu.state(long menu.id, long item.id, long disable, long checked, [long radio])

long gbf.set.menu.checked(long item.id)

long gbf.set.menu.disabled(long item.id)

long gbf.set.menu.enabled(long item.id)

long gbf.set.menu.not.checked(long item.id)

long gbf.set.menu.not.radio(long item.id)

long gbf.set.menu.radio(long item.id)

Description

The following functions are actual defines and they are defined as:

gbf.set.menu.checked(item.id)	gbf.set.menu.state(0, item.id, false, true)

gbf.set.menu.disabled(item.id)	gbf.set.menu.state(0, item.id, true, false)

gbf.set.menu.enabled(item.id)	gbf.set.menu.state(0, item.id, false, false)

gbf.set.menu.not.checked(item.id)	gbf.set.menu.state(0, item.id, false, false)

gbf.set.menu.not.radio(item.id)	gbf.set.menu.state(0, item.id, false, false, false)

gbf.set.menu.radio(item.id)	gbf.set.menu.state(0, item.id, false, false, true)

This function can disable a menu head or menu item and place or remove a ticmark on a menu item, which has been created using the gbf.set.menu.head() and/or gbf.set.menu.item() functions. Also a radio button (small circle) can be put in front of a menu items which has been created with the gbf.set.menu.item() function. For changing of the standard GBF menu items see function: gbf.set.std.menu(). To change only a item give 0 for the menu.id and to only change an menu give 0 for the item.id. When both values are 0 nothing will change.

The menu.id is the return value of the function gbf.set.menu.head() when that function was successfully completed.

Arguments: gbf.set.menu.state

menu.id	The menu identification.
item.id	The return value of the function gbf.set.menu.item() when that function was successful completed.
disable	When disable is set to true then the menu.id (if not 0) and item.id (if not 0) will become insensitive, that is white, which does not allow the end-user to select it. Also the associated keystroke with this item.id is not useable as long as this menu.id is disabled. The menu.id and item.id can become selectable again by using false for disable.
checked	When checked is true a ticmark will be added in front of the menu.id (if not 0) and item.id (if not 0). When checked is false these ticmarks will be removed again.
radio	When radio is given and true and checked  is false and item.id is not 0, then a radio button (small circle) will be added in front of this menu.id. These radio buttons should be used to indicate which of the possible alternatives is the current selected option. See, for example, the standard Find or Sort menu.
Arguments: gbf.set.menu.[enabled,disabled,radio,not radio, checked and not checked]

item.id	The return value of the function gbf.set.menu.item() when that function was successful completed.
Return values

0	Successful completion
GBF.ILL.MENU.ID	Unknown menu.id or item.id specified
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.open.depth()

Syntax

long gbf.set.open.depth(long open.depth)

Description

Sets the current open and read depth.

Arguments

open.depth	The number of levels the GBF will display when opening an interior node (double click on interior node or select one and press ENTER etc). When not all these levels have been read yet, the GBF will read the necessary levels. The default value for open.depth is 1. The special mnemonic GBF.OPEN.ALL can be used to identify that all available levels are read and opened, that is all the way down to either a cycle has been detected or a leaf node has been reached.
Return values

0	Successful completion
GBF.ILL.LEVEL	Open.depth is not a valid number of levels: < 0
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.open.strategy(), gbf.set.open.child(), gbf.set.open.read(), gbf.set.open.what()

Syntax

#include “ittgbfdefs”

long gbf.set.open.strategy(long open.strategy)

long gbf.set.open.child(long open.strategy)

long gbf.set.open.read(long open.strategy)

long gbf.set.open.what(long open.strategy)

Description

These functions set the open or close strategy, which is what the GBF should do when an interior node is closed and opened again as well as what should be done on the Open All menu item or Ctrl+O keystroke.

gbf.set.open.child()

The function gbf.set.open.child() deals with what to do with the children when reopening an interior node. The open.strategy in this case may be one of:

GBF.OPEN.AGAIN	Open again all interior nodes which were already open when the original interior node was closed. That is restore the full state after a close – reopen sequence.
GBF.OPEN.NONE	Do not open the interior nodes when reopening the original interior node, that is closes all these sub nodes.
GBF.OPEN.REFRESH	Delete all nodes beneath the given node, which implies that when reopening this node its children will be read again.

The default of GBF is to have the open.type  set to GBF.OPEN.AGAIN.

This open and close strategy is determined at the moment when the interior node gets closed (double click on open interior node and so on.). So when closing such a node, changing the open strategy and reopening that same interior node will reveal the contents of that node using the previous strategy and not the current strategy.

gbf.set.open.read()

The function gbf.set.open.read() deals with the Open All (Ctrl+O) menu item (keystroke) action. It determines what should be done on this action. The open.strategy in this case may be one of:

GBF.OPEN.NOREAD	Open only what is already known to the GBF. In other words use only that what has already been read before.
GBF.OPEN.READALL	First performs a read all (that is: menu item: Read All or keystroke Ctrl+R) and then open all nodes.
gbf.set.open.what()

The function gbf.set.open.what() determines on which object the Open All (Ctrl+O) menu item (keystroke) action works. The open.strategy in this case may be one of:

GBF.OPEN.ALLTREE	Operate on the whole object tree
GBF.OPEN.CURSEL	When one or more objects are currently selected then operate only on these objects, otherwise operate on the whole object tree.
gbf.set.open.strategy()

For the function gbf.set.open.strategy() the open.strategy is a combination of these three. These option flags should be add (‘+’) or bit.or()’ed. The default of GBF for gbf.set.open.strategy() is:

GBF.OPEN.AGAIN + GBF.OPEN.NOREAD + GBF.OPEN.ALLTREE.

Take care when using gbf.set.open.strategy()  in cases where only one or two of the open strategy parts has to be changed, since the other values should remain unchanged. This is in fact the reason why the other three functions are added. For example, when one wants to use the GBF.OPEN.READALL strategy the following code should be used:

function long force.open.read()

{

long retval, strategy

retval = gbf.get.open.strategy(strategy)

if retval < 0 then	return (retval)	endif

strategy = GBF.OPEN.READALL +

bit.and(strategy, bit.inv(GBF.OPEN.NOREAD

+ GBF.OPEN.READALL))

return (gbf.set.open.strategy(strategy))

}

Arguments

open.strategy	See above.
Return values

0	Successful completion
GBF.ILL.OPEN.TYPE	Unknown open.strategy specified
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.print.options()

Syntax

#include “ittgbfdefs”

long gbf.set.print.options(long print.options)

Description

This function sets the print options. The print.options is a combination of the following options. All these options should be added (bitwise) to construct the actual print.options value:

Whether or not icon descriptions must be printed:

GBF.PRINT.NO.ICONS	Icons descriptions will not be printed
GBF.PRINT.ICONS	Icons descriptions will be printed in between “<” and “>”

Whether or not the keys of the objects must be printed:

GBF.PRINT.NO.KEYS	Key of object will not be printed
GBF.PRINT.KEYS	Key of object will be printed in between “[“ and “]”

Whether the current tree contents must be printed or whether first the whole tree should be read:

GBF.PRINT.NO.READ	Print only what is already current in memory
GBF.PRINT.READ	Before printing, first read the whole tree

These options come in the place of the question dialog box whether to print the selection or the entire tree.

GBF.PRINT.NO.SEL	Do not ask anything, just print the current selection only
GBF.PRINT.SEL	Before printing ask whether to print all or only the current selection

The default print options of GBF is GBF.PRINT.DEFAULT which is:

GBF.PRINT.NO.ICONS + GBF.PRINT.NO.KEYS + GBF.PRINT.NO.READ + GBF.PRINT.SEL

However when an icon is added which has a description, then the GBF.PRINT.ICONS is automatically turned on.

Arguments

print.options	See above
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.read.levels()

Syntax

long gbf.set.read.levels(long read.levels, [ long show.levels])

Description

Sets the current number of levels that will be read (and shown) when an application returns one of the restart return values (see: gbf.menu.selected(): for example the GBF.DO.RESTART.TREE).

Arguments

read.levels	The number of levels that will be read.
show.levels	The number of levels that will be shown. (if not given show.levels will be set to the value of read.levels)
Return values

0	Successful completion
GBF.ILL.LEVEL	Read.levels and/or show.levels < 0
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.refresh.strategy()

Syntax

#include “ittgbfdefs”

long gbf.set.refresh.strategy(long refresh.rate, long refresh.type)

Description

Sets the automatic refresh rate and strategy, which means that after refresh.rate seconds the tree as maintained by GBF will be refreshed using the indicated strategy. A value of 0 for refresh.rate means no automatic refreshing and that refresh.type is ignored. The timing starts immediately after this function call when the GBF is already active, or immediately after the gbf.start()  call.

The default of GBF is to have a refresh.rate of 0.

Arguments

refresh.rate	The number of seconds between refreshes. A value of 0 means no automatic refreshing and that the refresh.type may be ignored.
refresh.type	The refresh.type may be one of the following: GBR.REFRESH.ALL refresh the whole tree, including what is not open GBF.REFRESH.OPEN refresh only what is open, so when an interior node is closed, its child nodes will not be updated.
Return values

0	Successful completion
GBF.ILL.REFRESH. RATE	Illegal (negative) refresh.rate
GBF.ILL.REFRESH. TYPE	Unknown refresh.type specified
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.resource()

Syntax

#include “ittgbfdefs”

long gbf.set.resource(long resource.type, <type> resource.value, …)

Description

This function sets the resources given by resource.type to the given resource.value. The arguments are given in name value pairs.

Table: Resource types

Resource name	Description	GBF default value
DsNbackground	background color	default BX input field background color
DsNforeground	foreground color	default BX input field foreground color
DsNfontSet	font	default BX font
DsNheigth	vertical size of the drawing area in pixels	480 or when the display is smaller than 480 the default is 400
DsNwidth	horizontal size of the drawing area in pixels	640 or when the display is smaller than 640 the default is 600
DsNtitle	title bar of main window of GBF	Session code (optionally), session description, user name
DsNx	horizontal position of the drawing area in pixels	Undetermined
DsNy	vertical position of the drawing area in pixels	Undetermined
GBF.LINE	color of normal and dashed lines to parent	same as DsNforeground
GBF.CYCLE	color of line which indicates cycles	red color (actually the define: RGB.RED)
GBF.HSEP	horizontal spacing between vertical line from parent to child icon in pixels	10
GBF.VSEP	vertical spacing between two consecutive rows (parent to first child, child to next child and so on.) in pixels	10
GBF.BUTTON	width and height of button	26
For a further explanation about the colors, see text.color in gbf.add.object().

In almost all cases the <type> will be long (or a domain of basic type int, long, enumerate, bitset and so on.), except when the resource.type is DsNtitle, since in this case the <type> must be multi-byte string.

Note that since Baan V the resource GBF.BUTTON is no longer valid, that is it is not possible to change the value. When this resource is obtained through the gbf.get.resource() then always the default value will be returned for backward compatibility reasons.

Arguments

resource.type	The resource type of which to set the value.
resource.value	The value for the resource type.
Return values

0	Successful completion
GBF.ILL.RESOURCE. TYPE	Unknown resource type specified
GBF.ILL.RESOURCE. VALUE	Value for given resource type is not valid
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related topics

gbf.get.resource()

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.search.strategy(), gbf.set.serach.headers(), gbf.set.search.sensitive(), gbf.set.search.set(), gbf.set.search.what()

Syntax

#include “ittgbfdefs”

long gbf.set.search.strategy(long search.strategy)

long gbf.set.search.headers(long search.strategy)

long gbf.set.search.sensitive(long search.strategy)

long gbf.set.search.set(long search.strategy)

long gbf.set.search.what(long search.strategy)

Description

The function gbf.set.search.strategy sets the search strategy, which means that starting with the next search, this strategy will be used.

gbf.set.search.set()

The function gbf.set.search.set() defines the set in which the wanted object is to be searched in. The search.strategy may be one of:

GBF.SEARCH.CURRENT	Use the current tree in memory, which may be an incomplete tree
GBR.SEARCH.ALL	Read the whole tree, which includes that what is not open, before searching
gbf.set.search.sensitive()

The function gbf.set.search.sensitive() defines whether or not the case must match. The search.strategy may be one of:

GBF.SEARCH.SENSITIVE	Use case sensitive searches, in other words an ‘a’ is different from an ‘A’
GBR.SEARCH.INSENSITIVE	Use case insensitive searches, in other words an ‘a’ is the same as an ‘A’
gbf.set.search.what()

The function gbf.set.search.what() defines what to search for. The search.strategy may be one of:

GBF.SEARCH.DESCRIPTION	Search in the descriptions of the objects
GBR.SEARCH.KEY	Search in the codes (or keys) of the objects
gbf.set.search.headers()

Finally the function gbf.set.search.headers() defines whether header objects (see: gbf.add.header()) should be included or excluded from the search. The search.strategy may be one of:

GBF.SEARCH.NO.HEADERS	Exclude header objects from the search
GBR.SEARCH.HEADERS	Include header objects in the search
gbf.set.search.strategy()

For the function gbf.set.search.strategy() the search.strategy is a combination of these three. These option flags should be add (‘+’) or bit.or()’ed. The default of GBF for gbf.set.search.strategy() is:

GBF.SEARCH.CURRENT + GBF.SEARCH.INSENSITIVE + GBF.SEARCH.DESCRIPTION + GBF.SEARCH.NO.HEADERS

Take care when using gbf.set.search.strategy()  in cases where only one or two the search strategy parts has to be changed since the other values should remain unchanged. This is in fact the reason why the other three functions are added. For example when one wants to use the GBF.SEARCH.INSENSITIVE strategy the following code should be used:

function long force.search.insensitive()

{

long retval, strategy

retval = gbf.get.search.strategy(strategy)

if retval < 0 then	return (retval)	endif

strategy = GBF.SEARCH.INSENSITIVE +

bit.and(strategy, bit.inv(GBF.SEARCH.SENSITIVE

+ GBF.SEARCH.INSENSITIVE))

return (gbf.set.search.strategy(strategy))

}

Note that when the search strategy is changed the submenu items under the search menu are also updated with the tic-mark showing the current search strategy (see gbf.init() menu options: GBF.MENU.SRCH.CURR, GBF.MENU.SRCH.READ and so on.).

Arguments

search.strategy	See above.
Return values

0	Successful completion
GBF.ILL.SEARCH. TYPE	Unknown search strategy
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.sort.strategy()

Syntax

#include “ittgbfdefs”

long gbf.set.sort.strategy(long sort.strategy)

Description

This function sets the automatic sort strategy, which tells the GBF how to sort the child nodes of an interior node. The sort.strategy  is the same for the whole tree, that is it is not possible to define different sort strategies for different interior nodes. If this is really wanted, then the application should be doing the sorting.

sort.startegy

The sort.strategy may be one of:

GBR.SORT.NONE	GBF does not sort itself, it uses the order in which the nodes are handed over
GBF.SORT.DESC	GBF will sort the nodes using the description
GBF.SORT.KEY	GBF will sort the node using the key
Apart from the item to be sorted on, also the sort order can be chosen. These options should be added to the sort.strategy. Possible values are:

GBF.SORT. ASCENDING	Ascending sorting
GBF.SORT. DESCENDING	Descending sorting
Finally you can also choose whether or not case insensitive sorting should be done. These options should be added to the sort strategy. Possible values are:

GBF.SORT.SENSITIVE	Make distinction between lower and upper case
GBF.SORT. INSENSITIVE	Make no distinction between lower and upper case
The default sort strategy of GBF is GBF.SORT.NONE.

Arguments

sort.strategy	See above.
Return values

0	Successful completion
GBF.ILL.SORT.TYPE	Unknown sort strategy specified
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.std.menu(), gbf.set.std.menu.checked(), gbf.set.std.menu.not.checked(), gbf.set.std.menu.enabled(), gbf.set.std.menu.
gbf.set.std.menu(), gbf.set.std.menu.checked(), gbf.set.std.menu.not.checked(), gbf.set.std.menu.enabled(), gbf.set.std.menu.disabled()

Syntax

long gbf.set.std.menu(long menu.pattern, long disable, long checked)

long gbf.set.std.menu.checked(long menu.pattern)

long gbf.set.std.menu.disabled(long menu.pattern)

long gbf.set.std.menu.enabled(long menu.pattern)

long gbf.set.std.menu.not.checked(long menu.pattern)

Description

The following functions are actual defines and they are defined as:

gbf.set.std.menu.checked(menu.pattern):	gbf.set.std.menu(menu.pattern, false, true)

gbf.set.std.menu.disabled(menu.pattern):	gbf.set.std.menu(menu.pattern, true, false)

gbf.set.std.menu.enabled(menu.pattern):	gbf.set.std.menu(menu.pattern, false, false)

gbf.set.std.menu.not.checked(menu.pattern):	gbf.set.std.menu(menu.pattern, false, false)

This function can disable standard GBF menu headings and/or menu items and place or remove a ticmark on a menu item, which has been created using the gbf.init() function. For changing of the customized menu headings and items see function: gbf.set.menu.state().

The menu.pattern holds the pattern of all standard menu items which should be updated. The pattern is build the same way as the default.menu argument in the gbf.init() function. So for example to disable all menu items one could use:

gbf.set.std.menu.disabled(GBF.MENU.ALL)

to disable the “Read All” and “Using Session”:

gbf.set.std.menu.disabled(GBF.MENU.FILE.READ + GBF.MENU.HELP.SESS)

When disable is set to true then all of the specified standard GBF menu items and headings will become insensitive, that is white, which does not allow the end-user to select it. Also the associated keystroke with this menu.pattern is NOT usable as long as these menu items are disabled. These standard GBF menu items can become selectable again by using false for disable.

When checked is true a ticmark will be added in front of all of the specified standard GBF menu items and headings. When checked is false these ticmarks will be removed again.

You can change a menu heading and/or menu item which has not been created during the gbf.init(). In this case no error will be returned, but of course nothing will be changed. Also all other created menu headings and items which are not specified in this menu.pattern will be left unchanged.

Note

It is strongly discouraged to manipulate menu entries that are otherwise dealt with by the GBF. These menu items are: all of the GBF.MENU.SRCH and GBF.MENU.SORT, as well as GBF.MENU.PRINT.

Arguments: gbf.set.std.menu

menu.pattern	The menu.pattern holds the pattern of all standard menu items which should be updated.
disabled	When disable is set to true all of the specified standard GBF menu items and headings will be disabled. Also the associated keystroke with this menu.pattern is not usable as long as these menu items are disabled. These standard GBF menu items can become selectable again by setting this parameter to false.
checked	If true a ticmark will be added in front of all of the specified standard GBF menu items and headings. When checked is set to false these ticmarks will be removed again.
Arguments: gbf.set.std.menu.checked, gbf.set.std.menu.not.checked, gbf.set.std.menu.enabled, gbf.set.std.menu.disabled

menu.pattern	The menu.pattern holds the pattern of all standard menu items which should be updated.
Return values

0	Successful completion
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.set.tree.report.subtitle()

Syntax

gbf.set.tree.report.subtitle(const string sub.title(80) mb)

Description

This function can be used to set the subtitle for the ASCII print report. The default value for this variable, which represents a subtitle for this report, is

"(<session code> <session description>)"

The presence of the <session code> depends on the user settings.

By means of this function an alternate subtitle can be set for ASCII print reports. It should be called during the initialization phase of any session that uses the GBF tree functionality.

Arguments

sub.title(80)	The subtitle for the ASCII print report.
Return values

None

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.start()

Syntax

long gbf.start([long read.levels, long show.levels])

Description

Activates the GBF,in other words it takes over control from the application. See also gbf.init() for more information.

read.levels

The gbf.start() function will first try to read the number of levels of the tree as specified with the read.levels argument. If the read.levels argument is not given, it is set to 1. The possibilities for read.levels and the actions are:

read.levels	description
< 0	return an error, GBF is not activated
GBF.READ.ALL	read all levels
1	read only top level
> 1	read up to the given number of levels

It is not considered an error when the specified read.levels cannot be read from the tree, thus when specifying too many levels which are not present in the actual tree.

show.levels

After this the number of levels contained in show.levels is displayed in the window. If the show.levels argument is not given, it is set to the value of read.levels. The possibilities for show.levels and the actions are:

show.levels	description
< 0	return an error, GBF is not activated
GBF.SHOW.ALL	show all levels which are read
<= read.levels	show up to the given number of levels
> read.levels	show up to read.levels

After this the main event loop is activated, effectively meaning that the GBF is now in control.

When the GBF is done it will return to the calling application, returning control to the main application.

Arguments

read.levels	See above.
show.levels	See above.
Return values

0	Successful completion
GBF.NO.MEMORY	Not enough memory
GBF.ILL.LEVEL	Illegal read.levels or show.levels given
GBF.ILL.STATE	GBF is not in the right state to deal with this function
GBF.CHILD.ABORT	Exited on a child request, see gbf.menu.action()
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.update.deffunc(), gbf.update.dropfunc(), gbf.update.desc(), gbf.update.icon(), gbf.update.menumask(), gbf.update.object()

Syntax

#include “ittgbfdefs”

long gbf.update.deffunc( long obj.id,  long default.function.id)

long gbf.update.dropfunc( long obj.id,  long drop.function.id)

long gbf.update.desc( long obj.id, const string object.description() mb)

long gbf.update.icon( long obj.id,  long icon.set)

long gbf.update.menumask( long obj.id,  long menumask)

long gbf.update.object( long obj.id, const string object.description() mb, [long icon.set, long default.function.id, long drop.function.id, long menumask, long text.color, long line.style ])

Restriction

These functions may only be called by the application when the GBF issues a call back to the main application, thus on a gbf.drag.drop(), gbf.menu.selected(), gbf.help.selected() or gbf.menu.selected() call. The object to be updated is identified by the given obj.id.

Description

All but gbf.update.object() are defines and these functions are defined as:

gbf.update.deffunc(obj.id, def.func)	gbf.update.object(obj.id, GBF.NO.UPD.DESC, GBF.NO.UPD.ICON, def.func, GBF.NO.UPD.FUNC, GBF.NO.UPD.MENU)
gbf.update.dropfunc(obj.id, drop.func)	gbf.update.object(obj.id, GBF.NO.UPD.DESC, GBF.NO.UPD.ICON, GBF.NO.UPD.FUNC, drop.func, GBF.NO.UPD.MENU)
gbf.update.desc(obj.id, description)	gbf.update.object(obj.id, description, GBF.NO.UPD.ICON, GBF.NO.UPD.FUNC, GBF.NO.UPD.FUNC, GBF.NO.UPD.MENU)
gbf.update.icon(obj.id, icon.set)	gbf.update.object(obj.id, GBF.NO.UPD.DESC, icon.set, GBF.NO.UPD.FUNC, GBF.NO.UPD.FUNC, GBF.NO.UPD.MENU)
gbf.update.menumask(obj.id, menu)	gbf.update.object(obj.id, GBF.NO.UPD.DESC, GBF.NO.UPD.ICON, GBF.NO.UPD.FUNC, GBF.NO.UPD.FUNC, menumask)
The gbf.update.object() function updates the given object, that is one or more of the attributes of the given obj.id are changed from what it was on its gbf.add.object() call, or any preceding  call. The items that can be updated are:

Arguments

obj.id	The obect identification
object.description	If GBF.NO.UPD.DESC, then the description will not be changed. Otherwise this will be the new description for this object. Note that any other value for which isspace()  returns true, such as for example: “ ”, the description will be invisible on the screen
icon.set	If GBF.USE.DEF.ICON then use the default icon, otherwise if GBF.NO.UPD.ICON, then the icon will not be changed, else this icon set will now be used
default.function.id	If GBF.USE.DEF.FUNC then use the default function, otherwise if GBF.NO.UPD.FUNC, then this function will not be changed, else this function will be used as the new default function (see gbf.add.object() for what the default function is supposed to do).
drop.function.id	If GBF.USE.DEF.FUNC then use the default function, otherwise if  GBF.NO.UPD.FUNC, then this function will not be changed, else this function will be used as the new drag and drop function (see gbf.add.object() for what the drag and drop function is supposed to do).
menumask	If GBF.NO.UPD.MENU then the menumask will not be changed, otherwise this will be the new menu mask
text.color	If 0 then the color of the text will not be changed (note: not even set to the default color), otherwise this will be the new color of the object.description text.
line.style	If given and GBF.LINE.SOLID (which happens to be 0) then a solid line will be used, otherwise a GBF.LINE.DASHED will draw dashed line to the parent. When this item is not given the object will use the line style it already had.
Of course more than one item can be changed in one call.

Return values

= 0	Successful completion
GBF.ILL.ICON	Illegal icon.set identification
GBF.ILL.FUNCTION	Illegal default.function.id or drop.function.id value
GBF.ILL.OBJECT	Illegal obj.id given
GBF.ILL.STATE	GBF is not in the right state to deal with this function
Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.bms.received()

Syntax

#include “ittgbfdefs”

long gbf.bms.received( long sender.id, const string mask(), const string mss(), long length)

Description

This function will be called by the GBF when the GBF receives a BMS message that it cannot handle itself. The application should now deal (or ignore) this message.

Note

The nature of these BMS messages is that they arrive at undeterminable times, so one should not assume that the message is related to the current selected object(s), so be very careful with actions or return values such as delete current selected object.

Arguments

sender.id	The Baan process which has send this message.
mask()	The mask with which the message has been send
mss()	The actual BMS message
length	The length of the message mss
Return values

The return value is treated in the same way as with the gbf.menu.selected() function call, but be very careful with operations on the current selected object.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.drag.drop()

Syntax

#include “ittgbfdefs”

long gbf.drag.drop( long drag.obj, const string drag.key(), long drag.value, long drag.type, long drop.obj, const string drop.key(), long drop.value, long drop.type, long button.mode)

Description

This function will be called by the GBF when a drag and drop operation has been performed by the end-user. Note that in order to receive these function calls, the GBF must be configured for drag and drop (see gbf.init()), otherwise it will not support drag and drop. Also when the GBF is not configured for multiple select, then always only one object can be dragged and dropped.

The drag.obj identifies the object(s) being dragged:

drag.obj.< 0	More that one object was currently selected when the drop was done and drag.obj contains the negative number of selected objects, that is: -drag.obj is the actual number of selected objects. So drag.obj in this case is NO valid object identification, but on the other hand drag.key, drag.value and drag.type contain the identification of the first selected object. All currently selected objects can be obtained using a gbf.get.selected() for each selected object. This case will only happen if the GBF is configured to support multiple select (see gbf.init())
drag.obj = 0	Cannot happen
drag.obj > 0	Precisely one object was selected when the drop was done and that object is identified by drag.obj as well as by the object.key and object.value, which have been given to the GBF on a preceding gbf.add.object() call, that includes the drop.type, which indicates the type of drag.obj. The given drag.obj identifies the object for the GBF and should be used only as object identification for other GBF functions like gbf.get.parent(), gbf.get.first.child(), gbf.get.next() and gbf.update.object().

The drop target, that is the object on which the selected objects are dropped, is identified by the drop.obj, drop.key, drop.value and drop.type, which have been given to the GBF on a preceding gbf.add.object() call.

The GBF will prevent dragging and dropping on or off header objects. In other words drag.type and/or drop.type will never be GBF.HEADER.

Note that the application may have defined other fetch child functions, in stead of this function, see gbf.set.child.function().Still the GBF assumes that the interface (incoming arguments as well as the return values) are exactly the same as defined here.

Arguments

drag.obj	See above.
drag.key()
drag.value
drag.type
drop.obj
drop.key()
drop.value
drop.type
button.mode	The button.mode indicates which keys are hold down, possible values: EVTSHIFTMASK and/or EVTCONTROLMASK, indicating that the Shift key and/or Ctrl key are/were pushed down at the moment of the drop.
Return values

The return value is treated in the same way as with the gbf.menu.selected() function call and it applies to both the dragged objects as well as to the drop object.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.children()

Syntax

#include “ittgbfdefs”

long gbf.get.children( const string object.key(), long object.value, long cur.level)

Description

This function will be called by the GBF whenever it has the need for the children of a specific parent, for example after a parent is opened or after a refresh.

Note that the application may have defined other fetch child functions, instead of this function, see gbf.set.child.function().Still the GBF assumes that the interface (incoming arguments as well as the return values) are exactly the same as defined here.

Using functions like gbf.get.first.child() and gbf.get.next() is dangerous and should be avoided, especially when the force.read is set to TRUE, since that may lead to recursive calls towards this gbf.get.children() function.

Arguments

object.key()	The parent is identified by the object.key and object.value, which have been given to the GBF on a preceding gbf.add.object() call. Note that in this particular call the obj.type argument must have been set to GBF.INTERIOR otherwise this function (gbf.get.children()) would not have been called for this object.
object.value
cur.level	The cur.level indicates the current level of the given object. The level is defined as: 1 for every object which is added to the GBF by a gbf.add.object() call when called from a gbf.get.top.level() function call  1 + cur.level for each child which is added to the GBF with gbf.add.object() when called from this gbf.get.children() call.
Return values

GBF.DO.CONTINUE or 0	Successful completion, GBF will continue working
GBF.DO.ABORT	Abort GBF, which will end the GBF and return with an error, see gbf.start()
GBF.DO.EXIT	Finish GBF, which will end the GBF and return with 0, see gbf.start()

Any return other than these values will be treated as if GBF.DO.ABORT has been returned

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.get.top.level()

Syntax

#include “ittgbfdefs”

long gbf.get.top.level()

Description

This function will be called by the GBF after it has been started to get the top level node(s).

The application should call for all nodes the function: gbf.add.object() with the appropriate arguments.

Arguments

None

Return values

GBF.DO.CONTINUE or 0	Successful completion, GBF will continue working
GBF.DO.ABORT	Abort GBF, which will end the GBF and return with an error, see gbf.start()
GBF.DO.EXIT	Finish GBF, which will end the GBF and return with 0, see gbf.start()

Any return other that these values will be treated as if GBF.DO.ABORT has been returned.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.help.selected()

Syntax

#include “ittgbfdefs”

void gbf.help.selected( long obj.id, const string object.key(), long object.value, long help.value)

Description

This function will be called when the object has been selected followed by a menu selection or a keystroke.

There are three possibilities for obj.id:

obj.id < 0	More that one object was currently selected when this menu item was chosen and obj.id contains the negative number of selected objects, that is: -obj.id is the actual number of selected objects. So obj.id in this case is NO valid object identification, but on the other hand object.key and object.value contain the identification of the first selected object. All currently selected objects can be obtained using a gbf.get.selected() for each selected object. This case will only happen if the GBF is configured to support multiple select (see gbf.init())
obj.id = 0	No object was currently selected when this menu entry was chosen, and object.key will be an empty string, that is isspace(object.key) is true.
obj.id > 0	Precisely one object was currently selected when this menu item was chosen and that object is identified by obj.id as well as by the object.key and object.value, which have been given to the GBF on a preceding gbf.add.object() call. The given obj.id identifies the object for the GBF and should be used only as object identification for other GBF functions.
The help.value identifies which help entry was chosen and what the end-user probably wants help on:

Menu entry	Help.value	Description (what to do)
Contents	GBF.MENU.HELP.CONT	give a table of contents of all available help within the current session that is using the GBF
What’s This?	GBF.MENU.HELP.SRCH	Starts the context sensitive help
Using Session	GBF.MENU.HELP.SESS	Give help of how to use the current session which is build using the GBF
The return value of this function is ignored, as it does not influence the normal flow of control of the application.

Arguments

obj.id	See above.
object.key()
object.value
help.value
Return values

None

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.menu.selected()

Syntax

#include “ittgbfdefs”

long gbf.menu.selected( long obj.id, const string object.key(), long object.value, long menu.option)

Description

This function will be called when the object has been selected followed by a menu selection or a keystroke.

obj.id

There are three possibilities for obj.id:

obj.id < 0	More that one object was currently selected when this menu item was chosen and obj.id contains the negative number of selected objects, that is: -obj.id is the actual number of selected objects. So obj.id in this case is NO valid object identification, but on the other hand object.key and object.value contain the identification of the first selected object. All currently selected objects can be obtained using a gbf.get.selected() for each selected object. This case will only happen if the GBF is configured to support multiple select (see gbf.init())
obj.id = 0	No object was currently selected when this menu entry was chosen, and object.key will be an empty string, that is isspace(object.key) is true.
obj.id > 0	Precisely one object was currently selected when this menu item was chosen and that object is identified by obj.id as well as by the object.key and object.value, which have been given to the GBF on a preceding gbf.add.object() call. The given obj.id identifies the object for the GBF and should be used only as object identification for other GBF functions like gbf.get.parent(), gbf.get.first.child(), gbf.get.next() and gbf.update.object().
menu.option

The selected menu item or keystroke is identified by the given menu.option, which has been returned by the GBF on a preceding gbd.set.menu.item() call or is one of the standard GBF buttons and menu items which are supported by the application (see argument standard.button of gbf.init()). The following table suggests what the application should do on these standard buttons:

Menu option	Description
GBF.BUTTON.COPY	Copy the current selected object(s)
GBF.BUTTON.CUT	Cut (delete) the current selected object(s)
GBF.BUTTON. DELETE	Delete the current selected object(s)
GBF.BUTTON.GRP. NEW	Insert a new group object
GBF.BUTTON.INSERT	Insert a new object
GBF.BUTTON.PASTE	Paste the contents of the cut/copy buffers into the current selected object
GBF.BUTTON.TEXT	Start the text editor for the current selected object(s)
GBF.BUTTON.UNDO	Undo the last operation
Note that the GBF will never delete objects by itself. So even after a GBF.BUTTON.CUT and/or GBF.BUTTON.DELETE action still a GBF.DO.DELETE.CURRENT (see below) must be returned. When the menu.option is GBF.BUTTON.COPY or GBF.BUTTON.CUT then the current selected object(s) are already stored in the so called Cut, Copy & Paste buffers, so there is no need to return a GBF.DO.CUTCOPY.INSERT return flag in these cases. Of course a return value of GBF.DO.CUTCOPY.CLEAR will indeed clear this buffer, even on this Cut or Copy operation.

After the application has been finished, the return value of this function to GBF will inform GBF what to do. There are a number of return categories defined, each having a number of different options. One flag of each group should be used to construct the full return value. These flags can be added (‘+’) or bitwise ‘or’ed.

Arguments

obj.id	See above.
object.key()
object.value
menu.option
Return values

category	define	description
redraw	GBF.DO.REDRAW.TREE	redraw the whole tree
refresh	GBF.DO.REFRESH.NONE	no refresh needed
	GBF.DO.REFRESH.CURRENT	refresh everything under the current selected object
	GBF.DO.REFRESH.LEVEL	refresh level on which current selected object resides
	GBF.DO.REFRESH.TREE	refresh the whole tree
restart	GBF.DO.RESTART.NONE	no restart needed
	GBF.DO.RESTART.CURRENT	restart everything under the current selected object
	GBF.DO.RESTART.LEVEL	restart level or which current selected object resides
	GBF.DO.RESTART.TREE	restart the whole tree
cut,. copy	GBF.DO.CUTCOPY.NONE	do nothing with the cut, copy paste buffers
& paste	GBF.DO.CUTCOPY.CLEAR	clear the cut, copy and paste buffers
	GBF.DO.CUTCOPY.INSERT	replace the contents of the cut, copy and clear buffers with the current selected objects Note: not needed after a GBF.BUTTON.CUT or GBF.BUTTON.COPY menu.option.
delete	GBF.DO.DELETE.NONE	do not delete object
	GBF.DO.DELETE.CURRENT	delete this occurrence of object, and if interior node all underlying nodes in this tree only
	GBF.DO.DELETE.GLOBAL	delete all occurrences of object from tree, and if interior node all underlying nodes in these trees only
level	GBF.DO.LEVEL.NONE	do not open or close anything
	GBF.DO.LEVEL.OPEN	open level only done for closed interior node, no operation in all other cases
	GBF.DO.LEVEL.CLOSE	close level only done for open interior node, no operation in all other cases
terminate	GBF.DO.CONTINUE	continue normal processing
	GBF.DO.ABORT	abort GBF, which will end the GBF and return with an error, see gbf.start()
	GBF.DO.EXIT	finish GBF, which will end the GBF and return with 0, see gbf.start()
	GBF.DO.NOT.EXIT	continue with processing (do NOT stop the GBF) rather than stopping. This should only be used when: gbf.save(…,…,…, GBF.MENU.FILE.QUIT) has been called.
The defines will be chosen such that a value of 0 means: do nothing special (not even a redraw or refresh of current object). In general all the above groups are mutual exclusive, that is using a member of one group does not affect using members from any other group. The only exception is that a member of the refresh group is ignored when a member of the restart group (other than GBF.DO.RESTART.NONE) is used.

In case of a multiple select, these options apply to all currently selected items except when one of the refresh or restart categories is used, as in this case always GBF.DO.REFRESH.TREE or GBF.DO.RESTART.TREE is used.

The difference between GBF.DO.RESTART.TREE and GBF.DO.REFRESH.TREE is that a

•	GBF.DO.REFRESH.TREE tries to keep the current view as similar as it is now on the screen. This is merge the (new) data from the application with which is already available in the GBF, and delete unretrieved data

•	GBF.DO.RESTART.TREE restarts the GBF from fresh, that is as if a gbf.start() has been executed, but see also: gbf.get.read.level() and gbf.set.read.level().

When no object is currently selected then also the GBF.DO.REFRESH.CURRENT and GBF.DO.REFRESH.LEVEL behave the same as a GBF.DO.REFRESH.TREE (refresh the whole tree). Similar w hen no object is currently selected then also the GBF.DO.RESTART.CURRENT and GBF.DO.RESTART.LEVEL behave the same as a GBF.DO.RESTART.TREE (restart the whole tree).

The difference between GBF.DO.REFRESH.CURRENT (or GBF.DO.REFRESH.LEVEL) is that the first one refreshes (or restarts) everything under the current selected object, excluding the current object, and the latter does a refresh (or restarts) on the parent object of the current selected object. So a GBF.DO.REFRESH.LEVEL does not refresh that parent, but refreshes all of its children, which includes the current selected object and all of its brother objects. Note that the current selected object can be updated using gbf.update() functions. The same applies to GBF.DO.RESTART.CURRENT and GBF.DO.RESTART.LEVEL.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.on.selection()

Syntax

#include “ittgbfdefs”

void gbf.on.selection( long obj.id, long obj.type, long transition)

Description

This function will be called when the user clicks on an object. It is made to create an extra possibility for the user to manipulate the state of the standard buttons through the function gbf.set.buttonstate() . It is recommended to use this function only for these purposes. The obj.id gives the id of the selected object and obj.type contains the type of the object, for example, GBF.LEAF, GBF.INTERIOR or GBF.HEADER. When an end user selects an object, the programmer wants to know to which state the object is moving. For example, when an object is selected and the end user clicks on the object again, then its transition state is that the object is moving from the selected state to the deselected state, thus the transition is GBF.DESELECT. When an object is not yet selected and the end user clicks on it, the transition state is from the unselected state to the selected state, thus the transition is GBF.SELECT.

Arguments

obj.id	The obj.id of the selected object.
obj.type	The type of object, GBF.LEAF, GBF.INTERIOR or GBF.HEADER.
transition	The new state, GBF.SELECT or GBF.DESELECT
Return Values

None.

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions


gbf.save()

Syntax

#include “ittgbfdefs”

long gbf.save( long obj.id, const string object.key(), long object.value, long save.type)

Description

This function will be called when the Save or Save+Exit menu has been called. The idea is that the main application should now save any unsaved data.

The save.type indicates for what reason this function is called. The possible values are:

Value	Menu item selected	Keystroke given	Button pressed
GBF.MENU.FILE.SAVE	Save	Ctrl+S	Save (floppy disk)
GBF.MENU.FILE.QUIT	Save+Exit	Ctrl+Q Alt+F4	Exit button on button bar X in top right hand corner
There are three possibilities for obj.id:

obj.id < 0	More that one object was currently selected when this menu item was chosen and obj.id contains the negative number of selected objects, that is: -obj.id is the actual number of selected objects. So obj.id in this case is no valid object identification, but on the other hand object.key and object.value contain the identification of the first selected object. All currently selected objects can be obtained using a gbf.get.selected() for each selected object. This case will only happen if the GBF is configured to support multiple select (see gbf.init())
obj.id = 0	No object was currently selected when this menu entry was chosen, and object.key will be an empty string, that is isspace(object.key) is true.
obj.id > 0	Precisely one object was currently selected when this menu item was chosen and that object is identified by obj.id as well as by the object.key and object.value, which have been given to the GBF on a preceding gbf.add.object() call. The given obj.id identifies the object for the GBF and should be used only as object identification for other GBF functions like gbf.get.parent(), gbf.get.first.child(), gbf.get.next() and gbf.update.object().
After the saving is done the return value of this function to GBF uses the same return patterns as gbf.menu.selected(). Note that even on GBF.MENU.FILE.QUIT the main application should still return to the GBF as the GBF will perform the exit part. This exit part may be skipped, that is the GBF will remain running when the special return value: GBF.DO.NOT.EXIT is returned in this case. This may be necessary when, for example, the user should have selected an object but they did not do so. The code in this case looks like:

function extern long gbf.save(…)

{

if (save.type = GBF.MENU.FILE.QUIT) and (obj.id = 0) then

| Please select at least one object before leaving

mess(“xxxxxxxxxx”, 1)

return (GBF.DO.NOT.EXIT)

endif

…

return (0)

}

Arguments

obj.id	See above.
object.key()
object.value
save.type
Return values

See gbf.menu.selected()

Related Help topics

Generic Browser Framework (GBF): overview

Generic Browser Framework: synopsis

Generic Browser Framework: typical usage

Generic Browser Framework: getting started

Generic Browser Framework: example

Generic Browser Framework: error codes and return values

Generic Browser Framework: standard menu items and function keys

Generic Browser Framework: messages and questions