iBaan ERP 5 - baansupport.com

iBaan ERP 5.2a Tools Technical Manual

A publication of:

Baan Development B.V. P.O.Box 143 3770 AC Barneveld The Netherlands

Printed in the Netherlands

© Baan Development B.V. 2002. 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.

Document Information

Code: U7795B US Group: User Documentation Edition: B Date: May, 2002

i

Tools Technical Manual

1 Database tools 1-1 General 1-1 bdbpre 1-1 bdbpost 1-6 bdbreconfig 1-11 refint 1-14

2 Database management 2-1 General 2-1 To access tables 2-1 tabledef6.2 2-1 fd6.2.package combination 2-2 Example table access (table and bshell on the same system) 2-2 Database drivers 2-2 To access tables on other systems 2-3 Audit trail 2-3 Database mirroring 2-3 Alternative databases 2-5 Communication protocols 2-5 Socket protocol 2-6 Local sockets 2-6 Remote sockets (only for database servers) 2-7 Pipes protocol 2-8 Message queue protocol 2-8 Example ipc_info file 2-9

3 Native language support 3-1 General 3-1 Composed characters 3-1 Conversion tables 3-2 Input conversion table 3-2 Output conversion table 3-2 Example of total conversion 3-2 NLS editor 3-4 Initial screen options 3-4 Maintenance of NLS conversion tables 3-5 NLS-related files 3-6

Table of contents

Table of contents

Tools Technical Manual ii

Terminal information file 3-6 Printer information file 3-7 Input and output conversion table 3-7 Terminal setup 3-8 Character sets and fonts 3-8 Sort tables 3-9 Shift tables 3-9 ISO 8859-1 character set (0-127) 3-10 DEC vt100/vt200 character set (0-127) 3-12 DEC vt100/vt200 character set (128-255) 3-14 List of compose sequences 3-16 Input/output table vt200 3-19 Output table 3-23 Printer output table MT910 HP Prestige character set 3-24 Overview of Esc/Ctrl codes 3-28

4 Information files 4-1 Terminal information file 4-1 Boolean entries 4-1 Numbers 4-2 Strings 4-3 Keys 4-9 Color support 4-12 To send colors separately 4-12 Colors in combination with code features 4-13 Parameterized strings 4-15 Example of terminal information files 4-17 Printer information files 4-22 Bar codes 4-27 Example of printer information file for the mt910 printer 4-30

5 User Interface (UI) page mode 5-1 Tab processing 5-2 Default Button handling 5-2 Event processing 5-2 How to select the UI page mode 5-4 How to mark UI objects as synchronizing fields 5-5

6 Customer-support tools 6-1 General 6-1 To log errors 6-1 Log file 6-1 Log-file layout 6-2 Log file maintenance 6-2

Table of contents

Tools Technical Manualiii

Submitting errors to customer support 6-2 Example error logging 6-3

7 Executable programs 7-1 Database management 7-1 General 7-1 Oracle 7-2 Informix 7-2 DB2 7-2 Logic server (bshell) 7-3 Bshell6.2 7-3 To debug the bshell during run time 7-4 Memory usage 7-8 Miscellaneous 7-9 bshcmd6.2 7-9 badmin6.2 7-12 Binary Logging And Tracing 7-12 Start Tracing 7-13 Log and trace options: 7-13 bls6.2 7-18 btop6.2 7-19 Installation 7-20 Development 7-20 Printer management 7-21 Shared memory 7-22 Network 7-22 TRITON Super Set 7-23 Middleware 7-24 UNIX equivalents 7-25 Miscellaneous 7-25

8 Errors 8-1 General 8-1 UNIX errors 8-1 Database errors 8-4

9 Shared memory management 9-1 General 9-1 To use the shared memory manager 9-1 Installation of shared memory 9-2 To create an entry in the shm_param file 9-2 Determine shared-memory parameters 9-3 To use shmvalues6.2 9-3 To use shmmanager6.2 9-4

Table of contents

Tools Technical Manual iv

To fill the entry in the shm_param parameter file 9-5 To install shared memory 9-6 To start shmtimer6.2 9-6 Error messages during installation 9-7 Syntax srdd_tab 9-9 To fill shared memory 9-10 Kernel requirements 9-11 General description of adjusting UNIX kernels 9-11 Kernel parameters 9-12 General kernel parameters 9-17 Example file shm_param parameter 9-18

10 Remote databases 10-1 General 10-1 Settings for remote database configurations 10-2 Local host 10-3 Remote 10-4 Local 10-4 tabledef6.2 10-5 User files 10-5 Remote 10-7 Local and remote tables 10-8 Settings for remote menus/forms/objects 10-8

11 Multibyte management 11-1 General 11-1 Triton Super Set 11-1 To use multibyte character sets 11-3 Installation 11-3 To print multibyte characters 11-3 Utilities 11-3 tsscomp6.2 11-3 tsscvt6.2 11-4 tssinfo6.2 11-5 Character set description 11-7 Locale information 11-9 Storage of multibyte characters 11-10

12 Audit management 12-1 General 12-1 Architecture 12-1 Auditing Process 12-2 Storage of audit-data 12-4 Sequence files 12-5

Table of contents

Tools Technical Manualv

Information file 12-5 Location of audit files 12-6 Other parameters of audit files 12-6 Audit management 12-7 Table data dictionary as seen by audit server 12-8 Commands logged by audit server 12-9 Data stored by audit server 12-9 Format of audit row 12-10 Examples of the audit row for various operations 12-12 Limit on the size of audit-data 12-13 Audit server 12-13 Long transactions and overflow file 12-13 Sequence termination 12-14 Sequence file maximum size reached 12-14 Table audit-data dictionary changed 12-15 Sequence terminated by user 12-16 Reusing sequence files 12-16 To lock a file 12-17 Limit on open files 12-17 To open large number of tables in a single session 12-18 Multisession support 12-19 File security for various audit management files 12-19 Audit server debugging options 12-19 To access transaction data 12-19 To create a transaction notification 12-20 Audit errors 12-21 Authorizations 12-21 Format of audit files 12-24 tabledef6.2 12-24 auditdef6.2 12-24 audit_spec file 12-25 audit_set 12-27 Information file 12-28 Sequence file 12-32

Table of contents

Tools Technical Manual vi

13 OLE Automation 13-1 General 13-1 iBaan ERP as OLE Automation server 13-2 Restrictions 13-4 Example: import iBaan ERP users 13-4 DLL function example 13-5 Visual Basic example 13-6 Example: To use iBaan ERP SQL 13-7 DLL information 13-7

1-1


This document is a reference guide explaining how you can customize the iBaan ERP application for use by specific organizations. It is intended for iBaan ERP application developers and application managers. You can use this reference guide to set up and maintain a iBaan ERP application.

In this document you will find information about database tools and management, audit management, native language support, and terminal information, as well as some limited installation instructions.

Chapter 1, “Database tools,” describes tools you can use for the following tasks:

Convert a database table to a sequential file (bdbpre). Create a database table from a sequential dump or append data to an existing

database table (bdbpost). Reconfigure a database table according to a new data dictionary

(bdbreconfig). Check or repair the referential integrity within the database (refint).

Chapter 2, “Database management,” discusses the working and usage of several protocols that can be used for local and remote communication.

Chapter 3, “Native language support,” describes the communication between the character set of a terminal and that of bshell6.2.

Chapter 4, “Information files,” describes terminal information files, which store information such as the type of terminal, terminal operations, how to access keys on the keyboard, color support, cursor movements, and whether code features are blinking, bold, or reversed.

About this document

Database tools

Tools Technical Manual 1-2

Chapter 5, “User Interface (UI) page mode,” describes the User Interface (UI) page mode in iBaan ERP. In normal mode, the 4GL Engine validates the entered data per field. In the UI page mode, the 4GL Engine validates data per page rather than per field. The synchronous interaction between the UI driver and the bshell is therefore significantly reduced, which improves response times.

Chapter 6, “Customer support tools,” describes two functions used to solve errors in a bshell environment: error logging and the bserel6.2 program. Error logging is to keep a record of error messages in a log file. The bserel6.2 program provides information on the BSE environment as installed on your system.

Chapter 7, “Executable programs,” describes all of the executable programs used for database management.

Chapter 8, “Errors,” describes all the errors that can occur when you are working in the iBaan ERP environment, and offers a solution.

Chapter 9, “Shared memory management,” discusses shared memory, which is a part of the internal memory intended for common usage.

Chapter 10, “Remote databases,” explains how the iBaan ERP client/server architecture enables the user to work with databases distributed over one or more systems.

Chapter 11, “Multibyte Management,” explains how to use the 32-bit wide character space, which has been implemented in iBaan ERP Tools to support all possible character sets.

Chapter 12, “Audit Management,” describes the audit management facility including the audit server, the audit management utility, and where audit-data is stored.

Chapter 13, “OLE Automation,” describes how iBaan ERP works with OLE Automation, an industry standard that applications use to expose their OLE objects to development tools, macro languages, and other applications that support OLE Automation.

1-1


General The database tools are designed for database management, and are independent of how the database is organized. At run time the system selects a database driver depending on the contents of the tabledef file. You can then use these database tools to:

Export data from a database table to a sequential (bdbpre) file.

Create a database table from a sequential file or append data to an existing database table (bdbpost).

Reconfigure a database table according to a new data dictionary (bdbreconfig).

Check or repair the referential integrity in the database (refint).

If there are changes in the data dictionary, for example, if fields are added or field lengths are changed, you can reconfigure the old table to a new one. The data dictionary changes are incorporated in the new table, which also contains the data dictionary table data.

The system you use determines the extension for the database tool name. For example, bdbpre used on Windows NT is called bdbpre.exe, and on UNIX it is called bdbpre6.2.

The following is a description of each of the database tools.

bdbpre NAME

bdbpre

Export database tables to a sequential file.

SYNOPSIS

bdbpre [–q output file] [–uUvVsxkK][–p package combination][–t sep][–o dir] [–d driver type][–N table [table ..]][–I file][–E file][–O file][ –M size] [–C company number list/range]

1 Database tools

Database tools


DESCRIPTION

The bdbpre tool reads tables for given company numbers, converts them into sequential data, and writes them to standard output. This output can be redirected to a file that can be used as input for bdbpost.

The bdbpre tool prints information such as names, the number of records, and any errors. You can use the –s option to suppress the messages produced by bdbpre at run time. This option is useful when you use the output of bdbpre as the direct input to bdbpost.

The fd6.2.package combination file is always used to search dictionary information. The following examples use $BSE/lib/tabledef6.2 to retrieve information about the database type and driver. If you want to use a specific database driver for a particular conversion, you can use the –d option. If you use this option, tabledef6.2 is not read.

You can use bdbpre in the following ways:

You can convert a database table for more than one company number by specifying a range of company numbers. For example:

bdbpre –Ntimcs099 –C000-005 > timcs099_dump

You can convert a database table for given company numbers. For example:

bdbpre –Ntimcs088 –C000 004 005 > timcs088_dump

You can specify all the tables for which you want to create a sequential dump in some file in package module format. The –I option reads this file and creates a sequential dump for each table and the specified company numbers. For example:

bdbpre –Iseqfile –C000-009 > BIGdump

The contents of the seqfile:

timcs001 timcs002 timcs003 ........ timcs099

Database tools

Tools Technical Manual1-3

In the previous examples the database driver type is retrieved from $BSE/lib/tabledef6.2. If you want to use a specific database driver for a particular conversion, you can use the –d option. If you use this option, tabledef6.2 is not read.

The database driver can be of the following types:

Oracle (oracle) Informix Online (informix) DB2 (db2) Microsoft SQL Server (msql)

The name between the brackets is the entry that must exist in the $BSE/lib/ipc_info file.

Enter the full database specification or host name, as in tabledef6.2 (optional with specifications). For example:

–d oracle –d "oracle(ORACLE_HOME=/usr/oracle)" –d bv8c03

Possible options:

–u/U Print usage information.

–v/V Print information about the version of bdbpre.

–p <package combination> The name of package combination that is to be used.

–s Suppress error messages, statistics, and so on.

–C Company numbers for given table, in two formats:

Specific company numbers (for example, 001 002 003) Range of company numbers (for example, 001-999)

–d Specify a specfic driver. If you use this option, bdbpre will bypass the tabledef6.2 file. You can use the -d option to copy data from one instance of a database to another, for example:

-d “oracle(ORACLE_HOME=/usr/oracle, ORACLE_SID=D1)”

Database tools


–N table [table …] Database table name. Specify specific table names, for example, –N timcs000 timcs016. The –I and –N options are mutually exclusive.

–I fileInput file with table names. The –I and –N options are mutually exclusive.

–E file Redirects errors to file.

–O file Redirects output to file.

–q output file Redirect terminal output to output file.

–k Drop table after dump is created.

–K Drop table. Create a backup before dropping. This is only possible if the DBMS supports this.

–t separator character Create a sequential file in which the fields have variable length and are separated by the separator character. Whenever you specify the –t option, a sequential file (.S) is created for each table in the current directory, unless the –o option is specified.

bdbpre –t"|" –Ntimcs016 –C000 creates timcs016000.S in the current directory. This sequential file is an ASCII dump of the timcs016000 table, in which case the fields are separated by |.

The options –x and –t are mutually exclusive.

–x Create a sequential file in which the fields have a fixed length and fields are not separated with a separator character. Whenever you specify the –x option, a sequential file (.F) is created for each table in the current directory, unless the –o option is specified.

bdbpre –x –Ntimcs016 –C000 creates timcs016000.F, which is an ASCII dump with fixed-length records.

–o Can be specified with the options –x and –t to specify the directory name in which the sequential file is created (.S or .F).

Database tools


–M size Can be specified with the options –o, –x and –t to specify the maximum size of the output file. If the maximum file size is reached, a new file (with an extenuation number) is opened and filled. Size can be specified as any number or a number followed by ‘K’, ‘M’ or ‘G’, for Kilo, Mega or Giga bytes. The maximum size is 2 Gbyte.

Convert Informix database to a sequential dump. The database driver is explicitly Informix. bdbpre –dinformix –Ntimcs000 –C000-004 > timcs000_dump

The database driver is retrieved from $BSE/lib/tabledef6.2 bdbpre –Ntimcs000 –C000-005 > timcs000_dump

Convert Oracle to Informix. bdbpre –s –doracle –Nttadv099 –C000 001 | bdbpost –dinformix

Transport the file to another database: bdbpre –t"|" –d"oracle(ORACLE_SID=D1)" –Ntimcs016 –C000 –oor_dump_016 bdbpre –x –dinformix –Ntimcs016 –C000 –oci_dump_016

SEE ALSO

bdbpost If you are piping your bdbpre output directly to bdbpost without giving the –s option, messages on the screen are jumbled.

If the –d option is not used, the database driver is taken from $BSE/lib/tabledef6.2. Also, if a remote driver is specified in tabledef6.2, the database table from the remote machine is used, but the data dictionary is taken from the current machine, which can cause great difficulties.

NOTES

Database tools


bdbpost NAME

bdbpost Create a database table from a sequential dump or append data to an existing database table.

SYNOPSIS

bdbpost [–I input file][–O output file][–{qE} output file] [–uUvVARfilxnmkK][–p package combination][–e file][–d driver type][–D seq_dir] [–t sep][-r row/trans][–c compnr][–C compnr range][pattern]

DESCRIPTION

The bdbpost tool reads from either the argument you supply or from the standard input and creates a new database table if that table does not exist. If the Append option is turned on, it appends data to an existing table. The bdbpost tool also compares current data dictionary information with the information in the dump. If they do not match, the bdbpost tool gives an error. If the current data dictionary is not present, it creates a data dictionary based on the dump. For each table, bdbpost prints information such as the table name, indexes, the number of records, and any errors.

The bdbpost tool is used to import data from sequential dumps that are created with bdbpre. For example:

This example shows how to use a sequential dump created by bdbpre.

On system 1:

bdbpre –Ntimcs016 –C000-003 > timcs_dump

On system 2:

bdbpost < timcs_dump

The next example shows the use of sequential dumps that are created with the –x or –t option of bdbpre. In this case the –D option is mandatory to retrieve the directory name in which .S or .F files are stored.

bdbpost –ddb2 –t"|" –D./seqdir bdbpost –dinformix –x –D./seqdir

–D directory name Specifies the directory in which the sequential files (files with extension .S or .F) are located. Use this option if you have used the –x or –t option of bdbpre to create the dump files.

Database tools


–t separator character Separator. Use this option if you want to import data from a sequential file that is created with the –t option of bdbpre. If you use the –t option, you will also have to specifiy a directory with the –D option.

If you want to load a sequential dump into the ttimcs016000 table, first move the sequential dump to the ttimcs directory with the name ttimcs016000.S. bdbpost –Dttimcs –t"|" searches for a .S file in ttimcs and if that file is found, the corresponding tables are created or appended.

With the –D option all .S files in that directory are used to create/append the tables, so be sure to remove unwanted .S files before running bdbpost.

–x If you want to load a sequential dump with fixed-length records without any separators. Use this option if you want to import data from a sequential file that is created with the –x option of bdbpre. If you use the –x option you must also specifiy a directory with the –D option.

Suppose you have used bdbpre to create sequential dumps in the directory dumps. bdbpost –D –x searches for .F files in dumps and for each file found, the corresponding table is created or appended.

In some of these examples the database driver type is retrieved from $BSE/lib/tabledef6.2. If you want to use a specific database driver for a particular conversion, you can use the –d option.

The database driver can be of the following types:

DB2 (db2). Oracle (oracle). Informix Online (informix). Microsoft-SQL Server (msql).

Enter the driver name of the database driver between the parentheses. See also the section “bdbpre.”

The following parameters can be used for bdbpost:


–v/V Print information about the version of bdbpost.

–p package combination The name of the package combination to be used.

EXAMPLE

CAUTION

EXAMPLE

Database tools


<pattern> Pattern to specify tables that are filtered out of the dump. Wildcards such as * and ? are allowed.

–c Company number for the tables to be created.

–C Range of company numbers on which to perform the bdbpost operation. This must be the last option specified in the command, other than the <pattern> option.

–d Specify a specfic driver. If you use this option bdbpre bypasses the tabledef6.2 file. You can use the -d option to copy data from one instance of a database to another, for example:


–x Import files with fixed length records. Use this option to import files created with the –x option of bdbpre.

–D directory name Specifies the directory that contains the files that must be imported.

–e file File to store the names of unsuccessfully created tables.

–k The existing tables are dropped.

–K The existing tables are dropped after a backup is made (if DBMS supports this).

–l Display contents of the dump file.

–I file Redirects input from file.

–O file Redirects output to file.

–E error Redirects errors to error.

–q output file Redirect terminal output to output file.

Database tools


–m Disable domain constraints.

–i Ignore domain range error and skip record.

–n Ignore referential integrity constraints.

–A Append to an existing table. If duplicate records exist, do not overwrite them from the dump. Create table if it does not exist.

–R Append to an existing table or create a new one. If a record already exists, the record in the dump replaces it. A summary is given at the end. Note that only the existence of the primary key is checked. If a primary key exists, the record is replaced. If the primary key does not exists but a secondary key exists, error 100 (duplicate record) occurs.

–t separator character Specify the used separator. Use this option if the dump file was created with the –t option of bdbpre.

–f Fast mode. Tables are created by first inserting all rows and then creating the indexes (if DBMS supports this). When using the –f option be aware of the following:

Interrupting bdbpost results in table inconsistency. An index cannot be created in case of a duplicate conflict. For large tables, the adding of indexes can take a long time (> 15 minutes).

–M Can be specified with the options –x, -t or –I to specify that the input file consists of multiple files. See also the –M option of bdbpre.

–r rows/transaction Defines after which number of inserted rows a commit is performed. The default value is 100. A number below 100 is changed to 100.

bdbpre –Nttadv000 –C000-010 > dump

bdbpost < dump Creates all tables in dump

bdbpost –l < dump Gives you names of tables in dump

EXAMPLES

Database tools


bdbpost –C000-005 < dump Creates tables only in the given company range

bdbpre –doracle –Nticom000 –C000-010 > dump

bdbpost –C000-005 ticom* < dump Creates tables only in the given company range and where the table name matches the ticom pattern.

bdbpost –R –C000-005 ttadv* < dump Creates/appends tables only in the given company range and where the table name matches the ttadv pattern. If duplicate records exist, they are replaced by records from the dump.

bdbpre –dinformix –Nttadv099 –C000-999 | bdbpost –ddb2 Converting from one database to another.

If a remote driver is specified in tabledef6.2, the database table from the remote machine is used but the data dictionary is taken from the current machine, which can cause great difficulties.

When the –m or –n option is used, the data in the database can violate the Baan integrity constraints. Data can violate the Baan domains or it can violate Baan referential integrity.

SEE ALSO

bdbpre

CAUTION

Database tools


bdbreconfig NAME

bdbreconfig

Reconfigure database table according to new data dictionary.

SYNOPSIS

bdbreconfig [–uUvVscinmfTZ][-r rows/trans][–t dir][–o file][–e file][–d driver type][–N table [table [..]] [–I file][–O file][–E file][–M size] [–p package combination] [–C company numbers]

DESCRIPTION

The bdbreconfig tool reads a table name and company numbers as arguments and converts them into a new table definition that matches a new data dictionary definition. The bdbreconfig tool requires the following:

A new data dictionary with a new extension. The current data dictionary (for example dtimcs016). Tables matching those in the current data dictionary.

After successful completion, old tables are dropped and new tables are created.

The bdbreconfig tool finds the optimum way to reconfigure. If there is no real change in the old and new data dictionaries, it prints the message “No conversion required.” It also sees to it that a database remains consistent.

You can perform some reconfigurations by modifying the old data dictionary. Otherwise the reconfiguration steps are:

1 Compare the current and the new data dictionaries.

2 If reconfiguration is required, create a sequential dump (R.<table name>, for example, R.timcs016244) for the specified tables.

3 Drop old tables.

4 From the sequential dump, build new tables that match the new data dictionary definition.

The following options are available with bdbreconfig:

–U/u Usage information.

–V/v Version information.

Database tools


–p package combination The name of the package combination to be used.

–s This suppresses error messages and other information.

–C Company numbers for a given table in these formats:

Specific company numbers (for example 001 002). Range of company numbers (for example 001-010).

–d Specify a specfic driver. If you use this option bdbpre will bypass the tabledef6.2 file. You can use the -d option to copy data from one instance of a database to another, for example:


–T If a domain changes, the table is not reconfigured.

–Z Reorganize the table. If you specify this option, the table is recreated. With this option, you do not need a data dictionary with the .new extension.

–I file Reconfigure all tables which names are listed in file. Each table name in file must be on a separate line. A table name may include a company number. For example, table tccom100 in company 570 is specified as tccom100570.

–i Ignore errors during reconfiguration, for example, duplicates.

–n Ignore referential integrity constraints.

–m Disable domain constraints.

–f Fast rebuild of table (first rows, then indexes).

–N table [table …] List of tables to be reconfigured.

–c This compares two data dictionaries and checks whether reconfiguration is required.

Database tools


–t direcory The directory name for temporary dump files.

–o file Creates a file with the names of all tables that have been successfully reconfigured.

–e file Creates a file with the names of all tables that have not been reconfigured successfully.

–O file Redirects output to output file file.

–E file Redirects errors to error file file.

–M size Specifies the maximum size of the dump file. If the maximum file size is reached a new file (with an extenuation number) is opened and filled. Size can be specified as any number or a number followed by ‘K’, ‘M’ or ‘G’, for Kilo, Mega or Giga bytes. The maximum size is 2Gbyte.

–r rows/transactions Defines after which number of inserted records a commit is performed. The default value is 100. A number below 100 is changed to 100.

The bdbreconfig tool reconfigures only one table of given company numbers at a time.

bdbreconfig –Ntimcs016 –C001 Reconfigures timcs016 for company number 001.

bdbreconfig –Ntimcs016 –C000-010 Reconfigures timcs016 for a range of company numbers.

If bdbreconfig is used without the –c option, the exit status is either 0 or 1, depending on successful or unsuccessful completion. If the exit status is 1 (unsuccessful) the file specified with the –o option contains tables that have been reconfigured, and the file specified with the –e option contains the tables that have not been reconfigured.

If bdbreconfig is used with the –c option, the file specified with the -o option contains the table names which are found correct, and the file specified with the -e option contains the table names that must be reconfigured.

Make a copy of the dump before executing the following.

EXAMPLE

CAUTION

Database tools


In case of interrupted reconfiguration while the R.table file still exists, the following command uses the R.ttadv100222 dump to rebuild the table.

bdbreconfig –N ttadv100222+

bdbreconfig –Ntimcs016 –C000-003 Reconfigures timcs016 for some company numbers according to the new data dictionary, provided that dtimcs/dtimcs016 and dtimcs/dtimcs016.new are present.

When the –m or –n option is used, the data in the database can violate the Baan integrity constraints. Data can violate the Baan domains or it can violate Baan referential integrity.

refint NAME

refint

Check or repair the referential integrity in the database.

SYNOPSIS

refint [–uU][-vV] [-l |-L file][-c][-n][-r][-s] [-p package][-I infile][-O outfile][-E errfile][-N table [table [..]]] [-C compnr [compnr [..]]]

DESCRIPTION

The refint tool checks the integrity of references in the database. You can also use it to repair the integrity of a corrupted database. Integrity refers to the accuracy or validity of data.

EXAMPLE

Database tools


You can use the following options:


–v/V Print version information.

–p pacakge combination The name of the package combination that is to be used.

–C compnr Specify company number.

–c Check validity of references.

–n Nullify undefined references, all references to the specified tables are checked.

–r Repair reference counters. From all specified tables the reference counters are checked and changed if necessary. Undefined references to the specified tables are displayed on the screen.

–l/-L file Creates a file that contains all undefined references. If you use the option –l, the name of this file will be ref_undefined. With the option –L you can specify your own file name.

–I file Check or repair all tables whose name appears in the file file. Each table name in file must be on a separater line. A table name may include a company number. For example, table tccom100 in company 570 is specified as tccom100570.

–N table The name of the table whose references must be checked or repaired. The table name may include a company numer. For example, you may specify –N ttadv100 or –N ttadv100999.

–s Handle one single-parent table only.

refint –Iref_tables –c –n –C100

refint –Ntimcs016 –l

EXAMPLES

Database tools


2-1


General Database servers and user interface servers perform processes different from those performed by the client, the bshell. They communicate with the bshell by using a communication protocol. This section discusses the working and usage of several protocols that can be used for local and remote communication.

Local communication means that server and client are started on the same host machine. Remote communication means that server and client are on different machines.

To access tables Tables can be distributed as follows:

Local: the tables and the bshell are on one system. Remote: the bshell is on one system; all the tables are on another system. Combination: some tables and the bshell are on one system; some tables are

on another system.

To access a table, the bshell and database drivers must know the database type and the location of the table. This information has been stored in the following files:

tabledef6.2 fd6.2.package combination

tabledef6.2 Table references that refer to a database type are stored in the tabledef6.2 file. This file is located in the $BSE/lib directory. To fill this file, use the Tables by Database (ttaad4111m000) and the Database Definitions (ttaad4510m000) sessions. If the tables are on a different system, you specify the host name of the remote system instead of entering the database type. The bshell knows which database server must be started and in which database the required tables can be found.

2 Database management

Database management


fd6.2.package combination The fd6.2.package combination file is used to refer the following dictionary types to a specific directory (path) for a specific package combination:

Forms. Menus. Objects. Program scripts. Functions. Report scripts.

The fd6.2.package combination file is located in the $BSE/lib directory. To fill this file, use the Directories of Software Components (ttadv1115m000) session. The specific directory path of the table definitions must be entered in the Package Combinations (ttaad1520m000) session and is also placed in the fd6.2.package combination file.

Example table access (table and bshell on the same system) This example roughly explains how the bshell accesses a table if both are on the same system.

Suppose you work with company number 001, and read in an application table ttmod003. The contents of tabledef6.2 are:

*:001:db2(DB2INSTANCE=baan):N

First, bshell reads tabledef6.2, searches for the reference and in this case starts the DB2 driver. A connection between bshell and the driver is made. Then the driver accesses the table and the database action is carried out.

Database drivers When an action is carried out on a table, a database driver is started in the background for the database type in question.

Database management


To access tables on other systems When the database is on a different machine, the communication takes place as described in the following example.

Suppose that in a bshell program running on the host_local system, you want to read a record from the ttmod000111 (table ttmod000 in company 111) table. This table is stored on the remote system, whose host name is host1. First, the bshell searches tabledef6.2 on the host_local system for the table in question. The file contains the following reference:

ttmod:111:host1

This means that all tables of ttmod with company number 111 are stored on the host1 remote system. Next, the bshell accesses the host1 system, where it reads tabledef6.2. This file contains the reference:

ttmod:111:db2(DB2INSTANCE=baan):N

This implies that the desired tables are stored in the DB2 database. The oracle driver is then started. The desired table is searched and accessed using tabledef6.2 on the host1 system. The record is read and its data is sent to the bshell program on the host_local system.

Audit trail Audit trail is a method by which actions on a record are logged in several audit files using an audit server. To work with audit trails, you must place the server name in the $BSE/lib/ipc_info file. In addition, you must specify in tabledef6.2 that you are using audit trail. To do this, set the Audit Trail field to Y or make the audit server the mirror server. See the section, “Database mirroring.” When the client performs an action on a table, the action is logged in an audit file through the audit server. See also the chapter “Audit management.”

Database mirroring Tables can be stored in one or more database systems. The tabledef6.2 file contains references to the database where the tables are saved and/or read. For each reference you can specify one or more database systems where the tables are positioned. An example is:

tccom:*:oracle8&host2.

This reference indicates that all tables of the tccom are in the Oracle database and on the host2 system.

Database management


The tables from the previous example are copies. A change applied to a table from tccom is carried through in the Oracle database on the local system and on the host2 remote system. Also, a change to the tccom tables on the remote system must be carried through in the database on the local system. This means that tabledef6.2 on the remote system must contain a reference to the local system.

If the system refers to a remote system, tabledef6.2 on that system is read. This file contains a reference to both the tables from tccom and to the systems where copies of the tccom tables are stored.

In case of a read action, if there is a local database for the tables, it is used without a lock to enhance performance. If no local database has been defined, a remote database is used.

The principle of database mirroring is outlined in the following figure.

Figure 1 Database mirroring In this example, a change applied to a table in tccom is carried through in both the Oracle database on the local system and in the DB2 database on the remote system. A table is read, without a lock, from the Oracle database.

Database management


Alternative databases The tabledef6.2 file contains references to the database where the tables are saved or read. For each reference you can specify an alternative database driver or host where the table is located.

Assume tabledef6.2 contains the following line:

*:*:host1|oracle

The previous example indicates that a table is searched or stored on host1. If that operation fails, the table is searched or stored in a local Oracle database. If this also fails, the table cannot be accessed.

If you are using mirroring databases, you can specify an alternative database driver or host for each database system.

*:*:oracle&host1|host2

The previous example means that a table must be accessible in a local Oracle database. Besides that, it is searched or stored on host1. If host1 is not available, the table is searched or stored on host2.

Communication protocols Communication between the client and the server includes both local and remote communication. Local communication means that both the client and the server are on the same system, which does not apply to remote communication.

Depending on the hardware configuration, you can choose the following protocols for the communication between the client and the server:

Sockets (local or remote). Pipes. Direct connection (through shared libraries).

Only the remote socket protocol can be used for remote communication.

For the communication between client and servers, the following files or directories are needed:

ipc_info (in the $BSE/lib directory).

A remote user file (ruser name). This file is located in the $BSE/lib/user directory, and is described in detail in the chapter “Remote databases.”

Database management


The ipc_info file contains the following data:

Server name. Protocol. Path of the server program.

The server name is the name of the server, which can be used in other files, for example in tabledef6.2 for database servers.

You can choose from the following protocols:

Socket (s). Pipes (p). Direct connection (d).

These protocols are described in more detail in the following sections.

The server's path can include environment variables, for example $BSE, which must be used as ${BSE}. An example of the ipc_info file is shown in Example ipc_info File.

Socket protocol A socket enables processes to communicate in both directions. The socket protocol is subdivided into local and remote sockets. Local sockets are used for local communication; remote sockets for remote communication. The client uses a local socket address if it is free at that moment. Both sockets are described in the following paragraphs.

Local sockets When a client (bshell) opens a table, the client reads tabledef6.2. If this file refers to a certain server, the client reads data about that server from the file ipc_info. The file ipc_info contains data such as the protocol to be used and the position of the executable server. Next, the client uses a socket to start the server and establish communication with the server.

Database management


Remote sockets (only for database servers) Suppose that the client on host A wants to open a table on host B as in the following figure.

Figure 2, Remote socket protocol This is done through sockets. The client reads tabledef6.2 on host A, which indicates that the table is on host B. The client logs on to host B using the password found in the file r<user name> in the $BSE/lib/user directory.

The client uses a remote execute call (rexec()) to start ipc_boot6.2 on host B, which starts fs6.2. fs6.2 is used to open, read, and write data from a remote $BSE directory.

The ipc_boot process reads ipc_info to find the directory in which fs6.2 is located. Then an exec() call is done, so that the ipc_boot6.2 process changes to fs6.2.

The client searches tabledef6.2 on host B, to determine which driver must be used to open the desired table, for example, Oracle.

Another remote execute call is done; this time to start the Oracle driver on host B. Again ipc_boot6.2 is started and reads ipc_info for the path of the Oracle driver. Now icp_boot6.2 does an exec() call to the Oracle driver.

Communication then proceeds normally between client and Oracle driver.

Database management


Pipes protocol The pipes protocol is analogous to the local socket protocol. In pipes protocol, the client and server communicate through unnamed pipe streams. A pipe is a UNIX function that enables processes to communicate in one direction. The communication between the client and the server takes place through two pipes.

Message queue protocol The message queue protocol is only used for local communication. With this protocol the client starts the server. The client and server communicate through a message queue using a semaphore key. This key indicates whether a message queue contains information, so that the client or server knows that information has been sent. See the following figure.

Figure 3, Message queue protocol For example, suppose the client wants to send information to the server. This information or message is put in a message queue, and the semaphore key is given the value of 1. The semaphore key shows the server that information has been sent, so that the server can read it. After the server reads it, the semaphore flag is reset and released, so that the client knows its information has been read. If the client process is canceled, the client will not put data in the message queue. However, the semaphore key is decremented using an undo value. The server reads the message queue and finds no message. Thus, the server knows that the client process has been terminated and stops its own process.

Database management


Example ipc_info file Server name Protocol (s/m/p) Path of executable server oracle7 s 0 0 s ${BSE}/bin/ora7_srv6.2 informix s 0 0 s /usr1/bse/bin/inf_srv6.2 Bshell s 0 0 s ${BSE}/bin/bshell6.2 fs6.2 s 0 0 p ${BSE}/bin/fs6.2

Database management


3-1


General Native Language Support controls the communication between the character set of a terminal and that of bshell6.2.

Bshell6.2 has the 8-bit character set of ISO 8859-1. Most terminals and printers do not support this character set, so Native Language Support techniques are implemented.

The character set of the terminal is uniform. However, various country-dependent keyboards can be used with the same terminal. Not all the characters of the terminal character set can be found on the keyboard. The remaining characters must be composed. How to compose characters is described in the section “Composed characters.”

An input conversion table is used to convert the character set of a terminal to that of the bshell. In this table a character from the terminal character set is converted to the corresponding value from the ISO 8859-1. This means that characters from the bshell must be converted again to correctly control the terminal or printer. Both the printer and the terminal need an output conversion table. For a description of the conversion tables, see the section “Conversion tables.”

To maintain the conversion tables you can use the NLS editor. This editor is described in the section “NLS editor.”

Composed characters Characters that are not found on a keyboard must be composed by a unique combination of two or more existing characters. An example of a list of composed characters is contained in the section “List of compose sequences.” Prior to entering the combination, you must press a compose key. The compose key is defined in the terminal information file of the terminal. For more information see the section “NLS-related files.”

The compose key can be linked to a special key on the keyboard, for example, a function key. You can also compose characters by using the Compose character key, if it is present on the keyboard. This key has the same function as the compose key.

3 Native language support

Native language support


The manufacturer of the terminal has defined the composed characters. The user documentation of the terminal contains a list of these composed characters.

Conversion tables You need two kinds of conversions to make the character sets of bshell and the terminal or printer compatible: input conversion and output conversion.

Input conversion table The input conversion table converts the entered characters to their corresponding values in the ISO 8859-1 character set. Composed characters and characters that are not compatible with the ISO character set must be included in this table. To record and/or modify an input conversion table, use the NLS editor, described in the section “NLS editor.” An example of an input conversion table is given in the section “ Input/output table vt200.”

Output conversion table The output conversion table converts the characters of the ISO character set to their corresponding values in the terminal or printer character set. You, therefore, need two output conversion tables:

Terminal output table. Printer output table.

In this way a character is displayed or printed as entered.

To record or modify an output conversion table you can use the NLS editor, described in the section “NLS editor.” An example of an output conversion table is given in section “ Input/output table vt200” and the section “Printer output table MT910 HP Prestige character set.”

Example of total conversion Terminal type: vt200 with North American keyboard Printer type: Mannesmann mt910 Required character: ÿ = ISO8859-1 code 255 = DEC vt200 code 253

The character ÿ is not found on a North American keyboard so it must be composed. The compose sequence can be y".



To convert the composed character (DEC code 253) to its ISO 8859-1 representation (code 255), the input conversion table of the terminal must contain the following line:

\255 y"

The result of the input conversion is that the Compose[y]["] keyboard input is stored as ISO character ÿ on disk or bshell memory. To display the entered (required) character on your screen, ISO code255 must be converted to DEC code 253. Therefore the terminal output conversion table must contain the following line:

\255 \253

To print the entered (required) character on a Mannesmann mt910 printer, the printer output table must contain the following line:

\255 y\b\168

This means that the ÿ character is printed as:

[y] <Backspace>["]

y \b \168

This example is shown in the following figure.

Figure 4, Example NLS conversion



NLS editor Use the NLS editor to maintain input and output conversion tables. To start the editor, type nlsedit6.2. To maintain printer output tables, use the –p option followed by the printer name. To maintain a terminal conversion table, the shell variable TERM must have the value corresponding to your terminal type.

For an X-terminal to display the characters of ISO 8859-1, you must have the right font. The section “NLS-related files” contains an example of suitable fonts.

After you have started the editor, the upper part of the ISO character set (160-255) is displayed. If a character cannot be displayed on your screen, it might be because it is not found in the character set of the terminal.

You can display feasible options by typing ?. Exit the editor by typing Q.

Initial screen options Feasible initial screen options are:

-d/h/o set decimal/hex/octal display mode

-t edit nls_in and nls_out tables

-r toggle display of characters

-s toggle character set

With the options -D, -H, and -O you can change the display mode of the character values into decimal, hexadecimal, or octal.

The -T option is used to edit the conversion tables. A second screen appears.

The initial screen shows the characters displayed by the terminal as defaults. With the -R option you can set this mode on/off.

The default characters displayed on the initial screen are characters of the upper part (160-255) of the ISO character set. With the -S option you can switch between the lower part (32-127) and the upper part of this character set.

You can display the initial screen options by typing ?. The window that appears also shows your terminal setup, NLS table names, and shell variable BSE.



Maintenance of NLS conversion tables By entering the -T option on the initial screen you can maintain the input and output conversion tables. Five columns are displayed as illustrated in the following example.

input int s # output A` 192 À 0 \192 A' 193 Á 1 \193 A\^ 194 Â 0 \194

The left column, input, contains the compose sequence of the input characters. This column also contains single input characters not transparent with the ISO character set.

The second column, int, displays the values of the characters in the ISO character set.

The third column, s, shows the characters as they are represented after output conversion.

The fourth column, #, contains the character set number. Character sets are defined at the terminal or printer. The possible values are 0-9, and the default is 0.

The last column, output, contains the output sequence of the characters. You can type the output sequence in decimal, hexadecimal, or octal code.

The bottom of the screen shows the display mode in which the values of the characters are displayed. The last line indicates the marked character. The numeric representations and description are also included.

Feasible options to maintain conversion tables are:

–D/H/O set decimal/hexadecimal/octal display mode

-N toggle numeric/alpha mode compose sequence

–ARROW DOWN next line

–ARROW UP previous line

–CTRL+N next page

–CTRL+P previous page

–K single key

–C enter compose sequence



–S enter output sequence

–W write nls_in and nls_out file

–+/- increment/decrement character set number

With the options -D, -H, and -O you can change the display mode of the character values into decimal, hexadecimal, or octal.

The -N option converts alphanumeric characters from the input and output table to their numeric values, and vice versa.

To move the bar to the following or previous line, use the key ARROW DOWN or ARROW UP.

Pressing CTRL+N or CTRL+P moves the bar 15 lines forward or backward.

To enter the input sequence of a single key, press -K. The editor asks you to press the required key. That character is included directly in the table. You do not need to press ENTER after you have entered the character.

After pressing -C you can enter the compose sequence. You can enter up to 35 characters.

To type the output sequence, enter -S. You can enter up to 35 characters.

After any modification, you can store the input and output tables by entering -W.

NLS-related files To work with NLS you must have the following files in your BSE environment:

Terminal information file$BSE/lib/terminf/... Printer information file$BSE/lib/printinf/... Input conversion table$BSE/lib/nlsinf/... Output conversion table$BSE/lib/nlsinf/...

You must also have the right terminal setup, shell variable TERM, and font. For some additional features you can use sort tables and shift tables.

Terminal information file The terminal information files have been placed in subdirectories of the $BSE/lib/terminf directory. For example, terminal information files starting with the letter v are placed in subdirectory v.



Two lines must be added to each terminal information file, to indicate the conversion tables used by the terminal:

nls_in=<terminal type>.in nls_out=<terminal type>.out,

For example, for a vt200 terminal, the terminal information file vt200 can contain the following lines:

nls_in=vt200.in nls_out=vt200.out,

The compose key code is also defined in the terminal information file:

kcompose=<compose key code>,

The code can be anything that does not conflict with other special keys. For example, suppose you want to define the compose key as ESC+C. Add the following line to the terminal information file:

kcompose=\ec,

Printer information file The printer information files have been placed in subdirectories of the $BSE/lib/printinf directory. For example, printer information files starting with the letter m are placed in subdirectory m.

The following line must be added to each printer information file, to indicate the output conversion table used by the printer:

nls_out=<printer type>.out,

For example, for an mt910 printer, the printer information file mt910 must contain the following line:

nls_out=mt910.out,

Input and output conversion table The input and output conversion tables are stored in the $BSE/lib/nlsinf directory. Possible table names in this directory are:

<terminal type>.in (input conversion terminal) <terminal type>.out (output conversion terminal) <printer type>.out (output conversion printer)

For each terminal there is one input and one output conversion table. For each printer there is only an output conversion table.



The format of every line in a conversion table is:

<string><tabs or spaces><string>

A string can consist of one or more:

ASCII codes (A-Z, a-z, and 0-9...) Octal codes (\01, \012, \012...) Decimal codes (\1, \12, \12...) Hexadecimal codes (\0x1, 0x12…) Control codes (Â, ^B, ^C…) Escape codes (\E, \e, \s, \n, \r, \f, \v, \b) Special codes (\\, \^ )

A list of control and escape codes is given in the “Overview of Esc/Ctrl codes” at the end of this chapter. The first column contains the numeric representation of the ISO 8859-1 character set.

In an input table, the second column contains the compose sequence of the input characters. In an output table, the second column contains the numeric representation of the output characters. The columns are separated by spaces or tabs. Examples of conversion tables are given in the section “ Input/output table vt200.”

Terminal setup The communication mode of the terminal must be 8-bit no parity. The shell variable TERM must have the name of the terminal information file of the terminal.

Character sets and fonts Line drawing characters do not need to be included in the character set. These characters are drawn by the bshell itself. To check the suitability of character sets, type the following command:

xfontsel –pattern –*-*-iso8859-1

To choose the font and set the FONT shell variable, type the following command:

csh: setenv FONT "`xfontsel –pattern *-c-*-iso8859-1-print`" sh: FONT="`xfontsel –pattern *-c-*-iso8859-1-print`" export FONT

After reducing the number of options, a character set can be chosen in this program.



Suitable character sets are:

-bitstream-terminal-medium-r-normal--18-140-100-100-c-110-iso8859-1 -misc-fixed-medium-r-normal--14-130-75-75-c-70-iso8859-1 -misc-fixed-medium-r-normal--15-120-100-100-c-90-iso8859-1

Sort tables You can use a sort that differs from the default sort method. To do this you can use a sort table to specify the weight of characters.

The file with the sort table has the default name:

$BSE/lib/nlsinf/sort.tab

You can make your own sort table by filling the SORT_TABLE environment variable with the name of your own sorting file. A sort table has two columns. The first one contains the character, the second contains the weight of that character.

For example, to sort the B before the A, create a sort table with the following contents:

\65 \66 or A B \66 \65 B A

You can use escape and control codes, like \012, \e, Â. See the section “Input and output conversion table” for more information.

Shift tables Shift tables can be used to specify lowercase and uppercase characters that belong together.

The file with the shift table has the default name:

$BSE/lib/nlsinf/shift.tab

You can make your own shift table by filling the SH_TABLE environment variable with the name of the file with your own shift table. A shift table has two columns. The first one contains the uppercase character, the second contains the lowercase character.

For example, to specify the lowercase and uppercase character c with cedilla, create a shift table with the following contents:

\199 \231



ISO 8859-1 character set (0-127) 0 16 32

SP 48

0 64

@ 80

P 96

` 112

p 1

17 33

! 49

1 65

A 81

Q 97

a 113

q 2 18 34

“ 50

2 66

B 82

R 98

b 114

r 3 19 35

# 51

3 67

C 83

S 99

c 115

s 4 20 36

$ 52

4 68

D 84

T 100

d 116

t 5 21 37

% 53

5 69

E 85

U 101

e 117

u 6 22 38

& 54

6 70

F 86

V 102

f 118

v 7 23 39

‘ 55

7 71

G 87

W 103

g 119

w 8 24 40

( 56

8 72

H 88

X 104

h 120

x 9 25 41

) 57

9 73

I 89

Y 105

I 121

y 10 26 42

* 58

: 74

J 90

Z 106

j 122

z 11 27 43

+ 59

; 75

K 91

[ 107

k 123

{ 12 28 44

‘ 60

< 76

L 92

\ 108

l 124

| 13 29 45

- 61

= 77

M 93

] 109

m 125

} 14 30 46

. 62

> 78

N 94

^ 110

n 126

- 15 31 47

/ 63

? 79

O 95

_ 111

o 127

128 144 160

NBSP 176

° 192

À 208

Ð 224

à 240

ð 129 145 161

¡ 177

± 193

Á 209

Ñ 225

á 241

ñ 130 146 162

¢ 178

² 194

Â 210

Ò 226

â 242

ò



131 147 163 £

179³

195Ã

211Ó

227ã

243ó

132 148 164 ¤

180'

196Ä

212Ô

228ä

244ô

133 149 165 ¥

181µ

197Å

213Õ

229å

245õ

134 150 166 ¦

182¶

198Æ

214Ö

230æ

246ö

135 151 167 §

183·

199Ç

215×

231ç

247÷

136 152 168 ¨

184,

200È

216Ø

232è

248ø

137 153 169 ©

185¹

201É

217Ù

233é

249ù

138 154 170 ª

186°

202Ê

218Ú

234ê

250ú

139 155 171 «

187»

203Ë

219Û

235ë

251û

140 156 172 ¬

188¼

204Ì

220Ü

236ì

252ü

141 157 173 SHY

189½

205Í

221Ý

237í

253ý

142 158 174 ®

190¾

206Î

222Þ

238î

254þ

143 159 175 |

191¿

207Ï

223ß

239ï

255ÿ



DEC vt100/vt200 character set (0-127) 0

NUL 0

16 DLE

10

32 SP

20

48 0

30

64 @

40

80 P

50

96 `

60

112p

70 1

SOH 1

17 DC1

11

33 !

21

49 1

31

65 A

41

81 Q

51

97 a

61

113q

71 2

STX 2

18 DC2

12

34 “

22

50 2

32

66 B

42

82 R

42

98 b

62

114r

72 3

ETX 3

19 DC3

13

35 #

23

51 3

33

67 C

43

83 S

53

99 c

63

115s

73 4

EOT 4

20 DC4

14

36 $

24

52 4

34

68 D

44

84 T

54

100d

64

116t

74 5

ENQ 5

21 NAK

15

37 %

25

53 5

35

69 E

45

85 U

55

101e

65

117u

75 6

ACK 6

22 SYN

16

38 &

26

54 6

36

70 F

46

86 V

56

102f

66

118v

76 7

BEL 7

23 ETB

17

39 ‘

27

55 7

37

71 G

47

87 W

57

103g

67

119w

77 8

BS 8

24 CAN

18

40 (

28

56 8

38

72 H

48

88 X

58

104h

68

120x

78 9

HT 9

25 EM

19

41 )

29

57 9

39

73 I

49

89 Y

59

105I

69

121y

79 10

LF A

26 SUB

1A

42 *

2A

58 :

3A

74 J

4A

90 Z

5A

106j

6A

122z

7A 11

VT B

27 ESC

1B

43 +

2B

59 ;

3B

75 K

4B

91 [

5B

107k

6B

123{

7B



12 FF

C

28 FS

1C

44 ‘

2C

60 <

3C

76 L

4C

92 \

5C

108l

6C

124|

7C 13

CR D

29 GS

1D

45 –

2D

61 =

3D

77 M

4D

93 ]

5D

109m

6D

125}

7D 14

SO E

30 RS

1E

46 .

2E

62 >

3E

78 N

4E

94 ^

5E

110n

6E

126–

7E 15

SI F

31 US

1F

47 /

2F

63 ?

3F

79 O

4F

95 _

5F

111o

6F

127DEL

7F



DEC vt100/vt200 character set (128-255) 128

80

144 DCS

90

160

A0

176°

B0

192À

C0

208

D0

224à

E0

240

F0 129

81

145 PU1

91

161 ¡

A1

177±

B1

193Á

C1

209Ñ

D1

225á

E1

241ñ

F1 130

82

146 PU2

92

162 ¢

A2

178²

B2

194Â

C2

210Ò

D2

226â

E2

242ò

F2 131

83

147 STS

93

163 £

A3

179³

B3

195Ã

C3

211Ó

D3

227ã

E3

243ó

F3 132

84

148 CCH

94

164

A4

180

B4

196Ä

C4

212Ô

D4

228ä

E4

244ô

F4 133

85

149 MW

95

165 ¥

A5

181µ

B5

197Å

C5

213Õ

D5

229å

E5

245õ

F5 134

86

150 SPA

96

166

A6

182¶

B6

198Æ

C6

214Ö

D6

230

E6

246ö

F6 135

151 EPA

97

167 §

A7

183·

B7

199Ç

C7

215

D7

231ç

E7

247

F7 136

152

98

168 ¨

A8

184

B8

200È

C8

216Ø

D8

232è

E8

248ø

F8 137

153

99

169 ©

A9

185¹

B9

201É

C9

217Ù

D9

233é

E9

249ù

F9 138

154

9A

170 ª

AA

186°

BA

202Ê

CA

218Ú

DA

234ê

EA

250ú

FA 139

155 CSI

9B

171 «

AB

187»

BB

203Ë

CB

219Û

DB

235ë

EB

251û

FB



140

156

9C

172

AC

188¼

BC

204Ì

CC

220Ü

DC

236ì

EC

252ü

FC 141

157 OSC

9D

173

AD

189½

BD

205Í

CD

221Ý

DD

237í

ED

253ý

FD 142

158 PM

9E

174

AE

190

BE

206Î

CE

222

DE

238î

EE

254

FE 143

159 APC

9F

175

AF

191¿

BF

207Ï

CF

223ß

DF

239ï

EF

255

FF



List of compose sequences Character Description Composition NBSP Nonbreaking space \s\s | Broken bar || " Diaeresis "" # Quotation mark ++ @ Commercial at sign Aa [ Opening bracket (( \ Backslash // ] Closing bracket )) { Opening brace (- | Vertical bar (or pipe) /^ } Closing brace )- ¡ Inverted exclamation mark !! ¢ Cent sign C/ £ Pound sign L- ¥ Yen Sign Y- § Section sign So ¤ Currency sign Xo © Copyright sign CO ® Registered trademark sign RO ª Feminine ordinal indicator A_ « Left angle quotation mark << ¬ Not sign -, SHY Soft hyphen -\ - Macron =- ° Degree symbol, Ring above 0^ ± Plus or minus +- ² Superscript two 2^ ³ Superscript three 3^ ' Acute accent '' × Multiplication sign Xx ÷ Division sign :- µ Micron sign /u



Character Description Composition ¶ Paragraph mark P! · Middle dot .^ º Masculine ordinal indicator o_ , Cedilla ,, ¹ Superscript one 1^ » Closing chevrons >> ¼ Common fraction one-quarter 14 ½ Common fraction one-half 12 ³ Common fraction three-quarter 34 ¿ Inverted question mark ?? À Uppercase A with grave accent A` Á Uppercase A with acute accent A' Â Uppercase A with circumflex accent A^ Ã Uppercase A with tilde A~ Ä Uppercase A with diaeresis A" Å Uppercase A with ring above A* Æ Uppercase ligature A with E AE Ç Uppercase C with cedilla C, È Uppercase E with grave accent E` É Uppercase E with acute accent E' Ê Uppercase E with circumflex accent E^ Ë Uppercase E with diaeresis E" Ì Uppercase I with grave accent I` Í Uppercase I with acute accent I' Î Uppercase I with circumflex accent I^ Ï Uppercase I with diaeresis I" Ð Uppercase Icelandic ETH D- Ñ Uppercase N with tilde N~ Ò Uppercase O with grave accent O` Ó Uppercase O with acute accent O' Ô Uppercase O with circumflex accent O^ Õ Uppercase O with tilde O~ Ö Uppercase O with diaeresis O" Ø Uppercase O with oblique stroke O/



Character Description Composition Þ Uppercase Icelandic thorn TH Ù Uppercase U with grave accent U` Ú Uppercase U with acute accent U' Û Uppercase U with circumflex accent U^ Ü Uppercase U with diaeresis U" Ý Uppercase Y with diaeresis Y" ß Lowercase German sharp s ss à Lowercase a with grave accent a` á Lowercase a with acute accent a' â Lowercase a with circumflex accent a^ ã Lowercase a with tilde a~ ä Lowercase a with diaeresis a" å Lowercase a with ring above a* æ Lowercase ligature a with e ae ç Lowercase c with cedilla c, è Lowercase e with grave accent e` é Lowercase e with acute accent e' ê Lowercase e with circumflex accent e^ ë Lowercase e with diaeresis e" ì Lowercase i with grave accent i` í Lowercase i with acute accent i' î Lowercase i with circumflex accent i^ ï Lowercase i with diaeresis i" ð Lowercase Icelandic ETH d- ñ Lowercase n with tilde n~ ò Lowercase o with grave accent o` ó Lowercase o with acute accent o' ô Lowercase o with circumflex accent o^ õ Lowercase o with tilde o~ ö Lowercase o with diaeresis o" ø Lowercase o with oblique stroke o/ þ Lowercase Icelandic thorn th ù Lowercase u with grave accent u` ú Lowercase u with acute accent u'



Character Description Composition û Lowercase u with circumflex accent u^ ü Lowercase u with diaeresis u" ý Lowercase y with acute accent y' ÿ Lowercase y with diaeresis y"

Input/output table vt200 \160 \s\s

\161 !!

\162 c/

\163 L-

\164 xo

\165 Y-

\166 ||

\167 So

\168 ""

\169 cO

\170 a_

\171 <<

\172 -,

\173 -\\

\174 rO

\175 =-

\176 0\^

\177 +-

\178 2^

\179 3^

\180 ''



\181 /u

\182 p!

\183 .\^

\184 ,,

\185 1^

\186 o_

\187 >>

\188 14

\189 12

\190 34

\191 ??

\192 A`

\193 A'

\194 A\^

\195 A~

\196 A"

\197 A*

\198 AE

\199 C,

\200 E`

\201 E'

\202 E\^

\203 E"

\204 I`

\205 I'

\206 I\^

\207 I"



\208 D-

\209 N~

\210 O`

\211 O'

\212 O\^

\213 O~

\214 O"

\215 xx

\216 O/

\217 U`

\218 U'

\219 U\^

\220 U"

\221 Y'

\222 TH

\223 ss

\224 a`

\225 a'

\226 a\^

\227 a~

\228 a"

\229 a*

\230 ae

\231 c,

\232 e`

\233 e'

\234 e\^



\235 e"

\236 i`

\237 i'

\238 i\^

\239 i"

\240 d-

\241 n~

\242 o`

\243 o'

\244 o\^

\245 o~

\246 o"

\247 :-

\248 o/

\249 u`

\250 u'

\251 u\^

\252 u"

\253 y'

\254 th

\255 y"



Output table \160 \s

\164 \168

\166 |

\168 "

\172 \183

\173 -

\174 \183

\175 \183

\180 \183

\184 \183

\190 \183

\208 D

\215 x

\222 P

\240 \183

\247 /

\253 y

\254 p

\255 \253



Printer output table MT910 HP Prestige character set \160 \s

\161 \184

\162 c\b|

\163 \175

\164 \186

\165 \188

\166 |

\167 \189

\168 \171

\169 \s

\170 a\b_

\171 <<

\172 \176

\173 -

\174 \s

\175 \176

\176 \179

\177 \254

\178 \s

\179 \s

\180 \168

\181 u

\182 \s

\183 .

\184 ,



\185 \s

\186 \250

\187 >>

\188 \247

\189 \248

\190 \s

\191 \185

\192 \161

\193 \224

\194 \162

\195 \225

\196 \216

\197 \208

\198 \211

\199 \180

\200 \163

\201 \220

\202 \164

\203 \165

\204 \230

\205 \229

\206 \166

\207 \167

\208 \227

\209 \182

\210 \232

\211 \231



\212 \223

\213 \233

\214 \218

\215 x

\216 \210

\217 \173

\218 \237

\219 \174

\220 \219

\221 \89

\222 \240

\223 \222

\224 \200

\225 \196

\226 \192

\227 \226

\228 \204

\229 \212

\230 \215

\231 \181

\232 \201

\233 \197

\234 \193

\235 \205

\236 \217

\237 \213

\238 \209



\239 \221

\240 \228

\241 \183

\242 \202

\243 \198

\244 \194

\245 \234

\246 \206

\247 /

\248 \214

\249 \203

\250 \199

\251 \195

\252 \207

\253 y\b\168

\254 \241

\255 \239



Overview of Esc/Ctrl codes ASCII mnemonic

Dec code Hec code Oct code Esc code Ctrl code

SOH 0001 0x01 0001 Â STX 0002 0x02 0002 ^B ETX 0003 0x03 0003 ^C EOT 0004 0x04 0004 ^D ENQ 0005 0x05 0005 Ê ACK 0006 0x06 0006 ^F BEL 0007 0x07 0007 ^G BS 0008 0x08 0010 \b ^H HT 0009 0x09 0011 Î LF 0010 0x0A 0012 \n ^J VT 0011 0x0B 0013 \v ^K FF 0012 0x0C 0014 \f ^L CR 0013 0x0D 0015 \r ^M SO 0014 0x0E 0016 ^N SI 0015 0x0F 0017 Ô DLE 0016 0x10 0020 ^P DC1 (Xon) 0017 0x11 0021 ^Q DC2 0018 0x12 0022 ^R DC3 (Xoff) 0019 0x13 0023 ^S DC4 0020 0x14 0024 ^T NAK 0021 0x15 0025 Û SYN 0022 0x16 0026 ^V ETB 0023 0x17 0027 ^W CAN 0024 0x18 0030 ^X EM 0025 0x19 0031 ^Y SUB 0026 0x1A 0032 ^Z ESC 0027 0x1B 0033 \e ^[ FS 0028 0x1C 0034 ^\ GS 0029 0x1D 0035 ^] RS 0030 0x1E 0036 ^^ SPACE 0032 0x20 0040 \s

4-1


Terminal information file A terminal information file stores information including the type of terminal, terminal operations, how to access keys on the keyboard, color support, cursor movements, whether code features are blinking, bold, reversed, and so on.

Terminal information files are stored in the $BSE/lib/terminf directory.

To create a new terminal information file, create a subdirectory in the terminf directory whose name is the first letter of the future terminal information file. The terminal information file is stored in that subdirectory. For example, the terminal information file for a vt100 terminal is stored in the directory:

$BSE/lib/terminf/v/

A terminal information file can contain three types of entries:

Boolean entries. Numbers. Strings.

Each entry is closed by a comma (,). Comment text can be added, preceded by a number sign (#). You can include another terminal information file at any position in the current file with the line, for example:

include=vt100,

Boolean entries A Boolean entry reflects a feature of the terminal. A Boolean entry is set to true by including it in the terminal information file. It is set to false either by not including it or by prefixing it by an exclamation point (!), for example, !vt100.

Here are the available Booleans and what they mean when set to true:

aux_dual

Indicates that output to the aux port also appears on the terminal screen. The terminal screen is disabled during aux printing.

color_cf Provides color control in combination with code features.

4 Information files

Information files


color_sep Colors and code features are controlled separately.

mcf You can move the cursor when the code feature (cf) is active.

mgr You can move the cursor when the program is in graphics mode.

nclrwc The terminal does not clear the screen when the width is switched from 80 to 132 columns or vice versa (No CLeaR on Window (width) Change).

vt100 After a character is entered on the last position (80 or 132), the cursor remains on that position. The following character causes the cursor to jump to the next line.

xhp Code features and graphic characters are not removed when they are overwritten by characters in normal mode, but have to be removed explicitly (HP terminals).

Numbers Numbers are variables that indicate the size of the terminal or particular features. The following numbers are available:

cf_pos= Number of positions required to switch a code feature on and off. The default value is 0. The maximum value depends on the terminal type.

cols= Number of available columns on the screen. The maximum is 132. If this value is set to 80 you cannot switch the display to 132 positions.

disp_vt100= Number of columns the cursor is to move if, in the last column (80th or 132nd), the terminal receives a backspace (vt100 mode). The default value is 1. The maximum value depends on the terminal type.

gr_pos= Number of positions required to switch the graphics mode on and off. The default value is 0. The maximum value depends on the terminal type.

lines= Number of lines on screen (variable). The LINES environment variable can overwrite this value.

Information files


tmo= Timeout sequence after pressing ESC. The given number divided by 10 specifies the time (in seconds) in which a sequence can be typed in after ESC. If no character is pressed between this time, the pressing of ESC is handled normally. The default timeout sequence is 5 (0.5 second).

Strings String variables are filled with a sequence of characters that can be used to perform particular terminal operations.

You can use the following special characters to assign string variables:

Escape codes: Control codes: ASCII code \b backspace \e or \E escape \f form feed \n new line \r carriage return \t tab \s space \nn decimal value nn= 1-255 \0nn octal value nn= 1-377 \xnn hexadecimal value nn= 1-FF (for example \x1F) Â t/m ^Z (1-26) ^[ (27) ^\(28) ^](29) ^^ (30) ^_ (31)

You can also use an octal value instead of an alphabetical representation. For example, “escape” becomes \033. The control codes are converted to the ASCII codes 1 to 31. For example, ^B equals the ASCII character with decimal value 2 (STX).

The following string variables are possible:

aux_off= Closes the auxiliary port. All data is displayed on the terminal.

aux_on= Opens the auxiliary port. All data sent to the terminal is passed to the aux port.

Information files


bell= Audible signal (usual value: ^G).

cadr= Absolute column positioning string. See the section “Parameterized strings” about the use of a parameterized string.

cbl= Character used in graphics mode to display the lower left corner (+). If it is not available, a viable alternative is +. Do not leave the variable empty, because this can result in screen layout problems.

cbr= Character used in graphics mode to display the lower right corner (+). If it is not available, a viable alternative is +. Do not leave the variable empty, because this can result in screen layout problems.

cf_b= Code feature, blinking.

cf_br= Code feature, blinking, and reversed.

cf_bru= Code feature, blinking, reversed, and underlined.

cf_bu= Code feature, blinking, and underlined.

cf_B= Code feature, bold.

cf_Bb= Code feature, bold, and blinking.

cf_Bbr= Code feature, bold, blinking, and reversed,

cf_Bbru= Code feature, bold, blinking, reversed, and underlined.

cf_Bbu= Code feature, bold, blinking, and underlined.

cf_Br= Code feature, bold, and reversed,

cf_Bru= Code feature, bold, reversed, and underlined.

Information files


cf_Bu= Code feature, bold, and underlined.

cf_n= Code feature, normal.

cf_r= Code feature, reversed.

cf_ru= Code feature, reversed, and underlined.

cf_u= Code feature, underlined.

clear= Clears the entire display and moves the cursor to the top left corner of the screen.

csr= Character sequence for changing the scrolling region. The first parameter indicates the start line. The second parameter indicates the end line of the scrolling region. See also the section “Parameterized strings.”

ctl= Character used in graphics mode to display the upper left corner (+). If it is not available, a viable alternative is +. Do not leave the variable empty, because this can result in screen layout problems.

ctr= Character used in graphics mode to display the upper right corner (+). If it is not available, a viable alternative is +. Do not leave the variable empty, because this can result in screen layout problems.

cu_off= Cursor off (invisible).

cu_on= Cursor on (visible).

cub= The cursor moves back the specified number of columns. See the section “Parameterized strings.”

cub1= The cursor moves back one position.

cud= The cursor moves down the specified number of rows. See the section “Parameterized strings.”

cud1=

Information files


The cursor moves down one row.

cuf= Move the cursor forward by the specified number of columns. See the section “Parameterized strings.”

cuf1= The cursor moves forward one position.

cup= Absolute cursor positioning. See the section “Parameterized strings.”

cuu= The cursor moves up by the specified number of rows. See the section “Parameterized strings.”

cuu1= The cursor moves up one row.

delch= Deletes the character below the cursor.

delli= Deletes one line.

dt= Character used in graphics mode to display the lower T-bar. If it is not available, a viable alternative is +. Do not leave the variable empty, because this can result in screen layout problems.

el= Deletes to the end of the row.

es= Deletes to the end of the screen.

ewin= Erases the current window.

flash= Flashes the screen instead of beeping when an error occurs.

gr_off= Turns graphics mode off.

gr_offB= Turns bold graphics mode off.

gr_on= Turns graphics mode on.

Information files


gr_onB= Turns bold graphics mode on.

hb= Character used in graphics mode to display the horizontal bar. If it is not available, a viable alternative is –. Do not leave the variable empty, because this can result in screen layout problems.

home= Positions the cursor in the upper left corner of the screen.

if= Name of file containing codes to initialize the terminal. This initialization is done after the initialization string in init and before the string in init2. In the file you can, for example, specify a large number of codes that do not fit in a string of soft font codes.

inch= Insert one character, usually a space at the current cursor position.

init= Initialization string sent to the terminal to set it up for proper use by the bshell. This string is sent before any other output.

init2= Initialization string sent to the terminal to set up. This string is sent during initialization of the terminal, after the init string and the codes in the file specified at the if entry.

inli= Insert one line.

kr= Character used in graphics mode to display the center crossbar (+). If it is not available, a viable alternative is +. Do not leave the variable empty, because this can result in screen layout problems.

ladr= Absolute line positioning string. See the UNIX manual TERMINFO(4) and the section “Parameterized strings” about defining such a string with one parameter.

lt= Character used in graphics mode to display the left T-bar. If it is not available, a viable alternative is +. Do not leave the variable empty, because this can result in screen layout problems.

nls_in= Name of NLS input conversion table. See the NLS4.2 user manual.

Information files


nls_out= Name of NLS output conversion table. See the NLS4.2 user manual.

rc= Restores cursor position and attributes saved with the character sequence specified with the sc entry.

reset= Reset initialization string. The terminal is set up in such a way that it can be used in UNIX or other programs. The string is sent after the bshell terminates execution.

rt= Character used in graphics mode to display the right T-bar. If it is not available, a viable alternative is +. Do not leave the variable empty, because this can result in screen layout problems.

sc= Save cursor position and attributes.

set0=, to set9= Set a character set of the terminal. The default set is set0.

set80= Set the display width to 80 column.

set132= Set the display width to 132 columns.

ut= Character used in graphics mode to display the upper T-bar. If it is not available, a viable alternative is +. Do not leave the variable empty, because this can result in screen layout problems.

vb= Character used in graphics mode to display the vertical bar. If it is not available, a viable alternative is | (pipeline). Do not leave the variable empty, because this can result in screen layout problems.

Information files


The following dim code features are used in graphics mode if the normal code features are defective. (Poppy and Wyse terminals):

cblB=. See cbl, but bold.

cbrB=. See cbr, but bold.

ctlB=. See ctl, but bold.

ctrB=. See ctr, but bold.

dtB=. See dt, but bold.

hbB=. See hb, but bold.

krB=. See kr, but bold.

ltB=. See lt, but bold.

rtB=. See rt, but bold.

utB=. See ut, but bold.

vbB=. See vb, but bold.

Keys This section describes how you can access keys on the keyboard. Use the string assigned to each entry to specify either the sequence that simulates the key or the sequence that is generated when the user presses the key.

If you want to use a special key in the bshell, you must specify this key in the terminal information file. If the key is present on the keyboard, you must assign the corresponding sequence to it. If the key is not present, you can assign another sequence.

For several key entries, a default value is given along with the ASCII code and decimal code. For example:

CTRL+J (LF, 10d)

The following keyboard entries are possible:

k1=, to k20= Specifies the function keys F1 to F20.

k1c=, to k20c= Specifies the function keys when the CTRL key is held down.

k1s=, to k20s= Specifies the function keys when the SHIFT key is held down.

Information files


k1sc=, to k20sc= Specifies the function keys when the SHIFT and CTRL keys are held down.

kbs= Backspace; moves cursor one position back. Default: CTRL+H (BS, 8d).

kbtab= Specifies the back tab key.

kcompose= Key compose; used to define a code for NLS character composition.

kcs= Key column switch. If it cannot display all 132 columns at once, switches function between the left and right half of the display (usually \eC or \ec).

kd= Key down; moves cursor one position down. Default: CTRL+J (LF, 10d).

kdc= Key delete character; removes one character. Default: <Del> (127d).

kdo= Key do.

kesc= Key escape.

kf= Key forward; moves cursor one position to the right. Default: CTRL+L (FF, 12d).

kfind= Key find.

khlp= Key help.

khome= Key home; moves the cursor to the upper left corner of the screen. Default: CTRL+^ (RS, 31d).

kid= Key interrupt debugging.

kinshere= Key insert.

kkill= Key kill.

kl= Key left; moves the cursor one position to the left. Default: CTRL+H (BS, 8d)

Information files


knscreen= Key page down.

kpr= Key print.

kpscreen= Key page up.

kre= Key refresh; rewrites screen (usually \eR or \er).

kremove= Key remove.

kselect= Key select.

ktab= Key tab.

ku= Key up; moves the cursor up one line. Default: CTRL+K (VT, 11d).

pf1=, to pf4= DEC vt100 “gold” keys. NOTE (only for Baan-C programmers):

When you use event functions, your program can catch the keys defined in your terminal information file. When the program catches a key-press event, it returns a code for that key. The codes used for the keys are shown in the $BSE/include6.2/bic_key header file.

For example, a line in the header file is:

#define KEY_F(1) 1024

This indicates that the F1 function key (k1 in a terminal information file) is identified by code 1024. You can use the KEY_F(1) macro in your program to check if the defined sequence for the F1 function key is given.

See the section ”Example of terminal information files” for an extensive example of terminal information files.

Information files


Color support Colors can be sent to the screen separately or in combination with code features, depending on the capabilities of the terminal. This is set in the terminal information file with the color_cf and color_sep Boolean values.

color_cf The code feature can be sent together with the color codes in one single escape sequence.

color_sep The color codes cannot be combined with the code features.

To send colors separately You can use the following string entries in the terminal information files to set the foreground and background color:

bg_black=

bg_red=

bg_green=

bg_yellow=

bg_blue=

bg_magenta=

bg_cyan=

bg_white=,

fg_black=

fg_red=

fg_green=

fg_yellow=

fg_blue=

fg_magenta=

fg_cyan=

fg_white=

Information files


You can also assign escape sequences to these entries. For example:

color_sep

bg_black=\e[40m

bg_red=\e[41m

bg_green=\e[42m

bg_yellow=\e[43m

bg_blue=\e[44m

bg_magenta=\e[45m

bg_cyan=\e[46m

bg_white=\e[47m,

fg_black=\e[30m

fg_red=\e[31m

fg_green=\e[32m

fg_yellow=\e[33m

fg_blue=\e[34m

fg_magenta=\e[35m

fg_cyan=\e[36m

fg_white=\e[37m,

Colors in combination with code features The following numbers are used as %p1 and %p2 parameters in combined code feature and color strings (color_cf).

black=0

red=1

green=2

yellow=3

blue=4

magenta=5

cyan=6

white=7

Information files


The colors can be sent to the terminal along with code features with the following string entries. The foreground and background color must be specified as parameters.

cf_co_n=, # colors as specified and code feature normal

cf_co_B=, # code feature bold

cf_co_b=, # code feature blinking

cf_co_Bb=, # code feature bold and blinking

cf_co_r=, # code feature reverse

cf_co_Br=, # code feature bold and reverse

cf_co_br=, # code feature blinking and reverse

cf_co_Bbr=, # code feature bold, blinking and reverse

cf_co_u=, # code feature underlined

cf_co_Bu=, # code feature bold underlined

cf_co_bu=, # code feature blinking underlined

cf_co_Bbu=, # code feature bold, blinking underlined

cf_co_ru=, # code feature reverse underlined

cf_co_Bru=, # code feature bold, reverse underlined

cf_co_bru=, # code feature blinking, reverse underlined

cf_co_Bbru=, # code feature bold, blinking, reverse underlined

For example:

cf_co_n=\e[0;22;%p1%{30}%+%d;%p2%{40}%+%dm

cf_co_B=\e[0;1;%p1%{30}%+%d;%p2%{40}%+%dm

cf_co_b=\e[0;5;22;%p1%{30}%+%d;%p2%{40}%+%dm

cf_co_Bb=\e[0;1;5;%p1%{30}%+%d;%p2%{40}%+%dm

cf_co_Br=\e[0;1;7;%p1%{30}%+%d;%p2%{40}%+%dm,

In the previous example, %p1 is foreground color; p1=0-7 and %p2 is background color; p2=0-7. See the section, “Colors in combination with code features.” For use of parameters within a string entry, see the section “Parameterized strings.”

Information files


Parameterized strings Some of the string entries described in the section “Terminal information file” require a number of parameters. For example, to address the cursor, the cup entry requires two parameters: the row and column to which to address to. The use of parameters in a string entry is described in this section.

The parameter mechanism uses a stack and special codes, starting with % to manipulate the stack.

Information files


The codes have the following meanings:

Code Meaning %d Take a number from the stack (pop()) %2d Take a number with a minimum of two digits %3d Take a number with a minimum of three digits %02d Take a number with exactly two digits %03d Take a number with exactly three digits %c Take a character from the stack %s Take a string from the stack %P[a-z] Take a variable [a-z] from the stack %p[1-9] Push a parameter [1-9] onto the stack %g[a-z] Get a variable [a-z] and push it onto the stack %{nn} Push a decimal constant nn onto the stack %+ Take two numbers from the stack and push their sum %- Take two numbers from the stack and push their subtraction; push(pop() – pop()) %* Take two numbers from the stack and push their multiplication %/ Take two numbers from the stack and push their division; push(pop() / pop()) %m Take two numbers from the stack and push the modulus of their division;

push(pop() mod pop()) %& Take two numbers from the stack and push the result of their logical AND. %| Take two numbers from the stack and push the result of their logical OR. %\^ Take two numbers from the stack and push the result of their logical EXOR. %= Take two numbers from the stack and compare them. Depending on the equality,

TRUE or FALSE is pushed onto the stack. %> Take two numbers from the stack and compare them. If the first number is greater

than the second, TRUE is pushed onto the stack, otherwise FALSE is pushed. %< Take two numbers from the stack and compare them. If the first number is less

than the second, TRUE is pushed onto the stack, otherwise FALSE is pushed. %! Take a number from the stack and push its negative value onto the stack. %\~ Take a number from the stack and push the result of its logical NOT. %I Add 1 to the first two parameters (for ANSI terminals). Binary operations are in

postfix form with the operands in the usual order. That is, to get x – 5, you must use %gx%{5}%- %i\e[%p1%d;p2%dr This example is used to change the scrolling region on C.Itoh terminals. The first parameter +1 specifies the start row, the second parameter +1 specifies the end row of the region. Both are used as numerics in the escape sequence.

EXAMPLES

Information files


\e[0;22;%p1%{30}%+%d;%p2%{40}%+%dm The sequence in this example is used to set a color and code feature. The code feature normal is set, the foreground color is set to the first parameter +30, and the background color is set to the second parameter +40.

Example of terminal information files This section contains examples of terminal information files for some terminal types. Examples are given of include files, color usage, function keys, setting fonts, and so on.

Comments and explanations are added where the number sign (#) precedes the text.

#******************************************************* # @(#) # @(#) File : vt100 # @(#) # @(#) Terminal : VTxxx terminals (CITOH / DEC) # @(#) Setup : VT100 – 7 bit; # @(#) Multinational Char. Set # @(#) Emulation Mode : ANSI 8-bit # @(#) Character Set : ISO Latin-1 # @(#) # @(#) Copyright : Baan Service b.v. (c) # @(#) Customer : Baan International b.v. # @(#) # @(#) Comment : If the terminal has a DEC Supplemental char.set # @(#) then vtansi_d must be included instead of vtansi # @(#) #******************************************************* # Include files #******************************************************* include=vtansi, #******************************************************* # @(#) # @(#) File : vtansi # @(#) # @(#) Comment : Generic terminf-file for VTxxx terminals # @(#) supporting ANSI mode and ISO character set # @(#) #******************************************************* #***************************** # Include files #***************************** include=vtansi.fkeys,

Information files


#***************************** # Booleans #***************************** vt100 #nclrwc mcf mgr, #***************************** # Numbers #***************************** cols=132 lines=24 cf_pos=0 gr_pos=0 tmo=5 disp_vt100=0, #***************************** # Strings #***************************** # Setup # # init \e[?3l set 80 cols # \e[0;1m reset attributes and set bold # \e> set keypad mode to numeric # \e[1l set cursor key mode to normal # \e[?25l set cursor mode to visible # init2 \e(B ASCII –> G0 # (fonts) \e-A Latin-1 –> G1 # Ô (SI) invoke G0 into GL # gr_on \e(0 Spec.Graph –> G0 # reset \e[0m reset attributes # \e[H cursor position 0,0 # \e[2J reset entire screen # init=\e[?3l\e[0;1m\e>\e[1l\e[?25l init2=\e(BÔ\e-A reset=\e[0m\e[0;0H\e[2J\e(BÔ\e-A, set80=\e[?3l set132=\e[?3h, bell=^G tmo=20, csr=%i\e[%p1%d;%p2%dr, # Line Draw Chars (Char.set: DEC Special Graphic) # gr_on=\e(0Ô gr_ond=\e(0Ô\e[0m

Information files


gr_off=\e(BÔ gr_offd=\e(BÔ\e[0m, cbl=m cbld=m cbr=j cbrd=j ctl=l ctld=l ctr=k ctrd=k dt=v dtd=v ut=w utd=w lt=t ltd=t rt=u rtd=u kr=n krd=n hb=q hbd=q vb=x vbd=x, # Code Features # cf_n=\e[0m cf_d=\e[0;1m cf_b=\e[0;5m cf_db=\e[0;1;5m cf_r=\e[0;7m cf_dr=\e[0;1;7m cf_br=\e[0;5;7m cf_dbr=\e[0;1;5;7m cf_u=\e[0;4m cf_du=\e[0;1;4m cf_bu=\e[0;4;5m cf_dbu=\e[0;1;4;5m cf_ru=\e[0;4;7m cf_dru=\e[0;1;4;7m cf_bru=\e[0;4;5;7m cf_dbru=\e[0;1;4;5;7m, # Cursor Control & Positioning # cu_on=\e[?25h cu_off=\e[?25l

Information files


cup=%i\e[%p1%d;%p2%dH, cuu=\e[%p1%dA cuu1=\e[1A cud=\e[%p1%dB cud1=\e[1B cuf=\e[%p1%dC cuf1=\e[1C cub=\e[%p1%dD cub1=\e[1D, home=\e[0;0H clear=\e[0;0H\e[2J\e[?25l, # Editing # inch=\e[@ delch=\e[P inli=\e[L delli=\e[M el=\e[0K es=\e[0J #ewin=, # Printer Control # aux_on=\e[5i aux_off=\e[4i, # Nls # nls_in=generic.in, #******************************************************** # @(#) # @(#) File : vtansi.fkeys # @(#) # @(#) Comment : Include-file for VTxxx terminals function-keys # @(#) (ANSI-compatible) # @(#) #******************************************************** # Available Keys #***************************** # Function Keys # #k6=\e[17~ #k7=\e[18~ #k8=\e[19~ #k9=\e[20~ #k10=\e[21~ k11=\e[23~

Information files


k12=\e[24~ k13=\e[25~ k14=\e[26~ #k15=\e[28~ #k16=\e[29~ #k17=\e[31~ #k18=\e[32~ #k19=\e[33~ #k20=\e[34~, # VT "Gold Keys" # pf1=\eOP pf2=\eOQ pf3=\eOR pf4=\eOS, # VT Cursor Pad # khlp=\e[28~ kdo=\e[29~ kfind=\e[1~ kinshere=\e[2~ kremove=\e[3~ kselect=\e[4~ kpscreen=\e[5~ knscreen=\e[6~ ku=\e[A kd=\e[B kf=\e[C kl=\e[D, #***************************** #BA6.2 Special Keys #***************************** #Misc. Keys # # F6 = kmenu F17 = kprocess # F7 = kcompose F18 = kkill # F8 = kre F19 = knextdisp # F9 = kcs F20 = kprevdisp # F10 = kswitch # kmenu=\e[17~, kcompose=\e[18~, kre=\e[19~, kcs=\e[20~, kswitch=\e[21~, kprocess=\e[31~,

Information files


kkill=\e[32~, knextdisp=\e[33~, kprevdisp=\e[34~, #*****************************

Printer information files The directory where printer information files are stored is $BSE/lib/printinf.

Create a subdirectory in the printinf directory. Its name must be the first letter of the future printer information file. The printer information file is stored in this subdirectory. For example, the printer information file for a Mannesmann mt910 is stored in the $BSE/lib/printinf/m/ directory.

The name of the file itself is an abbreviation of the printer name, for example, mt910.

You can include another printer information file at any position in the current file with the Include command. For example, include=mt910

The variables are filled in accordance with the specifications (escape sequences) of the printer as listed in the printer manual. Some of them can be omitted, because they are not required for the majority of the applications. These variables are marked with *.

A variable definition consists of a name, a =, an escape sequence (containing special characters), and a comma. Lines are closed by a new line character.

If a printer does not offer an escape sequence for boldface and underlined text, and the specific variables are left empty, the filter program simulates these functions by backspace and carriage return. The positions are then covered twice. You switch this simulation off by entering the value \000 for the definition of bold on/off or underline on/off, or by entering no value (for example pbold=,).

Information files


The escape sequences can contain special characters. They can be divided into escape codes and control codes.

Escape codes Control codes \b backspace Â to ^Z \E or \e escape ^[ \f form feed ^\ \n newline ^] \r carriage return ^^ \t tab ^_ \s space \nn decimal value nn=1-255 \0nn octal value nn=1-377 \xnn hexadecimal value nn=1-FF (for example \x1F)

You can use an octal value instead of an alphabetical representation. For example, “escape” then becomes \033.

The control codes are converted to the ASCII codes 1 to 31. For example, ^B equals the ASCII character with decimal value 2 (STX).

A printer information file can have the following Boolean entries:

rsf_pbold, reset font after pbold rsf_prev, reset font after prev rsf_punder, reset font after punder rsf_pobold, reset font after pobold rsf_porev, reset font after porev rsf_pounder, reset font after pounder

A printer information file can have the following variables:

barcode_dir= Bar-code directory (relative to $BSE/lib/barcode)

bin1= Select first paper bin.

bin2= Select second paper bin.

bin3= Select third paper bin.

Information files


bin4= Select fourth paper bin.

hpos= Set horizontal cursor position of the printer.

initpage= String sent before each page.

initpr= Initialization string preceding the output to the printer. This variable must be filled with the codes for large typeface.

initprog=X The output of program X (full path name) is sent to the printer.

initpr2= The second initialization string sent after initprog.

landscape= Select landscape printing.

large= Large typeface (10 cpi) control. Some printers require a code to change the typeface size.

nls_out= NLS output table name.

middle= Medium typeface (12cpi) control. Some printers require a code to change the typeface size.

You can use the following codes to set the print color:

p_black= p_red= p_green= p_yellow= p_blue= p_magenta= p_cyan= p_white=,

pbold= Print boldface characters. A boldface character can print wider than its original. This does not imply any proportional spacing. Printing graphic characters (with ASCII code over 127 decimal) yields additional line feeds on most Mannesmann printers. If this variable is not used, the bshell simulates boldface printing by reprinting each line, making use of the carriage return character.

Information files


pcbl= Print +. If this variable cannot be filled because the printer cannot print it, for example, a + is used.

pcbr= Print +. If this variable cannot be filled because the printer cannot print it, for example, a + is used.

pctl= Print +. If this variable cannot be filled because the printer cannot print it, for example, a + is used.

pctr= Print +. If this variable cannot be filled because the printer cannot print it, for example, a + is used.

pdbl_wide= Double wide mode on.

pdt= Print –. If this variable cannot be filled because the printer cannot print it, for example, a + is used.

pfont1=, to pfont16= Select font 1 to font 16. These fonts are user definable.

phb= Print –. If this variable cannot be filled because the printer cannot print it, for example, a – is used.

pitalic= Italic mode on.

pkr= Print +. If this variable cannot be filled because the printer cannot print it, for example, a + is used.

plt= Print |. If this variable cannot be filled because the printer cannot print it, for example, a + is used.

pnlq= NLQ mode on.

pobold= Switch off boldface printing without affecting character size.

podbl_wide= Double wide mode off.

Information files


pofont1=, to pofont16= Deselect font 1 to font 16. These fonts are user definable.

poitalic= Italic mode off.

ponlq= NLQ mode off.

porev= Reverse mode off.

portrait= Select portrait printing.

posubscript= Subscript mode off.

posuperscript= Superscript mode off.

pounder= Underlined printing off.

prev= Reverse mode (white on black).

prt= Print |. If this variable cannot be filled, for example, because the printer cannot print it, a + is used.

psubscript= Subscript mode on.

psuperscript= Superscript mode on.

punder= Print underlined characters. If this variable cannot be filled, the bshell simulates underlining by printing underscore characters on the next line.

put= Print –. If this variable cannot be filled because the printer cannot print it, for example, a + is used.

pvb= Print vertical bar. If this variable cannot be filled because the printer cannot print it, for example, a | (pipeline) is used.

Information files


q1=, to q13= These thirteen variables can be filled with strings that specify whether a character must be printed in double width, italicized, and so on. The variables are user-definable. These codes have been replaced and they will be removed in a future release.

resetpr= Resets the printer. The string is sent to the printer after all output. Fill this variable with a form feed (\014) followed by the large typeface codes.

resetprog=X The output of program X (full path name) is sent after the reset string.

resetpr2= The second reset string, sent after resetprog.

set0=, to set9= Set a character set of the printer. The default set is set0.

small= Small typeface (16.66-17 cpi) control. Some printers require a code to change typeface size.

usr1=, to usr16= Define user entry1 to user entry16.

Bar codes The report writer interfaces with the printer driver using bar-code scripts. A bar-code script saves the cursor position, prints a bar code with given height and returns to the saved cursor position. These scripts must be available in the barcode_dir directory. This directory is relative to $BSE/lib/barcode, so if barcode_dir = hp_barcode, the bar-code directory is $BSE/lib/barcode/hp_barcode. Bar-code scripts are prefixed by the word “type” and suffixed by a two-digit number. For example:

type01.

Information files


Following is an example of such a bar-code script. It saves the cursor position and restores it after the bar code has been printed. Bar codes can only be implemented when such a scheme is possible.

#!/bin/sh

#

# Sample driver for HP Laserjet 4

# with "Bar Codes & More Font Cartridge"

#

# Prints EAN/UPC with the code under it.

# $1 means the bar code

# $2 means the height of the bar code (number of lines)

#

code=$1

height=$2

Push()

{

# push cursor position (max 20x)

echo "\033&f0S\c"

}

Pop()

{

# pop cursor position

echo "\033&f1S\c"

}

NextRow()

{

# move to next row, relative

echo "\033&a+1R\c"

}

# – save cursor position – filter assumes same pos. after

bar code print

Push

str1=ècho $code | awk '{ print substr($1, 1, 5) }'`

str2=ècho $code | awk '{ print substr($1, 6, 5) }'`

# – select EAN/UPC 13 mil font

echo "\033(8Y\033(s1p12v0s3b0T\c"

while [ $height –gt 1 ]

do

Push

echo "($str1-$str2(\c"

Pop

NextRow

Information files


height=èxpr $height – 1`

done

# – last (empty) line of bar code

Push

echo "(- (\c"

Pop

# – select Courier 12cpi.

echo "\033(10U\033(s0p12.00h10.0v0s0b3T\c"

# – move x+25 dots

echo "\033*p+25X\c"

# – print code (text)

echo "$str1 $str2\c"

# – restore cursor position for filter

Pop

exit 0

Information files


Example of printer information file for the mt910 printer This shows what a printer information file can consist of. You can add comments in the same manner as in a terminal information file.

#mt910

small=\E{s16.66H\EL08

large=\E{s10H

middle=\E{s12H

initpr=\E{s12H\EF66

resetpr=\E{s12H\EF66\014

pctl=+

pctr=+

pcbl=+

pcbr=+

put=+

prt=+

plt=+

pdt=+

phb=-

pvb=|

pkr=+

pbold=\E"g1B

pobold=\E"g0B

prev=\E"g1K

porev=\E"g0K

punder=\EI

pounder=\EJ

pitalic=\E{s1S

poitalic=\E{s0S

landscape=\E"g1R

portrait=\E"g0R

nls_out=mt910.out,

5-1


This chapter describes the User Interface (UI) page mode in iBaan ERP. The UI page mode improves the response times on networks where information processing can be delayed, for example, in a wide area network (WAN).

In normal mode, the 4GL Engine validates the entered data per field. In the UI page mode, the 4GL Engine validates data per page, and not per field. The synchronous interaction between the UI driver and the bshell is therefore significantly reduced.

The UI page mode is designed for experienced iBaan ERP users, because the interaction between iBaan ERP and the user is not as extensive as in the normal mode.

In the normal mode, an error message is displayed immediately when data entered in the active field is not correct. In the UI page mode, an error-logging window appears, which shows all errors that occurred during the validation of all the data entered on the page.

In the UI page mode, the UI driver groups together a number of UI objects that form a logical unit. A UI object is for example, a field, a button, or a check box. The logical unit is known as a page. A page can be an Overview window or a tab in a details session with more than one tab.

If the UI page mode is selected, each UI object automatically belongs to a page. If the UI object is positioned on a tab, the object is considered part of the page associated with the related tab. In any other case, the UI object is part of the page associated with the Overview window.

5 User Interface (UI) page mode

User Interface (UI) page mode


The following functions are implemented in the UI page mode to improve network performance:

The UI handles the movement from an active element to another element without any communication with the bshell. An active element is a portion of the screen that is currently operational or subject to command operations. Usually the cursor or a highlighted section shows the active element on the display screen. Active elements are, for example, fields, command buttons, check boxes, or list boxes.

The UI client handles the behavior of the default button for the command buttons on a page.

Events that result from status changes of UI objects are delayed until a complete page is filled, or another synchronization event occurs. The delayed events are sent into a minimum number of network frames.

Tab processing When the UI page mode is selected, the UI driver processes Tab key movements in the details window. The Tab key sequence is identical to the creation order of the UI objects on a page. Other navigation keys, such as Page Up, Page Down, Home and End are reported to the bshell with the appropriate keystroke.

Default Button handling When the UI page mode is selected, the UI driver handles the default command button. This is the command button that is highlighted when the dialog box is initially displayed. It can also be the command button with the bold border, indicating that it is automatically selected if you press Enter.

Event processing If the UI page mode is selected, events are treated differently by the UI driver than when normal mode is selected. There are four different event categories:

Suppressed events. Delayed events. Synchronization events. Bypass events.



Suppressed events If the UI page mode is selected, a UI object does not send suppressed events to the bshell. Instead, suppressed events are handled locally by the UI driver on the client. An example of a suppressed event is to move from an active element to another active element.

Delayed events Status changes of UI objects can be delayed. As soon as a synchronization event occurs, for example, by clicking the Validate button, the changed UI objects are requested to synchronize their status with the 4GL engine. The delayed events are sent in the same order as the Tab key sequence of the UI objects on the page. This is not necessarily the order in which the user enters data. If possible, the delayed events are sent into one network frame to reduce response times.

Synchronization events The synchronization events make sure that the statuses of the changed UI objects are sent to the bshell for validation.

Synchronization events are:

Selecting a menu item. Clicking a button. Moving to another tab. Moving from a synchronizing field to another field. Starting a browse session. Pressing a key that is not handled by the UI client. Resizing a window. Using the scroll bar.

Bypass events The following bypass events are sent immediately to the bshell without first being synchronized with the delayed events:

Using the online Help. Closing a Windows application that was started through the application Start

feature of the UI client. Using OLE objects.



How to select the UI page mode The UI page mode is selected per user to make sure that inexperienced iBaan ERP users cannot use it. You must define the UI page mode in the user profile of the user. The user profile is defined in the User Management module in iBaan ERP Tools. Follow these steps to select the UI page mode for a user:

1 To select a user data template, or to create a new user data template, start the User Data Template (ttams1110m000) session in the Authorization Management System (AMS) module. Be sure to choose the Use Page Mode check box under Options on the System Data tab.

2 Start the User Data (ttaad2500m000) session in the User Management module. Double-click the user for which you want to select the UI page mode to start the details session.

3 Under Templates, enter the new User Data template, which is page-mode enabled. Click Save to return to the overview session.

4 On the Specific menu choose Convert Changes to Run Time DD to rebuild the user profile in the run time database.

5 Restart iBaan ERP to activate the changed user profile.

Check that the following are true to verify that the UI page mode has been successfully selected:

All the fields and options in the overview windows and detail windows are available.

All commands on the menus of the menu bar in an overview window are available.

On the Window menu the Validate command is available in an overview window.

The Validate button is displayed on a details window.



How to mark UI objects as synchronizing fields You can mark UI objects on an overview window or details window as synchronizing fields. This means that when you move from one active field or button to another field or button, all delayed events are sent to the bshell for validation. You can mark the following fields and buttons as synchronizing fields:

Edit fields. Check boxes. Option buttons. List boxes. Combo boxes.

You must use the Form Editor in iBaan ERP Tools to mark a form field as a synchronizing field. Complete the following steps to start the Form Editor:

1 On the iBaan ERP Tools menu, click Application Development, and then click Forms to start the Forms (ttadv3500m000) session.

2 Select a form. On the Specific menu choose Check Out to release the form for modification.

3 On the Specific menu, choose Edit/View Form to start the Form Editor.

Depending on the form type, the appropriate Form Editor starts. The following form editors are available in iBaan ERP:

The Static Form Editor, which shows the form in an ASCII format. The Dynamic Form Editor, which is a graphical editor in a Windows format.

You can carry out one of the following procedures to mark a field as a synchronizing field:

Static Forms 1 In the ASCII editor, click the field to start the Form Fields (ttadv3501s000)

session. 2 On the General tab, select the Synchronized check box. 3 Click Close to return to the Form Editor. 4 On the Specific menu, choose Check In to finish the procedure.



Dynamic Forms 1 In the graphical Dynamic Form Editor, click the field to start the Field

Properties session. 2 On the Miscellaneous tab, select the Synchronized check box. 3 Click OK to return to the graphical Dynamic Form Editor. 4 On the Specific menu, choose Check In to finish the procedure.

6-1


General This chapter describes an aspect essential to solving errors in a iBaan ERP environment: error logging. Error logging is to keep a record of error messages in a log file. The log file contains information on when the error occurred and which processes were then active. See the section “To log errors.”

If you want to submit an error to the Baan Customer Service and Support Site, add the error logging report to your error report.

To log errors Certain actions in a iBaan ERP application can result in an error. Usually an error is displayed and from it you can see what went wrong.

To localize errors, a status report of the program is written to a log file. Use this file to find out where and when the error occurred.

Log file The log files to which the errors are written are stored in the $BSE/log directory. Its name format is:

log.<program name>

This means that when an error occurs in bshell6.2, it is logged in the log.bshell6.2 file. If it occurs in bic6.2, it is logged in log.bic6.2, and so on.

On a Windows platform, errors are logged in the Windows Event Viewer.

6 Customer-support tools

Customer-support tools


Log-file layout The header of the log file is: START of log message, followed by:

Date, time, logon name, and TTY number. Source program name with line number. Keyword. Process, user, and group identifiers for program. User type, language code, logon code and TTY number of the user. Error number and bdb error number. Error message as displayed on screen.

Log file maintenance If the log file is not regularly purged it grows enormously, which affects your storage capacity. Also, a large log file is difficult to read. You are therefore advised to rename the log file to log.sav on a weekly basis. After a backup has been made of the system including log.sav, you can remove it from the system. The backup must be kept for two weeks.

Submitting errors to customer support If you are confronted with a bshell error message for which you have no solution, you can contact the Customer Support Center. To your report you must add the part of the log file that relates to it. You can print this part using the UNIX grep command (for example by date, time, logon code, or TTY number).

The following section contains an example of error logging. The log file contains two error reports. Suppose you want to print the first one. You can do this using grep in four ways: by date, time, user name, or TTY number. The following example shows the command lines for each of these:

cat log.bshell6.2 | grep 91-07-29 |pr |lp –d{printer name} date cat log.bshell6.2 | grep 16:53:14 | pr |lp –d{printer name} time cat log.bshell6.2 | grep bsp | pr |lp –d{printer name} name cat log.bshell6.2 |grep 22 | pr | lp –d{printer name} TTY



Example error logging Each line of the following output starts with date, time, logon name, and TTY number, such as the following:

98-03-04[15:06:54]etimban: 98-03-04[15:06:54]etimban: ******* S T A R T of Log message ******* 98-03-04[15:06:55]etimban: Log message called from /vobs/tt/lib/al_1/al_fpath.c: #241 keyword: sopen 98-03-04[15:06:55]etimban: Pid 19313 Uid 10575 Euid 10575 Gid 1700 Egid 1700 98-03-04[15:06:55]etimban: user_type S language 2 user_name etimban TTY ote locale ISO88591/NULL 98-03-04[15:06:55]etimban: Errno 2 (No such file or directory) bdb_errno 0 98-03-04[15:06:55]etimban: Log_mesg: 98-03-04[15:06:55]etimban: No definition in definition file for sopen(F_BRDD:dtffas402, dtffas402) 98-03-04[15:06:55]etimban: ********** E N D of Log message **********

NOTE



7-1


Database management This chapter describes the executable programs used for database management that are located in the $BSE/bin directory. Whether you have all the executable programs described in this chapter depends on your particular installation set.

The programs are sorted by type of database server. References are included for programs described in other documents.

General audit_srv6.2 This is the name of the server that handles logging of actions on the database. See the chapter “Audit management.”

bdbpre6.2 Program to convert database tables to a sequential dump. See the chapter “Database tools.”

bdbpost6.2 Program to create database tables from a sequential dump. See the chapter “Database tools.”

bdbreconfig6.2 Program to reconfigure database tables. See the chapter “Database tools.”

refint6.2 Function to check the referential integrity of database tables. See the chapter “Database tools.”

gcommand6.2 Database test program used internally to solve problems. Not intended for the end user.

qptool6.2 Database test program used internally to solve problems. Not intended for the end user.

blogind6.x A program that connects the client to the server using secure passwords.

7 Executable programs

Executable programs


Oracle ora7_inst6.2 The program used to install the Oracle driver.

ora7_deinst6.2 The program used to deinstall the Oracle driver.

ora7_srv6.2 This is the driver for Oracle Version 7.

ora7_maint6.2 The Oracle version of the program used to maintain the database.

ora8_srv6.2 This is the driver for Oracle Version 8.

ora8_maint6.2 The program used to maintain Oracle version 8.

Informix inf_install6.2 The program used to install the Informix driver.

inf_srv6.2 This is the Informix driver itself.

inf_admin6.2 The shell script for doing administration.

inf_maint6.2 The Informix version of the program used to maintain the database.

DB2 db2_install6.2 The program used to install the DB2 driver.

db2v5_srv6.2 This is the driver executable program that functions with DB2 V5.

db2_admin6.2 The shell script for doing administration with DB2.

db2v5_maint6.2 This is the maintenance executable program, to be used with the DBA module, which works with DB2 V5.

Executable programs


Logic server (bshell)

Bshell6.2 This is a virtual processor between the user interface, database drivers, applications, and the operating system. This program makes applications, including iBaan ERP Tools, independent of the operating system. The bshell functions as a shell between the application and the operating system.

When you start the user interface, it connects with the bshell on a machine on the network. This is the usual way to start the bshell. Note that you can run the bshell and user interface on different machines. The following settings are required:

Add a line to your local or remote $BSE/lib/ipc_info file similar to:

bshell s 0 0 s ${BSE}/bin/bshell6.2

When you run on a remote host fill the r user> file as described in the chapter “Remote databases”.

You can specify where the application logic server is located in the User Data Template (ttams1110m000) session. You must then connect the template to the user using the User Data (ttaad2500m000) session.

The DS_AS environment variable overrules these settings of the user file (example: DS_AS=host!bshell).

SYNOPSIS

Bshell6.2 [options] [program [program arguments]]

Options for bshell6.2 are described in the following sections:

To debug the bshell during run time − Baan CPU. − Scheduler. − File I/O. − Miscellaneous. − Message and log extract.

Memory usage. Miscellaneous.

To pass options to the bshell, enter them in the command line of the BW Configurator, for example:

-- –set CORE=1 –dbgcpu –dbgfun ttaad2100m000 − pass "-set CORE=1 –dbgcpu –dbgfun" options to Bshell − and run Application Configuration (ttaad2100m000) session

Executable programs


Bshell logs all its output to $BSE_TMP/bshell.PID. This log file is removed when the bshell exits normally. You can instruct the bshell to keep the log file with the –keeplog option.

To debug the bshell during run time To debug the bshell while the iBaan ERP application is running, display the Option Dialog dialog box, which appears as an icon while you run iBaan ERP, and click Debug Bshell. The Run Time Debugging of Bshell dialog box appears. You can also choose these options from the command line.

Baan CPU

Debug functions In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Debug Functions. Or, from the command line, run –dbgfun.

Use debug version of the CPU In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Debug CPU. Or, from the command line, run –dbgcpu.

Show Bshell CPU instructions In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Debug Instructions. Or, from the command line, run –dbginstr.

Dump 3GL stack traces on function entry In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Dump Stack Traces. Or, from the command line, run –dbgstack.

Debug get.var and put.var functions In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Getvat/Putvar debug. Or, from the command line, run –dbggpvar.

Show program flow In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Program Flow. Or, from the command line, run –dbgflow.

Scheduler

Debug scheduler In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Debug Scheduler. Or, from the command line, run –dbgsched.

Executable programs


Show process actions (for example, activate, sleep, kill) In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Show Process Actions. Or, from the command line, run –dbgmulact.

File I/O

Show all files that are currently opened by the Bshell In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Show Opened Files. Or, from the command line, run –dbgfile.

Debug file access In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Debug File Access. Or, from the command line, run –dbgfdev.

Miscellaneous

Show object information In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Show Object Information. Or, from the command line, run –dbgobj.

Show whether domains, data definitions and objects are loaded from disk or shared memory In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Show SRDD Use. Or, from the command line, run –dbgsrdduse.

Show various TSS debugging information In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Debug TSS. Or, from the command line, run –dbgtss.

Show data input options (not for fields) In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Debug data.input(). Or, from the command line, run –dbgdata.

Stop debugger, if possible, when a message is sent to the message window In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Debug Messages. Or, from the command line, run –dbgmesg.

Show loaded resources In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Debug Resources. Or, from the command line, run –dbgres.

Do not remove the logfile after ending the Bshell In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Keep Log File. Or, from the command line, run –keeplog.

Executable programs


Add time stamps to Bshell log output In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Add Time Stamps. Or, from the command line, run –logtime.

Database related

Show the Baan database activities initiated from the Bshell In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Show BDB Actions. Or, from the command line, run –dbgbdbact.

Show actions related to enums In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Print Enums. Or, from the command line, run –dbgenums.

Show locking errors In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Show Locking Errors. Or, from the command line, run –dbglck.

Show database server type In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Show BDB Server Type. Or, from the command line, run –dbgsrv.

BDB/SQL Tracing

To trace iBaan ERP database and SQL actions, display the Option Dialog dialog box and click Debug Bshell. The Run Time Debugging of Bshell dialog box appears. You can also choose these options from the command line.

BDB Debug Flags

Show the drivers and parameters currently in use In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Driver Type. Or, from the command line, run BDB_DEBUG=01.

Show database actions such as Insert, Update, Delete, Commit, and Abort In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Database Actions. Or, from the command line, run BDB_DEBUG=02.

Show information on currently set locks In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Delayed Locks. Or, from the command line, run BDB_DEBUG=04.

Executable programs


Show references between tables In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select References. Or, from the command line, run BDB_DEBUG=010.

Show all tables using native storage format In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Multibyte Storage. Or, from the command line, run BDB_DEBUG=040.

Show the permissions and roles allowed for each user In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Permissions/Roles. Or, from the command line, run BDB_DEBUG=0100.

BDB_DEBUG Value Shows the current setting that can be used in a –set BDB_DEBUG=<value> from the command line.

TT SQL TRACE Flags

Show the full text of a query with an ID number In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Show Query with ID. Or, from the command line, run TT_SQL_TRACE=040.

Show how long a query has been running In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Query Execution Times. Or, from the command line, run TT_SQL_TRACE=0200.

Show main SQL functions such as SQLExec, SQLParse, SQLFetch, and SQLBind In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Internal SQL Functions. Or, from the command line, run TT_SQL_TRACE=02000.

Show the best possible design for indexing, joins, and so on In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Query Evaluation Plan. Or, from the command line, run TT_SQL_TRACE=04000.

Show all full table scans In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Show Full Table Scans. Or, from the command line, run TT_SQL_TRACE=020000.

Executable programs


Show low-level communication between client and driver In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Show BDB Communication. Or, from the command line, run TT_SQL_TRACE=040000.

Show current time to level of milliseconds: YYYYMMDDhhmmss.mmm In the Option Dialog dialog box, select Debug Bshell. On the BDB/SQL Tracing tab, select Add Time Stamps (SQL). Or, from the command line, run TT_SQL_TRACE=0400000.

TT_SQL_TRACE value Shows the current setting that can be used in a –set TT_SQL_TRACE=<value> from the command line.

Memory usage Show currently running processes in bshell In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Dump Process List. This option is not available from the command line.

Show total memory usage In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Total Memory. Or, from the command line, run -dbgmemtot.

Show free memory list In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Free Memory. Or, from the command line, run –dbgmemfree.

Show used memory list In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Memory Used. Or, from the command line, run –dbgmemused.

Show memory usage per block In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Memory Block List. Or, from the command line, run –dbgmemblk.

Show all memory statistics In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select All Memory Info. Or, from the command line, run –dbgmem.

Executable programs


Add remark to log file (enter the remark in the field, then click the button) In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Write Remark to Log. This option is not available from the command line.

Display shared-memory information In the Option Dialog dialog box, select Debug Bshell. On the Bshell Debug Levels tab, select Display Shared Mem. This option is not available from the command line.

Miscellaneous –vV : version information.

–r : show resources.

–deftext : show Bshell tex.ts.

–mdebug : display Bshell messages sent to display server.

–dbgref : show reference paths.

–dbgrefer : show references.

–dbgbdbact : show database actions.

–dbgenums : show loading of enums.

–dbgpty : debug pseudo terminals (pty).

–dbgorb : debug ORB integration (where available).

–set var=val : set environment variable var to val.

–logfile <file> : log stdout/stderr output in file.

–appendlog : append to logfile (only useful with –logfile option).

–nolog : stdout and stderr go to the controlling terminal.

–delay sec : delay for sec seconds before continuing.

bshcmd6.2 This command can be used to change the log facilities of the Logic Server (bshell) or kill one or more bshell processes. The actions done with this command are performed while the bshell is runing.

SYNOPSIS

bshcmd6.2 [options] <bshell_pid>

Executable programs


Possible options:

–v : print version information.

–p : show process list.

–m : show memory usage.

–d <dbglvl> : set DEBUG_LEVEL to (octal) <dbglvl>.

The following <dbglvl> values are available:

0000000001 : show data input actions.

0000000002 : show object information.

0000000004 : show reference paths.

0000000020 : debug functions.

0000000040 : database server information.

0000000100 : show delayed locks.

0000000200 : show process actions (sleep, kill, and so on).

0000000400 : database reference information.

0000001000 : show database actions.

0000002000 : debug file access.

0000004000 : show loaded resources.

0000010000 : show loading of enums.

0000020000 : show Bshell CPU instructions.

0000040000 : use debug version of the CPU.

0000100000 : show whether domains, data definitions and objects are loaded from disk or shared memory.

0000200000 : debug get.var & put.var functions.

0000400000 : debug scheduler.

0001000000 : debug pseudo terminals.

0002000000 : show opened sequential files.

0004000000 : debug TSS functions.

00020000000: debut ORB integration.

00040000000: show stack traces.

Executable programs


00100000000: debug messages.

00200000000: show program flow.

–k pid : Kill bshell process ID pid.

–e : kill all bshell processes.

–M "message" : Send message to bshell.

–W sec : Wait until the previously issued command is executed. After this the previous command is overwritten.

–w sec : Wait sec seconds for bshell to execute command.

–u sec : Send SIGUSR1 to bshell (wakeup). Only to be used in combination with –w option. Waits sec seconds to see if the command is executed.

–s : Show entire contents of log file (if accessible).

Only to be used in combination with –p and –w option.

-l : Print log file name of bshell.

Only to be used in combination with –p and –w option.

-T cmdstr : Modify BDB_DEBUG or TT_SQL_TRACE (bshell) and DBSLOG, TT_SGL_TRACE, {DBMS}STAT (drivers) tracing variables. cmdstr can contain multiple commands of the form:

trace variable=value: set variable to value trace variable+value: add bits to variable trace variable-value: remove bits from variable

All output is stored in the bshell's log file (default: $BSE_TMP/bshell.pid).

Only one command can be active at a time. New commands overwrite previous ones.

Check the return value to see if a command has been processed.

The bshell_pid process number is a member of the output of the UNIX ps command.

bshcmd6.2 –s –p –w 10 <bshell_pid> Show the process list, and wait 10 seconds for a response. If no actions are done within 10 seconds, no output is given.

bshcmd6.2 –d 02000 <bshell_pid> Set DEBUG_LEVEL to 02000.

bshcmd6.2 –M "Hello" –u 10 –w 10 <bshell_pid> Send a message to a specific bshell.

REMARKS

EXAMPLES

Executable programs


bshcmd6.2 –k <pid> <bshell_pid> Kill the bshell process <pid>. The <pid> process number can be accessed from the shell program (ttstpshell) with the ps command.

bshcmd6.2 –T “TT_SQL_TRACE+02000” <bshell_pid> Set TT_SQL_TRACE to log interface calls.

badmin6.2 Used to perform administration of the bshell. The usage is as follows: badmin6.2 [-UuVv] [-qo outfile] [-qe errfile] –chkuser <user> | –chkgroup –ostype

Available options are:

–U or –u : print usage.

–V or –v : print release number.

–qo outfile : redirect standard output to file outfile.

–qe errfile : redirect error output to file errfile.

–chkuser <user> : returns a 0 if user exists, otherwise returns a 1.

–chkgroup <group> : returns a 0 if group exists, otherwise returns a 1.

–chkpwd <user> : returns a 0 if successful, otherwise returns a 1.

–getpwd <user> : returns a 0 if successful, otherwise returns a 1.

–ostype <ostype> : returns 0 if operating system is ostype, otherwise returns a 1. ostype can be either NT or UNIX.

–P : Tag for Aged Password Notification. Only effective with other flags.

Binary Logging And Tracing The tracing utility BLAT (binary logging and tracing) generates a set of related loggings that spawn the whole range from bshell to the database driver. All generated logs have a defined format that facilitates automatic processing.

This tracing allows you to log all transaction between database driver and database server. But you can also trace which session is executing a certain query and which processes are used on the operating system to perform the task and how the database driver splits a query.

Executable programs


The processing of the loggings is supposed to be done by using tools. The directory “$BSE/api/blat” contains the header files that define the binary log data. There is also a Perl module “Blat.pm” available for processing the log data using Perl scripts.

Start Tracing Currently there is only one way to activate BLAT. The environment variable “BLAT” has to be set to activate the logging.

The level of logging can be set per category, but The default logging can be set by assigning “default” to the environment variable BLAT. To avoid problems in the environment variable handling due to the presence of spaces in the BLAT configuration, an alternative separator can be used. This separator can be defined with the environment variable “BLATSEP”.

Using the Baan Windows interface (BW.exe) this can configured as follows: Start “BW Configuration” (BW.EXE /CONFIG) and fill in the field ‘Command’ as like the following example:

-- -set BLATSEP=_ -set BLAT=sql_s_01111_th_0_retry_s_1 [<sessioncode>]

A blat.log file –containing the trace output- will be generated in $BSE_TMP on the server.

Log and trace options:

Process related (proc)

This log type contains information that is needed to administer the Baan processes and their hierarchy.

The process related log gives information about process startup, process termination and the relation between Baan processes.

This log type generates the information that is needed to process and correlate the information in the general framework. Therefore this type is essential for the processing of all other logs. Because of this strong relationship, the initialization functions will automatically enable this log type when any other log is enabled.

Example: start this tracing with “proc s 01”

Defined log states:

the state is currently evaluated as Boolean (disabled when 0 or enabled otherwise). To avoid problems with future extensions, the state “01” should be used.

Executable programs


Threshold logging:

not applicable

Session related (sess)

This log type contains information about the lifetime of a Baan session and its propagation into other levels of the Baan processes.

The session related log gives information about the starting and stopping of sessions at several levels in the Baan clients and database drivers. A session at the 3GL level might result in multiple sessions in the lower levels. This happens as soon as multiple database drivers are needed to handle a Baan session, or when a session is modifying audited tables.

Example: start this tracing with “sess s 01”

Defined log states:

The logging at the highest version evaluates the state a Boolean (disabled when 0 or enabled otherwise). By specifying additional flags loggings at lower levels can be added.

Any value != 0 3GL / BDB level (client)

Flag 002 DBS level (database driver)

Flag 004 DBDL level (database driver / RDBMS integration)

(Not yet implemented)

Flag 010 DBS level (audit driver)

Threshold logging:

not applicable

Retry points (retry)

This log type contains information about the handling of the retry points in the bshell. The setting of a retry point is always explicitly done by a 3GL command.

A jump to a retry point can be the result of a 3GL command or the handling of recoverable BDB errors.

Example: start this tracing with “retry s 01”

Executable programs


Defined log states:

the state is currently evaluated as Boolean (disabled when 0 or enabled otherwise). To avoid problems with future extensions, the state “01” should be used.

Threshold logging:

not applicable

Transaction related (trans)

This log type contains information the handling of commit and abort actions.

The Transaction related log gives information about the handling at several levels in the Baan clients and database drivers. A transaction at the 3GL level might result in multiple transactions in the lower levels. This happens as soon as multiple database drivers are needed to handle a Baan session, or when a session is modifying audited tables.

In Baan a transaction corresponds with a session.

Example: start this tracing with “trans s 01 th 0.5”

Defined log states:

The logging at the highest version evaluates the state a Boolean (disabled when 0 or enabled otherwise). By specifying additional flags loggings at lower levels can be added.

Any value != 0 3GL / BDB level (client)

Flag 002 DBS level (database driver)

Flag 004 DBDL level (database driver / RDBMS integration)

(Not yet implemented)

Flag 010 DBS level (audit driver)

Threshold logging:

The “trans” log type supports the threshold mechanism.

Query related (sql)

This log type contains information the handling of queries.

A query at the 3GL level might result in multiple queries in the lower levels.

This is inherent to the design of the level-1 database drivers, but it might happen in level-2 as well.

Executable programs


Example: start this tracing with “sql s 011 th 1.5”

Defined log states (3GL / BDB level)

0000001 Log aggregated information.

0000002 Log all actions.

0000010 Log BaanSQL text.

0000020 Log bind variables.

0000040 Log selected data.

Defined log states (Database driver / Level-2):

0000100 Log aggregated information.

0000200 Log all actions.

0001000 Log database dependent SQL text.

0002000 Log bind variables.

0004000 Log selected data.

Defined log states (Database driver / Level-1):

0010000 Log aggregated information

Thresholds

The Query related log type supports threshold logging.

This means that logs are only generated after completing the command when a threshold has been exceeded. This implies that the order of the information that is generated on different levels will be reversed.

It is also possible that a log is delayed: when an exec exceeds the threshold, it might be needed to generate a parse log as well.

Future extensions

Where binds and selected values. Logs in the RDBMS dependant parts of the database drivers.

Threshold logging

Some types support thresholds (like the trans and sql loggings).

When a threshold has been set, all loggings that do not exceed the threshold value will be discarded.

Executable programs


Setting thresholds is a powerful method to limit the amount of generated data, while problems will still be visible.

Combining options

Multiple settings can be combined using the following syntax:

blat_expr : template

| template blat_oper blat_expr

;

template : named_template

| base_template

| log_descr

;

blat_oper : "+" (the next settings are enabled)

| "-" (the next settings are disabled)

| "=" (the next settings replaces the

current settings)

;

named_template : "default" | "off" ;

base_template : log_type log_elem_list ;

log_type : defined_type

| type_tag <number>

;

defined_type : "proc" | "sess" | "retry" | "trans"

| "sql" ;

state_tag : "s" | "state" ;

threshold_tag : "th" | "threshold" ;

type_tag : "t" | "type" ;

log_elem_list : log_elem

| log_elem_list log_elem

;

Executable programs


log_elem : log_state | log_thres ;

log_state : state_tag <number> ;

log_thres : threshold_tag duration ;

duration : duration in seconds (float)

| "default"

| "off"

;

log_descr : log_tag quoted_path ;

log_tag : "log" | "logfile" ;

quoted_path : """ <path> """ ;

Example:

BLAT=’ log “/tmp/mylog” default + sql s 01100 th 0.05 ‘

BLATSEP=_ BLAT= sql_s_01111_th_0_retry_s_1

bls6.2 Used to convert a binary trace file to a readable format. A Perl script with the same functionality is available in $BSE/api/blat/bls.pl as an example how to write dedicated tools to process the BLAT log files.

The usage is as follows: bls6.2 [-UuVv] [-help] [-log <file>] [ -th|threshold <n> ] [-proc <n>] [ -sess <n>] [ -retry <n> ] [ -sql <n> ] [-trans <n> ] [ - hn|hostname] [-fs <str>] [-rs <str>]




–help : print option description.

–log : specify the input file containing the data. If this option is omitted, “./blatlog” is used.

–th or –threshold : Filter all data with a duration shorter than the specified threshold (in millli-seconds).

Executable programs


–proc : Filter process related data. When the argument set to 0, this information is suppressed. (default: 1)

–retry : Filter retry point related data When the argument set to 0, this information is suppressed. (default: 1)

–sess : Filter session related data When the argument set to 0, this information is suppressed. (default: 1)

–sql : Filter query related data When the argument set to 0, this information is suppressed. (default: 1)

–trans : Filter transaction related data When the argument set to 0, this information is suppressed. (default: 1)

–hn or –hostname : show the hostname instead of the IP adress

–fs : set field separator (default ":")

–rs : set record separator (default "\n").

btop6.2 Used to process a binary trace file and relate queries from the bshell and database driver. The top <n> queries that did take the most (total or single-action) time are shown in a separate report.

The usage is as follows: btop6.2 [-UuVv] [-help] [-log <file>] [-top <n>] [-query_len <n>] [-line_len <n>] [-host] [–ip] [-fs <str>] [-rs <str>] [-dfmt <str>] [-oid] [-ototal]




–help : print option description.

–log : specify the input file containing the data. If this option is omitted, “./blatlog” is used.

–top : set the number of queries that are presented in the Top-<n> report (default 20).

–line_len : Top-<n> format option. Set the width of the Top-<n> report. (default 80 and when possible automatically derived from the terminal settings).

–query_len : Top-<n> format option. Set the length of the query as presented in the Top-<n>. (default derived from screen width).

Executable programs


–host : show the hostId (default suppressed).

–ip : Show the IP-address as hostId instead of the hostname.

–fs : set field separator (default ":").

–rs : set record separator (default "\n").

–dfmt : set date/time format (see strftime documentation). Sub-seconds = %%s.

–oid : sort processes and sessions on id (default on time).

–ototal : sort top queries on total time (default on max time per action).

The btop6.2 tool works on the log type ‘sql’, so take care to enable at least the following logging: ‘sql s 011’ to generate the needed information.

Installation cmt6.2 Script for component merge tool. Used to migrate the sources from user-customized applications to new iBaan ERP versions.

install6.2 Script for installing the iBaan ERP software.

install.help ASCII file containing Help for the installation procedure.

sh_server6.2 Shell server used to execute system-dependent commands.

bsp.setperm6.2 Script used to assign the correct permissions to all the iBaan ERP software.

binperm6.2. Script used to assign the correct permissions to binaries in the $BSE/bin directory after a new porting system is set up.

Development bic6.2 Program compiler for Baan C compiler.

repgen6.2 Report generator.

Executable programs


std_gen6.2 4GL-program preprocessor.

bic_cstub6.2 Converts a iBaan ERP library to a C library.

bic_info6.2 Shows information for a specified object.

Printer management filter6.2 Program to translate iBaan ERP native codes to printer codes used by the pdaemon6.2 program.

lp6.2 System spooler interface for the pdaemon6.2 program.

pdaemon6.2 Daemon process to print requests from the environment. This program must be started by the user root.

The options that can be used to call the printer daemon are:

–v : print version and porting information of the daemon.

–k : kill the running printer daemon.

–f : Start daemon as foreground process (for debugging).

–d n: Print debugging information to stderr. The higher n is, the more information is output.

–r : Remove the lock file and start daemon (use this in rc.start).

–h : print the above options.

Resources:

maxproc: maximum number of background (filter) jobs. Default: 20.

maxtries: maximum number of minutes to retry opening the database files. Default: 30 minutes.

sleeptime: sleep time between two polls. Default: 10 seconds.

shell_cmd: shell that runs the lp6.2 system interface. Default: /bin/sh.

strict: The interval in seconds that the printer daemon command (up/down) is checked for all devices. If this resource is not set, the printer daemon command of the device in question is checked as soon as a print job is found.

Executable programs


Change default values in the $BSE/lib/defaults/pdaemon6.2 file.

It is highly recommended that you group physical printers into logical printers. The daemon recognizes whether a printer is busy and chooses another physical printer device. It also calculates the size of the various queues for physical printers, so it chooses the queue with the lowest number of bytes.

Shared memory shmmanager6.2 Manager program for shared memory. See the chapter “Shared memory management.”

shmtimer6.2 Daemon process that stores and updates the current time in shared memory. See the chapter “Shared memory management.”

shmvalues6.2 Program to generate entries for the "shm_param" file. See the chapter “Shared memory management.”

srdd_init6.2 Program to load the data dictionary for the bshell from shared memory.

Network client6.2 Test program of the client part.

fs6.2 Program to handle remote file I/O. With this program you can approach files on another system. On the other system you must put the fs6.2 program in the ipc_info file. See the chapter “Database management.”

ipc_boot6.2 Program to start remote processes. See the chapter “Database management.”

server6.2 Test program of the server part.

IMPORTANT

Executable programs


TRITON Super Set tsscomp6.2 Compiles and checks TSS information file tss6.2. See the chapter “Multibyte management.”

tsscvt6.2 TSS conversion filter. See the chapter “Multibyte management.”

tssinfo6.2 Gives information about current TSS settings. See the chapter “Multibyte management.”

uniinfo6.2 The uniinfo6.2 option requires an argument: –u. The usage is as follows: uniinfo6.2 [-vahsdow] [-l locale] [-u Unicode hex value] [-n Native hex value]

uniinfo6.2 shows all Unicode values from 0x0000 to 0xffff and the corresponding native character values, UTF-8 values, and TSS character values in hexadecimal format. By default, uniinfo6.2 shows only values from 0x000 to 0x00ff.

uniinfo6.2 converts multibyte character strings into TSS strings or vice versa. You can determine the input/output character set by setting the locale with the –l flag, otherwise it is read from the user file. The default mode is to convert to the bshell's character set. This can be reversed with the –o option. Some additional options are:

–v : show version information.

–d : show additional debug information.

–w : do not accept any conversion warnings, but exit(1) instead.

–a : show all Unicode from 0x0000 to 0xffff.

–h : show Unicode from 0xE800 to 0xEA00.

–s : do not show when native character is zero.

–o : show the indexed contents of mapping tables.

–l : choose another locale.

–u : shows Native, UTF-8, and TSS value for the Unicode value.

–n : shows Unicode, UTF-8, and TSS value for the native value.

–t : shows Unicode, Native, and UTF-8 value for the TSS value.

–8 : shows Unicode, Native, and TSS value for the UTF-8 value.

Executable programs


–m : use shared memory instead of local application memory.

–p : performance check (you must use –dp option as parameter).

–dp : shows performance measurements of basic Unicode, UTF-8, and TSS conversion routines.

For more information, see the chapter “Multibyte management.”

unimap6.2 Do not use the –u option with this executable program. The usage is as follows: unimap6.2 [-vdeow] [mapping table file] [-l locale] [dbcs ranges]

This program generates Unicode mapping tables based on the mapping information file, which is provided in .txt format in Microsoft Excel. The mapping file is called locale and is located in $BSE/lib/unicode/. The locale.N2U file is the Native to Unicode mapping file, and the locale.U2N file is the Unicode to Native mapping file. The leading byte ranges of the double-byte character set can be specified as optional parameters.

Additional flags are:

–v : show program version.

–d : show additional debug information.

–e : add 0x8080 to convert JIS0208 values to EUC. This conversion is applied to Native to Unicode mapping file only.

–f : place no zero value where no mapping value is specified from 0x00 to 0x20 rather than 0x00 to 0xff.

–w : do not accept any conversion warnings, but exit(1) instead.

–o : print mapping tables in ASCII hex format.

–z : place zero value where no mapping value is specified.

See the chapter “Multibyte management.”

Middleware orb_srv6.2 Implementation program that supports the server portion of object request broker (ORB) communication.

bshellorb6.2 Variation of the bshell used to integrate iBaan ERP with CORBA programs.

Executable programs


UNIX equivalents compress6.2 Program to compress data. Equivalent to the UNIX compress command.

diff6.2 Program used to compare two files. Equivalent to the UNIX diff command.

kermit6.2 Serial communications program. Equivalent of the UNIX kermit command.

sort6.2 Sort program. Equivalent of the UNIX sort command. You can use the environment variable BSE_SORT to specify a path where temporary files are stored during the sort process.

Miscellaneous binput6.2 Program to read input. This can be used in shell scripts.

bput6.2 Program to set or print terminal settings.

encrypt6.2 Program to encrypt passwords, which is used to fill the r<user> file. See the chapter “Database management.”

mirror6.2 Program for demonstrations and courses.

nlsedit6.2 Editor to maintain input and output conversion tables for Native Language Support. See the chapter “Native language support.”

popup6.2 Program to handle popup screens. This can be used in shell scripts.

sum6.2 Sum program, used to calculate and patch executable programs.

Executable programs


8-1


General There are three categories of errors:

Error numbers 1-99 are generated by UNIX. Error numbers 100-899 are database errors. Error numbers 900-999 are network errors.

Error numbers between 34 and 100 are system-dependent.

UNIX errors 1 EPERM Not owner This error indicates an attempt to modify a file that cannot be modified, except by its owner or a super user. This error also appears when ordinary users attempt actions allowed only to the super user.

2 ENOENT No such file or directory This error 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 error means that no process can be found that corresponds to the one specified.

4 EINTR Interrupted system call This error means that an asynchronous signal (such as interrupt or quit), which the user has chosen 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 error means that there has been a 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 error means that 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.

8 Errors

Errors


7 E2BIG Arg list too long This error occurs when an argument list longer than 5120 bytes is presented to a member of the UNIX exec family system calls.

8 ENOEXEC Exec format error This error means 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. A magic number is the first two bytes in a file, used to determine what type of file it is. See a.out(5).

9 EBADF Bad file number This error means that either 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 error means that a process that has no child processes waiting has executed a wait. A child process is a process spawned by another process (the parent process).

11 EAGAIN No more processes This error means that a fork failed, either because the process table of the system is full or because the user is not allowed to create any more processes.

12 ENOMEM Not enough space This error means that during an exec or sbrk, a program has asked for more space than the system is able to supply. This is not a temporary condition. The maximum space size is a system parameter. The 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 error means that an attempt was made to access a file in a manner forbidden by the protection system.

14 EFAULT Bad address This error means that the system encountered a hardware fault when it attempted to use an argument of a system call.

15 ENOTBLK Block device required This error means that a nonblock file was specified where a block device was required, for example, in mount.

Errors


16 EBUSY Device busy This error means that an attempt was made to mount a device that was already mounted or to dismount a device on which there is an active file (open file, current directory, mounted-on file, active text segment). The error also occurs when an attempt is made to enable accounting that is already enabled.

17 EEXIST File exists This error means that an existing file was mentioned in an inappropriate context, for example, a link.

18 EXDEV Cross-device link This error means that an attempt was made to link to a file on another device.

19 ENODEV No such device This error means that an attempt was made to apply an inappropriate system call to a device, for example, a read on a write-only device.

20 ENOTDIR Not a directory This error means 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 error means that an attempt was made to write to a directory.

22 EINVAL Invalid argument This error means that an invalid argument was used, for example, dismounting a nonmounted device; mentioning 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 error means that the systems table of open files is full, and temporarily no more open commands can be accepted.

24 EMFILE Too many open files This error means that too many file descriptors are open. No process can have more than 20 file descriptors open at a time.

25 ENOTTY Not a typewriter This error means that the selected device does not have the properties of a terminal.

26 ETXTBSY Text file busy This error means that an attempt was made to execute a pure-procedure program that is currently open for writing or reading. It can also mean that an attempt was made to open for writing a pure-procedure program that is being executed.

Errors


27 EFBIG File too large This error means that the size of a file exceeded the maximum (1,082,201,088 bytes) or ULIMIT; see ulimit(S).

28 ENOSPC No space left on device This error means that when an ordinary file is written, there is no free space left on the device.

29 ESPIPE Illegal seek This error means that an lseek was issued to a pipe.

30 EROFS Read-only file system This error means that an attempt was made to modify a file or directory on a read-only device.

31 EMLINK Too many links This error means that an attempt was made to link more than the maximum number of links to a file. The maximum number of links to one file is 1000.

32 EPIPE Broken pipe This error means that a write was made 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 error means that the argument of a function in the math package is out of the domain of the function.

34 ERANGE Math result not representable This error means that the value of a function in the math package cannot be represented within machine precision.

Database errors 100 EDUPL This error means that a duplicate value exists.

101 ENOTOPEN This error means that the table is not open.

102 EBADARG This error means that an illegal argument has been specified.

103 EBADKEY This error means that an illegal key description has been specified. Use the bdbpre and bdbpost tools.

Errors


106 ENOTEXCL This error means that the table is not exclusively locked action. You can either wait until the lock on table is released or you can remove the lock yourself.

107 ELOCKED This error means that the record you are trying to retrieve is locked. You can either wait until the lock is released or remove the lock yourself.

108 EKEXISTS This error means that the key already exists.

109 EPRIMKEY This error means that you are trying to perform an illegal action on a primary key. Refer to the log file for more information.

110 EENDFILE This error means that the end of the file has been reached.

111 ENOREC This error means that no record was found that matches the query criteria.

112 ENOCURR This error means that there is no current record.

113 EFLOCKED This error means that the table is locked. You can either wait until the lock is released or you can remove the lock.

114 EFNAME File name too long This error means that you are using a file name that is too long. Refer to your system requirements to check the maximum length for a file name.

116 EBADMEM This error means that the system cannot allocate memory because it is out of memory. Try restarting the bshell as a possible solution.

117 EBADCOLL This error means that there is a problem with the collating or sorting order.

123 ENOSHMEM This error means that no shared memory is initialized. You can use, for example, the rc.start script to initialize shared memory.

129 EUSER This error means that too many sessions have been started.

136 ENOSPACE This error means that there is no space in shared memory. You can either initialize the shared memory, or change the shared memory parameters.

Errors


140 ETRANSON This error means that this operation is invalid when the transaction is on.

141 ETRANSOFF This error means that this operation is invalid when the transaction is off.

142 EADMON This error means that an administration process is running.

146 ENOSNAPSHOT This error means that the system cannot take a snapshot of the database, probably because it is locked by another user. You can either wait until the lock is released or you can remove the lock.

148 EOFRANGE This error means that there has been an error in the data-type range check.

201 EROWCHANGED This error means that the record was changed after a delayed lock.

202 EDBLOCKED This error means that the database is locked. You can either wait until the lock is released or you can remove the lock yourself.

203 ETRANSACTIONON This error means that this action is not allowed within a transaction.

204 EISREADONLY This error means that this transaction is read only.

205 ENOTINRANGE This error means that the field value is out of range and does not agree with the domain definition.

206 ENOTLOCKED This error means that the record is not locked.

207 EAUDIT This error means that there is an error of the audit trailer.

208 EPERMISSION This error means that the action you have just attempted is not allowed at this time.

209 EMIRROR This error means that there is an error in the mirroring of the database. The tables are inconsistent. You can use bdbpre and bdbpost to copy the tables correctly.

Errors


210 EMLOCKED This error means 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 error means that the transaction is started, but not updated. This is an internal bshell error.

214 EUNALLOWEDCOMPNR This error means that an operation for mapping company numbers is not allowed. If the logical company is not equal to the physical company, you are not allowed to do a drop/clear table operation.

215 EDBDILLEGAL This error indicates an illegal state that should never occur.

251 EAUDSETUP This error means that the audit server setup is not correct. See the log.audit file for more information.

252 EAUDCORRUPT This error means that an audit file is corrupt. See the log.audit file for more information.

253 EAUDLOCKED This error means that the audit file is locked by another user. See the log.audit file for more information.

254 EAUDABORT This error means that a commit transaction has failed in the audit server action See the log.audit file for more information.

301 ESQLQUERY This is a general SQL error code. This error occurs when there is a problem with the SQL syntax.

302 ESQLSYNTAX This error means that the SQL syntax is not correct.

303 ESQLREFER This error means that a reference in the query cannot be found.

304 ESQLUNDEFINED This error occurs when something went wrong but no error code can be set.

Errors


305 ESQLWRONGROW This error means that a wrong record was returned. This probably means either that the table index is corrupt or that the RDBMS has a different sorting order than the iBaan ERP software.

501 EMEMORY This is an internal memory error.

502 EBDBON This error means that the user is already logged on.

503 EBADADRS This error means that an illegal address has been used.

504 EBADFLD This error means that a column is undefined.

505 ENOSERVER This error means either that no server is specified in tabledef6.1, or that the server cannot be started. See the log file for more information.

506 ENOTABLE This error means that the table does not exist.

507 ETABLEEXIST This error means that the table that you are trying to create already exists.

508 EBDBNOTON This error means that you are not logged on to a database.

509 EBADCURSOR This error means that you have a bad memory cursor or that a bad table pointer has been specified.

510 EDBNOTON This error means that the database is not on. Start the database to correct the problem.

511 EWRONGVERSION This error means that the version of client is not the same as the version of the server.

512 EDDCORRUPT This error means that the data dictionary is corrupt. Use bdbpre and bdbpost tools to repair it.

513 ENODD This error means that the data dictionary was not found.

Errors


514 ESECURITY (Oracle) This is a security error. It probably means you do not have the correct user or group permission.

515 ELICENSEERROR This is a license error. It probably indicates an unpatched binary.

516 EUPDSEGM This error occurs during the making or filling of rollback segments. It probably means that the disk is full.

517 EDELAYED This is a general error indicating delayed locking.

518 ENOSESSION This error means that an invalid session code has been specified.

519 ENOCOMPNR This error means that either no company number or an illegal company number has been specified. A valid company number is a number between 0 and 999.

520 EBUFUPD This error occurs when flushing of buffered updates fails. The flushing can fail due to a lock or referential integrity constraint. 521 ENOSHM This error means that shared memory has not been loaded. See the chapter “Shared memory” for more information about starting shared memory.

522 EBDBDBCONNECTIONLOST This error means that the connection between the driver and database has been lost.

523 E_BDB_FULL Users request cannot be carried out because the required space is not available in the data base. The database administrator must extend or reorganize allocated space manually.

600 EREFERENCE This is a general reference error. For more information, see the log file.

601 EREFLOCKED This error means that the reference table is locked. You can either wait until the lock is released or remove the lock yourself.

602 EUNDEFREF This error means that the reference is not defined. It is probably a problem in the run time data dictionary. For more information, see the log file.

Errors


604 EREFUPDATE This error means that a reference could not be updated.

605 EREFEXISTS This error means that the record cannot be deleted while the reference exists. See the log file for more information.

606 EREFNOTEXISTS This error means that the reference does not exist.

607 ENOREFTBL This error means that the reference table was not found. The data dictionary might not be correct. See the log file for more information.

608 ENOREFCNT This error means that no reference counter fields are present.

609 EUPDREFCNT This error can occur when the reference counter is updated.

700 ESETLOCALE This error can occur when you are setting the locale. See the log file for more information.

If an error code greater than 1000 is displayed, the error can be retrieved as follows, depending on the database driver used:

Informix/Oracle: error – 1000 gives DB error

Example UNIX

Error no: 11400 Error: 11400 – 1000 = 10400 UNIX error = 0 (last two digits)

Example Oracle:

Error no: 1979 Error: 1979 – 1000 = 979 Not a GROUP BY

When a fatal error occurs, more information is stored in the log files in the $BSE/log directory. For example, if bdbpost causes an error, it is reported in the log.bdbpost file.

NOTE

9-1


General Shared memory is a part of the internal memory intended for common usage. All users can read from and write to it. In iBaan ERP Tools the shared memory contains part of the data dictionary.

A prerequisite for shared memory is that it must be supported by the hardware and there must be sufficient internal memory available.

This chapter describes the way shared memory can be used for iBaan ERP Tools.

To use the shared memory manager The shared memory manager is located in the $BSE/bin directory and can be started as follows:

shmmanager6.2 [-iksavr]

The options are:

–i: installation of shared memory.

–k: deletion of created shared-memory blocks. After shared memory is deleted you must reinstall it. You can only use this option if all processes that use shared memory have finished. If not, the system displays a message.

–s: display of technical information on the contents of shared memory. This includes:

Common bshell pointers Description of segment table

–a: display of allocation data, such as addresses, segments, size, and so on.

–v: display of machine and porting data.

9 Shared memory management

Shared memory management


–r: resetting of shared memory. Removes all data from shared memory except the first segment. You do not have to reinstall shared memory afterwards. The result of this option is the same as when using –k option followed by –i option. You can only use this option if all processes that use shared memory have finished. If not, the system displays a message:

# of attaches = <number> Cannot remove ..# of attaches not equal to zero

The –a, –i, and –v options are discussed in the section “Installation of shared memory.”

Installation of shared memory The bshell requires at least 4 MB of internal memory to function properly. After the kernel selects a virtual address, the kernel does not always leave enough memory for the bshell. You must therefore specify a virtual address to determine where shared memory is allocated in internal memory.

You can determine an adequate address using the shared memory manager, shmmanager6.2. This section includes the instructions for the installation of shared memory. Following the installation is a description of error messages that can come up during installation. The section “Kernel parameters” contains the minimum values of the kernel parameters.

To create an entry in the shm_param file The shmmanager6.2 program uses the shm_param parameter file, which contains parameters to install shared memory for a specific machine. This file is stored in the ${BSE}/lib directory.

Create an empty entry in this file for the machine in question. It must read as follows:

Machine_id/OS release:; { }

This entry must be preceded by a default entry. See also the section “Example file shm_param parameter file.”

The OS release is only used if the file contains more than one entry for the same machine ID. You can display the machine ID and the OS release using the shmmanager6.2 –v command.

NOTE



Determine shared-memory parameters You can determine these parameters by using one of the following commands:

shmvalues6.2 shmmanager6.2 –a

To use shmvalues6.2 The shmvalues6.2 program finds the boundaries of shared memory by itself and generates a default entry, which you can include in the shm_param parameter file. For example:

default:; { } Machine_id:; { } Machine_id/OS release:; { SHM_START = a40000 SHM_STEP = 80000 SHM_BUFSIZE = 512 SHM_MAXMEM = 10 }

SHM_START is the start address of the first shared-memory segment.

SHM_STEP is the difference between the start addresses of two consecutive segments.

SHM_BUFSIZE is the size of a segment in KB.

SHM_MAXMEM is the maximum number of segments.

The syntax for shmvalues6.2 is:

shmvalues6.2 [-dvV] [-m Seg_size_in_MB] [-s Seg_size_in_KB]

Possible options are as follows:

–d : the –d option provides you with additional information through error messages when the boundaries of the operating system are exceeded.

–m : the shmvalues6.2 program first tries to allocate 4 MB of memory to make sure enough memory is left after shared memory has been installed. You can use the –m option to increase or decrease the amount of allocated memory. You specify it in megabytes, that is, –m 3 = 3 MB.



–vV : the –v or –V option displays machine and porting data.

–s : Use this option to increase or decrease the SHM_BUFSIZE value (default 512 KB). This value must be less than or equal to the kernel parameter SHMMAX.

You can create a parameter file by entering:

shmvalues6.2>shm_param

The entry is written to standard output (stdout) and all error messages are written to stderr.

SHM_BUFSIZE is below recommendations; try tuning the kernel.

SHM_MAXMEM is below recommendations; try tuning the kernel.

Can't allocate <size> MB of memory: <system error message>; Please try tuning the kernel or lower the value

Couldn't create any ID of any size: <system error message>

Error while removing shmid <shmid>: <system error message>

Failed to attach any segment: <system error message>

Error while detaching shmid <shmid>: <system error message>

The shmvalues6.2 program returns a positive value in the event of a fatal error.

To use shmmanager6.2 If you cannot determine the shared-memory parameters by using shmvalues6.2, you can use the shared memory manager. This takes longer, but it yields more information on the addresses of the segments and on the instances where errors can occur.

Execute the shmmanager6.2 with the –a option.

You are prompted for the number of kilobytes to be allocated and the number of segments to be created. For the bshell, specify 4096 KB and 10 segments respectively.

NOTE

CAUTIONS

FATAL ERRORS



For example:

# shmmanager6.2 –a No. of kbytes to be malloc: 4096 No. of shm segments to be created: 10 addr[0]: 0xa40000 id[0]: 40 < SHM_START = a40000 addr[1]: 0xac0000 id[1]: 41 addr[2]: 0xb40000 id[2]: 42 addr[3]: 0xbc0000 id[3]: 43 addr[4]: 0xc40000 id[4]: 44 addr[5]: 0xcc0000 id[5]: 45 addr[6]: 0xd40000 id[6]: 46 addr[7]: 0xdc0000 id[7]: 47 addr[8]: 0xe40000 id[8]: 48 addr[9]: 0xec0000 id[9]: 49 < SHM_MAXMEM = 10 step 0x80000 < SHM_STEP = 80000 step 0x80000 step 0x80000 step 0x80000 step 0x80000 step 0x80000 step 0x80000 step 0x80000 step 0x80000 step 0x80000 ret 0

To fill the entry in the shm_param parameter file Enter the variables as determined in the shm_param parameter file. The following variables are mandatory:

The start address of the first shared-memory segment: SHM_START The number of shared-memory segments: SHM_MAXMEM The difference between the start addresses of the segments: SHM_STEP

You can retrieve the values of these variables from the information in the example on the preceding page. For this example, fill the entry in the parameter file as follows:

Machine_id/OS release:; { SHM_START = a40000 SHM_MAXMEM = 10 SHM_STEP = 80000 }



To install shared memory Use the –i option to install shared memory. For example:

# shmmanager6.2 –i BUFSZ 524288, MAXATTCH 10, START 0xa40000, STEP 0x80000 Start /usr/bse/bin/shmtimer6.2: Shmtimer started: pid = 22743, time = 790343035 (Tue Jan 17 12:43:55 1995) Starting successful

During installation the BSE shell variable must be the same as the one for the bshell users. You can avoid installing shared memory manually each time by including the installation in your system’s start-up procedure. If the BSE variable is not /usr/bse, it must be set during the start-up procedure and shmmanager6.2 must be started with the –I option.

To start shmtimer6.2 The UNIX time() function is a system call often called in database servers. On multiprocessor systems, use of the time() function can be quite heavy. Even though a process can run successively on different processors, this must be invisible to the process. The process requires that each processor returns the same time, using time(). Therefore, the processors have to synchronize their internal clocks every time the time() function is called.

The shmtimer6.2 program can prevent this overhead. shmtimer6.2 is a daemon process that writes the current time in shared memory. The time is updated every second. This reduces the number of calls of the time() function to a maximum of one per second.

When shared memory (shmmanager6.2 –i) is initialized, the shmtimer6.2 program starts. When shared memory is removed (shmmanager6.2 –k), the shmtimer6.2 stops first. The following options can be used for shmtimer6.2:

–i : Initialize shmtimer6.2 A shmtimer6.2 program is started, and runs in the background.

–k : Kill shmtimer6.2 The running shmtimer6.2 program is killed. The allocated shared memory is cleared, but not removed.

–s : Show status as stored in shared memory:

− The current time − The process ID of the running timer

–u : Show information about shmtimer6.2

NOTE



–v : show version and porting data of shmtimer6.2

When shmtimer6.2 stops, the shared memory is cleared, as described for the –koption. From then on, the system calls the UNIX time() function instead of reading the time from shared memory.

If shmtimer6.2 is killed, shmtimer6.2 cannot clear its shared memory. Because shmtimer6.2 is killed, the time in shared memory is never updated, but the time is still read from shared memory. In that case, shmtimer6.2 –s gives a warning. A new shmtimer6.2 can be started with shmtimer6.2 –i.

Error messages during installation The error messages are described in the order in which they can occur.

No more space # shmmanager6.2 –a No. of kbytes to be malloc: 4096 no more space abort – core dumped

This error happens because some computer systems put a limit on the amount of virtual memory (MAXUMEM) used by a process. Hence the shared memory manager cannot be capable of allocating 4096 K.

Solution: Adjust the kernel parameters. See the section “Kernel requirements.”

Cannot create shared-memory segments of 512K # shmmanager6.2 –a No. of kbytes to be malloc: 4096 No. of shm segments to be created: 10 shmget errno 22 etc...... Errno 22 (EINVAL): The kernel cannot create any shared-memory segments of 512 K (SHMMAX).




Not enough virtual memory # shmmanager6.2 –a No. of kilobytes to be malloc: 4096 No. of shm segments to be created: 10 shmat errno XX id 46 addr[0]: 0xa40000 id[0]: 40 addr[1]: 0xac0000 id[1]: 41 addr[2]: 0xb40000 id[2]: 42 addr[3]: 0xbc0000 id[3]: 43 addr[4]: 0xc40000 id[4]: 44 addr[5]: 0xcc0000 id[5]: 45 addr[6]: 0xffffffff id[6]: 46 (first invalid segment) addr[7]: 0 id[7]: 6747 (junk) addr[8]: 0 id[8]: 9644 (junk) addr[9]: 0 id[9]: 20492 (junk) step 0x80000 step 0x80000 step 0x80000 step 0x80000 step 0x80000 step 0x80000 step 0xff53ffff step 0x1 step 0 ret 0 Errno XX can be: 12 (ENOMEM): The user process does not have sufficient virtual memory (MAXUMEM) 24 (EMFILE): (In this example) the kernel cannot create more than 6 shared-memory segments per process (SHMSEG).


If the kernel cannot allocate 10 segments, as in the previous example, you need to fill the entry in the shm_param file as follows:

Machine_id/OS release:; { SHM_START = a40000 SHM_MAXMEM = 6 SHM_STEP = 80000 }



Syntax srdd_tab The srdd_tab6.2 file can be divided into several sections. Each section is indicated by the package combination for which components must be loaded into shared memory. For example:

package=31Sa

This parameter means that the components below this line belong to package combination 31Sa.

After this line the domains are specified first. For example: dti.pd dtt.pd

The following data is the table definitions. For example: dttaad000 dttaad001

After that the objects must be placed. For example: ottstpconv ottstpdisplay

So the syntax must be: package={pc} for domains: <d{p}.pd> for data definitions: <d{p}{t}> for objects and reports: <o{p}{m}{o}>

The abbreviations are: {pc} package combination {p} package {m} module {t} table {o} object (program/report)

You can also read parts of a data dictionary on a remote system into shared memory. To do this, write the host name of the remote system at the beginning of a line. For example:

${BSE}/standard6.2/ddbaan/dti/dti.pd ibm1!/usr3/bse/standard6.2/ddbaan/dtd/dtd.pd ${BSE}/standard6.2/ddbaan/dttadv/dttadv100 ${BSE}/standard6.2/ddbaan/dtppdm/dtppdm100 /usr2/bse/standard6.2/ttB40_a_CP/ottadv/oadv1100

If the srdd_tab6.2 file contains a redirection to a remote system, a remote user file must be available for the user who executes srdd_init6.2.



To fill shared memory You can load parts of the data dictionary into shared memory: data definitions, objects, reports, and domains. In the $BSE/lib/srdd_tab6.2 file, specify which parts to load into shared memory. You can fill the srdd_tab6.2 file that use iBaan ERP Tools:

Shared Memory Data (ttaad4150m000) session To load program and report objects.

%SEttaad1120m000 session To load table definitions and domains.

The parts of the data dictionary loaded into shared memory have an entry that consists of the inode number, date, time, and name. If the entry of a part in shared memory does not match the entry for that part on hard disk, the parts on hard disk are loaded locally, but not into shared memory. The old part remains in shared memory until you execute shmmanager –k to delete shared memory blocks. Then you reinstall shared memory using shmmanager –i.

Use the srdd_init6.2 program to load the parts of the data dictionary into shared memory. The available options are:

–l : print what is done by the program, including error messages, if any. Use only in combination with the –i option.

–i : initialize the parts that must be loaded in shared memory.

–p : print a list of loaded components.

–v : version information of the program.

Use the shmmanager6.2 –s command or the ipcs –m UNIX command to see which segments are used and how much space is left to load other parts of the data dictionary.

Error messages and other messages are written to stderr. You can write them to a file by entering the command:

srdd_init6.2 –i 2> file name

The ${BSE}/etc directory contains the rc.start file. This program is executed at system startup. Shared memory is installed, filled, and initialized for a BSE environment specified in this file. The shmvalues6.2, shmmanager6.2, and srdd_init6.2 programs are used.



Kernel requirements

General description of adjusting UNIX kernels

Static kernels

The kernel of a UNIX system is a program that runs from booting to shutting down. The kernel performs all actions in which user programs access resources. Internally, the kernel keeps lists of the actions that are executed simultaneously. Because those lists have limited capacity, a very large number of simultaneous actions can cause an overflow.

When there is an overflow, the kernel cannot process any new actions. Consequently, when another action is added to the list the system displays an error message. For example, if the number of files opened at the same time is greater than permitted by the kernel, the system responds with error message 23 (ENFILE File table overflow).

To avoid this error message, the user can create a new kernel that allows a larger number of files to be opened simultaneously. The kernel is stored on the system in different forms.

First, it includes sources, libraries, an include file and, most importantly, a file containing kernel parameters.

Second, the kernel is present as an executable and can be generated from the previously-mentioned files.

Third, a kernel runs in the internal memory.

Adjusting the kernel requires a three-step procedure:

1 Adjust the file with kernel parameters. 2 Generate the kernel as an executable from the parameter file. 3 Reboot the computer, allowing the new kernel to be loaded into internal

memory and be started.



Dynamic kernels

With a static kernel, boundaries are set through a kernel parameter. With a dynamic kernel, the user can adjust boundaries during run time. The kernel of an IBM system is fully dynamic (except for a few parameters), so the user does not have to reboot the computer to activate changes. You can use a command to modify the kernel of an IBM while the system is still running. Furthermore, the kernel is automatically adjusted if the required number of resources is greater than permitted by the kernel.

The kernels of Digital and Sun systems are semidynamic. When the system is booted, some kernel parameters are read from a file and the kernel is adjusted accordingly. The user can adjust other parameters while the kernel is running.

Kernel parameters The recommended values for the parameters presuppose the following conditions:

A standard iBaan ERP installation. One active session per bshell.

You can use the sar command while working in iBaan ERP to keep track of parameter usage and adjust the parameters where necessary. This is of particular interest for iBaan ERP customization. When using other databases, take into account the kernel tuning references from the corresponding documentation.

When using raw devices, you must set the parameters relating to the cache such as NBUF or BUFPAGES to low values, according to the database-specific documentation, not to the relatively high values suggested in this document.

The following descriptions for parameters refer to the number of users. If there is more than one active session per bshell, instead of number of users, read number of active sessions.

Processes

NPROC The NPROC parameter specifies the maximum number of processes that can be run simultaneously in the system.

NPROC = 64 * users & NPROC = 1.1 * MAXUP Adjust: error 11

NOTE



MAXUP The MAXUP parameter specifies the maximum number of processes that can be run per logon code. This restriction does not apply to the super user. If several users log on using the same logon code, those users must share this number of processes.

MAXUP=64 Adjust: error 11, message 'fork failed: too many processes'

REGION, NREGION The REGION parameter specifies the maximum number of program regions that can be active at the same time. Each UNIX process has at least three regions: text, data, and stack. The text part is shared if a program runs more than once. Shared memory also uses the region resources.

REGION=3* * NPROC

Files

NFILE The NFILE parameter specifies the maximum number of files that can be opened simultaneously on the system.

NFILE = 512 * users Adjust: Message “ file table overflow”

The command sar –v 1 1 shows the number of open files and the maximum number of files to be opened, under the file-sz header.

NOFILES, SFNOLIM(SVR4), MAXFILES (HP) The NOFILE parameter specifies the maximum number of files that can be opened per process.

NOFILES >+ 256 Adjust: error 24, Too many connected sessions (INGRES).

On an SVR4 system the user can use not only the sfnolim kernel parameter, but also a command to change the maximum number of open files per process. That command is “limit – 256”, including the quotation marks. This new value only applies in this shell.



Buffers

NBUF Under SVR3 and SVR4, the NBUF parameter has a different meaning.

SVR3 The NBUF parameter specifies the number of system buffers available for block I/O.

NBUF = 1/3 of total internal memory (SVR3) NBUF = 0 (HP)

SVR4 In UNIX SVR4, buffers contain only indexes, superblocks, and file header information. They do not contain file data. The actual file data is stored in pages of virtual memory. The amount of virtual memory available for this purpose is determined by the SEGMAPSZ parameter.

The NBUF parameter specifies the number of system buffer headers available for block I/O.

NBUF = default, for example, 100 Adjust: Performance problems (sar –b)

NHBUF The NHBUF parameter specifies the number of hash table entries that can be allocated in the system.

NHBUF = 1/5 * NBUF Adjust: Performance problems

BUFPAGES The BUFPAGES parameter specifies the number of pages in the file’s system buffer cache.

BUFPAGES = 1/3 of total internal memory) /4096, (HP) Adjust: Performance problems

SEGMAPSZ The SEGMAPSZ parameter specifies the size of the bitmap for file I/O. This map determines the number of 4K pages and therefore the amount of memory available for the I/O file. If the value is 0, the kernel calculates the value as a function of the amount of physical memory.

SEGMAPSZ = 0 or 1/x of total internal memory. Adjust: Performance problems



BUFHWM The BUFHWM parameter specifies the maximum amount of memory, in kilobytes, that can be used by block I/O buffers. If the value of BUFHWM is 0 (the default), the kernel sets the value of the I/O buffers to 25% of available memory.

Shared memory

SHMALL The SHMALL parameter specifies the maximum amount of shared-memory text segments that can be created.

SHMALL = SHMNI Adjust: error 24

SHMMAX The SHMMAX parameter specifies the maximum size, in bytes, of a shared-memory segment that can be created. Several shared-memory segments of this size can be created in an environment per process.

SHMAX >= SHM_BUFSIZE (in $BSE/lib/shm_param)

SHMMIN The SHMMIN parameter specifies the maximum size of a shared-memory segment in bytes.

SHMMNI = SHMSEG * ENVIRONMENTS Test with: ipcs –m

SHMSEG The SHMSEG parameter specifies the maximum number of shared-memory segments that can be used by a process.

SHMSEG = 30 Adjust: error 24

Semaphores

SEMMAP The SEMMAP specifies the number of entries in the control map used to manage semaphores. This map is used to keep track of free areas in the system pool of semaphores.

SEMMAP = SEMNI +2 Adjust: Message “Mfree map overflow”



SEMMNI The SEMMNI parameter specifies the maximum number of semaphore identifiers in the kernel. This is the number of unique semaphore sets that can be active at any given time.

SEMMNI = 32 * users Adjust: error 28

SEMMNS The SEMMNS parameter specifies the maximum number of ipc –sb semaphores permitted in the system.

SEMMNS = SEMMNI Test with: “ipc –sb”

SEMUME The SEMUME parameter specifies the maximum number of undo entries per undo structure. Each undo entry represents a semaphore that has been modified with the undo option specified in the semop(2) system call.

SEMUME = 10 Adjust: error 22

Message

MSGMAP The MSGMAP parameter specifies the number of entries in the control map, for example 100, used to manage message segments. Each entry in this map represents a free area in the message buffer area.

MSGMAP = default Adjust: Message “mfree map overflow”

MSGMAX The MSGMAX parameter specifies the maximum size of a message in bytes. If the protocol m (message queues) is used in the $BSSE/lib/ipc_info file, the value must be set to 4096.

MSGMAX = 4096 & MSGMAX <= MSGMNB

MSGMNB The MSGMNB parameter specifies the maximum length, in bytes, of a message queue.

MSGMNG = 4096 Check with: ipcs –qo



MSGMNI The MSGMNI parameter specifies the maximum number of message queues that can be used on the system.

MSGMNI=32 *users Adjust: error 28

MSGSEG The MSGSEG parameter specifies the number of message segments permitted on the system, for example 1024. Each message on a message queue consists of one or more message segments. The size of each segment is specified by the MSGSSZ parameter.

MSGSEG = default

MSGSSZ The MSGSSZ parameter specifies the size, in bytes, of a message segment, for example, 8. Each message consists of a contiguous set of message segments large enough to hold the text of the message.

MSGSSZ = default

MSGTQL The MSGTQL parameter specifies the maximum number of message headers, in other words, the maximum number of open messages.

MSGTQL = 32 * users

General kernel parameters

ULIMIT, HFSZLIM, SFSZLIM

SVR3 The ULIMIT parameter specifies the maximum size of a single file on disk. SCO UNIX and HP use blocks of 512K.

SVR4 The kernel parameter ULIMIT is not used in SVR4. SVR4 uses the HFSZLIM parameter for the hard limit and SFSZLIM for the soft limit. These parameters are in bytes.

SVR3 and SVR4 both contain the built-in command ULIMIT through which the kernel parameter value can be reduced.



NINODE The NINODE parameter specifies the maximum number of inodes that can be used in the SV file system. This includes open files, used pipes, and the current directory. The UFSNINODE parameter specifies the number of inodes for the UFS file systems.

Example file shm_param parameter # The default entry (please do not modify)

default:;

{

SHM_BUFSIZE = 512

SHM_MAXMEM = 30

SHM_STEP = 80000

}

SCO_UNIX_386/3.2.2:;

{

SHM_START = 80400000

SHM_MAXMEM = 10

SHM_STEP = 400000

}

10-1


General The client/server architecture as supported by iBaan ERP enables the user to work with several database types. These databases can be distributed over one or multiple systems. A remote database configuration is one where an application server (bshell) and the database are not on the same system.

The possible reasons for setting up a remote database configuration are:

System performance If all users start the application on the same system, the CPU is primarily occupied by the bshell and the display server. You can divide the load by letting the users work on local systems and keeping the database on a remote system.

Lack of disk space on local system If all tables cannot be stored on the same system due to a lack of disk space, some of the tables can be installed on a second system.

Distributed applications For practical reasons you can decide to install the application tables on different systems per application.

Mirrored databases For security reasons database actions can be carried out on two systems simultaneously by using database mirroring.

This chapter describes how to set up a remote database configuration and also explains how to use it.

10 Remote databases

Remote databases


Settings for remote database configurations To work with a remote database configuration, you must predefine a number of settings. You must know on which systems the tables are located, and also which types of databases are going to be used. Also, if the communication structure has not changed, the porting sets of the binaries on the local and remote systems can be different, otherwise they must be equal. It is recommended to have the same porting sets. This chapter explains how you can configure a remote database system.

The tables can be located in various ways in a remote database configuration:

All tables are located on one or more systems. A part of the tables are located on the local and another part of the tables are

located on a remote system.

Figure 5, All tables on remote system In the above figure, the user interface and the application logic (bshell) are both installed on the local host. From version 6.1 forward, they can be installed on different systems.

Assuming that all tables are installed on a remote system and the user interface and application logic (bshell) are installed locally, the following files must be available for the system to work normally:

Remote databases


Local host On the local host, the following files and directories must be present:

$BSE/bin:

audit_srv6.2 hostid6.2 ba6.2 kermit6.2 badmin6.2 licd6.2 Bdbpost6.2 licmon6.2 bdbpre6.2 lp6.2 Bdbreconfig6.2 nlsedit6.2 bic6.2popup6.2 pdaemon6.2 bic_cstub6.2 qcommand6.2 bic_info6.2 qptool6.2 Binperm6.2 refint6.2 binput6.2 repgen6.2 bput6.2 rz6.2 brand6.2 shmmanager6.2 Bshcmd6.2 shmvalues6.2 Bshell6.2 sort6.2 bsp.setperm6.2 srdd_init6.2 client6.2 std_gen6.2 Compress6.2 sum6.2 encrypt6.2 sz6.2 Explode6.2 tsscomp6.2 filter6.2 tsscvt6.2 Gcommand6.2 tssinfo6.2

$BSE/lib:

tabledef6.2 fd6.2.<package_comb> (optional) ipc_info /user/r<user>

$BSE/etc: rc.start rc.stop

$BSE/tmp

$BSE/log

Remote databases


Remote It is recommended that you install the complete $BSE environment on the remote system. If no application is started on the remote system, executable programs such as bshell6.2 and ba6.2 do not need to be installed there. It is practical if one or more users can run the application locally on the remote system. For this reason the application must be run on the remote system. That is why the entire BSE environment must be installed there.

The remote system must include at least the following files:

$BSE/bin: fs6.2 ipc_boot6.2 database_servers with associated executable programs, such as ora7_srv6.2 installation and validation programs, such as install6.2, licd6.2, and so on.

$BSE/lib: tabledef6.2 user/u<user> ipc_info driver-specific directory, for example, ora fd.6.2.<package_comb> (optional)

$BSE/etc – rc.start rc.stop

If these files are available on the local and the remote system, respectively, you can adapt the following files. The data dictionary contains sessions where you can adapt the files. It is better to adapt the files in the sessions in the data dictionary and not directly in the files themselves.

Local On the local system the following files are configuration dependent:

tabledef6.2 Database Definitions (ttaad4510m000) and Tables by Database (ttaad4111m000)).

u<user> Remote User Data (ttaad2500m000). r<user> Remote User Data (ttaad2501m000).

Remote databases


tabledef6.2 Start the application by executing the user interface (UI). The UI then starts the application logic (bshell), which reads the tabledef6.2 file to search for the table location and database type. Tables can be stored on a local or remote system, which is also indicated in this file.

The tabledef6.2 file is filled using the Database Definitions (ttaad4510m000) and Tables by Database (ttaad4111m000) sessions. These sessions indicate whether tables are installed on a remote database.

The tabledef6.2 file is located in the $BSE/lib directory. For more information about tabledef6.2, refer to the help text for Database Management business object.

You can specify whether each table is installed locally or remotely by entering the remote system name in the System Name field in the Database Definitions (ttaad4510m000) session. Then, use the Tables by Database (ttaad4111m000) session to assign tables to this table definition.

For example, assume that all tables are installed on the host1 remote system. This means that tabledef6.2 on the local system must contain the line: *:*:host1:N.

If all tables are on a remote system, you can set the BSE_REM variable on the local system. If there is no tabledef6.2 file on the local system, the bshell searches for this on the remote system, otherwise it reads the local tabledef6.2 file. The variable BSE_REM indicates the remote system:

BSE_REM=host1

User files To start an application, every user (logon) must have a user file. The bshell reads this user file to test whether the user is authorized to start the application. The Remote User Data (ttaad2501m000) session creates the $BSE/lib/user/r<user> file.

If all tables are installed on the remote system, the user files can be installed there, too, instead of on the local system. In that case you can set the BSE_REM system variable with the system name of the remote system, for example, BSE_REM=host1. The bshell looks first in the local $BSE/lib directory. If it cannot find the needed files there, it uses the BSE environment ($BSE/lib) on the remote system.

Remote databases


The remote system now reads the u user user file. To access tables on a remote system, you need to log on to the remote system. This is done using a remote logon user file named r user. You create this file with the Remote User Data (ttaad2501m000) session. Read session Help for information on how to create this file.

Variant I

Two variants of r user are possible. If the user’s logon is the same on the local and the remote system, variant I is sufficient. Define the remote system, the path on that system, and the password to log on to the remote system.

In variant I, the following information is needed:

Name of the remote host. BSE path on the remote host. Encrypted password on the remote host.

A user peter wants to work with iBaan ERP on his local workstation. The database tables he wants to use, however, are located on a remote system called host. To access the remote data, he needs a rpeter file in the $BSE/lib/user directory. If all tables are located on the remote system, he sets the following system variable:

BSE_REM=host1

This makes sure that everything is read from the remote BSE environment except the bin directory.

When using Variant I, user peter must have a logon entry on the remote system. The r user file must contain the name of the remote system, the path of the BSE on the remote system and the user’s encrypted password for the remote system.

Variant II

A second variant of r user allows you to log on to the remote host using another logon code. Indicate whether the UNIX and iBaan ERP permissions must be inherited from the other user. If so, the user u user file on the remote system must have the same UNIX logon as on the local system.

In variant II, the following information is needed:

Name of the remote host. BSE path on the remote host. Logon name on the remote host. Encrypted password on the remote host. SUID inherited logon.

EXAMPLE

Remote databases


The remote user file can contain more than one line. When using variant II, you can also specify a logon code to access the remote system. This can be a different logon code than “peter,” for example “john.” After that you enter the encrypted password for the remote logon (john). The remote system must still have a upeter user file. Variant II also allows you to take the UNIX and/or iBaan ERP authorizations defined for the john logon. To do so, specify Yes or No for the SUID and Inherit Logon fields. SUID switches the user ID from peter to john. Inherit Logon makes sure the iBaan ERP authorizations defined for john also apply to peter. To switch the user ID, the ipc_boot6.2 ($BSE/bin) file must have UNIX root permission and the s-bit must be set. From a security point of view this is not advisable. Here is an example of the two variants: Variant I: host1 /usr2/bse NZ+,AHtg&#K-kt"Q{$=Y3-"VLDN'CRtZ host2 /usr1/t/bse h8i0_-+8yujg@#c67h78i\{}907h67h5R

Variant II: host1 /usr2/bse john NZ+,AHtg&#K-kt"Q{$=Y3-"VLDN'CRtZ no yes host2 /usr1/t/bse h8i0_-+8yujg@#c67h78i\{}907h67h5R yes yes

Remote Whenever a local system connects to the remote system, ipc_boot6.2 is the first program to start. That process in turn starts fs6.2, which can read tabledef6.2 on the remote system. It finds an entry in tabledef6.2, showing the database type for a range of tables to be accessed. A database server is started, for example, ora7_srv6.2. The path for both fs6.2 and the database server is read from the $BSE/lib/ipc_info file.

Remote databases


Once on a remote system, you cannot call a third system. This means that tabledef6.2 must always have an entry on the tables.

Figure 6, Local and remote tables

Local and remote tables Tables are located on the local as well as on the remote host.

Another option is to distribute data storage over a local and a remote system. In that case both the local and the remote system must have the complete BSE environment installed.

The tabledef6.2 file now contains entries for local as well as remote system tables. This can also be defined in the Database Definitions (ttaad4510m000) and Tables by Database (ttaad4111m000) sessions.

Settings for remote menus/forms/objects Not only databases, but also forms, menus, objects and scripts can be distributed over one or more systems. The directories for the software components are defined in the Directories of Software Components (ttadv1115m000) session. This session fills the fd6.2.package_combination file. In this session you can specify whether the component is on the local or remote system. See also the session Help information.

11-1


General The currently used 8-bit wide character space is not large enough to fit most Asian character sets. Asian countries such as Japan, China, and Korea need at least 16 bits of character space to accommodate local characters. Therefore a 32-bit wide character space has been implemented in iBaan ERP Tools to support all possible character sets.

Be aware that a character is not necessarily the same as a byte and can take up more than one screen position. A character in the bshell occupies one or two screen positions at a size of 4 bytes.

Triton Super Set Triton Super Set (TSS) is a collection of character sets that can be used in iBaan ERP applications. TSS accommodates all multibyte character sets in a single package. TSS includes both ASCII character sets and multibyte character sets, such as Japanese, Chinese, Hebrew. To distinguish between, for example, Japanese and Chinese, TSS consists of planes, each of which holds a 64KB-size character set, or 256 pages of 256 characters.

This is shown in the following figure. Numbers are according to the hexadecimal system. For example, the value of 0x21 is 33 in the decimal notation.

Figure 7, iBaan ERP Super Set (TSS)

11 Multibyte management

Multibyte management


The characters 0x00 – 0x20 and 0x7F – 0x9F cannot be included in the sets, because these ranges contain control and escape codes. This leaves the following ranges:

0x212121 – 0x7EFFFF 0xA12121 – 0xFFFFFF

To distinguish TSS characters, the character contains the prefix 0x9B. Hence the complete TSS ranges are:

0x9B212121 – 0x9B7EFFFF 0x9BA12121 – 0x9BFFFFFF

Code Features (CF) and Line Drawing Characters (LDC) have been implemented in the code range of ISO-8859/1 as follows:

Line Drawing Characters | 0x80 – 0x8A Code Features | 0x8B – 0x9A TSS Lead byte | 0x9B Reserved | 0x9C – 0x9F

These code ranges do not conflict with the currently implemented EUC character sets, but they can cause problems when you import these codes. Also, these codes overlap with SHIFT-JIS trailing bytes, causing import conversion errors. Therefore the code ranges are translated into ASCII characters (0x00-0x7F) during the export phase and are converted back into the correct LDC and CF characters during the import phase.

Currently assigned planes are:

Character set Page Range from Range to Remarks KANJIEUC/SHIFTJIS 0x21 212121 217e7e JISX0208-1983 KANJIEUC/SHIFTJIS 0x23 2321a1 2321df JISX0201-1976 CCDC_HP15 0x24 24a121 24fe7e CCDC GB2312-80 0x25 25a1a1 25ffff GB2312-80 GB2312-80 0x26 26a120 26a17f Extended GB BIG5 0x27 27a140 27f9d5 CNS11643 0x28 28a1a1 28fefe CNS11643 Plane 1 CNS11643 0x29 29a121 29fe7e CNS11643 Plane 2



To use multibyte character sets

Installation Entering or displaying multibyte characters is subject to a series of conditions.

The window manager must support multibyte characters and must have been initialized in the proper native language. If necessary, change the LANG and LC_ALL shell variables before starting the window manager. This prevents the title bar of a window from displaying improper characters.

These settings are system-dependent.

If necessary, follow the procedure to add a character to TSS, as described in the iBaan ERP Super Set.

Enter the proper TSS locale in the Application Configuration (ttaad2100m000) session. The locale is defined in the Maintain Locale Data (%SEtttss0104m000) session and contains the definition of the character set.

To print multibyte characters To print multibyte characters, make sure the following conditions are met:

A device created in the Device Data (ttaad3500m000) session must be linked to a TSS locale that contains the definition of the character set in question. If the proper locale is not specified, the printer daemon cannot print the report.

The printer must be able to print the characters from the TSS locale. Check your printer manuals.

Utilities This section describes the available programs that belong to iBaan ERP Super Set. These programs are present in the $BSE/bin directory.

tsscomp6.2 NAME

tsscomp6.2

This program compiles and checks the tss6.2 TSS information file. This program is executed by the Convert TSS Data to Run Time (tttss0103m000) session.

SYNOPSIS

tsscomp6.2 [-svV] [-e error file] [-d debug level] [–i input file] [–o output file]



DESCRIPTION

tsscomp6.2 compiles the tss6.2 file, which contains the descriptions of all supported character sets into a fast-loading tss_c6.2 binary file. It also performs several checks on the entered data of the character sets.

The available options are:

-s Suppress output of errors. Check the exit value to determine if the program has been successful.

-e Write all warnings and errors to the file-error file.

-vV Prints version and porting information.

-d Used to provide some debugging information. This is a bit set.

-i Optional input file. Default $BSE/lib/tss6.2.

-o Optional output file. Default $BSE/lib/tss_c6.2.

Return values:

0 = success > 0 = failure

tsscvt6.2 NAME

tsscvt6.2

TSS conversion filter.

SYNOPSIS

tsscvt6.2 [-vV] [-dow] [-l locale]

DESCRIPTION

This program converts multibyte characters strings into TSS strings or vice versa. The input/output character set can be set using the –l option, but is read from the user file (locale resource) if not given.

Use the –o option to convert from TSS to the native character set.


-vV show version and porting information.

-d show some additional debug information.

-w Do not accept any conversion warnings, but exit(1) instead.



Return values:

0 = success > 0 = failure

tssinfo6.2 NAME

tssinfo6.2

This program offers information about the current settings such as your TSS locale, NLS locale, character set information, and so on.

SYNOPSIS

tssinfo6.2 [-vV] [-sf] [-l locale]

DESCRIPTION


-vV show version and porting information.

-s show character set definition of TSS locale.

-f show font assignments.

-l show information about the given locale. This is read from the user file if not given.

Command: tssinfo6.2 –sf User : bsp TSS locale : KANJIEUC_AIX32 TSS character set : KANJIEUC NLS locale : ja_JP Factor : 1

Multibyte strings: Database min. : 0x1 Database max. : 0x9b217e7e Forms min. : 0x20 Forms max. : 0x9b217e7e

Single byte strings: Database min. : 0x1 Database max. : 0x7f Forms min. : 0x20 Forms max. : 0x7a

EXAMPLE



Character set definition for KANJIEUC

NATIVE TSS From To from to 1 7f 1 7f 8ea1 8edf 9b2321a1 9b2321df a1a1 fefe 9b212121 9b217e7e

Font assignments

Font Display Size Font string 0 1 iso8859-1 1 2 jisx0208.1983-0 2 1 jisx0201.1976-0



Character set description The tss6.2 file in the $BSE/lib directory contains a description of the character set. Normally this file is filled using the TSS Character Sets (%SEtttss0101m000) session. This file describes all supported character sets with a special description language. The format is as follows:

Set(<number>, "Name", "Description") { ( range <number>-<number> in <expr> out <expr> store <number> bytes <number> setno <number> ) [more ranges...] } <number> can be hexadecimal: 0xnn, octal: 0nnn or decimal: nnn. <expr> can be: 1. simple type (fast) & value binary AND with value | value binary OR with value + value ADD value - value SUBTRACT value 2. complex type (slow) "expression". See the "expr" function.

Range Defines the input range (native data).

In/out Converts the character data for input (conversion to TSS) and output conversion to native character set).

Store Defines the place in the character set where the data is stored in TSS after the in conversion expression (add 0x9b000000 to see where it is stored, but not in the conversion entries).

Bytes Gives information about the number of bytes per native multibyte character.

setno Refers to the X-character set-number as defined in $BSE/lib/locale/LOCALE for display purposes. LOCALE is the current locale as defined in the user file.



A character set usually consists of several subsets, such as ASCII, KANJI-EUC, and KATAKANA in some Japanese environments.

Never change the character set data in an active environment. This can have catastrophic results, and the changed conversion tables can corrupt your data beyond repair.

KANJI-EUC

Set(3, "KANJIEUC", "Japanese EUC") { # ASCII ( range 0x1-0x7f store 0x0 bytes 1 setno 1 ) # KATAKANA (JISX0208) ( range 0x8ea1-0x8edf in &0x00ff out |0x8e00 store 0x232100 bytes 2 setno 3 ) # KANJI (JISX0201) ( range 0xa1a1-0xfefe in &0x7f7f out |0x8080 store 0x210000 bytes 2 setno 2 ) }

NOTE

EXAMPLE



Locale information The tss_locale6.2 file in the $BSE/lib directory contains all possible TSS locales that can be defined in the user file or specified with special commands, such as tsscvt6.2 –l locale. This file is filled by the Maintain Locale Data %SEtttss0104m000) session. The format is as follows:

Locale, Charset, NLS_locale, MBdbLow, MBdbHigh, MBFormLow, \ MBFormHigh, SBdbLow, SBdbHigh, SBFormLow, SBFormHigh

Locale As specified in the user file. Charset Any of the character sets defined in tss6.2. NLS_locale The NLS locale. Mainly used for character collation. May be NULL. MbdbLow The lowest possible multibyte character value for database storage. MBdbHigh The highest possible multibyte character value for database storage. MBFormLow The lowest possible multibyte character value for forms (see the expr function). MBFormHigh The highest possible multibyte character value for forms (see the expr function). SBdbLow The lowest possible single byte character value for database storage. SbdbHigh The highest possible single byte character value for database storage. SBFormLow The lowest possible single byte character value for forms (see the expr function). SBFormHigh The highest possible single byte character value for forms (see the expr function).

# Japanese – HPUX 9.0 KANJIEUC_HPUX: KANJIEUC, Japanese.euc, 1, 65278, 32, \ 65278, 1, 127, 32, 122

# \ is used here to indicate that the line following this character must actually be in the same line.

The $BSE/lib/locale directory contains files having names identical to the locale names, with character set information used to display the character set ranges. A set is chosen by the setno entry in the tss6.2 character set description file. These files are managed by the Fonts (tttss0106m000) session.

EXAMPLE



Taken from KANJIEUC_AIX

# character set display width iso8859-1 1 jisx0208.1983-0 2 jisx0201.1976-0 1

The sequence number of these character sets is the value that is used as setno entry in the tss6.2 file and in the TSS Character Sets (%SEtttss0101m000) session.

Storage of multibyte characters Normally the characters are stored as Native characters. However, you can also store the characters as TSS characters. To do that, the tss_mbstore6.2 file must be created in the $BSE/lib directory. That file contains the database fields, whose value or text must be stored as native instead of TSS characters.

native character : 8ea1 TSS character : 9b238ea1

The file is processed in the following order. The asterisk (*) refers to all tables.

* ppmmm### ppmmm###.field ppmmm###ccc ppmmm###ccc.field (p:package, m:module, #:table number, c:company number)

# entire table: ttaad320 # only field stat from ttaad320000 ttaad320000.stat

EXAMPLE

EXAMPLE

12-1


General This chapter introduces the audit management facility provided with iBaan ERP Tools from Version 6.0 onward. It describes the audit server, the audit management utility, and where audit-data is stored. It also describes the structure of the audit files and how to give users permissions to print, maintain, or clean audit-data.

Architecture The following diagram shows the audit selector and audit server in a process model.

1.1 audi t

se lec tor

1.2 audi t server

ac knowledge- ment

change to be audi ted

audi t tra il

transac tion no tifica tion

al l da tabase changes

audi t se lec tions

7

2

6

1

sequenc e id request

sequenc e id

1.3 sequenc e generato r

pr epare commit

3

4

5

commi t transac tion

8

database c lient layer (bshel l)

table converted to runtim e (file)

database t able(s)

ipc message

ipc message

ipc message

ipc message

ipc message

fi les

Process

Data

Legend :

12 Audit management

Audit management


Auditing Process The process can be described as follows.

The audit selector (database client layer of the bshell) checks whether each change on the source database meets the audit selections. If so, the audit selector sends a change to be audited (ipc message) to the audit server.

The audit server writes each change it receives to the audit trail (files). The audit server writes all changes for a transaction and then prepares the commit. The audit server requests a transaction ID from the sequence generator. Because the audit server requests a sequence ID, all audit servers must be running on the same application server.

After receiving the transaction ID, the audit server returns an acknowledgement to the audit selector, including the transaction ID and information on where the data is stored in the audit trail.

The audit selector waits until the audit server has logged all changes and acknowledged the prepare commit. Then the audit server creates a transaction

Audit management


notification (database insert). The user transaction and the transaction notification are committed within the same transaction scope.

A transaction notification consists of:

The transaction ID. User name. Session name. The commit time of the transaction. A list of tables updated by the transaction. For each table: an index to where the first log data of the first database action

on that table is stored.

Physically the transaction notifications are stored in a relational database table.

By default, Audit Notifications are stored in the Tools Company. If the transaction involved updates more that one table or company, the Audit Selector creates more than one transaction notification row.

Audit management


Below is a technical overview of the different components.

RDBMS

Audit server

DBdriver

tabledef

audit_set

audit_spec

Audit Trail

Sequencefiles

Sequencefiles

bshellAudit client

DBclient

Transactiondata

Transactionnotification

Auditdata

Auditdata

Rowdata

What to log

How tolog

Table infoaudit selections

Sequencegenerator

Sharedmemory

Transactionnotification Sequence

number

Transactioninformation

Trans action I D

auditdefWhere tolog

Semaphore

The DB-client part of the bshell reads the tabledef file with audit selections. The audit server reads the auditdef, audit_spec, and audit_set file.

The tabledef file specifies whether or not a table must be audited. The audit_spec file specifies how the audit trail is organized and handles permission issues. The audit_set file contains specifications about which columns to log.

The bshell sends the database actions or transaction data to the database driver. If a database action meets the audit selection criteria, it is also sent to the audit server. At commit time the audit server writes the audit-data to the audit trail and returns the transaction information and a transaction ID to the audit client. To create this transaction ID, the sequence generator creates a sequence number. Then the bshell writes a transaction notification within the user transaction scope.

Storage of audit-data For each table in each company number, the audit server uses a set of files to store audit-data. You can read audit files using the 4GL functions or the dictionary programs. This section describes the types of file that are used.

Audit management


Sequence files The audit-data is stored in a set of files called sequence files. There can be multiple sequence files per table per company number.

Apart from storing audit-data and transaction information, a sequence file also stores information about audited columns of the table, the audit-data dictionary.

The name of the sequence file is built using the table name and company number. The format of the sequence file name, where the prefix a indicates an audit file, just as t indicates a table itself, is as follows:

a<mmmnnn><company number>.<sequence file number> mmm represents the module code nnn represents the file number

For example, for table ttadv999 and company 000 the sequence files are:

aadv999000.000 aadv999000.001 aadv999000.002 aadv999000.003 ..........

For detailed information on the sequence file, refer to the section “Format of audit files.”

Information file There is one information file per table per company number, which:

Stores information about all sequence files used for this table/company number combination.

Contains controlling information used to create and maintain sequence files.

The name of the information file is based on the table name and the company number. The format of the information file name is as follows, where mmm represents the module code and nnn represents the file number:

a<mmmnnn><company number>.inf

For example, for table ttadv999 and company 0, the information file is aadv999000.inf.

There is one set of files per table name/company number combination. This means that any associated information, sequence file, or operation is identified by the table name/company number combination. For the sake of readability this document uses the word “table” to refer to a table name/company number combination.

NOTE

Audit management


Location of audit files The $BSE/lib/auditdef6. X file is used to specify the location of the sequence and information files for the tables. Under the directory specified in auditdef6.X, a subdirectory is created for each module. Audit files for all tables in this module, for all company numbers, are stored in this directory, unless a different directory is specified for different company numbers. The format of the directory name is:

a<Package Code><Module Code>

Here is an example of an entry in auditdef6.X:

ttadv:*:/usr/adv/AUDIT *:*:/usr1/AUDIT

In this example the audit files for all ttadv tables are stored in the /usr/adv/AUDIT/attadv directory. For all other tables, respective directories are created under /usr1/AUDIT. For example, atfacr is created for the Baan Finance (ACR) module, atiitm for the Baan Industry (ITM) module, and so on.

There can also be an entry such as:

ttadv:*:/usr/adv/AUDIT/#

In this case all ttadv tables are stored under specific respective company numbers. For example, for company number 000 the files are stored in the /usr/adv/AUDIT/000/attadv directory.

Other parameters of audit files The location of the audit files is controlled as explained in the section “Location of audit files.”

The user can control other parameters. These are defined in a file named $BSE/lib/audit_spec. For more information on this file, and specifications of parameters in it, refer to Format of Audit Files.

Information file The tables for which audit trail is enabled can contain sensitive data such as company financial information. This means that the audit files also contain sensitive data. Audit management contains a security mechanism by which access to the audit-data can be controlled according to user requirement.

A security level is defined per table/company number combination. Depending on the security level, users can or cannot access or modify the audit-data. The audit server reads the security level from the audit_spec file and stores it in the information file of the table.

Audit management


The central audit management utility (see the Audit Management business object), uses this security level to control audit-data access and modification.

Sequence File The start and end sequence numbers for a table are specified in the audit_spec file. For example, if the start sequence for the ppbdb000 table in company 000 is 0 and the end sequence is 999, the table has the following sequence files:

abdb000000.000 abdb000000.001 .... abdb000000.998 abdb000000.999

For the same table, if the start sequence for company 100 is 1, and the end sequence is 50, the files are:

abdb000100.001 abdb000100.002 .... abdb000100.049 abdb000100.050

In principle, all audit-data for a table/company number combination can be written to a single sequence file. But because this file becomes too big to manage properly, the audit-data is split across multiple sequence files.

The maximum size of a sequence file for a table is defined in the audit_spec file. If the limit is exceeded, the audit server tries to use the next sequence file.

Audit management The audit management version 6.2 incorporates the following features in iBaan ERP audit management utility:

Audit-data is stored in a set of files, instead of in a single file. Multiple files allow for better management than a single large file.

Each transaction is identified by a transaction header, which logs useful information about the transaction, such as the corresponding user and time. Also, the data is organized per transaction. Each transaction has a header followed by all audit-data, which enables easy tracking of the changes that users have made.

When the audit-data is being written, information of audited columns in tables is also stored in audit files. If the table data dictionary is later changed, you can still interpret old audit-data by using the stored column information.

Audit management


Table level commands affecting table data such as create table, clear table, and drop table, are also logged by the audit server.

Audit management such as printing audit files and display audit sequences is done by using the sessions belonging to the Audit Management business object.

The transaction notification server sends a message to the audit file indicating when a transaction has successfully been completed.

Table data dictionary as seen by audit server When a table data dictionary is created in a iBaan ERP environment, the audit trail can be enabled for each column. This allows a user to audit a single column or all the columns on the table.

The audit server is concerned only with audited columns of a table. It logs the information only for the audited columns. If a column is not audited, no information is logged for it. If the table has no audited columns, no information is logged for the table. The tabledef6.2 file specifies the tables for which audit is enabled. See also the section “To access tables” in the chapter on database management.

For the rest of this chapter, it is assumed that all columns are to be audited unless stated otherwise.

The audit-data dictionary (the information of audited columns) is stored in the sequence header. This information is stored in a particular order of table columns. First, information for all audited primary key columns is stored in the order in which they form the primary key. Next, information of remaining audited columns is stored in the order in which they occur in the table.

For example, suppose a table has columns c1, c2, c3, c4, c5, c6 with primary key (c4, c2) and all columns except c5 are audited. The audit-data dictionary contains information for the columns in this order: c4, c2, c1, c3, c6. For each column, the audit-data dictionary stores the column name without the table name prefix, field type, size, and depth. The format of a column entry in the audit-data dictionary is as follows:

Name Type Depth Size Name Stores column name without table name prefix.

Audit management


Type Single byte indicating field type. The defines in BDB layer for field type are used, because 4GL also uses the same values. For example, for the CHAR field, the BDB type is BDB_CHAR, and the 4GL counterpart DB.CHAR has the same define as BDB_CHAR.

Depth Single byte, indicating depth of the field.

Size 2 bytes, indicating field size. For array fields this is the total size of all fields in array.

Commands logged by audit server The audit server tracks all commands that affect the table data, that is, Insert, Update, and Delete commands. It also tracks certain table level commands such as Create Table, Drop Table, and Clear Table, which affect all rows in a table.

For each of these commands, the audit server puts certain information in the audit files. This information can be considered as Audit Row in the audit file.

The audit server does not track select commands (with or without lock), or other table-level commands such as Change Order, Count Rows, Create Index or Drop Index, because they do not change the table data in any way.

Data stored by audit server

Application data

In accordance with the application user requirement, the audit server reserves an extra four bytes in each audit row, which application programs can use. This 4-byte space is called application data. The audit server does not interpret the application data in any way.

Table operations

For table operations such as create table, drop table, and clear table, the audit server stores only a one-byte indicator. If a non-empty table is dropped or cleared, a delete row operation is created for all rows in the table!

Row operations

For row operations, the audit server keeps the values of audited fields. In addition to field values, the audit server also stores a one-character code indicating the type of row operation.

Audit management


Insert actions The new values of all audited fields to be inserted are stored in the audit file.

Delete actions The field values of the record to be deleted are stored in the audit file.

Update actions You can set up a configuration to store only the primary key columns and those values that have been changed, or include columns of a record that have not been changed. You use the file audit_set to specify the tables that have additional columns logged.

The following table shows the levels of detail you can specify:

Level Description Example

1 Table name with company and column tccom110:812:colm 2 Table name for all companies and column tccom110:*:colm 3 Table name with company tccom110:812 4 Table name for all companies tccom110:* 5 Module name with company tccom:812 6 Module name for all companies tccom:* 7 Package name with company tc:812 8 Package name for all companies tc:* 9 All-package with company *:812 10 All-package for all companies *:*

Format of audit row The format of the audit row in the sequence file is as follows:

Length Appl Data Action Data... Length A two-byte field that indicates the length of this audit row (excluding this field itself).

Appl Data A four-byte field reserved for application program usage. The audit server, when writing a row, initializes this to nulls.

Audit management


Action A one-byte character code indicating the action done on the table. The following codes are available:

-C create table -R drop table -L clear table -I insert row -D delete row -U update row

Data The previous fields fulfill the audit requirement for table-level actions. No Data field is included for table-level actions.

For row level actions, the important values of audited fields are stored as data, as explained in the following sections.

Insert/Delete actions Values of all audited fields are stored for insert and delete actions. They are stored in the same field order as that of the audit-data dictionary of a sequence header. If the audit-data dictionary of a table has columns in the order c4, c2, c1, c3, c6, the values are stored in the same order.

Update actions For update actions, the field number precedes the field values in the audit row. Field numbers used here are related to the sequence of fields in the audit-data dictionary and not to the original table data dictionary. Suppose a table has columns c1, c2, c3, c4, c5, c6, with primary key (c4, c2), and all except c5 are audited. The audit-data dictionary contains information for these columns in order c4, c2, c1, c3, c6. Thus the field number 0 refers to field c4 and not to field c1. Similarly, field 3 refers to c1 and not to c3. For update actions, an audit row looks as follows:

Length Appl Data U Multiple Field Entries A single field entry is as follows:

Field Number Changed? Old Value New Value Field Number A two-byte entry that indicates the field in the audit-data dictionary.

Audit management


Changed A single-byte flag, used to indicate whether the field is updated or not. The field value for primary key fields must be stored, whether they are changed or not. When the field value is changed, the corresponding flag is set to Y, otherwise it is set to N. The values for all other audited fields are stored in the audit row only if they are changed, so for these fields, the flag is always set to Y.

Old Value The old value of the field that is being updated. For a primary key column that is not changed, this is the only value stored.

New Value If an audited field value is changed, this represents the new value. For primary key audited fields that are not changed, this field is not present in the audit row.

Using this logic, the following is possible:

The primary key field (audited) is not changed. In this case the field entry is:

Field number N Old Value The primary key field or any other audited fields are changed. In this case the field entry is as follows:

Field number Y Old Value New Value Here the new value follows the old value.

Examples of the audit row for various operations Suppose you have a table with the columns c1, c2, c3, c4, c5, c6 with primary key (c4, c2). If all columns except c5 are audited, the audit-data dictionary contains information for these columns in order c4, c2, c1, c3, c6. The field number 0 then refers to field c4, field number 1 is c2, and so on.

Create Table Length Appl Data 'C'

Here the length is the same for all tables, 5.

Drop Table Length Appl Data 'R'


Audit management


Clear Table Length Appl Data 'L'


Insert Row Length Appl Data ‘I’ c4 c2 c1 c3 c6

Here c4, c2, and so on, indicate the values of the corresponding fields. Each field entry size is the size of the field itself.

Delete Row Length Appl Data ‘D’ c4 c2 c1 c3 c6

Update Row Assume that c2 (primary key column) and c6 are changed.

Length Appl 'U' 0 N c4.o 1 Y c2.o c2.n 4 Y c6.o c6.n Here, the entry for field 0 (c4) is present, although it is not changed, because the field is a primary key field. Its only value stored is c4.o, the old value. Because c2 (field 1) and c6 (field 4) are changed, their old and new values are stored as .o and .n respectively.

Limit on the size of audit-data All audit-data generated in a transaction for a table is always put in a single sequence file. The transaction data is never split up across sequence files. If the current sequence does not have enough space to write the transaction data (that is, if its size exceeds the maximum sequence size), the audit server tries to write the transaction data in the next sequence file. If the transaction data cannot be accommodated in the entire sequence file, the audit server cancels the transaction. If this happens, the application programmer must either reduce the scope of the transaction or increase the maximum file size for the sequence file.

Audit server

Long transactions and overflow file The audit server buffers audit-data in its memory buffers until the end of the transaction. For example, if during a transaction, 100 rows are inserted in a table and then a commit is done, all the audit rows for the insert are buffered by the audit server. This data is written to the audit files only at the time of commit.

Audit management


The audit server uses individual memory buffers for each table. The size of the buffers is set to enable them to hold large amounts of data. However, the memory buffers might not be able to contain the results of a very large transaction. In this case, the audit server uses an overflow file to buffer the remaining data.

The overflow file is created in $BSE/tmp. There is one overflow file per session per server. Its name is made using the session ID and process ID (pid) of the audit server, as follows:

ao.{Session Id>.<Process Id of the Audit Server>

A single overflow file is used to buffer data for all the tables in the session for which the memory buffers were insufficient. At the end of the transaction, if any table has data in the overflow file. The overflow file is read and put in the corresponding sequence file. After all data has been read and copied from the overflow file, the overflow file is deleted.

If a transaction is canceled, the overflow file is deleted.

The memory buffers of the audit server can hold a large amount of data. If the audit server still has to use the overflow file, the transaction is too big. This can be a flaw in application design or coding. If possible, such transactions must be avoided.

Sequence termination The audit server uses a set of sequence files to store audit-data for a table. The audit server switches from one sequence file to the next under the following circumstances.

Sequence file maximum size reached Audit-data generated in a transaction for a table is written to a single sequence file. If the size of the transaction data exceeds the maximum sequence-file size limit for the current sequence, the audit server marks the current sequence file as terminated, and writes the transaction data to the next sequence file.

Before the audit server switches to the next sequence, it ensures that the maximum possible space is available. If the transaction data for the table still cannot be accommodated, then it cannot be put in any sequence file. This is an error condition and the audit server cancels the transaction. Note that in this case the current sequence is not terminated. When this error occurs, you can either increase the maximum size of the sequence file or reduce the scope of the transaction.

NOTE

Audit management


Table audit-data dictionary changed When the audit server starts using a sequence, it writes the audit-data dictionary to the sequence headers of the sequence file and the information file. Audit-data in the sequence file depends on the audit-data dictionary of that sequence. For example, for an insert/delete action, all audited field values are put in the sequence in which they occur in the audit-data dictionary. For updates, the field values are preceded by field numbers, which are offsets in the audit-data dictionary. The reading of audit-data by the 4GL interface also depends on the audit-data dictionary of the sequence.

If the audit-data dictionary changes after the system writes some audit-data to a sequence file, you cannot continue using the same sequence. In this case, the audit server stops using the current sequence and marks it closed while the audit-data dictionary has been changed. It starts using the next sequence.

Note that here the switch is made only if the audit-data dictionary changes. This is different from changing the table data dictionary. Changing the table-data dictionary does not mean that the audit-data dictionary is also changed.

Events that lead to changes in the audit-data dictionary are in the following example.

Suppose you have a table with columns c1, c2, c3, c4, c5, c6 with primary key (c4, c2) in which all except c5 are audited. The audit-data dictionary contains information for these columns in order c4, c2, c1, c3, c6.

Consider the following changes:

Number of audited columns changed If the audit trail status for any field is changed, the audit-data dictionary changes. For example, if audit trail is enabled for c5, the audit-data dictionary must have column information in the order c4, c2, c1, c3, c5, c6. This is different from the audit-data dictionary of the current sequence, so a sequence change occurs. Similarly, if auditing is disabled for c1, the new audit-data dictionary is c4, c2, c3 and c6, which is different from the current audit-data dictionary. As a result, a sequence change occurs.

Order of audited primary key columns changed Initially the primary key was (c4, c2). If its definition is changed to (c2, c4), the new audit-data dictionary is c2, c4, c1, c3, c6. Because this is different from the audit-data dictionary of the current sequence, the audit server closes the current sequence and uses the next sequence.

Audit management


Order of other audited columns changed The audit-data dictionary changes if the order changes in which the columns (other than the primary key columns) occur in the table definition. For example, if the table is now defined as c1, c2, c4, c5, c6, c3, the new audit-data dictionary is c4, c2, c1, c6, c3. In this case the sequence order is changed.

Number of audited primary key columns changed You can change the number of audited primary key columns without affecting any of these conditions. For example, if the primary key definition is changed to (c4, c2, c1), the new audit-data dictionary is the same as the current audit-data dictionary. But because c1 is now a primary key field, its value must be stored in an update action even if it is not changed. In earlier updates in the current sequence, this would not have been done. To make the sequence file consistent, the audit server switches to the next sequence.

Sequence terminated by user If current security allows them to, application users can terminate the current sequence by using the central audit management utility (see the Audit Management business object). Application programs can also terminate the sequence. In this case the terminating program sets the sequence end date and time and the sequence status.

Reusing sequence files Suppose you have a table with start sequence 0 and end sequence 49 for a total of 50 audit files. In the first run, each sequence file is created. After all 50 sequences are created and used, the audit server normally uses sequence 0 again, overwriting the existing file.

If you do not want this to happen, you can disable the reuse feature. Instead of overwriting the file, the audit server then sends an error message saying that the file must be deleted before the server can reuse the files. Thus when the reuse feature is disabled, an existing sequence file is not overwritten. You have to delete the file by using the Purge Audit Files (ttaad4161m000) session before the audit server can continue. If the reuse feature is enabled, the audit server overwrites any existing sequence file.

If you want to receive a message before the data in audit files is destroyed, you must disable the reuse feature. This can be done by not specifying a SEQREUSE keyword in the audit_spec file. If you want to use the reuse feature, include the keyword SEQREUSE in the audit_spec file.

NOTE

Audit management


Always delete the sequence files using the Purge Audit Files (ttaad4261m000) session rather than by using commands such as rm or del. This is because the status of the sequence file is maintained in the sequence header in the information file. When this session deletes the sequence file, it also sets the status of this sequence in the information file as deleted. If the file is removed by any other means, the status is not set and this results in inconsistency.

To lock a file When writing the data for a transaction, the audit server can close the current sequence and start using the next sequence. Thus it can change the current sequence field in the information file header. It also changes the sequence status and sequence end time for the current sequence, and changes the status and start date/time of the next sequence.

Even if the audit server does not switch sequences, it needs to change the current offset in the information header and the number of transactions in the sequence header. This means that it always changes the information header and the sequence header. Moreover, because the sequence header is maintained in the sequence file and information file, both of these must be changed.

At the start of a transaction termination command for each table and before writing buffered data to the audit file, the audit server locks the information file header and sequence header in the information file and in the sequence file. The audit server puts write locks on, so that no other read or write lock can succeed. After the data for all tables is written, the locks on all tables are released. If there is an error on any table, the status of transactions for tables already written is changed to abort and the locks on all tables are released.

Limit on open files When writing audit-data for a table, the audit server has to open the information file and one sequence file for that table. Once these are opened, they are kept open for subsequent use even after the end of a transaction. These open files can be used in all subsequent transactions involving this table.

Having so many files open, however, means that the server can reach the operating systems limit of maximum open files per process. For example, if a transaction involves 15 tables, 30 files are opened at the end of that transaction. If the next transaction has 10 different tables, 20 more files are opened. At the end of the second transaction 50 files are open, which is over the maximum limit.

Audit management


When this limit is reached, the server closes two open files: the information file and the sequence file for a table. The server uses the least recently used (LRU) criteria to choose the table for which the files are closed, as explained in the following paragraph.

The audit server uses a data structure, called a handler, to keep track of the file descriptors for the information and sequence files on each table. When these files are opened, the file descriptors are stored in the handler. The handlers of all tables are kept in a linked list in an LRU manner. For example, when files are first opened, the handler is allocated and is put in most recently used (MRU) position. As other tables are opened, this handler moves toward the LRU position. Later on, if this table is involved in another transaction, the same handler is reused and is again moved to the MRU position. Also, when a file is open, all data is written to the file before the data goes to the next table. Thus, until all data is written for a table in the current transaction, the handler for that table is guaranteed to stay in the MRU position and in no way can it reach the LRU position.

If the audit server reaches the open file limit when opening a new information file, sequence file, or overflow file, it picks up the LRU handler in the handler list and closes its information file and sequence file. The assumption is that because the table has not recently been used, it is the best choice as a victim for closing files.

To open large number of tables in a single session A session can update a large number of tables. On systems that have a small maximum number of open files, this can create a problem. Suppose a session with a limit of 30 open files starts to update 50 tables. After opening the information and sequence files for the first 30 tables, the system reaches the maximum limit of open files. When files for table31 are opened, the LRU logic is activated and files for table1 are closed. But table1 is itself in transaction and its files are locked. When the audit server closes the files, the locks are released and other processes can alter the files. Now the same audit server may again need to operate on the audit files of table1.

This means that the audit files for table1 need to be opened again. But if the files were changed in the meantime, the status is changed to ABORT_DONE. In this case, the audit server gives an error and cancels the transaction.

Audit management


Multisession support The audit server supports multiple sessions, which means that the same audit server is used for multiple sessions within the client.

The audit-data dictionary of a table is kept globally. The same table/company number in multiple sessions shares a single audit-data dictionary.

The handlers (one used per table/company number combination) are kept in global lists. If multiple sessions operate on the same table/company number combination, they share a single handler.

File security for various audit management files It is important that the audit_spec file has read permission for all users, and that write permission is granted only to the administrator user. Otherwise users other than the administrator can change the security parameter in the file, which would allow them illegal access.

Audit server debugging options For debugging purposes, a code is put in the audit server at appropriate stages to print useful information. In normal usage, this printing is not enabled. You can enable it by setting an AUDITLOG environment variable. You can print various types of information by setting this variable to different values. The values must be set as octals.

0001 General information. 0002 Print audit rows generated. 0004 Print audit-data dictionary for table. 0010 Print data structures such as information header, sequence header, and

transaction header.

The information is put in a log file. The name of the file is audit.log.pid of the server. This file is created in the current directory of the audit server.

To access transaction data Previous versions of the audit trail files required that transaction data be accessed in sequence. This is very time consuming if the last transaction must be retrieved from a sequence file.

To speed things up, the audit server now saves the audit file offset internally. The audit server combines the offsets per audit file, the table name, and the company number, and sends them in a message back to the bshell at the moment of the commit.

Audit management


The information sent by the audit server to the bshell contains the following data:

Tablename T1 Company number C1 Sequence number of audit file S1 Offset of transaction X1 in sequence file Tablename T2 Company number C2 Sequence number of audit file S2 Offset of transaction X2 in sequence file

The following table shows an example:

Tablename Company number

Audit file sequence number

Offset in audit file

ttadv100 000 001 2353 tccom010 812 065 1406 tfgld045 812 123 56028

After the application has finished updating the database, the data is committed. The bshell requests a transaction ID from the audit server. The audit server generates a sequence number and sends it back to the bshell together with the transaction information message. The bshell uses this information to create a transaction notification, and sends a commit to the database.

To create a transaction notification The two-phase commit protocol used in previous versions has been replaced by the transaction notification. This eliminates the in-doubt transactions that can occur if the transaction is prepared but the data is not yet committed or aborted.

The bshell writes this transaction notification into a notification table in the database, within the user transaction. If the transaction commits, the bshell writes the transaction notification, and if the transaction aborts the bshell does not write the notification. The bshell creates a transaction notification for each transaction that is logged in the audit trail.

The transaction notification contains the transaction ID and information on where to find the transaction information in the audit sequence file. These transaction notifications can be used as a trigger for any process that needs to react to database changes such as a replication process, and enables fast access to the audit trail data.

Audit management


Audit errors The audit server uses the following error messages. If you receive one of these error messages, refer to $BSE/log/log.audit for more information regarding the cause of the error.

E_AUD_SETUP 251 The audit setup is not correct. This can occur if the specification in the $BSE/lib/audit_spec file is not in proper format.

TOSEQ 6 SECURITY 28 MAXSEQSIZE 25K or No table/company number combination.

aa:00a:TOSEQ 6 SECURITY 28 MAXSEQSIZE 25K Incorrect company number.

*:*:TOSEQ 6 SECURITY 28 MAXSEQSIZE 5K The maximum sequence size limit is less than the specified limits. Refer to the section “Format of audit files” for details about the format of this file. It can also mean that the current sequence file was illegally removed or that the sequence files were removed without using the 4GL interface. Audit files used during the first run can also cause this error.

E_AUD_CORRUPT 252 An audit file is corrupt. Some corruption of the information file has occurred. There is a mismatch of sequence headers in the information file and the sequence file.

E_AUD_LOCKED 253 Another user has locked the audit file. Multiple users are trying to use the same audit file at the same time. The audit file is locked before it can be modified, and the next user receives an error message.

E_AUD_ABORT 254 Commit transaction has failed in audit server. The audit file is changed when the audit-data is written to the audit file. When too many files are opened and the maximum limit is reached, the LRU file is closed. This error can refer to the file used in the transaction. When the file is reopened, the starting date time of the sequence header is checked with memory data structure. If they are not the same, the E_AUD_ABORT error is returned.

Authorizations The Administrator user grants audit security permissions to users using the Audit Authorizations (ttaad4562m000) session. These permissions determine whether the user can use the sessions in the Audit Management business object.

Security permissions assigned to users are checked against previously existing records to see if they conflict.

Audit management


You can assign security permissions for all packages, modules, table numbers, and companies. You can give some permissions for all packages, and disable these permissions by giving no permissions to a range of packages.

You can use the Specified command to give particular permissions to a specified package. By using Specified, the highest priority is given to the security permissions assigned for that particular package, module, table and company.

You cannot assign security permissions for a range within a range. Suppose you assign some permissions using the All command, then disable permissions for a range between tt—vv. You cannot then enable permissions within this range or an overlapping range. However, you can use the Specified command to enable the permissions for a specific package.

The conflicting records are not stored in the table.

The security permissions for users are stored in a table ttaad462, which you can access accessed using the sessions within the Audit Management business object.

The security checking is done at two layers, one at the user level and another for reading audit information. The user can have permissions at the user level but not for reading the audit information. At audit level, the security permissions are stored in the audit information header of the audit information file.

User level permissions Audit level permissions None Print All Clean Print Maintain Clean Application-defined Maintain

At user level, the Administrator user can grant permissions in different combinations. The Administrator user assigns its own permissions to print and clean audit information through the Audit Authorizations (ttaad4562m000) session, on the menu iBaan ERP Tools, Audit Management. The only session the Administrator user is allowed to execute without being assigned any security permissions, is the maintain session.

Audit management


For example:

None No permissions All Print, clean, and maintain permissions Print Only print permissions Print/Clean Print and clean permissions Print/Clean/Maintain Same as All

None and All are mutually exclusive.

At audit level the permissions can be granted in combinations except application-defined. Only maintain can be combined with application-defined.

Print Only print permissions Print/Clean Print and clean permissions Print/Clean/Maintain Same as all permissions Application defined Access to some sessions restricted Maintain/Application Only maintain permission, no print

and clean-defined permissions The user cannot print or clean up any audit information. To print, clean, or maintain the audit information from the audit files, the permissions must exist at both levels.

Permission at user level Print or print/clean Permission at audit level Application-defined

The user cannot print or clean up any audit information in the audit files using the sessions in the Audit Management business object. It is possible, however, to run the Audit Information File (ttaad4160s000) session, because the user has maintain permission only at audit file level.

Permission at user level Maintain or print/maintain or clean/maintain Permission at audit level Maintain/application-defined

If the user is not the Administrator and only application-defined exists at the audit file level, no session of the Audit Management business object can be executed. The administrator user can use the maintain session even if no permissions are assigned to the administrator user. However, the administrator user cannot use print and clean sessions unless security permissions are assigned to the administrator.

NOTE

Audit management


If user bsp has print permission at user level, a further check is made to see the security permissions at audit level. User bsp is only allowed to continue if print permission is available at the audit level. Otherwise the session is canceled and an appropriate message is displayed.

Format of audit files tabledef6.2 The tabledef file specifies which table is stored in which database and on which host. Each table includes a unique database and host where tabledef can be found. Tabledef also contains audit selections to indicate whether or not a table must be audited. For more information about tabledef, refer to the chapter on Database Management.

auditdef6.2 This file is used to specify the directories in which audit files are created. There is one such file for each BSE environment, and it is located in $BSE/lib.

This file has the following structure:

<Table Name>:<Company Number>:<Directory Name>

The following section lists the meaning of each field.

Table Name This indicates the table and can be in the following formats:

"*" – means all tables in all packages.

Package – means all tables in this package. For example, tf, td, and so on.

Package and module code – all tables in the module. For example, tccom, ttadv.

Package, module, and table number – for example, ttadv999, tccom010.

Company Number Tables can be chosen based on company number. For example:

* – all companies. 100 – company 100 only. 100,000 – company 100 and 000.

Audit management


Directory Directory in which the audit files are stored. Under this directory, another directory is created, called:

aPackage + Module Code

audit_spec file The audit_spec file is used to specify audit file parameters. There is one such file for each BSE environment, and it is located in the $BSE/lib directory.

The format of the file is Table Name:Company Number:Audit Specifications

Following is the meaning of each field.

Table Name Indicates the table. The table name can have the following formats:

* All tables in all packages.

Package All tables in this package, for example tf, td, and so on.

Package and module code All tables in the module, for example, tccom, ttadv.

Package, module and table number For example ttadv999, tccom010.

Company This can be in one of following formats.

* All companies.

100 Single company, for example, company 100 only.

100,000 Comma-separated list of companies, for example, company 100 and 000.

Specifications The following specifications can be put in the file.

Start sequence This is specified by the keyword FROMSEQ or fromseq. The start sequence is always 000. The user cannot change this.

Audit management


To sequence This is specified by the keyword TOSEQ or toseq followed by a sequence number. Note that there must be a space between the keyword and the sequence number. For example:

TOSEQ 999 or toseq 999

If the end sequence is not specified for a table/company combination, the default is 999.

Maximum sequence file size This is specified by the keyword MAXSEQSIZE or MAXSEQSIZE followed by a size specification. Note that there must be a space between the keyword and the size specification. The size can be specified in:

− Bytes for example, MAXSEQSIZE 10000 (10000 bytes). − Kilobytes for example, MAXSEQSIZE 10K (10KB or 10*1024 bytes). − Megabytes, for example, MAXSEQSIZE 2M (2MB or 2*1024*1024

bytes).

Note that for kilobyte and megabyte specifications, the characters K and M must be uppercase only and there cannot be a space between the number and the specification character.

If the maximum sequence size is not specified for a table/company combination, the default is 512K.

Whether sequences can be reused or not. If existing sequences can be reused without deleting them first, the keyword SEQREUSE or seqreuse must be put in the specifications. If you do not want this, do not put the keyword in the specifications. If this is not specified for a table, the sequence reused is not allowed.

Security assigned to current table/company number audit files. This is specified as keyword SECURITY or security followed by a security number. Note that there must be a space between the keyword and the security specifications. For example:

SECURITY 4 or security 4

Audit management


The different security levels and their codes are as follows:

Security Value Print 4 Clean 8 Maintain 16 Application defined 32

The combination of these is explained in the section"Authorizations''.

To specify clean and maintain, security is specified as security 24 (the sum of 8 + 16).

Application-defined cannot be combined with print and clean. It can be combined with maintain permissions only. Note that these specifications can be put in any order.

The audit_spec file must have a default entry covering all tables/company numbers. This can be done with an asterisk (*) for table and company number fields. This must be the last line of the file.

A sample audit_spec file can look as follows:

ttadv999:000:TOSEQ 99 FROMSEQ 000 MAXSEQSIZE 2M tt:000:seqreuse toseq 49 maxseqsize 1M tf:000:toseq 49 seqreuse maxseqsize 20K *:*:FROMSEQ 000 TOSEQ 499 MAXSEQSIZE 100K

The audit_spec file must have read permission for all users and write permission for the administrator user only. Otherwise users other than the administrator can change the security parameter in the file, which would allow them illegal access.

audit_set When the audit server starts, it reads the audit_set file and stores it in a fast-access structure like a hash list.

Then at run time, when the audit server writes an updated record to the audit trail, the audit server searches the fast-access structure for an entry that matches the table on which the update was done. The audit server searches first the table level, then the module level, then the package level, and finally the all-package level until it finds a matching entry.

The audit_set file is used to specify columns of tables which always will be logged with every update row.

CAUTION

NOTE

Audit management


Several levels of detail can be given: specifications for all packages, all modules in a package, all tables in a module. Specifications can be made for one company or all companies. Also column names of a table can be specified, in this case not all but only those columns specified will be logged in addition with the changed columns. Each entry must specify Y for extra columns being logged or N for no extra columns.

This results in the following levels of detail:

Level Description Example 1 Table name with company and column tccom110:812:Y:colm 2 Table name for all companies and column tccom110:*:Y:colm 3 Table name with company tccom110:812:Y 4 Table name for all companies tccom110:*:Y 5 Module name with company tccom:812:Y 6 Module name for all companies tccom:*:Y 7 Package name with company tc:812:Y 8 Package name for all companies tc:*:Y 9 All-package with company *:812:Y 10 All-package for all companies *:*:Y

Level 1 and 2 are column levels. The levels 3 through 10 are table levels.

Information file There is one information file per table per company number. You can read the information file by using the 4GL functions or the dictionary programs.

The information file contains the controlling information for the sequence files, called the information header, followed by the sequence headers of all the sequence files created.

The format of the information file name, where mmm means module code and nnn means table number, is as follows:

a mmmnnn company number.inf

For example, the name for table ttadv999, company 0, is aadv999000.inf.

The structure of the information file is a header called information header, followed by multiple sequence headers, one for each sequence created.

Audit management


Information header

Field Length (bytes)

Description

Version Information 4 Str This is used by the audit server to store the version information. This must never be modified by any application by any means.

Table Name 8 Str Table for which audit information is stored. Company Number 2 Int Company number of the table. Status 1 Int The status specifies whether sequence

reuse is allowed or not. From Sequence Number

2 Int Audit-data will be stored in sequence files specified from this value.

To Sequence Number

2 Int This is the last sequence file after which sequence reuse will be started or the user will have to take appropriate action like deleting the existing file before reusing it.

End Sequence Number

2 Int This specifies the last sequence written in the info file. This field is for internal use by the audit server only. The user must never change this by any means otherwise the audit server will not work correctly.

Max. Size of 1 Audit File in Bytes

4 Int This specifies the maximum file size of a sequence file.

Security Level 2 Int This determines the users who have access to the information in the audit files. The security permissions regarding access to audit information are stored here.

Current Sequence Number

2 Int This determines the current sequence number that will be used to write the audit-data in the sequence file.

Offset in Current Sequence File.

4 Int This specifies the offset in the current sequence file where the audit-data will be written.

Reserved Space 8 This space is not used at present and is reserved for future use. Application programs must never use this space as this space may be used by a future release of audit server.

Length of Fllowing Sequence Header

2 Int The length of the first sequence header in the info file.

Audit management


Sequence header

Each sequence file begins with a sequence header. The information file contains copies of sequence headers for all sequences created.


Description

Sequence Number 2 Int This specifies the sequence number of the sequence file.

Creation Date 8 Str This specifies the creation date, in UTC, of the sequence file. Format: YYYYMMDD.

Creation Time 6 Str This specifies the creation time, in UTC, of the sequence file. Format: HHMMSS.

Termination Date 8 Str This specifies the termination date, in UTC, of the sequence file. Format: YYYYMMDD.

Termination Time 6 Str This specifies the termination time, in UTC, of the sequence file. Format: HHMMSS.

Status 2 Int The status gives information to the user whether the sequence file was user-terminated or was closed because of DD change or because a transaction data was not possible to accommodate in the sequence file. Possible values are: 0001 : Terminated because of size. 0002 : Table DD changed. 0004 : User forced. 0010 : Sequence and info header mismatch. 0020 : To be set only in info header. Set when the sequence is removed. 0040 : Change in sequence file version. 0100 : Version number present in sequence.

Number of Transaction in the Sequence

2 Int This specifies the data of the number of transactions present in the sequence file.

Application Info – 1 4 These bytes are reserved for storing data specific to the application. If the application needs to store any information in the audit files, these fields must be used to store that information.

Audit management


Application Info – 2 4 Application Info – 3 4 Application Info – 4 4 Number of Fields Being Audited

2 Int Total number of fields being audited.

Number of Fields in Primary Index

1 Int Field information for all fields being audited is written below. First, the fields that are part of the primary index are written, in the same sequence as they are in the primary index. Next, all remaining fields are written in the order in which they occure in table DD. For example, if fields f1, f2, f3, f4 are being audited and the primary index is on f4, f2, then field information will be written first for f4, next for f2. Then it will be written for all remaining fields. Number of Fields in Primary Index will indicate how many fields are in primary key. For example, for the above example, the following field value should be 2 and the field layout will be f4, f2, f1, f3.

<Field Data 1> … <Field Data n> n = number of fields being audited Sequence Version 4 Str Change note: In BAAN IVc and earlier

releases the sequence version is not available. In that case these four bytes are reserved space.

Reserved Space 4 This is reserved space. Applications should not use this space and this may be used by future releases of audit servers.

Length of Following Sequence Header

2 Int The length of the next sequence header in the info file.

Field data


Description

Field Name 8 Str Name of the audited field Field Type 1 Int Type of the field Field Depth 1 Int Array depth of field Field Length 2 Int Length of the field

Audit management


Sequence file Multiple sequence files are used to store audit-data for each table/company number combination. You can read the sequence files by using the 4GL functions or the dictionary programs. The format of the sequence file name, where mmm refers to the module code and nnn means table number, is as follows:

a mmmnnn company number.sequence file number

For example, these sequence files can exist for table ttadv999, company number 0:

aadv999000.000 aadv999000.001 aadv999000.002 aadv999000.003 ....

The sequence file contains the table name and company number, followed by the sequence header. This is followed by transaction data of multiple transactions. Transaction data is followed by a transaction header and contains multiple audit rows generated for the transaction.

Sequence file layout


Description

Table name 8 Str Name of the table Company number 2 Int Company number of the table Length of sequence header

2 Int The length of the next sequence header.

<sequence header> <transaction header 1> <transaction data 1> … <transaction header n> n = number of transactions in the

sequence file (specified in the transaction header)

<transaction data n>

Audit management


Transaction header format

You need to log both the operating system user ID and the iBaan ERP user name. This is because a user can change the USER environment variable and use different iBaan ERP user names. Also, different iBaan ERP users can have different table privileges in SQL databases. Programs can find the operating system logon name by using the operating system user ID print.

Operating system user id 4 Baan User Name 8 Date ( YYYYMMDD ) 8 Time ( HHMMSS ) 6 Session Name 15

The transaction status can have one of the following values:

COMMIT_DONE

ABORT_DONE

From BAAN IVc onward, the status can also have the following flags. The values for these flags can be found in the audit include file.

The Audit Server does not write the status PREPARE_DONE anymore!

GATI_UTC_FLDS

Transaction Status 1 Number of audit rows in the transaction 2

Also since BAAN IVc, the following fields are added at this position.

{ GATI 0 4 GATI 1 4 Commit Date ( YYYYMMDD ) 8 Commit Time ( HHMMSS ) 6 Reserved space 8 }

Total bytes of data of this transaction 4

You need to log both the operating system user ID and the iBaan ERP user name. This is because a user can change the USER environment variable and use different iBaan ERP user names. Also, different iBaan ERP users can have different table privileges in SQL databases. Programs can find the operating system logon name by using the operating system user ID print.

EXAMPLE

NOTE

Audit management



Description

UNIX User Id 4 Int ID of the user on UNIX. On NT is field is 0. Baan User Name 8 Str You need to log both OS user ID and Baan

User name. This is because an OS user can operate using different Baan user names by changing the USER environment variable. Different Triton users can have different table privileges in SQL databases. So, both must be stored. Using an OS user ID, print programs can find the UNIX logon name, and so on.

Old Commit Date/Time

14 Str Historical commit time in UTC. Format: YYYYMMDDhhmmss

Commit Date/Time 14 Str Commit time of transaction in UTC. Format: YYYYMMDDhhmmss. This Commit Date/Time is equal over all audit tables that are involved in this transaction. Change note: This field is only available from BAAN IVc onwards.

Session Name 15 Str Name of the session in which the transaction was carried out.

Transaction Status 1 Int Transaction Status can have one of following values: COMMIT_DONE, ABORT_DONE. From iBaan ERP onwards the transaction status will be irrelevant, because it is determined in the transaction notifications.

Number of Audit Rows in the Transaction

2 Int Number of audit rows for this table, so not all audit rows of the complete transaction.

Transaction ID 0 4 Int Change note: This field is only available from BAAN IVc onwards.

Transaction ID 1 4 Int Change note: This field is only available from BAAN IVc onwards.

Reserved Space 8 Change note: This field is only available from BAAN IVc onwards.

Total Bytes in Transaction

4 Int Total bytes of data of this transaction.

Audit management


Transaction data format


Description

Length of Row 2 Int Length of the audit row. SNAT 4 Int Sequence Number in Audit Transaction. Application Data 4 In every audit row, 4 bytes of space is kept to

store application data. This data is stored and manipulated by 4-GL applications and not by the audit server. The audit server just keeps the 4 bytes of extra space to be used later.

Type of Operation 1 Str Type of operation is a single character field, indicating the database action done on the table. Following are the characters used to indicate audited database actions: C: Create Table. L: Clear Table. R: Drop (Remove) Table. I: Insert row. D: Delete row. U: Update row.

Row Data ... In the audit row, the row data is present only for row-level actions. The field values, whenever stored, are stored in the same format as their data type. Thus value for a long field is also stored as long in the audit row. Thus the length of each field entry in the audit row is the same as the length of the column. For insert, the row data consists of field values (that is, the values to be inserted) of all audited fields, in the order in which they occur in the audit DD. For delete, the row data consist of field values (of the row to be deleted) of all audited fields, in the order in which they occur in audit DD. In case of update, not all fields in the table can be updated. Yet for all fields (also those that have not been changed) the old and new values are stored. Field numbers are used to identify the fields. A field number for a field is its position in the audit DD (starting with field 0).

Audit management


Change note: In versions before iBaan ERP the following holds for updates: In case of update, not all fields in the table can be updated. So, apart from storing field values, an identifier is required to specify the field to which this data belongs. Here, field numbers are used to identify the fields. A field number for a field is its position in the audit DD (starting with field 0). An entry for a field looks as follows: Field Number 2 Bytes. Is the value changed 1 Byte. (‘Y’ or ‘N’). Old Value .. New Value ..

Here, if the field is changed, both old and new values are stored. If a primary audited key field is not changed, only a single value is stored. For other audited fields, if they are not changed, nothing is stored. For all primary key audited fields and all other audited fields that are changed, these entries are made to make the audit-data. For more information on audit rows and examples, refer to the chapter on the audit server.

Transaction status

Length: 1 byte. Transaction status can have the following values:

− COMMIT_DONE − ABORT_DONE

Number of audit rows in the transaction Length: 2 bytes

Total bytes of data of this transaction Length: 4 bytes

Transaction data format:

Length of the row (Length: 2 bytes). Application data (Length: 4 bytes). Type of operation (Length: 1 byte) Row data.

Audit management


Four bytes of space is kept in every audit row to store application data. This data is stored and manipulated by 4GL applications and not by the audit server. The audit server keeps the 4 bytes of extra space to be used later. The type of operation is a single character field, indicating the database action done on the table.

The following characters are used to indicate audited database actions.

C – Create table. L – Clear table. R – Drop (remove) table I – Insert row. U – Update row.

In the audit row, the row data is present only for row level actions. The field values, when stored, are stored in the same format as their data type. This means that a value for a long field is stored as a long data type in the audit row. The length of each field entry in the audit row is the same as the length of the column.

The row data for an insert consists of the field values to be inserted of all audited fields, in the order in which they occur in the audit-data dictionary.

The row data for a delete consists of the field values of the row to be deleted and of all audited fields, in the order in which they occur in the audit-data dictionary.

Not all fields in the table are updated for an update. Apart from storing field values, an identifier is required to specify the field to which this data belongs. Field numbers are used to identify the fields. The field number is its position in the audit-data dictionary, starting with field 0.

An entry for a field contains the following information:

Field number – 2 bytes. Is the value changed – 1 byte (Y or N). Old Value. New Value.

If a field is changed here, both old and new values are stored. If an audited primary key field is not changed, only the old value is stored. If other audited fields are not changed, nothing is stored. For all changes made to all audited fields, entries are made to the audit-data.

13-1


General OLE Automation is an industry standard that applications use to expose their OLE objects to development tools, macro languages, and other applications that support OLE Automation. For example, a spreadsheet application can expose a worksheet, chart, cell, or range of cells—all as different types of objects. A word processor can expose objects such as application, document, paragraph, sentence, or selection.

When an application supports OLE Automation, the objects it exposes can be accessed by Visual Basic. You can use Visual Basic to manipulate these objects by invoking methods on the object or by getting or setting the object’s properties. For example, if you create an OLE Automation object named MyObj, you can write the following code to manipulate the object:

Dim MyObj As Object 'declaration

Sub PrintWordDoc()

Set MyObj = CreateObject("Word.Basic") 'start MS Word

MyObj.FileNewDefault 'open a new file

MyObj.Bold 1

MyObj.Insert "Hello, world." 'insert new text

MyObj.FilePrint 'print current file

MyObj.FileSaveAs "C:\WORDPROCDOCS\TESTOBJ.DOC"

MyObj.AppClose 'close MS Word

Set MyObj = Nothing

Exit Sub

End Sub

This example runs Microsoft Word to create and print a document with the text, “Hello, world.”

The application that exposes objects is called an OLE Automation server, the application using those objects is called an OLE Automation client.

13 OLE Automation

OLE Automation


In fact the OLE Automation interface can be compared to the C Interface of iBaan ERP. Where the C Interface offers an interface from other C programs to iBaan ERP, OLE Automation offers an interface from other MS Windows applications to iBaan ERP. The implementation is based on the iBaan ERP 4GL parse_and_exec_function function in the same way as the C Interface.

iBaan ERP as OLE Automation server In combination with the BW user interface, iBaan ERP is also an OLE Automation server. The iBaan ERP application exposes an object through which clients can call iBaan ERP dynamic link library (DLL) functions. This section describes how you can create and use this iBaan ERP object.

The iBaan ERP application exposes just one object, which is the application object. In Visual Basic this object can be created with:

Set BaanObj = CreateObject("Baan.Application")

This starts iBaan ERP with the BW user interface invisibly, in other words only the Option Dialog icon is displayed. OLE Automation objects, such as BaanObj, can have methods and properties. A method is a function that can be started to perform a certain action. A property is an attribute that has a value. Property values can be set or retrieved.

The iBaan ERP application object has the following methods:

dllname, functioncall ParseExecFunction. Quit.

The iBaan ERP application object has the following properties:

Name Type Value can be Timeout long Set FunctionCall string Set Error long Retrieved ReturnValue string Retrieved ReturnCall string Retrieved Binary boolean Set

OLE Automation


These methods and properties allow Visual Basic programmers to call any function in any DLL. For example:

BaanObj.Timeout = 10 ' 10 seconds timeout

BaanObj.ParseExecFunction "mydll", "myfunction(arg1, arg2)"

If BaanObj.Error <> 0 Then MsgBox("An error occurred")

MsgBox("The return value is " + BaanObj.ReturnValue)

This calls the myfunction function in the DLL named mydll. Note how arguments are passed to myfunction. If arguments are passed by reference they can be changed by the function call. Therefore the ReturnCall property contains the modified arguments after the call.

The Timeout property is used to prevent blocking on erroneous calls. The Error property contains the return status of the ParseExecFunction call, and the ReturnValue property is the actual return value of the DLL function. If the DLL function returns a long value, it is converted to a string in ReturnValue.

To return binary data in ReturnCall arguments, the binary property must be set to True. ReturnCall can contain null characters.

Possible values for the Error property are:

0 success.

-1 unknown DLL name.

-2 unknown function name.

-3 syntax error in function call.

-10 timer expired.

-11 fatal error in function.

To end an automation session you can quit a iBaan ERP application as in this example:

Set BaanObj = Nothing

OLE Automation


Restrictions When you use the OLE Automation interface, you must consider the following restrictions:

Due to the 3GL parse_and_exec_function function, you cannot supply arrays as arguments to a DLL function.

DLL functions with a variable number of arguments or optional arguments are not supported.

When a string is passed by reference, the result cannot become longer than the input string. When a string must be filled make sure it is initialized with the same number of spaces as the maximum length that can be returned. The maximum length is defined in the domain of the variable.

The maximum size of the FunctionCall string is 4KB (bshell limit).

The maximum size of the ReturnValue string is 4KB (bshell limit).

Two client applications cannot simultaneously use the same BW to make DLL function calls.

Example: import iBaan ERP users This example fills an MS Excel spreadsheet with the names of all iBaan ERP users. To do this, you must:

Implement DLL functions to obtain the names of the users from the database. Implement some Visual Basic code in MS Excel.

OLE Automation


DLL function example The following DLL, called demo.dll, contains two functions that retrieve the names of the users from the database. One function initiates the query and gets the first name, and the other gets the next name. When the last record has been returned, an empty string is returned.

table tttaad200

long sql_id

function extern string get_first_user()

{

string sql_query(512)

string user(512)

switch.to.company(0)

sql_query = "select ttaad200.user from ttaad200"

sql_id = sql.parse(sql_query)

sql.exec(sql_id)

e = sql.fetch(sql_id)

if e = 0 then

user = ttaad200.user

else

user = ""

endif

return(user)

}

function extern string get_next_user()

{

string user(512)

e = sql.fetch(sql_id)

if e = 0 then

user = ttaad200.user

else

user = ""

endif

return(user)

}

OLE Automation


Visual Basic example MS Excel contains Visual Basic for Applications (VBA), which allows for scripting to control both the Excel application and other applications through OLE Automation. The following is the Visual Basic source that calls the DLL functions and displays the results in a spreadsheet. The subroutine GetBaanERPUsers is an MS Excel macro that can be invoked through buttons or menus on the spreadsheet.

Dim user As String

Dim BaanObject As Object

Sub GetBaanERPUsers()

On Error GoTo CannotConnectToBaanERP

' run iBaan ERP

Set BaanObject = CreateObject("Baan.Application")

On Error GoTo BaanAutomationError

' get first user

BaanObject.ParseExecFunction "demodll",

"get_first_user()"

If (BaanObject.Error <> 0) Then GoTo

BaanAutomationError

user = BaanObject.ReturnValue

Row = 1

Column = 1

While (user <> "")

' fill the spreadsheet

Worksheets("Main Sheet").Cells(Row, Column)

= user

Row = Row + 1

If Row > 15 Then

Row = 1

Column = Column + 2

End If

' get next user

BaanObject.ParseExecFunction "demodll"

"get_next_user()"

If (BaanObject.Error <> 0) Then GoTo

BaanAutomationError

OLE Automation


user = BaanObject.ReturnValue

Wend

' exit iBaan ERP

Set BaanObject = Nothing

Exit Sub

' error handling

CannotConnectToBaanERP:

MsgBox "Unable to connect to iBaan ERP"

Exit Sub

BaanAutomationError:

MsgBox "A iBaan ERP automation error occurred"

Set BaanObject = Nothing

Exit Sub

End Sub

Example: To use iBaan ERP SQL The following example fills an MS Excel spreadsheet using iBaan ERP SQL. To implement this, a DLL called ottdllsql_query has been developed to parse and execute the query. To receive more information about this library, enter the following command:

*> bic_info6.2 –eu ottdllsql_query

DLL information The DLL ottdllsql_query contains:

Functions to parse, execute, and stop a query: − olesql_parse − olesql_fetch − olesql_break − olesql_close

Functions to import query results into Visual Basic: − olesql_getstring − olesql_getint − etc.

OLE Automation


A function to convert an Easy SQL query to a string: − easysql_to_olesql

Declaration of external variables, such as: − olesql_count − olesql_float0, olesql_float1 ... olesql_float9 (double variables) − olesql_int0, olesql_int1 ... olesql_int9 (long variables)

An MS Excel example is installed in the SAMPLES directory of BW (BAAN.XLS). This spreadsheet contains several macros.

The first macro, GetBaanUsers, shows a number of iBaan ERP users on the Worksheet Users spreadsheet. To use it, click the button on the Worksheet Users that starts this macro. For more information refer to the Visual Basic code in Worksheet Module 1.

The second macro, GetItemCount, shows all item groups in iBaan ERP with the numbers of items per item group on the Worksheet Itemcount spreadsheet. Click the button on the Worksheet Itemcount to start this macro. To run the macro you must insert an Easy SQL query in the iBaan ERP application. To insert the query, start the Query Data (ttadv3580m000) session, insert a record named item and choose Maintain Query by Text Manager. In the text editor, enter the following query:

select tiitm001.citg, | Item group

count(tiitm001.item) | Item

from tiitm001 | Item data

group by tiitm001.citg

order by tiitm001.citg

Date post:	10-Nov-2021
Category:	Documents
Upload:	others
View:	5 times
Download:	0 times

iBaan ERP 5 - baansupport.com

Documents