BaanERP Toolsbaansupport.com/docs/Baan5/BaanERP-5.0b-Tools-Technical-Manual.pdf · Oracle 9-2...

BaanERP ToolsTechnical Manual

A publication of:

Baan Development B.V.P.O.Box 1433770 AC BarneveldThe Netherlands

Printed in the Netherlands

© Baan Development B.V. 1998.All rights reserved.

The information in this documentis subject to change withoutnotice. No part of this documentmay be reproduced, stored ortransmitted in any form or by anymeans, electronic or mechanical,for any purpose, without theexpress written permission ofBaan Development B.V.

Baan Development B.V.assumes no liability for anydamages incurred, directly orindirectly, from any errors,omissions or discrepanciesbetween the software and theinformation contained in thisdocument.

Document Information

Code: U7040C USGroup: User DocumentationEdition: CDate: October, 1998

i

Technical Manual

1 Installing BaanERP Windows (BW) 1-1Hardware and software requirements 1-1Installing the BaanERP Windows (BW) software 1-2Installation directory of BaanERP Windows (BW) 1-9The BECS utility 1-10Functionality of BECS 1-10Registering the BECS utility 1-10

2 BI server 2-1Introduction 2-1Architecture 2-1Requirements for installation 2-4Installing the BI server 2-5Moving the BI server to another system 2-7Configuring the BI server 2-7Starting the BI server 2-7BI server as a Windows NT Service 2-9Adjusting the BI HTML-page 2-10Client issues 2-11

3 Database tools 3-1General 3-1bdbpre 3-1bdbpost 3-6bdbreconfig 3-10refint 3-14

4 Database management 4-1General 4-1Accessing tables 4-1tabledef6.2 4-1fd6.2.package combination 4-2Example table access (table and Bshell on the same system) 4-2Database drivers 4-2Accessing tables on other systems 4-3Audit trail 4-3Database mirroring 4-3Alternative databases 4-5

Table of contents

Table of contents

Technical Manual

ii

Communication protocols 4-5Socket protocol 4-7Local sockets 4-7Remote sockets (only for database servers) 4-7Pipes protocol 4-8Message queue protocol 4-8Example ipc_info file 4-9

5 Native language support 5-1General 5-1Composed characters 5-1Conversion tables 5-2Input conversion table 5-2Output conversion table 5-2Example of total conversion 5-3NLS editor 5-4Initial screen options 5-5Maintenance of NLS conversion tables 5-5NLS-related files 5-7Terminal information file 5-7Printer information file 5-8Input and output conversion table 5-8Terminal setup 5-9Character sets and fonts 5-9Sort tables 5-9Shift tables 5-10ISO 8859-1 character set (0-127) 5-11DEC vt100/vt200 character set (0-127) 5-13DEC vt100/vt200 character set (128-255) 5-15List of compose sequences 5-17Input/output table vt200 5-20Output table 5-24Printer output table MT910 HP Prestige character set 5-25Overview of Esc/Ctrl codes 5-29

6 Information files 6-1Terminal information file 6-1Boolean entries 6-1Numbers 6-2Strings 6-3Keys 6-9Color support 6-11Sending colors separately 6-11

Table of contents

Technical Manual

iii

Colors in combination with code features 6-13Parameterized strings 6-14Example of terminal information files 6-16Printer information files 6-21Bar codes 6-26Example of printer information file for mt910 printer 6-29

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

8 Customer support tools 8-1General 8-1Error logging 8-1Log file 8-1Log file layout 8-2Log file maintenance 8-3Submitting errors to customer support 8-3Example error logging 8-4

9 Executable programs 9-1Database management 9-1General 9-1Oracle 9-2Sybase 9-2Informix 9-2DB2 9-3Logic server (Bshell) 9-3Bshell6.2 9-3Debugging the Bshell during run time 9-4Memory usage 9-9Miscellaneous 9-10bshcmd6.2 9-10badmin6.2 9-13Installation 9-13Development 9-14License management 9-14licd6.2 9-14licmon6.2 9-15Printer management 9-16Shared memory 9-17

Table of contents

Technical Manual

iv

Network 9-17TRITON Super Set 9-18Time zone utilities 9-20Middleware 9-20UNIX equivalents 9-20Miscellaneous 9-21

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

11 Shared memory management 11-1General 11-1Using the shared memory manager 11-1Installation of shared memory 11-2Create an entry in the file shm_param file 11-2Determine shared-memory parameters 11-3Using shmvalues6.2 11-3Using shmmanager6.2 11-4Fill the entry in the shm_param parameter file 11-5Installation of shared memory 11-6Starting shmtimer6.2 11-6Error messages during installation 11-7Syntax srdd_tab 11-9Filling shared memory 11-10Kernel requirements 11-11General description of adjusting UNIX kernels 11-11Kernel parameters 11-12General kernel parameters 11-17Example parameter file shm_param 11-18

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

Table of contents

Technical Manual

v

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

14 Audit management 14-1General 14-1Storage of audit data 14-1Sequence files 14-1Information file 14-2Location of audit files 14-2Other parameters of audit files 14-3Audit management 14-4Table data dictionary as seen by audit server 14-5Commands logged by audit server 14-6Data stored by audit server 14-6Format of audit row 14-7Examples of the audit row for various operations 14-9Limit on the size of audit data 14-10Audit server 14-10Long transactions and overflow file 14-10Sequence termination 14-11Sequence file maximum size reached 14-11Table audit data dictionary changed 14-11Sequence terminated by user 14-13Transaction termination 14-13Reusing sequence files 14-16File locking 14-16Limit on open files 14-17Opening large number of tables in single session 14-18Multisession support 14-18File security for various audit management files 14-18Audit server debugging options 14-19Audit errors 14-19

Table of contents

Technical Manual

vi

Authorizations 14-20Format of audit files 14-22auditdef6.2 14-22Information file 14-23Sequence file 14-26audit_spec file 14-31

15 OLE Automation 15-1General 15-1BaanERP as OLE Automation server 15-2Restrictions 15-4Example: Import BaanERP users 15-4DLL function example 15-5Visual Basic example 15-6Example: Using BaanERP SQL 15-7DLL information 15-7

Technical Manual

vii

This document is a reference guide explaining how you can customize theBaanERP application for use by specific organizations. It is intended for use byBaanERP application developers and application managers. You can use thisreference guide to set up and maintain a BaanERP application.

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

Chapter 1, “Installing BaanERP Windows (BW),” describes how to installBaanERP Windows (BW). This assumes that you already have BaanERPinstalled on the server.

Chapter 2, “BI server,” summarizes how to install the BaanERP Internet Serverapplication, which is used as a gateway between the BaanERP Internet client(BI) and the BaanERP application server (Bshell), to expose the BaanERPfunctionality to the Internet domain.

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

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

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

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

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

Chapter 5, “Native language support,” describes the communication between thecharacter set of a terminal and that of Bshell6.2.

Chapter 6, “Information files,” describes terminal information files, which storeinformation such as the type of terminal, terminal operations, how to access keyson the keyboard, color support, cursor movements, and whether code features areblinking, bold, or reverse.

About this document

About this document

Technical Manual

viii

Chapter 7, “User Interface (UI) Page mode,” describes the User Interface (UI)Page mode in BaanERP. In normal mode, the 4GL Engine validates the entereddata per field. In the UI Page mode, the 4GL Engine validates data per pagerather than per field. The synchronous interaction between the UI driver and theBshell is therefore significantly reduced, which improves response times.

Chapter 8, “Customer support tools,” describes two functions used for solvingerrors in a Bshell environment: error logging and the bserel6.2 program. Errorlogging is keeping a record of error messages in a log file. The program bserel6.2provides information on the BSE environment as installed on your system.

Chapter 9, “Executable programs,” describes all of the executable programs usedfor database management.

Chapter 10, “Errors,” describes all the errors that can occur when you areworking in the BaanERP environment, and offers a solution.

Chapter 11, “Shared memory management,” discusses shared memory, which isa part of the internal memory intended for common usage.

Chapter 12, “Remote databases,” explains how the BaanERP client/serverarchitecture enables the user to work with databases distributed over one or moresystems.

Chapter 13, “Multibyte Management,” explains how to use the 32-bit widecharacter space, which has been implemented in BaanERP Tools to support allpossible character sets.

Chapter 14, “Audit Management,” describes the audit management facilityincluding the audit server, the audit management utility, and where audit data isstored.

Chapter 15, “OLE Automation,” describes how BaanERP works with OLEAutomation, an industry standard that applications use to expose their OLEobjects to development tools, macro languages, and other applications thatsupport OLE Automation.

Technical Manual

1-1

This chapter describes how to install BaanERP Windows (BW). It assumes thatBaanERP is already installed on the server. If this is not the case, refer to thedatabase-specific installation guide.

BaanERP Windows (BW) is a graphical user interface (GUI) program inBaanERP. BW runs on an Intel compatible PC in a Windows 95 or Windows NTenvironment. BW displays BaanERP as an application with the same look andfeel as a native Windows application.

This chapter describes:

n The hardware and software requirementsn How to install the BaanERP Windows (BW) softwaren The installation directory of BaanERP Windows (BW)n The BaanERP Windows (BW) environment variables

Hardware and software requirementsThe following software and hardware requirements must be met before you caninstall BaanERP Windows (BW).

n The operating system Windows 95 or Windows NT Server version 4.0 mustbe installed and running.

n The system on which BaanERP Windows is to be installed, must be at leastan Intel-based system with a 50 MHz 486DX processor. Furthermore,BaanERP Windows requires at least a SVGA video display, 16 MB of mainmemory (RAM), and 8 MB of free disk space.

1 Installing BaanERP Windows (BW)

Installing BaanERP Windows (BW)

Technical Manual

1-2

Installing the BaanERP Windows (BW)softwareTo install the BaanERP Windows (BW) software, you can follow one of theseprocedures:

n If you have a UNIX BaanERP server, the BaanERP Windows (BW) softwarecan be copied from the directory $BSE/mswindows/Bw5.xx on the server toa temporary directory on the client by using ftp. Double-click the filesetup.exe. This starts the BW installation program.

n If the client has a local CD-ROM drive, you can install BaanERP Windows(BW) directly by using the BaanERP distribution CD-ROM.

n If the client has no CD-ROM drive, you can share the CD-ROM of the server.

The description below assumes that your client has a local CD-ROM drive and isrunning the Windows NT operating system.

Take the following steps to install BaanERP Windows.

1 Close all running applications and insert the BaanERP distribution CD-ROMin the CD-ROM drive.

2 A Welcome message is displayed. Choose Next.

3 A Licence Agreement message screen is displayed. Choose Yes.

4 The Select environment dialog box is displayed.

NOTE


Technical Manual

1-3

Click Install new environment if you perform a fresh installation, and entera name for the new installation. If you want to upgrade an existing BWinstallation, you must click Select existing environment to choose theexisting environment to be upgraded. Choose Next to continue.

5 The Choose Destination Location dialog box is displayed. The layout of thedialog box depends on whether you are installing BW on a PC client or aWindows NT server.

If you are installing on a PC client, the following dialog box is displayed:


Technical Manual

1-4

If you are installing on a Windows NT server, the following dialog box isdisplayed:

Accept the default path or choose Browse to enter another path. Choose Nextto continue.

6 The Setup Type dialog box is displayed:


Technical Manual

1-5

You can select the following server types:− User Interface

This type is a BaanERP Windows (BW) client.

− User Interface and LogicThis type is a stripped version of a BaanERP Windows NT server (withlocal application logic).

− Full installation (including application files and database)This type is the complete BaanERP Windows NT server version.

7 Select User Interface and choose Next. The Select Program Folder dialogbox is displayed. Select the Program Folder to which the BaanERP Windowsicons must be added (default BaanERP) and choose Next.

8 The Setup Information dialog box is displayed. Choose Next to continuewith the displayed setup (or choose Back to change the displayed setup).

9 After the software is installed you must choose OK to exit the installationscript. The BaanERP program folder is displayed. Double-click the BWConfiguration Tool icon. The BW Configuration dialog box is displayed.

10 Supply the following information.

On the Application Server tab you must fill in the following boxes:− Hostname

Enter the host name of the BaanERP server.


Technical Manual

1-6

− Connect AsEnter a valid user name as known on the BaanERP server.

− Ask password at startupIf this check box is selected, you can only supply the password during theBaanERP login procedure.

− Use saved passwordIf this check box is selected, the BaanERP logon procedure is skipped,and the saved password is used.

− Current userSelect this check box to make use of the Windows Integrated Securityfeature. In this case you will use your current user identity to log on to theBaanERP Windows NT server.

For Windows 95 the unified logon feature will only work if you areactually logged on to Windows 95.

You can only make use of the Windows Integrated Security feature, ifyour BaanERP server is a Windows NT server.

− BSEEnter the path to the BSE environment on the BaanERP server (equals theBSE environment variable on the BaanERP server).

− Bshell nameEnter the application logic to use on the remote BaanERP host (changingthe default of bshell will only be useful during debugging).

− CommandEnter the option you want to pass to the bshell. You can, for example,define environment variables by using the following syntax:

-- -set Environment Variable1=xxx -set Environment Variable2=yyy

On the NLS tab, you must fill in the following box:

− LocaleSelect the character set to be used (the default character set isInternational [ISO]).

On the Font tab, fill in the following box:

− Font TypeEnter the desired font type. You can change the setting by choosing thebutton at the right side of the font boxes.

NOTE

NOTE


Technical Manual

1-7

On the Automation tab, you can fill in the following box:

− Class NameThis box contains the name of the Baan automation objectBaan.Application.server, where server is the hostname of the BaanERPserver you supplied on the Application Server tab.

Choose Save As on the Application Server tab to save the new configurationin a different configuration file. However, only one configuration can beactive per BaanERP session.

11 Choose RUN! to start your BaanERP session.

The BaanERP .bwc files are registered by the Windows NT or Windows 95operating system. You can find the .bwc files in the directory Lib\User underthe installation directory of the BaanERP client software. This implies thatyou can start a BaanERP logon procedure by double-clicking the icon in frontof the relevant .bwc file in the File Manager. You can also make BaanERPprogram icons by dragging the .bwc configuration files to a Program Group.

NOTE

NOTE


Technical Manual

1-8

12 From the BaanERP Tools menu, choose Software InstallationÐInstallation. Open the Download Help Files (ttadv8245m000) session. Thissession has two options:

− Download help filesThis command installs the windows Help files on your client. Select thepackages for which you want to see Help and choose Download HelpFiles from the Specific menu.

− Edit HTML Help transfer scriptWhen you install HTML help on an HTTP server, you must edit theHTML Help transfer script. This script is used for transferring the HTMLhelp files from the application server to the HTTP server. To execute thisscript, you need access to the HTTP server.


Technical Manual

1-9

Installation directory of BaanERP Windows(BW)The installation directory C:\Program Files\Baan\BW5 is created during thesetup process of BaanERP Windows (BW). During setup you can change thisinstallation directory. This section assumes you have chosen the default name forthe installation directory of BaanERP Windows (BW).

The following subdirectories are created in directory C:\ProgramFiles\Baan\BW5 during setup:

n C:\Program Files\Baan5\BW\binThis directory contains the bw.exe program to start the BaanERP application.It also contains the bwconfig.dll for the configuration program.

n C:\Program Files\Baan5\BW\libThis directory contains the files bw.ini (initialization file), bw5.reg (objectregistration file), bw.tlb (type library information for OLE Automation), andtss_bw (language support).

n C:\Program Files\Baan\BW5\logThis directory contains logging information about BaanERP Windows.

n C:\Program Files\Baan\BW5\samplesThis directory contains a Microsoft Excel spreadsheet, which is an exampleof the use of OLE Automation to access BaanERP dynamic link libraries.

n C:\Program Files\Baan\BW5\tmpThis directory contains the temporary files.

n C:\Program Files\Baan\BW5\helpThis directory contains the Help files.

The following subdirectories are created in the directory C:\ProgramFiles\Baan\BW5\lib.

n C:\Program Files\Baan\BW5\lib\nlsinfThis directory contains the special character set file xwindows.in.

n C:\Program Files\Baan\BW5\lib\userThis directory contains the configuration files.


Technical Manual

1-10

The BECS utilityIf you want to use both a BAAN IV and a BaanERP server from a singleworkstation, you must install two different BW versions on your workstation.Before the BECS utility was available, this generated the problem that both BWversions wanted to be the owner of the BW configuration files (the files withextension .bwc, in which your configuration settings are stored). Therefore, itwas unpredictable which BW version would be started if you double clicked a.bwc file.

This problem is solved by the BECS utility: it enables you to run different BWversions on a single workstation.

Functionality of BECS

The BECS utility offers the following functionality:

n It takes the ownership of files with the extension .bwc. By doing this, itresolves the potential conflict described above. After BECS is correctlyinstalled, you will start BECS by double clicking on a .bwc file. Based on thelocation of your .bwc file, BECS will locate the associated BW version, andstart this BW version accordingly. For this, your .bwc file must be stored inthe lib\user subdirectory of the directory where you installed the BW version.BECS will start bin\BW.exe in this same directory.

n It can show you the different BW-versions installed on your system. Once theBW versions have been registered, you will get an overview of all the .bwcfiles for the BW versions if you start BECS. This enables you to go to theconfiguration screen for each of the .bwc files, and to launch BW using theselected configuration screen.

Registering the BECS utility

To make BECS.exe the owner of all .bwc files, you must follow the steps below:

1 Copy BECS to the location you want to have it, for example,C:\Program Files\Baan\BECS.exe.

2 In the same directory where you found this file you can find the fileBECS.reg. At the end of this file, you will find the following lines:

HKEY_CLASSES_ROOT\BW_Configuration\shell\Open\command ="$(BSE)\bin\BECS.exe" "%1"HKEY_CLASSES_ROOT\BW_Configuration\shell\Config\command ="$(BSE)\bin\BECS.exe" -config "%1"


Technical Manual

1-11

3 Please edit this file, and replace the portion $(BSE)\bin\BECS.exe by thepath of your choice, for example, C:\Program Files\Baan\BECS.exe.

4 Execute the file BECS.reg by double clicking it. This will make BECS.exethe owner of all .bwc files.

Registering BW environments

To let BECS.exe show all available .bwc files, you must create registry keys forall BW environments. You can do so by following the steps below:

1 Start regedit

2 Go to HKEY_LOCAL_MACHINE\SOFTWARE\Baan

3 Create a new key for each BW environment you want to register, forexample, both Baan4 and Baan5. Within each key you must add a new stringvalue named BSE, containing the patname to the directory where youinstalled the BW version. For example, the settings could look like the onesbelow:

[HKEY_LOCAL_MACHINE\SOFTWARE\Baan\Baan4]"BSE"="C:\\Program Files\\Baan\\Bw4"[HKEY_LOCAL_MACHINE\SOFTWARE\Baan\Baan5]"BSE"="C:\\Program Files\\Baan\\Bw5"


Technical Manual

1-12

Technical Manual

2-1

IntroductionThe BaanERP Internet Server ap

plication (BI server) is used as a gateway between the BaanERP Internet client(BI) and the BaanERP application server (Bshell), to expose the BaanERPfunctionality to the Internet domain.

Architecture

The architecture of the BI server is shown in the following figure:

Figure 1, BI server architecture

The following components are included in the architecture:

n A Bshell running on an application-server system. This is a normal BaanERPapplication server to which both BaanERP Windows (BW) clients and BIapplets can connect. For each client (BI or BW) there is always oneconnection with a Bshell.

n An HTTP-server system, on which an HTTP-server application runs, and oneor more BI server applications. This setup is used as a gateway between theBaanERP applications and Internet browsers. BI applets always connect tothe Bshell through the BI server. There is never a direct connection betweenBshell and BI applet.

2 BI server

BI server

Technical Manual

2-2

One of the HTML pages, which is managed by the HTTP server, contains areference to the BI applet. When a browser performs a GET for this page, theBI applet is downloaded to the requesting browser. The HTTP-server systemand the application-server system can be one system or they can be twodistinct systems.

n A client system running a Java-enabled HTML browser. The BI applet runswithin this browser. The BI applet establishes a direct TCP/IP connectionwith the BI server running on the HTTP-server system or on another system.

The following figure shows a timing diagram for setting up the connectionbetween a BI applet and a Bshell using the BI server.

Figure 2, Connection using the BI server

BI server

Technical Manual

2-3

Security is important when you offer application functionality over the Internet.Security provision is available at three levels:

1 The HTTP server security mechanisms can be used to offer secure access tothe HTML page containing the BI applet.

2 Secure communication between the BI server and the BI applet is supportedusing the Secure Sockets Layer (SSL) v3.0 protocol.

3 Application-server system authentication.

The first level can be used to restrict access to the BI applet to a set of registeredusers. This feature is completely dependent on the HTTP server and is notdescribed here.

The second level offers secure communication between the BI server and the BIapplet. At this level the SSL protocol is supported. The SSL protocol providesconnection security that has these basic properties:

n The connection is private. Encryption is used after an initial handshake todefine a secret key. Symmetric cryptography is used for data encryption.

n The peer’s identity can be authenticated by using asymmetric or public keycryptography.

n The connection is reliable. Message transport includes a message integritycheck using a message authentication code (MAC).

The BI server uses a CipherSuite that does not offer server-side certification orclient-side authentication. Furthermore, the CipherSuite uses exportable versionsof the cryptographic algorithms so that the software can be delivered to allcountries.

Note that Secure Sockets Layer (SSL) client-side certification is not used,because this would require that each client get and store a certificate from acertification authority. Instead, client authentication relies on the user name andpassword validation used to connect to the application-server system. When youuse a Secure Sockets Layer (SSL) connection, this user name and password areencrypted when they are transmitted from the BI applet to the BI server. Inaddition, you can restrict access to the HTML-page containing the BI applet byusing the HTTP server security mechanisms, which might also require clientauthentication.

The BI server can be configured to use:

n No Secure Sockets Layer (SSL) securityn Secure Sockets Layer (SSL) security

BI server

Technical Manual

2-4

The third level uses the authentication mechanism of the application-serversystem. Each BI user provides a user name and password to log on to theapplication-server system.

Configuration

The BI server allows for configuration of important communication parametersby a system administrator. These configuration parameters include:

n Listener portn Enable/disable Secure Sockets Layer (SSL) securityn Application-server system name or IP addressn Enable/disable logging of access history and errorsn When logging is enabled, the log file name

Requirements for installationBefore you start the installation, you must note the following requirements:

n Required related productsn Performance requirementsn Installation requirements

These requirements are explained in the following sections.

Required related products

The BI server depends on the following related products, which must be installedon the HTTP-server system:

n A Java run time environment that conforms to the JDK 1.1.n An HTTP server capable of downloading Java applets to a browser

Performance requirements

The number of clients that can be supported by a single BI server application isnot restricted by the BI server. However, the Java virtual machine or theunderlying operating system can limit the number of simultaneous clientssupported by one instantiation of the BI server.

BI server

Technical Manual

2-5

Installation requirements

These are the requirements for installing the BI server and BI client componentson the HTTP-server system.

Before installing the BI components on the HTTP-server system, you mustinstall and configure the following third-party products:

n An HTTP server. The operating system of the HTTP-server systemdetermines which HTTP server must be installed. To run the HTTP server ona Windows NT server, you must install Microsoft Internet Information Server(IIS). If your server is running on a UNIX system you can, for example,install Netscape Enterprise servers or Apache.

n A Java virtual machine compatible with Java 1.1. The operating system of theHTTP-server system determines which Java virtual machine must beinstalled. Contact your operating system supplier to get an implementation ofa Java virtual machine.

Installing the BI serverAfter you have prepared the HTTP-server system as described in the section“Requirements for installation,” perform the following steps to install the BIcomponents on the HTTP-server system.

Both the HTTP-server system and the BaanERP application server can be UNIXor Windows NT systems. The following example installation assumes that youare installing on a UNIX platform.

1 Copy the BI installation file $BSE/internet/bisetup.class from the BaanERPserver to the HTTP-server system.

2 Start the BI installation program by entering the following on the commandline:

java bisetup

The java string is the name of the Java interpreter. This name is supplier-dependent (for example, jview for the Microsoft Java virtual machine).

NOTE

BI server

Technical Manual

2-6

3 The installation program asks for a destination directory for the BIcomponents. This must be a directory in the HTML tree that you can accessthrough the HTTP server (a directory below the document root directory ofthe HTTP server). If this directory does not yet exist, it is created. Aftercompleting the installation program, the directory structure on the targetsystem is similar to the following structure:

$PUBLIC_HTML/$TARGETDIR/client/ie4/bi.cab /grid.cab /ssl.cab /netscape/bi.jar /bi.html /readme.txt /images/logo.jpg /server/*.class

In this structure you can access the $PUBLIC_HTML directory in the HTMLtree through the HTTP server, in a directory below the document rootdirectory of the HTTP server.

$TARGET_DIR is a directory below $PUBLIC_HTML where the BIpackage has been installed.

4 At this point you must determine on which TCP port you want the BI serverto listen. Choose a free port.

5 Edit the HTML file that you can find at$PUBLIC_HTML/$TARGETDIR/client/bi.html. All the parametersmentioned in the section “Adjusting the BI HTML-page” must be filled inaccording to the actual configuration.

6 Start the BI server program. See the section “Starting the BI server” fordetails. The arguments must correspond with the values entered in the HTMLfile.

BI server

Technical Manual

2-7

Moving the BI server to another systemSome firewall configurations require that the BI server run on a system otherthan the HTTP-server system. In this case you must perform the following stepsafter you have performed steps 1-3 described in the section “Installing the BIserver.”

1 Install a virtual machine compatible with Java 1.1 on the system where youwant to run the BI server.

2 Copy the BI-server class files from the HTTP-server system to the samesystem. These class files can be found on the HTTP-server system at:$PUBLIC_HTML/$TARGETDIR/server. You must copy this completedirectory tree, preserving the directory structure.

3 Determine the TCP port on which you want the BI server to listen. Choose afree port.

4 Edit the HTML file on the HTTP-server system, which you can find at$PUBLIC_HTML/$TARGETDIR/client/bi.html. All the parametersmentioned in the section “Adjusting the BI HTML-page” must be filled inaccording to the actual configuration.

5 Start the BI server program. See the section “Starting the BI server” fordetails. The arguments must correspond with the values entered in the HTMLfile.

Configuring the BI serverThis section describes the additional steps to configure the BI server after theinstallation, and contains the following sections:

n Starting the BI servern Adjusting the BI HTML-page

Starting the BI server

The following command shown starts the BI server, listening on one TCP/IP portand forwarding incoming connections to the application-server systemappserver. The java string is the name of the Java interpreter. This name issupplier dependent, for example, jview for the Microsoft Java virtual machine.

java BI server [–s ] [–l logfile] [–c] [–t level] –p port –a appserver

BI server

Technical Manual

2-8

Options

–sWhen this option is specified, the Secure Sockets Layer (SSL) is enabled . Whenthis option is not specified, SSL is disabled. When security is enabled, the BIapplet must also use SSL for communication with the BI server. The BI appletgets this information through the applet parameters in the HTML page. See theparameter SECURITY in the section “Adjusting the BI HTML-page.”

–l logfileWhen this command is specified, logging of access history and errors isredirected to the file defined by the logfile placeholder. When this command isomitted, logging information is sent to the standard output, the Java console. Thelevel of logging detail is set with the –t command.

–cWhen this option is specified, the logging file indicated with the option –l is firstcleared, that is, truncated. If this option is not specified and the logging filespecified with the –l option already existed, all logging information is appendedto this file.

–t levelWhen this option is specified the level of detail for logging can be specified. Ahigher level gives more detail. Level 0 disables logging. The default for thisoption is level 1. The maximum level is 3.

–p portThis mandatory option is used to specify the port number on which this BI serverlistens for incoming BI applet connections. Usually a port number higher than1024 must be chosen, because lower numbers are reserved for system services.The BI applet must also use this port number when connecting to the BI server.The BI applets gets this port number via the applet parameters in the HTMLpage. See the parameter PORT in the section “Adjusting the BI HTML-page.”

–a appserverThis mandatory parameter specifies the application-server system. The appservercan be the hostname of the application-server system or its IP address.

BI server

Technical Manual

2-9

BI server as a Windows NT ServiceIf you are running the BI server on a Windows NT system, you can install the BIserver as a Windows NT Service. Before you do this, make sure that you canstart the BI server in your environment by manually starting the server. To installthe BI server as an NT Service you must perform the following steps:

1 Install the Windows NT Resource Kit. This section assumes it is installed atC:\ntres.

2 From the Windows NT Resource Kit, install the executable SRVANY.EXEas an NT Service. You can do this by entering the following commands at theDOS command prompt:

− C:\>cd \ntres− C:\ntres>INSTSRV BiService1 c:\ntres\srvany.exe

3 Start the Control Panel and choose the Services applet. Now perform thefollowing steps:

− In the Services applet, choose BiService1− Choose Startup− In the Startup dialog box, select the startup type Automatic− Select Log on as System Account. Do not allow this service to interact

with Desktop− Close the Control Panel

4 Start a registry editor, for example, regedt32, and perform the followingsteps:

− Look up HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\BiService1.

− Add another key under this key named: Parameters− Add the values listed in the following table to this key:

Registry values

Value name Value type Value string

Application REG_SZ C:\winnt\jview.exe

AppParameter REG_SZ BI server –l <logfile> –c –a <hostname> –p<portnum>

AppDirectory REG_SZ $PUBLIC_HTML\$TARGETDIR\server

Close the registry editor.

5 When you restart your Windows NT system, the service is startedautomatically.

BI server

Technical Manual

2-10

If you want more than one BI server to be started as a Windows NT Service,repeat steps 1 - 5, and use another name for BiService1.

Adjusting the BI HTML-page

The following example shows the content of an HTML-page loading the BIapplet in a browser.

<appletarchive="netscape/bi.jar"code=BiLogonwidth=400height=200><param name=cabinets value="ie4/bi.cab, ie4/grid.cab, ie4/ssl.cab"><param name=HOSTNAME value=””><param name=PORT value=2000><param name=SECURITY value=NONE><param name=BSE value=/usr/bse><param name=BSHELL value=bshell><param name=COMMAND value=""></applet>

The parameters that must be passed to this applet are as follows:

n HOSTNAMEThe value of this parameter is the TCP/IP hostname or IP address of thesystem on which a BI server application is listening. When this parameter isomitted or set to an empty string, the BI applet connects to the server, fromwhich the HTML-page containing the applet code was running. This is thedefault value. However, some firewall configurations require that the BIserver runs on a system other than the HTTP-server system. See the section“Moving the BI server to another system”.

n PORTThe value of this parameter is the port number on the HTTP server system onwhich a BI server application is listening. This must correspond with the portnumber passed to the BI server with the –p option. The BI applet alwaysconnects to the server from which the HTML-page containing the applet codewas running. The default value is 2000.

n SECURITYThe value of this parameter is used to determine the security mode of theconnection between the BI applet and the BI server. If this value is “SSL,”the BI applet starts a Secure Sockets Layer (SSL) connection with the BIserver. (The BI server must have been started with the –s option for therelated port).

BI server

Technical Manual

2-11

If this value is “NONE” or this parameter is omitted, the BI applet starts anormal TCP/IP connection with the BI server. (The BI server must have beenstarted without the –s option for the related port).

The default value is NONE.

n BSEThe value of this parameter is the BSE directory path on the application-server system. It is used to set the correct Bshell environment. The defaultpath is /usr/bse.

n BSHELLThe value of this parameter is the Bshell name on the application-serversystem. It is used to indicate which Bshell must be started (tag in$BSE/lib/ipc_info). The default value is Bshell.

n COMMANDThe value of this parameter is the command string to be passed to the Bshell.This can be the environment setting for the Bshell and the name of the firstsession to be started. The default command is empty.

Client issuesAt the time of writing this document, no detailed information about the supportedbrowsers at the client side could be given. For the most up-to-date informationabout the supported browsers refer to the file$PUBLIC_HTML/$TARGET_DIR/client/readme.txt, installed on the HTTP-server system.

BI server

Technical Manual

2-12

Technical Manual

3-1

GeneralThe database tools are designed for database management, and are independentof how the database is organized. At run time the system selects a database driverdepending on the contents of the file tabledef. You can then use these databasetools to:

n Convert a database table to a sequential file (bdbpre)

n Create a database table from a sequential dump or append data to an existingdatabase table (bdbpost)

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

n Check or repair the referential integrity within the database (refint)

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

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

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

bdbpreNAME

bdbpre

Convert database tables to a sequential file.

SYNOPSIS

bdbpre [–q output file] [–uUvVsrxyzkK][–p pack_comb][–t sep][–o dir][–d driver type][–N table [table ..]][–I file][–E file][–O file][–C company number list/range]

3 Database tools

Database tools

Technical Manual

3-2

DESCRIPTION

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

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

The file fd6.2.package combination is always used for searching dictionaryinformation. The following examples use $BSE/lib/tabledef6.2 to getinformation about the database type and driver. If you want to use a specificdatabase driver for a particular conversion, you can use the –d option. If you usethis option, tabledef6.2 is not read.

You can use bdbpre in the following ways:

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

bdbpre –Ntimcs099 –C000-005 > timcs099_dump

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

bdbpre –Ntimcs088 –C000 004 005 > timcs088_dump

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

bdbpre –Iseqfile –C000-009 > BIGdump

Type cat seqfile to view the contents of seqfile:

timcs001timcs002timcs003........timcs099

Database tools

Technical Manual

3-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 aparticular 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:

n Sybase (sybase)n Oracle (oracle)n Informix Online (informix)n DB2 (db2)n 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 (optionalwith specifications). For example:

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

Possible options:

–u/UPrint usage information.

–v/VPrint information about the version of bdbpre.

–p <pack_comb>define package combination.

–sSuppress error messages, statistics, and so on.

–CCompany numbers for given table, in two formats:

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

–dDatabase driver type, as follows:O (Oracle) I (Informix) S (Sybase) D (DB2) M (Microsoft SQL-Server)You can use the -d option to copy data from one instance of a database toanother, for example:

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

Database tools

Technical Manual

3-4

–NDatabase table name. Specify specific table names, for example, –N timcs000timcs016. The –I and –N options are mutually exclusive.

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

–E fileRedirects errors to file

–O fileRedirects output to file

–q output fileRedirect terminal output to file output file

–kDrop table after dump is created.

–KDrop table. Create a backup before dropping. This is only possible if the DBMSsupports this.

–tUsed to insert a separator (Default \0). Useful for separating the fields whendownloading records from the Bshell.

You want to download your database to UNIFY which uses | as a separator.Whenever you specify the –t parameter, a sequential file (.S) is created for eachtable in the current directory unless the –o option is specified.

bdbpre –t"|" –Ntimcs016 –C000 creates timcs016000.S in the currentdirectory. This sequential file is an ASCII dump of table timcs016000, in whichcase the fields are separated by |. You can load this file directly into Oracle,UNIFY, and so on, using SQL.

The options –x and –t are mutually exclusive.

–xCreates an ASCII dump with a fixed-length record and without any separators.This option is useful for downloading to databases such as dBASEIII, whichrequire fixed-length records without any separators.

In some cases a value is printed in the dump file that does not match the numberof digits before decimal points (DIGV). For example, suppose DIGV=3 and theprinted value=1234. The whole value, more than 3 digits, is written in the dumpfile, and an error message appears. To prevent this, you can use the followingoptions in combination with the –x option:

EXAMPLE

EXAMPLE

Database tools

Technical Manual

3-5

–ySkip out-of-domain records for fixed-length dumps. See –x.

–zSet value to 0 (zero) if value and DIGV do not match, that is, nullifies out-of-domain records. Creates individual, fixed-length ASCII File with the extension.F. See –x.

bdbpre –x –Ntimcs016 –C000 creates timcs016000.F, which is an ASCII dumpwith fixed-length records. This file can be loaded directly into dBaseIII.

–oCan be specified with the options –x and –t to specify the directory name inwhich the sequential file is created (.S or .F).

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

The database driver is retrieved from $BSE/lib/tabledef6.2bdbpre –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_016bdbpre –x –dinformix –Ntimcs016 –C000 –oci_dump_016

SEE ALSO

bdbpost

If you are piping your bdbpre output directly to bdbpost without giving the –soption, 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 thedatabase table from the remote machine is used, but the data dictionary is takenfrom the current machine, which can cause great difficulties.

EXAMPLE

EXAMPLES

NOTES

Database tools

Technical Manual

3-6

bdbpostNAME

bdbpost

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

SYNOPSIS

bdbpost [–I input file][–O output file][–{qE} output file][–uUvVARfilxnmkK ][–p pack_comb][–e file][–d driver type][–D seq_dir][–t sep] [–c compnr][–C compnr range][pattern]

DESCRIPTION

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

The bdbpost tool can be run using a sequential dump created by bdbpre or byusing sequential dumps from other databases. The different methods are shownin the following examples:

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

On system 1:

bdbpre –doracle –Ntimcs016 –C000-003 > timcs_dump

On system 2:

bdbpost < timcs_dump

This example shows the use of sequential dumps (–x or –t option of bdbpre)from other databases. In this case the –D option is mandatory to get the directoryname in which .S files are stored.

bdbpost –dinformix –t"|" –D./seqdirbdbpost –doracle –x –D./seqdir

Options –x, –t, and –D are required when you upload ASCII files from anotherdatabase to the Bshell format.

Database tools

Technical Manual

3-7

–DPath for sequential files, which have the extension .S or .F.

–tSeparator. If you want to load a sequential dump containing separators(for example, dump from UNIFY has separator |), make sure the file name is thetable name with the extension .S.

If you want to load a UNIFY sequential dump into the table ttimcs016000, firstmove the sequential dump to the ttimcs directory with 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 thetables, so be sure to remove unwanted .S files before running bdbpost.

–xIf you want to load a sequential dump with a fixed-length record without anyseparators (.F files, for example dump from dBase-III), make sure the file nameis the table name with the extension .F.

Suppose you want to load a dBASEIII sequential dump into the timcs016000table (Oracle organization). bdbpost –doracle –Ddbase –x searches for an .Ffile in dbase and if that file is found the corresponding table is created orappended.

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 aparticular conversion, you can use the –d option.

The database driver can be of the following types:

n Sybase (sybase)n Oracle (oracle)n Informix Online (informix)n DB2 (db2)n Microsoft-SQL Server (msql)

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

The following parameters can be used for bdbpost:


–v/VPrint information about the version of bdbpost.

EXAMPLE

CAUTION

EXAMPLE

Database tools

Technical Manual

3-8

–pDefine package combination

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

–cCompany number for the tables to be created.

–CRange of customer numbers on which to perform the bdbpost operation. Thismust be the last option specified in the command, other than the <pattern>option.



–xLoad ASCII file (.F) with fixed-length records.

–DThe directory name for ASCII files to be loaded.

–eFile to store the names of unsuccessfully created tables.

–kThe existing tables are deleted.

–KThe existing tables are deleted after a backup is made (if DBMS supports this).

–lDisplay contents of input.

–I <file>Redirects input from input file <file>.

–O <file>Redirects output to output file <file>.

–E <file>Redirects errors to error file <file>.

Database tools

Technical Manual

3-9

–q <output file>Redirect terminal output to output file.

–mDisable domain constraints.

–iIgnore domain range error and skip record.

–nIgnore referential integrity constraints.

–AAppend to an existing table. If duplicate records exist, do not overwrite themfrom the dump. Print duplicate record summary at the end. Create table if it doesnot exist.

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

–tSpecify the used separator. The –t option is used when loading an ASCII filefrom another database.

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

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

bdbpre –doracle –Nttadv000 –C000-010 > dump

bdbpost –doracle < dumpCreates (appends) all tables in dump

bdbpost –l < dumpGives you names of tables in dump

bdbpost –C000-005 < dumpCreates/appends tables only in the given customer range

bdbpre –doracle –Nticom000 –C000-010 > dump

EXAMPLES

Database tools

Technical Manual

3-10

bdbpost –C000-005 ticom* < dumpCreates/appends tables only in the given customer range and where the tablename matches the pattern ticom.

bdbpost –R –C000-005 ttadv* < dumpCreates/appends tables only in the given customer range and where table namematches the pattern ttadv. If duplicate records exist, they are replaced by recordsfrom the dump.

bdbpre –dsybase –Nttadv099 –C000-999 | bdbpost –doracleConverting from one database organization to another (From Sybase to Oracleorganization).

bdbpost –doracle –Dunify –t"|"Loading from other databases (UNIFY to Oracle)

bdbpost –Doracle –x –dsybase(Oracle to Sybase)

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

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

SEE ALSO

bdbpre

bdbreconfigNAME

bdbreconfig

Reconfigure database table according to new data dictionary.

SYNOPSIS

bdbreconfig [–uUvVpscinmfTZ][–t dir][–o file][–e file][–d driver type][–N table [table [..]] [–I file][–O file][–E file][–S number][–C companynumbers]

CAUTION

Database tools

Technical Manual

3-11

DESCRIPTION

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

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

After successful completion, old tables are deleted and new tables are generated.

The bdbreconfig tool finds the optimum way to reconfigure. If there is no realchange in the old and new data dictionaries, it prints the message “No conversionrequired.” 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 new data dictionaries.

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

3 Delete old tables.

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

The following options are available with bdbreconfig:

–U/uUsage information.

–V/vVersion information.

–pThe name of the used package combination.

–p <pack. comb.>Define the package combination.

–sThis suppresses error messages and other information.

–CCompany numbers for a given table in these formats:

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

Database tools

Technical Manual

3-12



–TIf the domain changes, the table is not reconfigured.

–BBackup table instead of dropping.

–ZReorganize, that is, clean up, the table.

–IThe file with table names.

–iIgnore errors during reconfiguration, for example, duplicates.

–nIgnore referential integrity constraints.

–mDisable domain constraints.

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

–NList of tables to be reconfigured.

–cThis compares two data dictionaries and checks whether reconfiguration isrequired.

–tThe directory name for temporary dump files.

–IFile with table names to reconfigure.

–oFile with successfully reconfigured tables.

–eFile with unsuccessfully reconfigured tables.

Database tools

Technical Manual

3-13

–O fileRedirects output to output file file.

–E fileRedirects errors to error file file.

–S numbernumber is the maximum size per sequence. number can be specified as anynumber or a number followed by K for kilobytes, M for megabytes, and G forgigabytes. The default size is 2G per dump sequence.

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

bdbreconfig –Ntimcs016 –C001Reconfigures timcs016 for company no. 001.

bdbreconfig –Ntimcs016 –C000-010Reconfigures 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 at the –o option contains tables that can bereconfigured, and the file at the –e option contains the tables that cannot bereconfigured.

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

Make a copy of the dump before executing the following.

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

bdbreconfig –N ttadv100222+

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

bdbreconfig –dsybase –Ntimcs016 –C000Reconfigures Sybase table timcs016000.

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

EXAMPLE

CAUTION

EXAMPLE

Database tools

Technical Manual

3-14

refintNAME

refint

Check or repair the referential integrity within the database.

SYNOPSIS

refint [–uU][-vV][-b|-B file][-a |-A file][-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 alsouse it to repair the integrity of a corrupted database. Integrity refers to theaccuracy or validity of data.

The environment variable KEY_BUFFER specifies the number of keys stored ina buffer before updating the database. Default KEY_BUFFER=10000.

You can use the following options:


–v/VPrint version information.

–pDefine package combination.

–CSpecify company numbers.

–b/BList references before repair (-b output file is ref_before).

–a/AList references after repair (-a output file is ref_after).

–cCheck validity of references.

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

Database tools

Technical Manual

3-15

–rRepair reference counter, from all specified tables the reference counters arechecked and changed if necessary. Undefined references to the specified tablesare displayed on the screen.

–l/LFile for undefined references. (-l file is ref_undefined).

–IFile containing table names to be checked.

–N <table>Specify table (format: ttadv100 or ttadv100999).

–sHandle one single-parent table only.

refint –Iref_tables –c –n –C100

refint –Ntimcs016 –l

EXAMPLES

Database tools

Technical Manual

3-16

Technical Manual

4-1

GeneralDatabase servers and user interface servers perform processes different fromthose performed by the client, the Bshell. They communicate with the Bshellusing a communication protocol. This section discusses the working and usage ofseveral protocols that can be used for local and remote communication.

Local communication means that server and client are started on the same hostmachine. Remote communication means that server and client are on differentmachines.

Accessing tablesTables can be distributed as follows:

n Local: the tables and the Bshell are on one systemn Remote: the Bshell is on one system; all the tables are on another systemn 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 typeand the location of the table. This information has been stored in the followingfiles:

n tabledef6.2n fd6.2.package combination

tabledef6.2

Table references that refer to a database type are stored in the file tabledef6.2.This file is located in the directory $BSE/lib. To fill this file, use the Tables byDatabase (ttaad4111m000) and Database Definitions (ttaad4510m000) sessionson the BaanERP ToolsÈDatabase ManagementÈDatabase Definitions andDirectories. If the tables are on a different system, you specify the host name ofthe remote system instead of entering the database type. The Bshell knows whichdatabase server must be started and in which database the required tables can befound.

4 Database management

Database management

Technical Manual

4-2

fd6.2.package combination

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

n Formsn Menusn Objectsn Program scriptsn Functionsn Report scripts

The file fd6.2.package combination is located in the directory $BSE/lib. To fillthis file, use the Directories of Software Components (ttadv1115m000) session inthe BaanERP ToolsÈ Application CustomizationÈ Packages and Modulesmenu. The specific directory path of the table definitions must be entered in thePackage Combinations (ttaad1520m000) session and is also placed in thefd6.2.package combination file. You can access this session through theBaanERP ToolsÈ Application DevelopmentÈ Packages and Modules menu.

Example table access (table and Bshell on the samesystem)

This example roughly explains how the Bshell accesses a table if they are on thesame system.

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

*:001:oracle7(ORACLE_HOME=/a1/oracle/product/7.3.3,ORACLE_SID=baan5):N

First, Bshell reads tabledef6.2, searches for the reference and in this case startsthe Oracle server. A connection between Bshell and server is made. Then theserver accesses the table and the database action is carried out.

Database drivers

When an action is carried out on a table, a database driver (server) is started inthe background for the database type in question.

Database management

Technical Manual

4-3

Accessing tables on other systems

When the database is on a different machine, the communication takes place asdescribed in the following example.

Suppose that in a Bshell program running on the system host_local, you want toread a record from the table ttmod000111 (table ttmod000 in company 111). Thistable is stored on the remote system, whose host name is host1. First, the Bshellsearches tabledef6.2 on the system host_local for the table in question. The filecontains the following reference:

ttmod:111:host1

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

ttmod:111:oracle

This implies that the desired tables are stored in the Oracle database. The oracleserver is then started. The desired table is searched and accessed usingtabledef6.2 on the system host1. The record is read and its data is sent to theBshell program on the system host_local.

Audit trail

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

Database mirroring

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

tccom:*:oracle&host2.

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

Database management

Technical Manual

4-4

The tables from the previous example are copies. A change applied to a tablefrom tccom is carried through in the Oracle database on the local system and onthe remote system host2. Also, a change to the tccom tables on the remote systemmust be carried through in the database on the local system. This means thattabledef6.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. Thisfile contains a reference to both the tables from tccom and to the systems wherecopies of the tccom tables are stored.

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

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

Figure 3, Database mirroring

In this example, a change applied to a table in tccom is carried through in boththe Sybase database on the local system and in the Oracle database on the remotesystem. A table is read, without a lock, from the Sybase database.

Database management

Technical Manual

4-5

Alternative databases

The file tabledef6.2 contains references to the database where the tables aresaved and/or read. For each reference you can specify an alternative databasedriver 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 thatoperation fails, the table is searched or stored in a local Oracle database. If thisalso fails, the table cannot be accessed.

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

*:*:oracle&host1|host2

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

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

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

n Sockets (local or remote)n Pipesn Message queues

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

For the communication between client and servers, the following files and/ordirectories are needed:

n ipc_info (in the $BSE/lib directory)

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

Database management

Technical Manual

4-6

The ipc_info file contains the following data:

n Server namen Operation moden Semaphore keyn Message keyn Protocoln Path of the server program

The server name is the name of the server, which can be used in other files, forexample in tabledef6.2 for database servers. Only the single mode can be used asoperation mode, because the multimode is not yet implemented. In single mode,one server can communicate with one client. The client can communicate withmore than one server, however, as shown in the following figure.

Figure 4, Single operation mode

The semaphore key and message key have not been implemented either.

You can choose from the following protocols:

n Socket (s)n Message queue (m)n Pipes (p)

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

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

Database management

Technical Manual

4-7

Socket protocol

A socket is a UNIX function that enables processes to communicate in bothdirections. The socket protocol is subdivided into local and remote sockets. Localsockets are used for local communication; remote sockets for remotecommunication. 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 filerefers to a certain server, the client reads data about that server from the fileipc_info. The file ipc_info contains data such as the protocol to be used and theposition of the executable server. Next, the client uses a socket to start the serverand establish communication with the server.

Remote sockets (only for database servers)

Suppose that the client on host A wants to open a table on host B as in thefollowing figure.

Figure 5, Remote socket protocol

Suppose that the client on host A wants to open a table on host B.

This is done through sockets. The client reads tabledef6.2 on host A, whichindicates that the table is on host B. The client logs on to host B using thepassword found in the file r<user’s name> in the $BSE/lib/user directory.

Database management

Technical Manual

4-8

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 $BSEdirectory.

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

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

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

Communication then proceeds normally between client and Oracle driver.

Pipes protocol

The pipes protocol is analogous to the local socket protocol. In pipes protocol,the client and server communicate through unnamed pipes streams. A pipe is aUNIX function that enables processes to communicate in one direction. Thecommunication 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 thisprotocol the client starts the server. The client and server communicate through amessage queue using a semaphore key. This key indicates whether a messagequeue contains information, so that the client or server knows that informationhas been sent. See the following figure.

Figure 6, Message queue protocol

Database management

Technical Manual

4-9

For example, suppose the client wants to send information to the server. Thisinformation or message is put in a message queue, and the semaphore key isgiven the value of 1. The semaphore key shows the server that information hasbeen sent, so that the server can read it. After the server reads it, the semaphoreflag 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 serverreads the message queue and finds no message. Thus, the server knows that theclient process has been terminated and stops its own process.

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

Technical Manual

4-10

Technical Manual

5-1

GeneralNative Language Support controls the communication between the character setof a terminal and that of Bshell6.2.

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

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

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

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

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

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

5 Native language support

Native language support

Technical Manual

5-2

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

Conversion tablesYou need two kinds of conversion to make the character sets of Bshell and theterminal or printer compatible: input conversion and output conversion.

Input conversion table

The input conversion table converts the entered characters to their correspondingvalues in the ISO 8859-1 character set. Composed characters and characters thatare 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, describedin the section “NLS editor.” An example of an input conversion table is given inthe section “Input/output table vt200.”

Output conversion table

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

n Terminal output tablen Printer output table

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

To record and/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 tablevt200” and the section “Printer output table MT910 HP Prestige character set.”


Technical Manual

5-3

Example of total conversionTerminal type: vt200 with North American keyboardPrinter type: Mannesmann mt910Required character: ÿ = ISO8859-1 code 255 = DEC vt200 code 253

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

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

\255 y"

The result of the input conversion is that the keyboard input Compose[y]["] isstored as ISO character y on disk or Bshell memory.

To display the entered (required) character on your screen, ISO code255 must beconverted to DEC code 253. Therefore the terminal output conversion table mustcontain the following line:

\255 \253

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

\255 y\b\168

This means that character ÿ is printed as:

[y] <Backspace>["]

y \b \168


Technical Manual

5-4

This example is shown in the following figure.

Figure 7, Example NLS conversion

NLS editorUse the NLS editor to maintain input and output conversion tables. To start theeditor, type nlsedit6.2. To maintain printer output tables, use the –p optionfollowed by the printer name. To maintain a terminal conversion table, the shellvariable 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 theright 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 bebecause it is not found in the character set of the terminal.

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


Technical Manual

5-5

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 thecharacter 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 upperpart (160-255) of the ISO character set. With the -S option you can switchbetween 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 appearsshows also 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 andoutput conversion tables. Five columns are displayed as illustrated in thefollowing 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 ISOcharacter set.

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

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


Technical Manual

5-6

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

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

The bottom of the screen shows the display mode in which the values of thecharacters are displayed. The last line indicates the marked character. Thenumeric 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 thecharacter values into decimal, hexadecimal, or octal.

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

To move the bar to the following or previous line, use the key ARROW DOWN orARROW 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 topress the required key. That character is included directly in the table. You do notneed to press ENTER after you have entered the character.

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


Technical Manual

5-7

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 filesTo work with NLS you must have the following files in your BSE environment:

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

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

Terminal information file

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

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

nls_in=<terminal type>.innls_out=<terminal type>.out,

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

nls_in=vt200.innls_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. Forexample, suppose you want to define the compose key as ESC+C. Add thefollowing line to the terminal information file:

kcompose=\ec,


Technical Manual

5-8

Printer information file

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

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

nls_out=<printer type>.out,

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

nls_out=mt910.out,

Input and output conversion table

The input and output conversion tables are stored in directory $BSE/lib/nlsinf.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 eachprinter 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:

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

A list of control and escape codes is given in the Overview of Esc/Ctrl codes.”The first column contains the numeric representation of the ISO 8859-1 characterset.

In an input table, the second column contains the compose sequence of the inputcharacters. In an output table, the second column contains the numericrepresentation of the output characters. The columns are separated by spaces ortabs.


Technical Manual

5-9

Examples of conversion tables are given in the section “Input/output tablevt200.”

Terminal setup

The communication mode of the terminal must be 8-bit no parity. The shellvariable TERM must have the name of the terminal information file of theterminal.

Character sets and fonts

Line drawing characters do not need to be included in the character set. Thesecharacters are drawn by the Bshell itself. To check the suitability of charactersets, type the following command:

xfontsel –pattern –*-*-iso8859-1

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

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 thisprogram.

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 canuse 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 environment variableSORT_TABLE with the name of your own sorting file. A sort table has twocolumns. The first one contains the character, the second contains the weight ofthat character.


Technical Manual

5-10

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

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

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

Shift tables

Shift tables can be used to specify lowercase and uppercase characters thatbelong 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 environment variableSH_TABLE with the name of the file with your own shift table. A shift table hastwo columns. The first one contains the uppercase character, the second containsthe lowercase character.

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

\199 \231


Technical Manual

5-11

ISO 8859-1 character set (0-127)

0 16 32SP

480

64@

80P

96‘

112p

1 17 33!

491

65A

81Q

97a

113q

2 18 34“

502

66B

82R

98b

114r

3 19 35#

513

67C

83S

99c

115s

4 20 36$

524

68D

84T

100d

116t

5 21 37%

535

69E

85U

101e

117u

6 22 38&

546

70F

86V

102f

118v

7 23 39‘

557

71G

87W

103g

119w

8 24 40(

568

72H

88X

104h

120x

9 25 41)

579

73I

89Y

105I

121y

10 26 42*

58:

74J

90Z

106j

122z

11 27 43+

59;

75K

91[

107k

123{

12 28 44‘

60<

76L

92\

108l

124|

13 29 45-

61=

77M

93]

109m

125}

14 30 46.

62>

78N

94^

110n

126-

15 31 47/

63?

79O

95_

111o

127


Technical Manual

5-12

128 144 160NBSP

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 173SHY

189½

205Í

221Ý

237í

253ý

142 158 174®

190¾

206Î

222Þ

238î

254þ

143 159 175|

191¿

207Ï

223ß

239ï

255ÿ


Technical Manual

5-13

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

NUL

0

16DLE

10

32SP

20

480

30

64@

40

80P

50

96‘

60

112p

70

1SOH

1

17DC1

11

33!

21

491

31

65A

41

81Q

51

97a

61

113q

71

2STX

2

18DC2

12

34“

22

502

32

66B

42

82R

42

98b

62

114r

72

3ETX

3

19DC3

13

35#

23

513

33

67C

43

83S

53

99c

63

115s

73

4EOT

4

20DC4

14

36$

24

524

34

68D

44

84T

54

100d

64

116t

74

5ENQ

5

21NAK

15

37%

25

535

35

69E

45

85U

55

101e

65

117u

75

6ACK

6

22SYN

16

38&

26

546

36

70F

46

86V

56

102f

66

118v

76

7BEL

7

23ETB

17

39‘

27

557

37

71G

47

87W

57

103g

67

119w

77

8BS

8

24CAN

18

40(

28

568

38

72H

48

88X

58

104h

68

120x

78

9HT

9

25EM

19

41)

29

579

39

73I

49

89Y

59

105I

69

121y

79

10LF

A

26SUB

1A

42*

2A

58:

3A

74J

4A

90Z

5A

106j

6A

122z

7A

11VT

B

27ESC

1B

43+

2B

59;

3B

75K

4B

91[

5B

107k

6B

123{

7B


Technical Manual

5-14

12FF

C

28FS

1C

44‘

2C

60<

3C

76L

4C

92\

5C

108l

6C

124|

7C

13CR

D

29GS

1D

45–

2D

61=

3D

77M

4D

93]

5D

109m

6D

125}

7D

14SO

E

30RS

1E

46.

2E

62>

3E

78N

4E

94^

5E

110n

6E

126–

7E

15SI

F

31US

1F

47/

2F

63?

3F

79O

4F

95_

5F

111o

6F

127DEL

7F


Technical Manual

5-15

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

80

144DCS

90

160

A0

176°

B0

192À

C0

208

D0

224à

E0

240

F0

129

81

145PU1

91

161¡

A1

177±

B1

193Á

C1

209Ñ

D1

225á

E1

241ñ

F1

130

82

146PU2

92

162¢

A2

178²

B2

194Â

C2

210Ò

D2

226â

E2

242ò

F2

131

83

147STS

93

163£

A3

179³

B3

195Ã

C3

211Ó

D3

227ã

E3

243ó

F3

132

84

148CCH

94

164

A4

180

B4

196Ä

C4

212Ô

D4

228ä

E4

244ô

F4

133

85

149MW

95

165¥

A5

181µ

B5

197Å

C5

213Õ

D5

229å

E5

245õ

F5

134

86

150SPA

96

166

A6

182¶

B6

198Æ

C6

214Ö

D6

230

E6

246ö

F6

135 151EPA

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 155CSI

9B

171«

AB

187»

BB

203Ë

CB

219Û

DB

235ë

EB

251û

FB


Technical Manual

5-16

140 156

9C

172

AC

188¼

BC

204Ì

CC

220Ü

DC

236ì

EC

252ü

FC

141 157OSC

9D

173

AD

189½

BD

205Í

CD

221Ý

DD

237í

ED

253ý

FD

142 158PM

9E

174

AE

190

BE

206Î

CE

222

DE

238î

EE

254

FE

143 159APC

9F

175

AF

191¿

BF

207Ï

CF

223ß

DF

239ï

EF

255

FF


Technical Manual

5-17

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


Technical Manual

5-18


¶ 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/


Technical Manual

5-19


Þ 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'


Technical Manual

5-20


û 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 ’’


Technical Manual

5-21

\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"


Technical Manual

5-22

\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\^


Technical Manual

5-23

\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"


Technical Manual

5-24

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


Technical Manual

5-25

Printer output table MT910 HP Prestigecharacter 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 ,


Technical Manual

5-26

\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


Technical Manual

5-27

\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


Technical Manual

5-28

\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


Technical Manual

5-29

Overview of Esc/Ctrl codes

ASCIImnemonic

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


Technical Manual

5-30

Technical Manual

6-1

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

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

To create a new terminal information file, create a subdirectory in the terminfdirectory whose name is the first letter of the future terminal information file.The terminal information file is stored in that subdirectory. For example, theterminal 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:

n Boolean entriesn Numbersn Strings

Each entry is closed by a comma (,). Comment text can be added, preceded by anumber sign (#). You can include another terminal information file at anyposition 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 trueby including it in the terminal information file. It is set to false either by notincluding 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_dualIndicates that output to the aux port also appears on the terminal screen. Theterminal screen is disabled during aux printing.

color_cfProvides color control in combination with code features.

6 Information files

Information files

Technical Manual

6-2

color_sepColors and code features are controlled separately.

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

mgrYou can move the cursor when the program is in graphics mode.

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

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

xhpCode features and graphic characters are not removed when they are overwrittenby 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 defaultvalue 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 isset 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. Themaximum value depends on the terminal type.

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

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

Information files

Technical Manual

6-3

tmo=Timeout sequence after pressing ESC. The given number divided by 10 specifiesthe time (in seconds) in which a sequence can be typed in after ESC. If nocharacter 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 toperform particular terminal operations.

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

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

You can also use an octal value instead of an alphabetical representation. Forexample, “escape” becomes \033. The control codes are converted to the ASCIIcodes 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.

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

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

Information files

Technical Manual

6-4

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

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

cf_b=Code feature, blinking.

cf_br=Code feature, blinking, and reverse.

cf_bru=Code feature, blinking, reverse, 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 reverse.

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

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

cf_Br=Code feature, bold, and reverse.

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

cf_Bu=Code feature, bold, and underlined.

cf_n=Code feature, normal.

cf_r=Code feature, reverse.

Information files

Technical Manual

6-5

cf_ru=Code feature, reverse, 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 parameterindicates the start line. The second parameter indicates the end line of thescrolling region. See also the section “Parameterized strings.”

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

ctr=Character used in graphics mode to display the upper right corner (+). If it is notavailable, a viable alternative is +. Do not leave the variable empty, because thiscan 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=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.

Information files

Technical Manual

6-6

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 resultin 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.

gr_onB=Turns bold graphics mode on.

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

Information files

Technical Manual

6-7

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 doneafter the initialization string in init and before the string in init2. Within the fileyou can, for example, specify a large number of codes that do not fit in a stringof 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 duringinitialization of the terminal, after the string init and the codes in the filespecified at entry if.

inli=Insert one line.

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

ladr=Absolute line positioning string. See the UNIX manual TERMINFO(4) and thesection “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, aviable alternative is +. Do not leave the variable empty, because this can result inscreen layout problems.

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

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

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

Information files

Technical Manual

6-8

reset=Reset initialization string. The terminal is set up in such a way that it can be usedin UNIX or other programs. The string is sent after the Bshell terminatesexecution.

rt=Character used in graphics mode to display the right T-bar. If it is not available, aviable alternative is +. Do not leave the variable empty, because this can result inscreen 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 resultin 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 thiscan result in screen layout problems.

The following dim code features are used in graphics mode if the normal codefeatures 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.

Information files

Technical Manual

6-9

utB=. See ut, but bold.

vbB=. See vb, but bold.

Keys

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

If you want to use a special key in the Bshell, you have to specify this key in theterminal information file. If the key is present on the keyboard, you must assignthe corresponding sequence to it. If the key is not present, you can assign anothersequence.

For several key entries, a default value is given along with the ASCII code anddecimal 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.

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, switchesfunction 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).

Information files

Technical Manual

6-10

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)

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.

Information files

Technical Manual

6-11

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):

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

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) isidentified by code 1024. You can use the macro KEY_F(1) in your program tocheck if the defined sequence for the F1 function key is given.

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

Color supportColors 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 terminalinformation file with the Boolean values color_cf and color_sep.

color_cfThe code feature can be sent together with the color codes in one single escapesequence.

color_sepThe color codes cannot be combined with the code features.

Sending colors separately

You can use the following string entries in the terminal information files to setthe foreground and background color:

bg_black=

bg_red=

bg_green=

Information files

Technical Manual

6-12

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=

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

Information files

Technical Manual

6-13

fg_white=\e[37m,

Colors in combination with code features

The following numbers are used as %p1 and %p2 parameters in combined codefeature and color strings (color_cf).

black=0

red=1

green=2

yellow=3

blue=4

magenta=5

cyan=6

white=7

The colors can be sent to the terminal along with code features with thefollowing string entries. The foreground and background color must be specifiedas 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

Information files

Technical Manual

6-14

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 isbackground color; p2=0-7. See the section, “Colors in combination with codefeatures.” For use of parameters within a string entry, see the section“Parameterized strings.”

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

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

Information files

Technical Manual

6-15

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. Dependent 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 mustuse %gx%{5}%-

%i\e[%p1%d;p2%drThis example is used for changing the scrolling region on C.Itoh terminals. Thefirst parameter +1 specifies the start row, the second parameter +1 specifies theend row of the region. Both are used as numerics in the escape sequence.

EXAMPLES

Information files

Technical Manual

6-16

\e[0;22;%p1%{30}%+%d;%p2%{40}%+%dmThe sequence in this example is used for setting a color and code feature. Thecode 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 filesThis section contains examples of terminal information files for some terminaltypes. Examples are given of include files, color usage, function keys, settingfonts, and so on.

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

#*******************************************************# @(#)# @(#) 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

Technical Manual

6-17

#*****************************# Booleans#*****************************vt100#nclrwcmcfmgr,#*****************************# Numbers#*****************************cols=132lines=24cf_pos=0gr_pos=0tmo=5disp_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[?25linit2=\e(BÔ\e-Areset=\e[0m\e[0;0H\e[2J\e(BÔ\e-A,set80=\e[?3lset132=\e[?3h,bell=^Gtmo=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

Technical Manual

6-18

gr_off=\e(B^Ogr_offd=\e(B^O\e[0m,cbl=mcbld=mcbr=jcbrd=jctl=lctld=lctr=kctrd=kdt=vdtd=vut=wutd=wlt=tltd=trt=urtd=ukr=nkrd=nhb=qhbd=qvb=xvbd=x,# Code Features#cf_n=\e[0mcf_d=\e[0;1mcf_b=\e[0;5mcf_db=\e[0;1;5mcf_r=\e[0;7mcf_dr=\e[0;1;7mcf_br=\e[0;5;7mcf_dbr=\e[0;1;5;7mcf_u=\e[0;4mcf_du=\e[0;1;4mcf_bu=\e[0;4;5mcf_dbu=\e[0;1;4;5mcf_ru=\e[0;4;7mcf_dru=\e[0;1;4;7mcf_bru=\e[0;4;5;7mcf_dbru=\e[0;1;4;5;7m,# Cursor Control & Positioning#cu_on=\e[?25hcu_off=\e[?25l

Information files

Technical Manual

6-19

cup=%i\e[%p1%d;%p2%dH,cuu=\e[%p1%dAcuu1=\e[1Acud=\e[%p1%dBcud1=\e[1Bcuf=\e[%p1%dCcuf1=\e[1Ccub=\e[%p1%dDcub1=\e[1D,home=\e[0;0Hclear=\e[0;0H\e[2J\e[?25l,# Editing#inch=\e[@delch=\e[Pinli=\e[Ldelli=\e[Mel=\e[0Kes=\e[0J#ewin=,# Printer Control#aux_on=\e[5iaux_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

Technical Manual

6-20

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=\eOPpf2=\eOQpf3=\eORpf4=\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[Akd=\e[Bkf=\e[Ckl=\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

Technical Manual

6-21

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

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

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

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 filewith 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 variablesare marked with *.

A variable definition consists of a name, a =, an escape sequence (containingspecial 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 thesefunctions by backspace and carriage return. The positions are then covered twice.You switch this simulation off by entering the value \000 for the definition ofbold on/off or underline on/off, or by entering no value (for example pbold=,).

Information files

Technical Manual

6-22

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

Escape codes Control codes

\b backspace ^A to ^Z

\E or \e escape ^[

\f form feed ^\

\n newline ^]

\r carriage return ^^

\t tab ^_

\s space

\xx decimal value xx=1-255

\0xx octal value xx=1-377

\xxx hexadecimal value xx=1-FF (for example \x1F)

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

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

A printer information file can have the following Boolean entries:

n rsf_pbold, reset font after pboldn rsf_prev, reset font after prevn rsf_punder, reset font after pundern rsf_pobold, reset font after poboldn rsf_porev, reset font after porevn 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

Technical Manual

6-23

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 befilled with the codes for large typeface.

initprog=XThe 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 changethetypeface size.

nls_out=NLS output table name.

middle=Medium typeface (12cpi) control. Some printers require a code to change thetypeface 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 (withASCII code over 127 decimal) yields additional line feeds on most Mannesmannprinters. If this variable is not used, the Bshell simulates boldface printing byreprinting each line, making use of the carriage return character.

Information files

Technical Manual

6-24

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

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

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

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

pdbl_wide=Double wide mode on.

pdt=Print –. If this variable cannot be filled because the printer cannot print it, forexample, 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, forexample, a – is used.

pitalic=Italic mode on.

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

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

pnlq=NLQ mode on.

pobold=Switch off boldface printing without affecting character size.

podbl_wide=Double wide mode off.

Information files

Technical Manual

6-25

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 cannotprint it, a + is used.

psubscript=Subscript mode on.

psuperscript=Superscript mode on.

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

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

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

Information files

Technical Manual

6-26

q1=, to q13=These 13 variables can be filled with strings that specify whether a charactermust 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 futurerelease.

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

resetprog=XThe 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 changetypeface 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 andreturns to the saved cursor position. These scripts must be available in thedirectory barcode_dir. This directory is relative to $BSE/lib/barcode, so ifbarcode_dir = hp_barcode, the bar-code directory is$BSE/lib/barcode/hp_barcode. Bar-code scripts are prefixed by the word “type”and post fixed by a two-digit number. For example:

type01.

Information files

Technical Manual

6-27

Following is an example of such a bar-code script. It saves the cursor positionand restores it after the bar code has been printed. Bar codes can only beimplemented 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=`echo $code | awk '{ print substr($1, 1, 5) }'`

str2=`echo $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

Technical Manual

6-28

height=`expr $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

Technical Manual

6-29

Example of printer information file for mt910printerThis shows what a printer information file can consist of. You can add commentsin 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,

Information files

Technical Manual

6-30

Technical Manual

7-1

This chapter describes the User Interface (UI) Page mode in BaanERP. The UIPage mode improves the response times on networks where informationprocessing can be delayed, for example, a wide area network (WAN).

In normal mode, the 4GL Engine validates the entered data per field. In the UIPage mode, the 4GL Engine validates data per page, and not per field. Thesynchronous interaction between the UI driver and the Bshell is thereforesignificantly reduced.

The UI Page mode is designed for experienced BaanERP users, because theinteraction between BaanERP and the user is not as extensive as in the normalmode.

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

In the UI Page mode, the UI driver groups together a number of UI objects thatform 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 tabin 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 pageassociated with the related tab. In any other case, the UI object is part of the pageassociated with the overview window.

The following functions are implemented in the UI Page mode to improvenetwork performance:

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

n The UI client handles the behavior of the default button for the commandbuttons on a page.

7 User Interface (UI) Page mode

User Interface (UI) Page mode

Technical Manual

7-2

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

Tab processingWhen the UI page mode is selected, the UI driver processes Tab key movementsin the details window. The Tab key sequence is identical to the creation order ofthe 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 handlingWhen the UI Page mode is selected, the UI driver handles the default commandbutton. This is the command button that is highlighted when the dialog box isinitially displayed. It can also be the command button with the bold border,indicating that it is automatically selected if you press Enter.

Event processingIf the UI Page mode is selected, events are treated differently by the UI driverthan when normal mode is selected. There are four different event categories:

n Suppressed eventsn Delayed eventsn Synchronization eventsn Bypass events

Suppressed eventsIf the UI Page mode is selected, a UI object does not send suppressed events tothe Bshell . Instead, suppressed events are handled locally by the UI driver on theclient. An example of a suppressed event is moving from an active element toanother active element.

Delayed eventsStatus changes of UI objects can be delayed. As soon as a synchronization eventoccurs, for example, by using the Validate button, the changed UI objects arerequested to synchronize their status with the 4GL engine. The delayed eventsare 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, thedelayed events are sent into one network frame, to reduce response times.


Technical Manual

7-3

Synchronization eventsThe synchronization events make sure that the statuses of the changed UI objectsare sent to the Bshell for validation.

Synchronization events are:

n Selecting a menu itemn Clicking a button on a toolbar, or a pushbuttonn Moving to another tabn Moving from a synchronizing field to another fieldn Starting a browse sessionn Pressing a key that is not handled by the UI clientn Resizing a windown Using the scroll bar

Bypass eventsThe following bypass events are sent immediately to the Bshell without firstbeing synchronized with the delayed events:

n Using the online Helpn Closing a Windows application that was started through the application Start

feature of the UI clientn Using OLE objects

How to select the UI Page modeThe UI Page mode is selected per user to make sure that inexperienced BaanERPusers cannot use it. You must define the UI Page mode in the user profile of theuser. The user profile is defined in the User Management module in BaanERPTools. 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 theUser Data Template (ttams1110m000) session in the AuthorizationManagement System (AMS) module. Be sure to select the Use Page modecheck box under Options on the System Data tab.

2 Start the User Data (ttaad2500m000) session in the User Managementmodule. Double-click the user for which you want to select the UI Page modeto start the details session.

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

4 Click on the Specific menu Convert Changes to Runtime DD to rebuild theuser profile in the runtime database.


Technical Manual

7-4

5 Restart BaanERP to activate the changed user profile.

Check that the following are true to verify that the UI Page mode has beensuccessfully selected:

n All the fields and options in the overview windows and detail windows areavailable

n All commands on the menus of the menu bar in an overview window areavailable

n On the Window menu the Validate command is available in an overviewwindow

n The Validate button shows on a details window

How to mark UI objects as synchronizingfieldsYou can mark UI objects on an overview window or details window assynchronizing fields. This means that when you move from one active field orbutton to another field or button, all delayed events are sent to the Bshell forvalidation. You can mark the following fields and buttons as synchronizingfields:

n Edit fieldsn Check boxesn Option buttonsn List boxesn Combo boxes

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

1 On the BAANERP Tools menu, click Application Development, and thenclick Forms to start the Forms (ttadv3500m000) session.

2 Select a form. On the Specific menu click Check Out to release the form formodification.

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

Depending on the form type, the appropriate Form Editor starts. The followingform editors are available in BaanERP:

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


Technical Manual

7-5

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

Static Forms1 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, click Check In to finish the procedure.

Dynamic Forms1 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, click Check In to finish the procedure.


Technical Manual

7-6

Technical Manual

8-1

GeneralThis chapter describes two aspects essential to solving errors in a Bshellenvironment: error logging and the bserel6.2 program. Error logging is keeping arecord of error messages in a log file. The log file contains information aboutwhen the error occurred and which processes were then active. See the section“Error logging.”

The program bserel6.2 provides information on the BSE environment as installedon your system. Among other things, bserel6.2 checks permissions, theavailability of programs, and the correctness of program objects. This data can becollected in a report and viewed on screen, printed, or sent to a file.

If you want to submit an error to the Customer Support Center of Baan InfoSystems, add both the error logging report and the bselrel6.2 report to your errorreport.

Error loggingCertain actions in a Bshell program can result in an error. Usually an error isdisplayed and from it you can see what went wrong.

To localize Bshell 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 the errors are written to are stored in directory $BSE/log. Its nameformat is:

log.<program name>

This means that when an error occurs in Bshell6.2, it is logged in the filelog.Bshell6.2. If it occurs in bx6.2, it is logged in log.bx6.2, and so on.

8 Customer support tools

Customer support tools

Technical Manual

8-2

Log file layout

The header of the log file is: "START of log message", followed by:

n Date, time, logon name, and TTY numbern Source program name with line numbern Keywordn UNIX process, user, and group identifiers for programn User type, language code, logon code and TTY number of the usern error number and bdb error numbern error message as displayed on screen

If, for instance, you end a Bshell program with an Interrupt (CTRL+\), this actionis written as an error in the log file. The message keyword is “core dump.” Thelog file also contains the following blocks:

n Process Listn Screen Dumpn Process Information

The Process List block is a list of the active Bshell processes at the moment theerror occurred. This list contains the following information for each Bshellprocess:

n Process identifiern Parentn Statusn cpu.flagsn Process namen Line number (debug mode only)


Technical Manual

8-3

The Screen dump block contains the screen active at the moment the erroroccurred. The last block, Process Information, contains the individual processinformation about each process from the list. It can consist of:

n The line from the process list for the process involvedn Session code, process ID, and parent numbern Objectn Main tablen Zoom fieldn Return zoom fieldn Default printern Formsn Reportsn Tablesn Variables, including values in force when the error occurred (empty strings,

strings with value 0, and strings consisting of tabs are not logged). Thesection “Example error logging” contains an example of error logging

Log file maintenanceIf the log file is not regularly purged it grows enormously, which affects yourstorage capacity. Also, a large log file is difficult to read. You are thereforeadvised to rename the log file to log.save on a weekly basis, using the UNIX mvcommand. After a backup has been made of the system including log.save, youcan remove it from the system. The backup tape should be kept for two weeks.

Submitting errors to customer support

If you are confronted with a Bshell error message for which you have nosolution, you can contact the Customer Support Center (formerly known asResponse Center). To your report you add the part of the log file relating 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 containstwo error reports. Suppose you want to print the first one. You can do this usinggrep in four ways: by date, time, user name, or TTY number. The followingexample shows the command lines for each of these:

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


Technical Manual

8-4

Example error loggingEach line of the following output starts with date, time, logon name, and TTYnumber, 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: #241keyword: sopen98-03-04[15:06:55]etimban: Pid 19313 Uid 10575 Euid 10575 Gid 1700 Egid 170098-03-04[15:06:55]etimban: user_type S language 2 user_name etimban TTY ote localeISO88591/NULL98-03-04[15:06:55]etimban: Errno 2 (No such file or directory) bdb_errno 098-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

Technical Manual

9-1

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

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

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

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

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

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

dpt6.2Test program of database actions. Program for internal use, not for the end user.

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

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

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

9 Executable programs

Executable programs

Technical Manual

9-2

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

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

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

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

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

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

Sybasesyb_install6.2The program used to install the Sybase driver.

syb_srv6.2This is the Sybase driver itself.

syb_admin6.2The shell script for doing administration.

syb_maint6.2The Sybase version of the program used to maintain the database.

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

inf_srv6.2This is the Informix driver itself.

inf_admin6.2The shell script for doing administration.

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

Executable programs

Technical Manual

9-3

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

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

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

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

Logic server (Bshell)

Bshell6.2

This is a virtual processor between the user interface, database drivers,applications, and operating system. This program makes applications, includingBaanERP Tools, independent of the operating system. The Bshell functions as ashell between the application and the operating system.

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

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

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

n When running on a remote host fill the r user> file as described in thechapter “Remote databases”.

n You can specify where the application logic server is located in the User DataTemplate (ttams1110m000) session on the Authorization ManagementSystemÈ Definition of TemplatesÈ Miscellaneous menu. You must thenconnect the template to the user using the User Data (ttaad2500m000) sessionon the BaanERP ToolsÈ Database Management menu.

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

Executable programs

Technical Manual

9-4

SYNOPSIS

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

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

n Debugging the Bshell during run time− Baan CPU− Scheduler− File I/O− Miscellaneous− Message and log extract

n Memory usagen Miscellaneous

The al_1 function parse_arguments recognizes the following options by default:

-- : end of parameter list-set var=val : set environment variable var to val

To pass options to the Bshell, enter them in the command line of the BWConfigurator, for example:

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

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

Debugging the Bshell during run time

To debug the Bshell while the BaanERP application is running, display theOption Dialog dialog box, which appears as an icon while you runningBaanERP, and click Debug Bshell. The Runtime debugging of Bshell dialogbox displays. You can also choose these options from the command line.

Baan CPU

Debug functionsIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Debug Functions. Or, from the command line, run –dbgfun.

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

Executable programs

Technical Manual

9-5

Show Bshell CPU instructionsIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Debug Instructions. Or, from the command line, run –dbginstr.

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

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

Show program flowIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Program Flow. Or, from the command line, run –dbgflow.

Scheduler

Debug schedulerIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Debug Scheduler. Or, from the command line, run –dbgsched.

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

File I/O

Show all files that are currently opened by the BshellIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Show opened files. Or, from the command line, run –dbgfile.

Debug file accessIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Debug file access. Or, from the command line, run –dbgfdev.

Executable programs

Technical Manual

9-6

Miscellaneous

Show object informationIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Show object information. Or, from the command line, run –dbgobj.

Show whether domains, data definitions and objects are loaded from disk orshared memoryIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Show SRDD use. Or, from the command line, run –dbgsrdduse.

Show various TSS debugging informationIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Debug TSS. Or, from the command line, run –dbgtss.

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

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

Show loaded resourcesIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Debug Resources. Or, from the command line, run –dbgres.

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

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

Database related

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

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

Executable programs

Technical Manual

9-7

Show locking errorsIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Show locking errors. Or, from the command line, run –dbglck.

Show database server typeIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Show BDB server type. Or, from the command line, run –dbgsrv.

BDB/SQL Tracing

To trace BaanERP database and SQL actions, display the Option Dialog box andclick Debug Bshell. The Runtime debugging of Bshell dialog box appears. Youcan also choose these options from the command line.

BDB Debug Flags

Shows the drivers and parameters currently in useIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Driver Type. Or, from the command line, runBDB_DEBUG=01.

Show database actions such as Insert, Update, Delete, Commit, and AbortIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Database Actions. Or, from the command line, runBDB_DEBUG=02.

Show information on currently set locksIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Delayed Locks. Or, from the command line, runBDB_DEBUG=04.

Show references between tablesIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select References. Or, from the command line, runBDB_DEBUG=010.

Show all tables using native storage formatIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Multibyte Storage. Or, from the command line, runBDB_DEBUG=040.

Show the permissions and roles allowed for each userIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Permissions/Roles. Or, from the command line, runBDB_DEBUG=0100.

Executable programs

Technical Manual

9-8

BDB_DEBUG ValueShows 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 numberIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Show query with ID. Or, from the command line, runTT_SQL_TRACE=040.

Show how long a query has been runningIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Query execution times. Or, from the command line, runTT_SQL_TRACE=0200.

Show main SQL functions such as SQLExec, SQLParse, SQLFetch, andSQLBindIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Internal SQL functions. Or, from the command line, runTT_SQL_TRACE=02000.

Show the best possible design for indexing, joins, and so onIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Query evaluation plan. Or, from the command line, runTT_SQL_TRACE=04000.

Show all full table scansIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Show full table scans. Or, from the command line, runTT_SQL_TRACE=020000.

Show low-level communication between client and driverIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Show BDB communication. Or, from the command line, runTT_SQL_TRACE=040000.

Show current time to level of milliseconds: YYYYMMDDhhmmss.mmmIn the Option Dialog dialog box, choose Debug Bshell. On the BDB/SQLTracing tab, select Add time stamps (SQL). Or, from the command line, runTT_SQL_TRACE=0400000.

TT_SQL_TRACE valueShows the current setting that can be used in a –set TT_SQL_TRACE=<value>

from the command line.

Executable programs

Technical Manual

9-9

Memory usage

Show currently running processes in BshellIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Dump Process List. This option is not available from thecommand line.

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

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

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

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

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

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

Display shared-memory informationIn the Option Dialog dialog box, choose Debug Bshell. On the Bshell DebugLevels tab, select Display Shared Mem. This option is not available from thecommand line.

Executable programs

Technical Manual

9-10

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 thiscommand are performed while the Bshell is runing.

SYNOPSIS

bshcmd6.2 [options] <bshell_pid>

Possible options:

–v : print version information.

–p : show process list.

–m : show memory usage.

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

Executable programs

Technical Manual

9-11

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 loadedfrom 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.

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.

Executable programs

Technical Manual

9-12

–W sec : Wait until the previously issued command is executed. After this theprevious 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) andDBSLOG, TT_SGL_TRACE, {DBMS}STAT (drivers) tracing variables. cmdstrcan contain multiple commands of the form:

trace variable=value: set variable to valuetrace variable+value: add bits to variabletrace 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 previousones.

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 pscommand.

bshcmd6.2 –s –p –w 10 <bshell_pid>Show the process list, and wait 10 seconds for response. When no actions aredone 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.

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

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

REMARKS

EXAMPLES

Executable programs

Technical Manual

9-13

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.

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

Installationcmt6.2Script for component merge tool. Used to migrate the sources from user-customized applications to new BaanERP versions.

install6.2Script for installing the BaanERP software.

install.helpASCII file containing Help for the installation procedure.

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

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

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

Executable programs

Technical Manual

9-14

Developmentbic6.2Program compiler for Baan C compiler.

repgen6.2Report generator.

std_gen6.24GL-program preprocessor.

bic_cstub6.2Converts a BaanERP library to a C library.

bic_info6.2Shows information for specified object.

bic_jstub6.2Generates a Java class from a BaanERP DLL object.

License managementbrand6.2Program to authorize an environment. You must be logged in as the root user torun this program.

hostid6.2Program to print the host identification number.

Available options:


–o : print this number in an octal format.

–h : print this number in a hexadecimal format.

licd6.2

Daemon process to watch over the license. Because sockets are used, theEthernet software must be installed before you can use the license daemon.

The file $BSE/lib/licence6.2 must contain the name of the host on which thelicense daemon is running, as follows:

n host name (must be present in /etc/hosts)n internet address (x.x.x.x)

Note that brand6.2 expects to find the host name in licence6.2.

Executable programs

Technical Manual

9-15

Available options:


–d : debug.

–f : keep licd6.2 running in foreground. This is useful with the –d option.

licmon6.2

Monitor to retrieve information from the license daemon. The options that can beused when starting the monitor are:


–b : show brand information.

–B : show brand information from brand file and shared memory.

–C : clear brand information from shared memory. Use this option when sharedmemory is incorrect.

–w : show users.

–W : show other connections.

–k : kill license daemon.

–u : show user count.

–s : show statistics.

–d : print debug information.

–h host : retrieve information from the given host.

–p n : ping the license server n times (test connection).

The commands that can be entered within the license monitor are:

brand information : show the brand information of this host.

help : show the available commands.

ping [n] : ping the license server [n times] (test connection).

quit : quit license monitor.

stats : show server statistics.

users : show user count who [all]: list users [all: list other logons].

Executable programs

Technical Manual

9-16

Resources:

licence_timeout : specifies the number of seconds the license daemon waits for areply from another license daemon, or the number of seconds a Bshell waits for areply from the license daemon. The default is 30 seconds. Do not lower thisvalue. With wide area networks (WAN) it is advisable to set this value to 60.You can change or set the licence_timeout setting in the resource file.

Printer managementfilter6.2Program to translate BaanERP native codes to printer codes used by thepdaemon6.2 program.

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

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

The options that can be used at calling 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 moreinformation 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 which runs the lp6.2 system interface. Default: /bin/sh.

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

Executable programs

Technical Manual

9-17

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

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

Shared memoryshmmanager6.2Manager program for shared memory. See the chapter “Shared memorymanagement.”

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

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

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

Networkclient6.2Test program of the client part.

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

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

server6.2Test program of the server part.

IMPORTANT

Executable programs

Technical Manual

9-18

TRITON Super Settsscomp6.2Compiles and checks TSS information file tss6.2. See the chapter “Multibytemanagement.”

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

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

uniinfo6.2The 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 thecorresponding native character values, UTF-8 values, and TSS character valuesin hexadecimal format. By default, uniinfo6.2 shows only values from 0x000 to0x00ff.

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 –lflag, otherwise it is read from the user file. The default mode is to convert to thecharacter set of the Bshell. This can be reversed with the –o option. Someadditional 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

Technical Manual

9-19

–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 TSSconversion routines.

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

unimap6.2Do 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 mappinginformation file, which is provided in .txt format in Microsoft Excel. Themapping file is called locale and is located in $BSE/lib/unicode/. The filelocale.N2U is the Native to Unicode mapping file, and the file locale.U2N is theUnicode to Native mapping file. The leading byte ranges of the double-bytecharacter 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 toNative to Unicode mapping file only.

–f : place no zero value where no mapping value is specified from 0x00 to 0x20rather 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.”

Executable programs

Technical Manual

9-20

Time zone utilitieszic6.2Time zone information compiler.

zdump6.2Dumps time zone information to standard output.

date6.2Shows the dates based on BaanERP time zones.

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

bshellorb6.2Variation of the Bshell used to integrate BaanERP with CORBA programs.

UNIX equivalentscompress6.2Program to compress data. Equivalent to the UNIX compress command.

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

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

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

Executable programs

Technical Manual

9-21

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

bput6.2Program to set or print terminal settings.

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

mirror6.2Program for demonstrations and courses.

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

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

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

Executable programs

Technical Manual

9-22

Technical Manual

10-1

GeneralThere are three categories of errors:

n Error numbers 1-99 are generated by UNIX or XENIXn Error numbers 100-899 are database errorsn Error numbers 900-999 are network errors

Error numbers between 34 and 100 are system dependent.

UNIX errors

1 EPERM Not ownerThis error indicates an attempt to modify a file that cannot be modified, exceptby its owner or super user. This error also appears when ordinary users attempt todo things allowed only to the super user.

2 ENOENT No such file or directoryThis error occurs when a specified file name should exist but does not, or whenone of the directories in a path name does not exist.

3 ESRCH No such processThis error means that no process can be found that corresponds to the onespecified.

4 EINTR Interrupted system callThis error means that an asynchronous signal (such as interrupt or quit), whichthe user has chosen to catch, occurred during a system call. If the system resumesexecution after processing the signal, it will appear as if the interrupted systemcall returned this error code.

5 EIO I/O errorThis error means that there has been some physical I/O error. In some cases, thiserror can point to the call following the one to which it actually applies.

6 ENXIO No such device or addressThis error means that I/O on a special file refers to a subdevice that either doesnot exist, or is beyond the limits of the device. It may also occur when, forexample, a tape drive is not online or no disk pack is loaded on a drive.

10 Errors

Errors

Technical Manual

10-2

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

8 ENOEXEC Exec format errorThis error means that a request has been made to execute a file which, although ithas the appropriate permissions, does not start with a valid magic number. Amagic number is the first two bytes in a file, used to determine what type of file itis. See a.out(5).

9 EBADF Bad file numberThis error means that either a file descriptor does not refer to an open file, or thata write request has been made to a file that is opened only for reading that a readrequest has been made to a file that is opened only for writing.

10 ECHILD No child processesThis error means that a process that has no child processes waiting, has executeda wait. A child process is a process spawned by another process (the parentprocess).

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

12 ENOMEM Not enough spaceThis error means that during an exec or sbrk, a program has asked for morespace than the system is able to supply. This is not a temporary condition. Themaximum space size is a system parameter. The error can also occur when thearrangement of text, data and stack segments requires too many segmentationregisters, or if there is not enough swap space during a fork.

13 EACCES Permission deniedThis error means that an attempt was made to access a file in a manner forbiddenby the protection system.

14 EFAULT Bad addressThis error means that the system encountered a hardware fault when it attemptedto use an argument of a system call.

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

Errors

Technical Manual

10-3

16 EBUSY Device busyThis error means that an attempt was made to mount a device that was alreadymounted 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 occurswhen an attempt is made to enable accounting that is already enabled.

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

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

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

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

22 EINVAL Invalid argumentThis error means that an invalid argument was used, for example, dismounting anonmounted device; mentioning an undefined signal in signal or kill; reading orwriting a file for which lseek has generated a negative pointer. This error is alsoused by the math functions described in the (S) entries of the UNIX manual.

23 ENFILE File table overflowThis error means that the systems table of open files is full, and temporarily nomore open commands can be accepted.

24 EMFILE Too many open filesThis error means that too many file descriptors are open. No process can havemore than 20 file descriptors open at a time.

25 ENOTTY Not a typewriterThis error means that the selected device does not have the properties of aterminal.

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

Errors

Technical Manual

10-4

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

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

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

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

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

32 EPIPE Broken pipeThis error means that a write was made on a pipe for which there is no process toread the data. This condition normally generates a signal. The error is returned ifthe signal is ignored.

33 EDOM Math arg out of domain of funcThis error means that the argument of a function in the math package is out of thedomain of the function.

34 ERANGE Math result not representableThis error means that the value of a function in the math package cannot berepresented within machine precision.

Database errors

100 EDUPLThis error means that a duplicate value exists.

101 ENOTOPENThis error means that the table is not open.

102 EBADARGThis error means that an illegal argument has been specified.

103 EBADKEYThis error means that an illegal key description has been specified. Use thebdbpre and bdbpost tools.

Errors

Technical Manual

10-5

106 ENOTEXCLThis error means that the table is not exclusively locked action. You can eitherwait until the lock on table is released or you can remove the lock yourself.

107 ELOCKEDThis error means that the record you are trying to retrieve is locked. You caneither wait until the lock is released or remove the lock yourself.

108 EKEXISTSThis error means that the key already exists.

109 EPRIMKEYThis error means that you are trying to perform an illegal action on a primarykey. Refer to the log file for more information.

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

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

112 ENOCURRThis error means that there is no current record.

113 EFLOCKEDThis error means that the table is locked. You can either wait until the lock isreleased or you can remove the lock.

114 EFNAME File name too longThis error means that you are using a file name that is too long. Refer to yoursystem requirements to check the maximum length for a file name.

116 EBADMEMThis error means that the system cannot allocate memory because it is out ofmemory. Try restarting the Bshell as a possible solution.

117 EBADCOLLThis error means that there is a problem with the collating, or sorting order.

123 ENOSHMEMThis error means that no shared memory is initialized. You can use for examplethe rc.start script to initialize shared memory.

129 EUSERThis error means that too many sessions have been started.

136 ENOSPACEThis error means that there is no space in shared memory. You can eitherinitialize the shared memory, or change the shared memory parameters.

Errors

Technical Manual

10-6

140 ETRANSONThis error means that this operation is invalid when the transaction is on.

141 ETRANSOFFThis error means that this operation is invalid when the transaction is off.

142 EADMONThis error means that some administration process is running.

146 ENOSNAPSHOTThis error means that the system cannot take a snapshot of the database, probablybecause it is locked by another user. You can either wait until the lock is releasedor you can remove the lock.

148 EOFRANGEThis error means that there has been an error in the data type range check.

201 EROWCHANGEDThis error means that the record was changed after a delayed lock.

202 EDBLOCKEDThis error means that the database is locked. You can either wait until the lock isreleased or you can remove the lock yourself.

203 ETRANSACTIONONThis error means that this action is not allowed within a transaction.

204 EISREADONLYThis error means that this transaction is read only.

205 ENOTINRANGEThis error means that the field value is out of range and does not agree with thedomain definition.

206 ENOTLOCKEDThis error means that the record is not locked.

207 EAUDITThis error means that there is an error of the audit trailer.

208 EPERMISSIONThis error means that the action you have just attempted is not allowed at thistime.

209 EMIRRORThis error means that there is an error in the mirroring of the database. The tablesare inconsistent. You can use bdbpre and bdbpost to copy the tables correctly.

Errors

Technical Manual

10-7

210 EMLOCKEDThis error means either that the record is locked in the mirrored database, or thatthe tables are inconsistent, or that the mirroring definition in tabledef6.2 is notcompatible.

213 ETRANSACTIONOPENThis error means that the transaction is started, but not updated. This is aninternal Bshell error.

214 EUNALLOWEDCOMPNRThis 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 allowedto do a drop/clear table operation.

215 EDBDILLEGALThis error indicates an illegal state that should never occur.

251 EAUDSETUPThis error means that the audit server setup is not correct. See the log.audit filefor more information.

252 EAUDCORRUPTThis error means that an audit file is corrupt. See the log.audit file for moreinformation.

253 EAUDLOCKEDThis error means that the audit file is locked by another user. See the log.auditfile for more information.

254 EAUDABORTThis error means that a commit transaction has failed in the audit server actionSee the log.audit file for more information.

301 ESQLQUERYThis is a general SQL error code. This error occurs when there is a problem withthe SQL syntax.

302 ESQLSYNTAXThis error means that the SQL syntax is not correct.

303 ESQLREFERThis error means that a reference in the query cannot be found.

304 ESQLUNDEFINEDThis error occurs when something went wrong but no error code can be set.

Errors

Technical Manual

10-8

305 ESQLWRONGROWThis error means that a wrong record was returned. This probably means eitherthat the table index is corrupt or that the RDBMS has a different sorting orderthan the BaanERP software.

501 EMEMORYThis is an internal memory error.

502 EBDBONThis error means that the user is already logged on.

503 EBADADRSThis error means that an illegal address has been used.

504 EBADFLDThis error means that a column is undefined.

505 ENOSERVERThis error means either that no server is specified in tabledef6.1, or that theserver cannot be started. See the log file for more information.

506 ENOTABLEThis error means that the table does not exist.

507 ETABLEEXISTThis error means that the table you are trying to create already exists.

508 EBDBNOTONThis error means that you are not logged on to a database.

509 EBADCURSORThis error means that you have a bad memory cursor or that a bad table pointerhas been specified.

510 EDBNOTONThis error means that the database is not on. Start the database to correct theproblem.

511 EWRONGVERSIONThis error means that the version of client is not the same as the version of theserver.

512 EDDCORRUPTThis error means that the data dictionary is corrupt. Use bdbpre and bdbposttools to repair it.

513 ENODDThis error means that the data dictionary was not found.

Errors

Technical Manual

10-9

514 ESECURITY (Oracle)This is a security error. It probably means you do not have the correct user orgroup permission.

515 ELICENSEERRORThis is a license error. It probably indicates an unpatched binary.

516 EUPDSEGMThis error occurs during the making or filling of rollback segments. It probablymeans that the disk is full.

517 EDELAYEDThis is a general error indicating delayed locking.

518 ENOSESSIONThis error means that an invalid session code has been specified.

519 ENOCOMPNRThis error means that either no company number an illegal company number hasbeen specified. A valid company number is a number between 0 and 999.

520 EBUFUPDThis error occurs when flushing of buffered updates fails. The flushing can faildue to a lock or referential integrity constraint.

521 ENOSHMThis error means that shared memory has not been loaded. See the chapter“Shared memory” for more information about starting shared memory.

522 EBDBDBCONNECTIONLOSTThis error means that the connection between the driver and database has beenlost.

600 EREFERENCEThis is a general reference error. For more information, see the log file.

601 EREFLOCKEDThis error means that the reference table is locked. You can either wait until thelock is released or remove the lock yourself.

602 EUNDEFREFThis error means that the reference is not defined. It is probably a problem in therun time data dictionary. For more information, see the log file.

604 EREFUPDATEThis error means that a reference could not be updated.

Errors

Technical Manual

10-10

605 EREFEXISTSThis error means that the record cannot be deleted while the reference exists. Seethe log file for more information.

606 EREFNOTEXISTSThis error means that the reference does not exist.

607 ENOREFTBLThis error means that the reference table was not found. The data dictionarymight not be correct. See the log file for more information.

608 ENOREFCNTThis error means that no reference counter fields are present.

609 EUPDREFCNTThis error can occur when the reference counter is updated.

700 ESETLOCALEThis error can occur when you are setting the locale. See the log file for moreinformation.

If an error code greater than 1000 is displayed, the error can be retrieved asfollows, depending on the database driver used:

Informix/Oracle: error – 1000 gives DB error

Example UNIX

Error no: 11400Error: 11400 – 1000 = 10400UNIX error = 0 (last two digits)

Example Oracle:

Error no: 1979Error: 1979 – 1000 = 979 Not a GROUP BY

When a fatal error occurs, more information is stored in the log files in thedirectory $BSE/log. For example, if bdbpost causes an error, it is reported in thefile log.bdbpost.

NOTE

Technical Manual

11-1

GeneralShared memory is a part of the internal memory intended for common usage. Allusers can read from and write to it. In BaanERP Tools the shared memorycontains part of the data dictionary.

A prerequisite for shared memory is that it must be supported by the hardwareand there must be sufficient internal memory available.

This chapter describes the way shared memory can be used for BaanERP Tools.

Using the shared memory managerThe shared memory manager is located in the $BSE/bin directory and can bestarted as follows:

shmmanager6.2 [-iksavr]

The options are:

–i: installation of shared memory.

–k: deletion of created shared-memory blocks. After shared memory is deletedyou must reinstall it. You can only use this option if all processes that use sharedmemory have finished. If not, the system displays a message.

–s: display of technical information on the contents of shared memory. Thisincludes:

− 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.

11 Shared memory management

Shared memory management

Technical Manual

11-2

–r: resetting of shared memory. Removes all data from shared memory exceptthe first segment. You do not have to reinstall shared memory afterwards. Theresult 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 havefinished. 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 sharedmemory.”

Installation of shared memoryThe Bshell requires at least 4 MB of internal memory to function properly. Afterthe kernel selects a virtual address, the kernel does not always leave enoughmemory for the Bshell. You must therefore specify a virtual address to determinewhere 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 ofshared memory. Following the installation is a description of error messages thatcan come up during installation. The section “Kernel parameters” contains theminimum values of the kernel parameters.

Create an entry in the file shm_param file

The shmmanager6.2 program uses the shm_param parameter file, whichcontains parameters to install shared memory for a specific machine. This file isstored in directory ${BSE}/lib.

Create an empty entry in this file for the machine in question. It must read asfollows:

Machine_id/OS release:;{}

This entry must be preceded by a default entry. See also the section “Exampleparameter file shm_param.”

The OS release is only used if the file contains more than one entry for the samemachine ID. You can display the machine ID and the OS release using thecommand shmmanager6.2 –v.

NOTE


Technical Manual

11-3

Determine shared-memory parameters

You can determine these parameters by using one of the following commands:

n shmvalues6.2n shmmanager6.2 –a

Using shmvalues6.2

The program shmvalues6.2 finds the boundaries of shared memory by itself andgenerates a default entry, which you can include in the shm_param parameterfile. For example:

default:;{}Machine_id:;{}Machine_id/OS release:;{SHM_START = a40000SHM_STEP = 80000SHM_BUFSIZE = 512SHM_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 consecutivesegments.

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 errormessages when the boundaries of the operating system are exceeded.

–m : the program shmvalues6.2 first tries to allocate 4 MB of memory to makesure enough memory is left after shared memory has been installed. You can usethe –m option to increase or decrease the amount of allocated memory. Youspecify it in megabytes, that is, –m 3 = 3 MB.


Technical Manual

11-4

–vV : the –v or –V option displays machine and porting data.

–s : Use this option to increase or decrease the SHM_BUFSIZE value (default512 KB). This value must be less than or equal to the kernel parameterSHMMAX .

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 writtento 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 thekernel 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.

Using 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 moreinformation on the addresses of the segments and on the instances where errorscan occur.

Execute the shmmanager6.2 with the –a option.

You are prompted for the number of kilobytes to be allocated and the number ofsegments to be created. For the Bshell, specify 4096 KB and 10 segments,respectively.

NOTE

CAUTIONS

FATAL ERRORS


Technical Manual

11-5

For example:

# shmmanager6.2 –aNo. of kbytes to be malloc: 4096No. of shm segments to be created: 10addr[0]: 0xa40000 id[0]: 40 < SHM_START = a40000addr[1]: 0xac0000 id[1]: 41addr[2]: 0xb40000 id[2]: 42addr[3]: 0xbc0000 id[3]: 43addr[4]: 0xc40000 id[4]: 44addr[5]: 0xcc0000 id[5]: 45addr[6]: 0xd40000 id[6]: 46addr[7]: 0xdc0000 id[7]: 47addr[8]: 0xe40000 id[8]: 48addr[9]: 0xec0000 id[9]: 49 < SHM_MAXMEM = 10step 0x80000 < SHM_STEP = 80000step 0x80000step 0x80000step 0x80000step 0x80000step 0x80000step 0x80000step 0x80000step 0x80000step 0x80000ret 0

Fill the entry in the shm_param parameter file

Enter the variables as determined in the shm_param parameter file. Thefollowing variables are mandatory:

n The start address of the first shared-memory segment: SHM_STARTn The number of shared-memory segments: SHM_MAXMEMn The difference between the start addresses of the segments: SHM_STEP

You can retrieve the values of these variables from the information in theexample on the preceding page. For this example, fill the entry in the parameterfile as follows:

Machine_id/OS release:;{SHM_START = a40000SHM_MAXMEM = 10SHM_STEP = 80000}


Technical Manual

11-6

Installation of shared memory

Use the –i option to install shared memory. For example:

# shmmanager6.2 –iBUFSZ 524288, MAXATTCH 10, START 0xa40000, STEP 0x80000Start /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 theBshell users. You can avoid installing shared memory manually each time byincluding the installation in your system’s start-up procedure. If the BSE variableis not /usr/bse, it must be set during the start-up procedure and shmmanager6.2must be started with the –I option.

Starting shmtimer6.2

The UNIX time() function is a system call often called in database servers. Onmultiprocessor systems, use of the time() function can be quite heavy. Eventhough a process can run successively on different processors, this must beinvisible to the process. The process requires that each processor returns thesame time, using time(). Therefore, the processors have to synchronize theirinternal clocks every time the time() function is called.

The shmtimer6.2 program can prevent this overhead. shmtimer6.2 is a daemonprocess that writes the current time in shared memory. The time is updated everysecond. This reduces the number of calls of the time() function to a maximum ofone per second.

When shared memory (shmmanager6.2 –i) is initialized, the shmtimer6.2program starts. When shared memory is removed (shmmanager6.2 –k), theshmtimer6.2 stops first. The following options can be used for shmtimer6.2:

–i : Initialize shmtimer6.2A shmtimer6.2 program is started, and runs in the background.

–k : Kill shmtimer6.2The running shmtimer6.2 program is killed. The allocated shared memory iscleared, 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


Technical Manual

11-7

–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 ofreading the time from shared memory.

If shmtimer6.2 is killed, shmtimer6.2 cannot clear its shared memory. Becauseshmtimer6.2 is killed, the time in shared memory is never updated, but the timeis 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 –aNo. of kbytes to be malloc: 4096no more spaceabort – core dumped

This error happens because some computer systems put a limit on the amount ofvirtual memory (MAXUMEM) used by a process. Hence the shared memorymanager can not 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 –aNo. of kbytes to be malloc: 4096No. of shm segments to be created: 10shmget errno 22etc......Errno 22 (EINVAL): The kernel cannot create any shared-memory segments of 512 K(SHMMAX).



Technical Manual

11-8

Not enough virtual memory

# shmmanager6.2 –aNo. of kilobytes to be malloc: 4096No. of shm segments to be created: 10shmat errno XX id 46addr[0]: 0xa40000 id[0]: 40addr[1]: 0xac0000 id[1]: 41addr[2]: 0xb40000 id[2]: 42addr[3]: 0xbc0000 id[3]: 43addr[4]: 0xc40000 id[4]: 44addr[5]: 0xcc0000 id[5]: 45addr[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 0x80000step 0x80000step 0x80000step 0x80000step 0x80000step 0x80000step 0xff53ffffstep 0x1step 0ret 0Errno 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-memorysegments perprocess (SHMSEG).


If the kernel cannot allocate 10 segments, as in the previous example, you needto fill the entry in the shm_param file as follows:

Machine_id/OS release:;{SHM_START = a40000SHM_MAXMEM = 6SHM_STEP = 80000}


Technical Manual

11-9

Syntax srdd_tabThe srdd_tab6.2 file can be divided into several sections. Each section isindicated by the package combination for which components have to be loadedinto shared memory. For example:

package=31Sa

This parameter means that the components below this line belong to packagecombination 31Sa.

After this line first the domains are specified. For example:dti.pddtt.pd

The following data is the table definitions. For example:dttaad000dttaad001

After that the objects have to be placed. For example:ottstpconvottstpdisplay

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 sharedmemory. To do this, write the host name of the remote system at the beginning ofa line. For example:

${BSE}/standard6.2/ddbaan/dti/dti.pdibm1!/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 file srdd_tab6.2 contains a redirection to a remote system, a remote userfile must be available for the user who executes srdd_init6.2.


Technical Manual

11-10

Filling shared memoryYou can load parts of the data dictionary into shared memory: data definitions,objects, reports, and domains. In the file $BSE/lib/srdd_tab6.2, specify whichparts to load into shared memory. You can fill the file srdd_tab6.2 usingBaanERP Tools:

Shared Memory Data (ttaad4150m000) sessionTo load program and report objects.

%SEttaad1120m000 sessionTo load table definitions and domains.

The parts of the data dictionary loaded into shared memory have an entryconsisting of the inode number, date, time, and name. If the entry of a part inshared memory does not match the entry for that part on hard disk, the parts onhard disk are loaded locally, but not into shared memory. The old part remains inshared memory until you execute shmmanager –k to delete shared memoryblocks. Then you reinstall shared memory using shmmanager –i.

Use the srdd_init6.2 program to load the parts of the data dictionary into sharedmemory. The available options are:

–l : print what is done by the program, including error messages, if any. Use onlyin 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 UNIX command ipcs –m to seewhich segments are used and how much space is left to load other parts of thedata dictionary.

Error messages and other messages are written to stderr. You can write them to afile by entering the command:

srdd_init6.2 –i 2> file name

Directory ${BSE}/etc contains the file rc.start. This program is executed atsystem startup. Shared memory is installed, filled, and initialized for a BSEenvironment specified in this file. The programs shmvalues6.2,shmmanager6.2, and srdd_init6.2 are used.


Technical Manual

11-11

Kernel requirements

General description of adjusting UNIX kernels

Static kernels

The kernel of a UNIX system is a program that runs from booting to shuttingdown. 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 simultaneousactions 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 anerror message. For example, if the number of files opened at the same time isgreater 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 largernumber of files to be opened simultaneously. The kernel is stored on the systemin different forms.

First, it includes sources, libraries, an include file and, most importantly, a filecontaining kernel parameters.

Second, the kernel is present as an executable and can be generated from thepreviously-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 started.

Dynamic kernels

With a static kernel, boundaries are set through a kernel parameter. With adynamic kernel, the user can adjust boundaries during run time. The kernel of anIBM system is fully dynamic (except for a few parameters), so the user does nothave to reboot the computer to activate changes. You can use a command tomodify the kernel of an IBM while the system is still running. Furthermore, thekernel is automatically adjusted if the required number of resources is greaterthan permitted by the kernel.


Technical Manual

11-12

The kernels of Digital and Sun systems are semidynamic. When the system isbooted, some kernel parameters are read from a file and the kernel is adjustedaccordingly. The user can adjust other parameters while the kernel is running.

Kernel parameters

The recommended values for the parameters presuppose the followingconditions:

n A standard BaanERP installationn One active session per Bshell

You can use the sar command while working in BaanERP to keep track ofparameter usage and adjust the parameters where necessary. This is of particularinterest for BaanERP customization. When using other databases, take intoaccount the kernel tuning references from the corresponding documentation.

When using raw devices, you must set the parameters relating to the cache suchas NBUF or BUFPAGES to low values, according to the database-specificdocumentation, not to the relatively high values suggested in this document.

The following descriptions for parameters refer to the number of users. If there ismore than one active session per Bshell, instead of number of users, read numberof active sessions.

Processes

NPROCThe NPROC parameter specifies the maximum number of processes that can berun simultaneously in the system.

NPROC = 64 * users & NPROC = 1.1 * MAXUPAdjust: error 11

MAXUPThe MAXUP parameter specifies the maximum number of processes that can berun per logon code. This restriction does not apply to the superuser. If severalusers log on using the same logon code, those users must share this number ofprocesses.

MAXUP=64Adjust: error 11, message ’fork failed: too many processes’

NOTE


Technical Manual

11-13

REGION, NREGIONThe REGION parameter specifies the maximum number of program regions thatcan 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

NFILEThe NFILE parameter specifies the maximum number of files that can beopened simultaneously on the system.

NFILE = 512 * usersAdjust: Message “ file table overflow”

The command sar –v 1 1 shows the number of open files and the maximumnumber of files to be opened, under the header “file-sz.”

NOFILES, SFNOLIM(SVR4), MAXFILES (HP)The NOFILE parameter specifies the maximum number of files that can beopened per process.

NOFILES >+ 256Adjust: error 24, Too many connected sessions (INGRES).

On an SVR4 system the user can use not only the kernel parameter sfnolim, butalso a command to change the maximum number of open files per process. Thatcommand is “ limit – 256” , including the quotation marks. This new value onlyapplies in this shell.


Technical Manual

11-14

Buffers

NBUFUnder SVR3 and SVR4, the NBUF parameter has a different meaning.

SVR3The NBUF parameter specifies the number of system buffers available forblock I/O.

NBUF = 1/3 of total internal memory (SVR3)NBUF = 0 (HP)

SVR4In UNIX SVR4, buffers contain only indexes, superblocks, and file headerinformation. They do not contain file data. The actual file data is stored inpages of virtual memory. The amount of virtual memory available for thispurpose is determined by the SEGMAPSZ parameter.

The NBUF parameter specifies the number of system buffer headers availablefor block I/O.

NBUF = default, for example, 100Adjust: Performance problems (sar –b)

NHBUFThe NHBUF parameter specifies the number of hash table entries that can beallocated in the system.

NHBUF = 1/5 * NBUFAdjust: Performance problems

BUFPAGESThe BUFPAGES parameter specifies the number of pages in the file’s systembuffer cache.

BUFPAGES = 1/3 of total internal memory) /4096, (HP)Adjust: Performance problems

SEGMAPSZThe SEGMAPSZ parameter specifies the size of the bitmap for file I/O. Thismap determines the number of 4K pages and therefore the amount of memoryavailable for file I/O. If the value is 0, the kernel calculates the value as afunction of the amount of physical memory.

SEGMAPSZ = 0 or 1/x of total internal memory.Adjust: Performance problems


Technical Manual

11-15

BUFHWMThe BUFHWM parameter specifies the maximum amount of memory, inkilobytes, 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 availablememory.

Shared memory

SHMALLThe SHMALL parameter specifies the maximum amount of shared-memory textsegments that can be created.

SHMALL = SHMNIAdjust: error 24

SHMMAXThe SHMMAX parameter specifies the maximum size, in bytes, of a shared-memory segment that can be created. Several shared-memory segments of thissize can be created in an environment per process.

SHMAX >= SHM_BUFSIZE (in $BSE/lib/shm_param)

SHMMINThe SHMMIN parameter specifies the maximum size of a shared-memorysegment in bytes.

SHMMNI = SHMSEG * ENVIRONMENTSTest with: ipcs –m

SHMSEGThe SHMSEG parameter specifies the maximum number of shared-memorysegments that can be used by a process.

SHMSEG = 30Adjust: error 24

Semaphores

SEMMAPThe SEMMAP specifies the number of entries in the control map used tomanage semaphores. This map is used to keep track of free areas in the systempool of semaphores.

SEMMAP = SEMNI +2Adjust: Message “Mfree map overflow”


Technical Manual

11-16

SEMMNIThe SEMMNI parameter specifies the maximum number of semaphoreidentifiers in the kernel. This is the number of unique semaphore sets that can beactive at any given time.

SEMMNI = 32 * usersAdjust: error 28

SEMMNSThe SEMMNS parameter specifies the maximum number of semaphores ipc –sbpermitted in the system.

SEMMNS = SEMMNITest with: “ipc –sb”

SEMUMEThe SEMUME parameter specifies the maximum number of undo entries perundo structure. Each undo entry represents a semaphore that has been modifiedwith the undo option specified in the semop(2) system call.

SEMUME = 10Adjust: error 22

Message

MSGMAPThe MSGMAP parameter specifies the number of entries in the control map, forexample 100, used to manage message segments. Each entry in this maprepresents a free area in the message buffer area.

MSGMAP = defaultAdjust: Message “mfree map overflow”

MSGMAXThe MSGMAX parameter specifies the maximum size of a message in bytes. Ifthe protocol m (message queues) is used in the file $BSSE/lib/ipc_info, the valuemust be set to 4096.

MSGMAX = 4096 & MSGMAX <= MSGMNB

MSGMNBThe MSGMNB parameter specifies the maximum length, in bytes, of a messagequeue.

MSGMNG = 4096Check with: ipcs –qo


Technical Manual

11-17

MSGMNIThe MSGMNI parameter specifies the maximum number of message queuesthat can be used on the system.

MSGMNI=32 *usersAdjust: error 28

MSGSEGThe MSGSEG parameter specifies the number of message segments permittedon the system, for example 1024. Each message on a message queue consists ofone or more message segments. The size of each segment is specified by theMSGSSZ parameter.

MSGSEG = default

MSGSSZThe MSGSSZ parameter specifies the size, in bytes, of a message segment, forexample, 8. Each message consists of contiguous set of message segments largeenough to hold the text of the message.

MSGSSZ = default

MSGTQLThe MSGTQL parameter specifies the maximum number of message headers, inother words, the maximum number of open messages.

MSGTQL = 32 * users

General kernel parameters

ULIMIT, HFSZLIM, SFSZLIM

SVR3The ULIMIT parameter specifies the maximum size of a single file on disk.SCO UNIX and HP use blocks of 512K.

SVR4The kernel parameter ULIMIT is not used in SVR4. SVR4 uses the parameterHFSZLIM for the hard limit and SFSZLIM for the soft limit. These parametersare in bytes.

SVR3 and SVR4 both contain the built-in command ULIMIT through which thekernel parameter value can be reduced.


Technical Manual

11-18

NINODEThe NINODE parameter specifies the maximum number of inodes that can beused in the SV file system. This includes open files, used pipes, and the currentdirectory. The UFSNINODE parameter specifies the number of inodes for theUFS file systems.

Example parameter file shm_param# 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

}

Technical Manual

12-1

GeneralThe client/server architecture as supported by BaanERP enables the user to workwith several database types. These databases can be distributed over one ormultiple systems. A remote database configuration is one where an applicationserver (bshell) and the database are not on the same system.

The possible reasons for setting up a remote database configuration are:

n System performanceIf all users start the application on the same system, the CPU is primarilyoccupied by the Bshell and the display server. You can divide the load byletting the users work on local systems and keeping the database on a remotesystem.

n Lack of disk space on local systemIf 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.

n Distributed applicationsFor practical reasons you can decide to install the application tables ondifferent systems per application.

n Mirrored databasesFor security reasons database actions can be carried out on two systemssimultaneously using database mirroring.

This chapter describes how to set up a remote database configuration and alsoexplains how to use it.

12 Remote databases

Remote databases

Technical Manual

12-2

Settings for remote database configurationsTo work with a remote database configuration, you must predefine a number ofsettings. You must know on which systems the tables are located, and also whichtypes of databases are going to be used. Also, if the communication structure hasnot changed, the porting sets of the binaries on the local and remote systems canbe different, otherwise they must be equal. It is recommended to have the sameporting sets. This chapter explains how you can configure a remote databasesystem.

The tables can be located in various ways in a remote database configuration:

n All tables are located on one or more systemsn A part of the tables are located on the local and another part of the tables are

located on a remote system

Figure 8, All tables on remote system

In figure 8, the user interface and the application logic (Bshell) are both installedon the local host. From version 6.1 forward, they can be installed on differentsystems.

Assuming that all tables are installed on a remote system and the user interfaceand application logic (Bshell) are installed locally, the following files must beavailable for the system to work normally:

Remote databases

Technical Manual

12-3

Local host

On the local host, the following files and directories must be present:

$BSE/bin:

audit_srv6.2 hostid6.2ba6.2 kermit6.2badmin6.2 licd6.2Bdbpost6.2 licmon6.2bdbpre6.2 lp6.2Bdbreconfig6.2 nlsedit6.2bic6.2popup6.2 pdaemon6.2bic_cstub6.2 qcommand6.2bic_info6.2 qptool6.2Binperm6.2 refint6.2binput6.2 repgen6.2bput6.2 rz6.2brand6.2 shmmanager6.2Bshcmd6.2 shmvalues6.2Bshell6.2 sort6.2bsp.setperm6.2 srdd_init6.2client6.2 std_gen6.2Compress6.2 sum6.2encrypt6.2 sz6.2Explode6.2 tsscomp6.2filter6.2 tsscvt6.2Gcommand6.2 tssinfo6.2

$BSE/lib:tabledef6.2fd6.2.<package_comb> (optional)ipc_info/user/r<user>

$BSE/etc:rc.startrc.stop

$BSE/tmp

$BSE/log

Remote databases

Technical Manual

12-4

Remote

It is recommended that you install the complete $BSE-environment on theremote system. If no application is started on the remote system, executableprograms such as Bshell6.2 and ba6.2 do not have to be installed there. It ispractical if one or more users can run the application locally on the remotesystem. For this reason they must be run on the remote system. That is why theentire BSE environment must be installed there.

The remote system must include at least the following files:

$BSE/bin:fs6.2ipc_boot6.2database_servers with associated executable programs, such as ora7_srv6.2installation and validation programs, such as install6.2, licd6.2, and so on.

$BSE/lib:tabledef6.2user/u<user>ipc_infodriver-specific directory, for example, orafd.6.2.<package_comb> (optional)

$BSE/etc – rc.startrc.stop

If these files are available on the local and the remote system, respectively, youcan adapt the following files. The data dictionary contains sessions where youcan adapt the files. It is better to adapt the files in the sessions in the datadictionary and not directly in the files themselves.

Local

On the local system the following files are configuration dependent:

n tabledef6.2 Database Definitions (ttaad4510m000) and Tables by Database(ttaad4111m000))

n u<user> Remote User Data (ttaad2500m000)n r<user> Remote User Data (ttaad2501m000)

Remote databases

Technical Manual

12-5

tabledef6.2

Start the application by executing the user interface (UI). The UI then starts theapplication logic (Bshell), which reads the file tabledef6.2 to search for the tablelocation and database type. Tables can be stored on a local or remote system,which is also indicated in this file.

The file tabledef6.2 is filled using the Database Definitions (ttaad4510m000) andTables by Database (ttaad4111m000) sessions on the menu BaanERP ToolsÈDatabase ManagementÈ Database Definitions and Directories. Thesesessions indicate whether tables are installed on a remote database.

The file tabledef6.2 is located in the $BSE/lib directory. For more informationabout tabledef6.2, refer to the help text for business object DatabaseManagement, on the menu BaanERP ToolsÈ Database ManagementÈDatabase Definitions and Directories.

You can specify whether each table is installed locally or remotely by enteringthe remote system name in the System Name field in the Database Definitions(ttaad4510m000) session. Then use the Tables by Database (ttaad4111m000)session on the menu BaanERP ToolsÈ Database ManagementÈ DatabaseDefinitions and Directories to assign tables to this table definition.

For example, assume that all tables are installed on the remote system host1. Thismeans 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 variable BSE_REM on thelocal system. If there is no tabledef6.2 file on the local system, the Bshellsearches for this on the remote system, otherwise it reads the local tabledef6.2file. 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 readsthis user file to test whether the user is authorized to start the application. TheRemote User Data (ttaad2501m000) session creates the file$BSE/lib/user/r<user>.

If all tables are installed on the remote system, the user files can be installedthere, too, instead of on the local system. In that case you can set the systemvariable BSE_REM with the system name of the remote system, for exampleBSE_REM=host1. The Bshell looks first in the local $BSE/lib directory. If itcannot find the needed files there, it uses the BSE environment ($BSE/lib) on theremote system.

Remote databases

Technical Manual

12-6

The remote system now reads the user file u user. To access tables on a remotesystem, you need to log on to the remote system. This is done using a remotelogon user file named r user. You create this file using the Remote User Data(ttaad2501m000) session. Read session Help for information on how to createthis file.

Variant I

Two variants of r user are possible. If the user’s logon is the same on the localand the remote system, variant I is sufficient. Define the remote system, the pathon that system, and the password to log on to the remote system.

In variant I, the following information is needed:

n Name of remote hostn BSE path on remote hostn Encrypted password on remote host

A user “peter” would like to work with BaanERP on his local work station. Thedatabase tables he wants to use, however, are located on a remote system calledhost. To access the remote data, he needs a file rpeter in the directory$BSE/lib/user. If all tables are located on the remote system, he sets thefollowing system variable:

BSE_REM=host1

This makes sure that everything is read from the remote BSE environment exceptthe bin directory.

When using Variant I, user peter must have a logon entry on the remote system.The file r user must contain the name of the remote system, the path of the BSEon 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 anotherlogon code. Indicate whether the UNIX and BaanERP permissions must beinherited from the other user. If so, the user file u user on the remote systemmust have the same UNIX logon as on the local system.

In variant II, the following information is needed:

n Name of remote hostn BSE path on remote hostn Logon name on remote hostn Encrypted password on remote hostn SUID inherited logon

EXAMPLE

Remote databases

Technical Manual

12-7

The remote user file can contain more than one line.

When using variant II, you can also specify a logon code to access the remotesystem. This can be a different logon code than “peter,” for example “john.”After that you enter the encrypted password for the remote logon (john). Theremote system must still have a user file upeter.

Variant II also allows you to take the UNIX and/or BaanERP authorizationsdefined for the logon john. To do so, specify “yes” or “no” for the fields SUIDand Inherit Logon. SUID switches the user ID from peter to john. Inherit Logonmakes sure the BaanERP authorizations defined for john apply also to peter.

To switch the user ID, the file ipc_boot6.2 ($BSE/bin) must have UNIX rootpermission root and the s-bit must be set. From a security point of view this isnot advisable.

Here is an example of the two variants:

Variant I:

host1 /usr2/bse NZ+,AHtg&#K-kt"Q{$=Y3-"VLDN’CRtZhost2 /usr1/t/bse h8i0_-+8yujg@#c67h78i\{}907h67h5R

Variant II:

host1 /usr2/bse john NZ+,AHtg&#K-kt"Q{$=Y3-"VLDN’CRtZ no yeshost2 /usr1/t/bse h8i0_-+8yujg@#c67h78i\{}907h67h5R yes yes

Remote

Whenever a local system connects to the remote system, ipc_boot6.2 is the firstprogram to start. That process in turn starts fs6.2, which can read tabledef6.2 onthe remote system. It finds an entry in tabledef6.2, showing the database type fora range of tables to be accessed.

A database server is started, for example, ora7_srv6.2. The path for both fs6.2and the database server is read from the file $BSE/lib/ipc_info.

Once on a remote system, you cannot call a third system. This means thattabledef6.2 must always have an entry on the tables.

Remote databases

Technical Manual

12-8

Figure 9, 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. Inthat case both the local and the remote system must have the complete BSEenvironment installed.

The file tabledef6.2 now contains entries for local as well as remote systemtables. This can also be defined in the Database Definitions (ttaad4510m000) andTables by Database (ttaad4111m000) sessions on the menu BaanERP ToolsÈDatabase ManagementÈ Database Definitions and Directories.

Settings for remote menus/forms/objectsNot only databases, but also forms, menus, objects and scripts can be distributedover one or more systems. The directories for the software components aredefined in the Directories of Software Components (ttadv1115m000) session.This session fills the file fd6.2.package_combination. In this session you canspecify whether the component is on the local or remote system. See also thesession Help information.

Technical Manual

13-1

GeneralThe currently used 8-bit wide character space is not large enough to fit mostAsian character sets. Asian countries such as Japan, China, and Korea need atleast 16 bits of character space to accommodate local characters. Therefore a 32-bit wide character space has been implemented in BaanERP Tools to support allpossible character sets.

Be aware that a character is not necessarily the same as a byte and can take upmore than one screen position. A character in the Bshell occupies one or twoscreen positions at a size of 4 bytes.

Triton Super SetTriton Super Set (TSS) is a collection of character sets that can be used inBaanERP applications. TSS accommodates all multibyte character sets in asingle package. TSS includes both ASCII character sets and multibyte charactersets, such as Japanese, Chinese, Hebrew. To distinguish between, for example,Japanese and Chinese, TSS consists of planes, each of which holds a 64KB-sizecharacter set, or 256 pages of 256 characters.

This is shown in the following figure. Numbers are according to the hexadecimalsystem. For example, the value of 0x21 is 33 in the decimal notation.

Figure 10, BaanERP Super Set (TSS)

13 Multibyte management

Multibyte management

Technical Manual

13-2

The characters 0x00 – 0x20 and 0x7F – 0x9F cannot be included in the sets,because these ranges contain control and escape codes. This leaves the followingranges:

0x212121 – 0x7EFFFF0xA12121 – 0xFFFFFF

To distinguish TSS characters, the character contains the prefix 0x9B. Hence thecomplete TSS ranges are:

0x9B212121 – 0x9B7EFFFF0x9BA12121 – 0x9BFFFFFF

Code Features (CF) and Line Drawing Characters (LDC) have been implementedin the code range of ISO-8859/1 as follows:

n Line Drawing Characters | 0x80 – 0x8An Code Features | 0x8B – 0x9An TSS Lead byte | 0x9Bn Reserved | 0x9C – 0x9F

These code ranges do not conflict with the currently implemented EUC charactersets, but they can cause problems when you import these codes. Also these codesoverlap 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 CFcharacters during the import phase.

Currently assigned planes are:

Character set Page Range from Range to RemarksKANJIEUC/SHIFTJIS 0x21 212121 217e7e JISX0208-1983KANJIEUC/SHIFTJIS 0x23 2321a1 2321df JISX0201-1976CCDC_HP15 0x24 24a121 24fe7e CCDCGB2312-80 0x25 25a1a1 25ffff GB2312-80GB2312-80 0x26 26a120 26a17f Extended GBBIG5 0x27 27a140 27f9d5CNS11643 0x28 28a1a1 28fefe CNS11643 Plane 1CNS11643 0x29 29a121 29fe7e CNS11643 Plane 2HEBREW 0x30 3021a0 3021fa ISO-8859/8


Technical Manual

13-3

Using 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 beeninitialized in the proper native language. If necessary, change the shell variablesLANG and LC_ALL before starting the window manager. This prevents the titlebar 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 theBaanERP 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.

Printing multibyte characters

To print multibyte characters, make sure the following conditions are met:

n A device created in the Device Data (ttaad3500m000) session must be linkedto a TSS locale that contains the definition of the character set in question. Ifthe proper locale is not specified, the printer daemon cannot print the report.

n The printer must be able to print the characters from the TSS locale. Checkyour printer manuals.

UtilitiesThis section describes the available programs belonging to BaanERP Super Set.These programs are present in the directory $BSE/bin.

tsscomp6.2

NAME

tsscomp6.2

This program compiles and checks TSS information file tss6.2. This program isexecuted by the Convert TSS Data to Runtime (tttss0103m000) session.

SYNOPSIS

tsscomp6.2 [-svV] [-e error file] [-d debug level] [–i input file] [–o output file]


Technical Manual

13-4

DESCRIPTION

tsscomp6.2 compiles the file tss6.2, which contains the descriptions of allsupported character sets into a fast-loading binary file tss_c6.2. It also performsseveral 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 theprogram has been successful.

-e Write all warnings and errors to 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:

n 0 = successn > 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 theuser 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.


Technical Manual

13-5

Return values:

n 0 = successn > 0 = failure

tssinfo6.2

NAME

tssinfo6.2

This program offers information about the current settings such as your TSSlocale, 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 fileif not given.

Command: tssinfo6.2 –sfUser : bspTSS locale : KANJIEUC_AIX32TSS character set : KANJIEUCNLS locale : ja_JPFactor : 1

Multibyte strings:Database min. : 0x1Database max. : 0x9b217e7eForms min. : 0x20Forms max. : 0x9b217e7e

Single byte strings:Database min. : 0x1Database max. : 0x7fForms min. : 0x20Forms max. : 0x7a

EXAMPLE


Technical Manual

13-6

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


Technical Manual

13-7

Character set descriptionThe file tss6.2 in the directory $BSE/lib contains a description of the characterset. Normally this file is filled using the TSS Character Sets(%SEtttss0101m000) session.This file describes all supported character set 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 Convert 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 multibytecharacter.

setno Refers to the X-character set-number as defined in $BSE/lib/locale/LOCALE for display purposes. LOCALE is the currentlocale as defined in the user file.


Technical Manual

13-8

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 havecatastrophic results, and the changed conversion tables can corrupt your databeyond repair.

KANJI-EUC

Set(3, "KANJIEUC", "Japanese EUC"){# ASCII(range 0x1-0x7fstore 0x0bytes 1setno 1)# KATAKANA (JISX0208)(range 0x8ea1-0x8edfin &0x00ffout |0x8e00store 0x232100bytes 2setno 3)# KANJI (JISX0201)(range 0xa1a1-0xfefein &0x7f7fout |0x8080store 0x210000bytes 2setno 2)}

NOTE

EXAMPLE


Technical Manual

13-9

Locale informationThe file tss_locale6.2 in the directory $BSE/lib contains all possible TSS localesthat can be defined in the user file or specified with special commands, such astsscvt6.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 beNULL.

MbdbLow The lowest possible multibyte character value for databasestorage.

MBdbHigh The highest possible multibyte character value for databasestorage.

MBFormLow The lowest possible multibyte character value for forms (seethe expr function).

MBFormHigh The highest possible multibyte character value for forms (seethe expr function).

SBdbLow The lowest possible single byte character value for databasestorage.

SbdbHigh The highest possible single byte character value for databasestorage.

SBFormLow The lowest possible single byte character value for forms (seethe expr function).

SBFormHigh The highest possible single byte character value for forms (see the expr function).

# Japanese – HPUX 9.0KANJIEUC_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 bein the same line.

The directory $BSE/lib/locale contains files having names identical to the localenames, with character set information used to display the character set ranges. Aset is chosen by the setno entry in the tss6.2 character set description file. Thesefiles are managed by the Fonts (tttss0106m000) session.

EXAMPLE


Technical Manual

13-10

Taken from KANJIEUC_AIX

# character set display widthiso8859-1 1jisx0208.1983-0 2jisx0201.1976-0 1

The sequence number of these character sets is the value that is used as setnoentry in the tss6.2 file and in the TSS Character Sets (%SEtttss0101m000)session.

Storage of multibyte charactersNormally the characters are stored as TSS characters. However, you can alsostore the characters as native characters. To do that, the file tss_mbstore6.2 mustbe created in the $BSE/lib directory. That file contains the database fields, whosevalue or text must be stored as native instead of TSS characters.

native character : 8ea1TSS character : 9b238ea1

The file is processed in the following order. The asterisk (*) refers to all tables.

*ppmmm###ppmmm###.fieldppmmm###cccppmmm###ccc.field(p:package, m:module, #:table number, c:company number)

# entire table:ttaad320# only field stat from ttaad320000ttaad320000.stat

Do not store native data as SHIFT-JIS. This conflicts with the LDC (line drawingcharacters) and CF (code features) characters. It is better to store native data asKANJI-EUC. You can use the SHIFT-JIS character set for the user interfaceBX/BW. These programs have been designed to handle this conflict, by addingspecial flags to all stored characters.

For other parts of the BaanERP application it is problematic to store the SHIFT-JIS characters combined with LCD and CF characters. A good approach is tochoose tables for which data must be stored as SHIFT-JIS. These tables can bemanually added to the file tss_mbstore6.x.

EXAMPLE

EXAMPLE

Technical Manual

14-1

GeneralThis chapter introduces the audit management facility provided with BaanERPTools from Version 6.0 onward. It describes the audit server, the auditmanagement utility, and where audit data is stored. It also describes the structureof the audit files. Finally, this chapter explains how to give users permissions toprint, maintain, or clean audit data.

Storage of audit dataFor each table in each company number, the audit server uses a set of files tostore audit data. You can read audit files using the 4GL functions or thedictionary programs. This section describes the types of file that are used.

Sequence files

The audit data is stored in a set of files called sequence files. There can bemultiple sequence files per table per company number.

Apart from storing audit data and transaction information, a sequence file alsostores information about audited columns of the table, the audit data dictionary.

The name of the sequence file is built using the table name and companynumber. The format of the sequence file name, where prefix a indicates an auditfile, just as t indicates a table itself, is as follows:

a<mmmnnn><company number>.<sequence file number>mmm represents the module codennn represents the file number

For example for table ttadv999 and company 000 the sequence files are:

aadv999000.000aadv999000.001aadv999000.002aadv999000.003..........

For detailed information of the sequence file, refer to the section “Format ofaudit files.”

14 Audit management

Audit management

Technical Manual

14-2

Information file

There is one information file per table per company number, which:

n Stores information about all sequence files used for this table/companynumber combination

n Contains controlling information used to create and maintain sequence files

The name of the information file is based on the table name and the companynumber. The format of the information file name is as follows, where mmmrepresents 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 isaadv999000.inf.

There is one set of files per table name/company number combination. Thismeans that any associated information, sequence file, or operation is identifiedby the table name/company number combination. For the sake of readability thisdocument uses the word “table” to refer to a table name/company numbercombination.

Location of audit files

The file $BSE/lib/auditdef6.X is used to specify the location of the sequence andinformation files for the tables. Under the directory specified in auditdef6.X, asubdirectory is created for each module. Audit files for all tables in this modulefor all company numbers are stored in this directory, unless a different directoryis 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 directory/usr/adv/AUDIT/attadv. For all other tables, respective directories are createdunder /usr1/AUDIT. For example, atfacr is created for the BaanERP Finance acrmodule, atiitm for the BaanERP Industry itm module, and so on.

NOTE

Audit management

Technical Manual

14-3

There can also be an entry such as:

ttadv:*:/usr/adv/AUDIT/#

In this case all ttadv tables are stored under specific respective companynumbers. For example, for company number 000 the files are stored underdirectory /usr/adv/AUDIT/000/attadv.

Other parameters of audit files

The location of the audit files is controlled as explained in the section “Locationof 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 ofparameters in it, refer to Format of Audit Files.

Information fileThe tables for which audit trail is enabled can contain sensitive data such ascompany financial information. This means that the audit files also containsensitive data. Audit management contains a security mechanism by whichaccess to the audit data can be controlled according to user requirement.

A security level is defined per table/company number combination. Dependingon the security level, users can or cannot access or modify the audit data. Theaudit server reads the security level from the audit_spec file and stores it in theinformation file of the table. The central audit management utility (see the AuditManagement business object), uses this security level to control audit data accessand modification.

Sequence FileThe start and end sequence numbers for a table are specified in the audit_specfile. For example, if for table ppbdb000 within company 000, the start sequenceis 0 and the end sequence is 999, the table has the following sequence files:

abdb000000.000abdb000000.001....abdb000000.998abdb000000.999

Audit management

Technical Manual

14-4

For the same table, if for company 100 the start sequence is 1, and the endsequence is 50, the files are:

abdb000100.001abdb000100.002....abdb000100.049abdb000100.050

In principle, all audit data for a table/company number combination can bewritten to a single sequence file. But because this file becomes too big to manageproperly, 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 managementThe audit management version 6.2 incorporates the following features inBaanERP audit management utility:

n Audit data is stored in a set of files, instead of a single file. Multiple filesallow for better management than a single large file. See the section “Storageof audit data.”

n Each transaction is identified by a transaction header, which logs usefulinformation about the transaction, such as the corresponding user and time.Also, the data is organized per transaction. Each transaction has a headerfollowed by all audit data, which enables easy tracking of the changes thatusers have made.

n When the audit data is being written, information of audited columns intables 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.

n Table level commands affecting table data such as create table, clear table,and drop table, are also logged by the audit server.

n Audit management such as printing audit files and display audit sequences isdone by using the sessions belonging to the Audit Management businessobject.

Audit management

Technical Manual

14-5

Table data dictionary as seen by audit server

When a table data dictionary is created in a BaanERP environment, the audit trailcan be enabled for each column. This allows a user to audit a single column or allthe columns on the table.

The audit server is concerned only with audited columns of a table. It logs theinformation only for the audited columns. If a column is not audited, noinformation is logged for it. If the table has no audited columns, no informationis logged for the table. The file tabledef6.2 specifies the tables and columns forwhich audit is enabled. See also the section “Accessing tables” in the chapter ondatabase management.

For the rest of this chapter, it is assumed that all columns are to be audited unlessstated otherwise.

The audit data dictionary (the information of audited columns) is stored in thesequence header. This information is stored in a particular order of tablecolumns. First, information for all audited primary key columns is stored in theorder in which they form the primary key. Next, information of remainingaudited 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 containsinformation for the columns in this order: c4, c2, c1, c3, c6. For each column, theaudit data dictionary stores the column name without the table name prefix, fieldtype, size, and depth. The format of a column entry in the audit data dictionary isas follows:

Name Type Depth Size

NameStores column name without table name prefix.

TypeSingle byte indicating field type. The defines in BDB layer for field type areused, 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 samedefine as BDB_CHAR.

DepthSingle byte, indicating depth of the field.

Size2 bytes, indicating field size. For array fields this is the size total of all fields inarray.

Audit management

Technical Manual

14-6

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 ascreate 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 theaudit 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 othertable level commands such as change order, count rows, or create or drop index,because they do not change the table data in any way.

Data stored by audit server

Row operations

For row operations, the audit server keeps the values of audited fields.

Insert actionsThe new values of all audited fields to be inserted are stored in the audit file.

Delete actionsThe field values of the record to be deleted are stored in the audit file.

Update actionsTo comply with an application user requirement, the old and new values of thefields that are changed in an update are stored. Primary key field values are alsostored, even if they have not been changed. In addition, if any other auditedcolumn changes, its old and new values are stored. If an audited field is notchanged, and it is not a primary key field, its value is not stored in the audit row.

In addition to field values, a one-character code indicating the type of rowoperation is also stored.

Table operations

For table operations such as create table, drop table, and clear table, it issufficient to store only an indicator. The audit server stores a one-byte indicatorfor table operations.

Audit management

Technical Manual

14-7

Application data

In accordance with the application user requirement, the audit server keeps 4bytes extra space reserved in each audit row, to be used by application programs.Application programs are free to use this space for their own usage. This 4-bytespace is called application data. The audit server does not interpret theapplication data in any way.

Format of audit row

The format of the audit row in the sequence file is as follows:

Length Appl Data Action Data...

LengthA two-byte field that indicates the length of this audit row (excluding this fielditself).

Appl DataA four-byte field reserved for application program usage. The audit server, whenwriting a row, initializes this to nulls.

ActionA one-byte character code indicating the action done on the table. The followingcodes are available:

-C create table

-R drop table

-L clear table

-I insert row

-D delete row

-U update row

DataThe previous fields fulfill the audit requirement for table-level actions. No Datafield is included for table-level actions.

Audit management

Technical Manual

14-8

For row level actions, the important values of audited fields are stored as data, asexplained in the following sections.

Insert/Delete actionsValues of all audited fields are stored for insert and delete actions. They arestored in the same field order as that of the audit data dictionary of a sequenceheader. 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 actionsFor 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 datadictionary and not to the original table data dictionary. Suppose a table hascolumns c1, c2, c3, c4, c5, c6, with primary key (c4, c2), and all except c5 areaudited. The audit data dictionary contains information for these columns inorder c4, c2, c1, c3, c6. Thus the field number 0 refers to field c4 and not to fieldc1. Similarly field 3 refers to c1 and not to c3. For update actions, an audit rowlooks as follows:

Length Appl Data ’U’ Multiple field entries

A single field entry is as follows:

Field number Changed? Old value New value

Field numberA two-byte entry that indicates the field in the audit data dictionary.

ChangedA single-byte flag, used to indicate whether the field is updated or not. The fieldvalue for primary key fields must be stored, whether it is changed or not. Whenthe field value is changed, the corresponding flag is set to Y, otherwise it is set toN. The values for all other audited fields are stored in the audit row only if theyare changed, so for these fields, the flag is always set to Y.

Old ValueThe old value of the field that is being updated. For a primary key column that isnot changed, this is the only value stored.

New ValueIf an audited field value is changed, this represents the new value. For primarykey audited fields that are not changed, this field is not present in the audit row.

Audit management

Technical Manual

14-9

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 thefield 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 primarykey (c4, c2). If all columns except c5 are audited, the audit data dictionarycontains information for these columns in order c4, c2, c1, c3, c6. The fieldnumber 0 then refers to field c4, field number 1 is c2, and so on.

Create TableLength Appl Data ’C’

Here the length is the same for all tables, 5.

Drop TableLength Appl Data ’R’


Clear TableLength Appl Data ’L’


Insert RowLength Appl Data ‘I’ c4 c2 c1 c3 c6

Here c4, c2, and so on, indicate the values of the corresponding fields. Each fieldentry size is the size of the field itself.

Audit management

Technical Manual

14-10

Delete RowLength Appl Data ‘D’ c4 c2 c1 c3 c6

Update RowAssume 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 thefield is a primary key field. Its only value stored is c4.o, the old value. Becausec2 (field 1) and c6 (field 4) are changed, their old and new values are stored as .oand .n respectively.

Limit on the size of audit data

All audit data generated in a transaction for a table is always put in a singlesequence file. The transaction data is never split up across sequence files. If thecurrent sequence does not have enough space to write the transaction data (that isif its size exceeds the maximum sequence size), the audit server tries to write thetransaction data in the next sequence file. If the transaction data cannot beaccommodated in the entire sequence file, the audit server cancels thetransaction. If this happens, the application programmer must either reduce thescope 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 thetransaction. For example, if during a transaction 100 rows are inserted in a tableand then a commit is done, all the audit rows for the insert are buffered by theaudit server. This data is written to the audit files only at the time of commit.

The audit server uses individual memory buffers for each table. The size of thebuffers is set to enable them to hold large amounts of data. However, the memorybuffers might not be able to contain the results of a very large transaction. In thiscase, 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 sessionper server. Its name is made using the session ID and process ID (pid) of theaudit server, as follows:

ao.{Session Id>.<Process Id of the Audit Server>

Audit management

Technical Manual

14-11

A single overflow file is used to buffer data for all the tables in the session forwhich the memory buffers were insufficient. At the end of the transaction, if anytable has data in the overflow file. The overflow file is read and put in thecorresponding sequence file. After all data has been read and copied from theoverflow 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 theaudit server still has to use the overflow file, the transaction is too big. This canbe a flaw in application design or coding. If possible, such transactions must beavoided.

Sequence termination

The audit server uses a set of sequence files to store audit data for a table. Theaudit server switches from one sequence file to the next under the followingcircumstances.

Sequence file maximum size reached

Audit data generated in a transaction for a table is written to a single sequencefile. If the size of the transaction data exceeds the maximum sequence-file sizelimit for the current sequence, the audit server marks the current sequence file asterminated and writes the transaction data to the next sequence file.

Before the audit server switches to the next sequence, it ensures that themaximum possible space is available. If the transaction data for the table stillcannot be accommodated, then it cannot be put in any sequence file. This is anerror condition and the audit server cancels the transaction. Note that in this casethe current sequence is not terminated. When this error occurs, you can eitherincrease the maximum size of the sequence file or reduce the scope of thetransaction.

Table audit data dictionary changed

When the audit server starts using a sequence, it writes the audit data dictionaryto the sequence headers of the sequence file and the information file. Audit datain the sequence file depends on the audit data dictionary of that sequence. Forexample, for an insert/delete action, all audited field values are put in thesequence in the order in which they occur in the audit data dictionary. Forupdates, the field values are preceded by field numbers, which are offsets in theaudit data dictionary. The reading of audit data by the 4GL interface is alsodependent on the audit data dictionary of the sequence.

NOTE

Audit management

Technical Manual

14-12

If the audit data dictionary changes after the system writes some audit data to asequence file, you cannot continue using the same sequence. In this case, theaudit server stops using the current sequence and marks it closed while the auditdata dictionary has been changed. It starts using the next sequence.

Note that here the switch is made only if the audit data dictionary changes. Thisis different from changing the table data dictionary. Changing table datadictionary does not mean that the audit data dictionary is also changed.

Events that lead to changes in the audit data dictionary are in the followingexample.

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 containsinformation for these columns in order c4, c2, c1, c3, c6.

Consider the following changes:

Number of audited columns changedIf 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 havecolumn information in the order c4, c2, c1, c3, c5, c6. This is different from theaudit 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, c3and c6, which is different from the current audit data dictionary. As a result, asequence change occurs.

Order of audited primary key columns changedInitially the primary key was (c4, c2). If its definition is changed to (c2, c4), thenew audit data dictionary is c2, c4, c1, c3, c6. Because this is different from theaudit data dictionary of the current sequence, the audit server closes the currentsequence and uses the next sequence.

Order of other audited columns changedThe 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 dictionaryis c4, c2, c1, c6, c3. In this case the sequence order is changed.

Audit management

Technical Manual

14-13

Number of audited primary key columns changedYou can change the number of audited primary key columns without affectingany 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 datadictionary. But because c1 is now a primary key field, its value must be stored inan update action even if it is not changed. In earlier updates in the currentsequence, 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 currentsequence by using the central audit management utility (see the AuditManagement business object). Application programs can also terminate thesequence. In this case the terminating program sets the sequence end date andtime and the sequence status.

Transaction termination

When a transaction is started, the audit server buffers audit data until thetransaction ends. Depending on the manner in which the transaction is ended,two types of behavior are possible: simple commit/abort or two-phase commit.

Simple commit and abort

When doing simple commit, the buffered data for all tables in the transaction iswritten to the corresponding sequence file, one table at a time. For example,suppose a transaction involves four tables t1, t2, t3, and t4. When doing thecommit, first the audit data for t1 is written, then the data for t2, and so on. Whenthe data for all tables is written successfully, the audit server sends a successcode back to the client.

If writing data for any table fails, the audit server returns the E_BDB_ABORTerror to the client indicating that the transaction is canceled. If this happens andthe data is already written for some tables, it must be marked invalid. In thisexample, if the audit server fails to write data for table t3 after writing data fortables t1 and t2, the server changes the status of transactions for tables t1 and t2to ABORT_DONE.

If the client decides to cancel the transaction, the audit server just discards thebuffered data for the tables, if any. No data needs to be written for any table.

Audit management

Technical Manual

14-14

Two-phase commit protocol

Beginning with Tools release 6.1c, BaanERP supports the two-phase commitfunctionality for audit servers only. Two-phase commit is not supported fordatabase servers.

A three-part process takes place when an application issues a commit:

n Prepare audit drivers (first phase)n Simple commit to all database driversn Commit audit drivers (second phase)

Prepare audit drivers (first phase)To prepare for a commit, the system writes audit data to the audit files and setsthe PREPARE_DONE flag in the status field of the transaction header in thesequence files of the tables involved.

If the preparation for a commit fails for any one table during the update ofmultiple audited tables, the PREPARE_DONE is reversed. That is, theABORT_DONE flag is set for the tables on which the PREPARE_DONE wasset. PREPARE_DONE is not set for the remaining tables. The audit server issuesan E_BDB_ABORT error to the client to indicate that the transaction hasaborted.

Simple commit to all database driversNext a commit is issued to all the database drivers involved in the transaction. Ifthe commit fails for any of the database servers, the system issues an ABORT onthe remaining database servers. Because BaanERP does not support two-phasecommit for database servers, the system cannot issue an ABORT on the databaseservers for which the commit was already issued.

Commit audit drivers (second phase)After all database drivers have successfully committed, all audit servers involvedin the transaction are committed. A COMMIT_DONE flag is set in thetransaction status field of the transaction header for all the audited tablesinvolved in the transaction.

If the commit fails for any table, the transaction status field is set toABORT_DONE for all audited tables involved in the transaction, includingtables for which a COMMIT_DONE was set. When all the tables involved in thetransaction have both their PREPARE_DONE and COMMIT_DONE flags set,the transaction has been successfully completed and successfully audited.

Audit management

Technical Manual

14-15

How to use and set two-phase commit

If any of the audited tables involved in the transaction is specified in the file$BSE/lib/xchdef, the transaction performs a two-phase commit. Otherwise, thedecision is based on the resource variable dbcinit. If dbcinit is set to 01, two-phase audit commit is used for all audit transactions regardless of whether thetable is specified in the file $BSE/lib/xchdef.

If none of the audited tables involved in the transaction is specified in the filexchdef, and if dbcinit is not set to 01, a simple audit commit is performed for thattransaction.

Performing a simple commit is fast. But performing a two-phase commitguarantees that, if both PREPARE_DONE and COMMIT_DONE flags are set, afull commit is done.

For Drop Table and Create Table actions, two-phase commit is always usedregardless of whether the audited table is specified in xchdef file or dbcinit is set.

Format of $BSE/lib/xchdef6

The format of an entry in the xchdef6 file is as follows:

table_name:company_number:{Y|N}

ttadv:*:Ytiitm001:*:Yttaad410:000:Y*:*:N

In this example, two-phase commit is used for the following tables:

n all tables in the module ttadv for all companiesn table tiitm001 for all companiesn table ttaad410 for company 000 only

For other tables the decision is based on the setting of the dbcinit resourcevariable. If the xchdef6 file is not present, the system behaves as though the filewere present with the entry:

*:*:N

In other words, the decision is based on the dbcinit resource variable only.

EXAMPLE

Audit management

Technical Manual

14-16

Reusing sequence files

Suppose you have a table with start sequence 0 and end sequence 49, for a totalof 50 audit files. In the first run, each sequence file is created. After all 50sequences 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 ofoverwriting the file, the audit server then sends an error message saying that thefile must be deleted before the server can reuse the files. Thus when the reusefeature is disabled, an existing sequence file is not overwritten. You have todelete the file by using the Purge Audit Files (ttaad4161m000) session beforethe audit server can continue. If the reuse feature is enabled, the audit serveroverwrites any existing sequence file.

If you want to receive a message before the data in audit files is destroyed, youmust disable the reuse feature. This can be done by not specifying a SEQREUSEkeyword in audit_spec file. If you want to use the reuse feature, include thekeyword SEQREUSE in the audit_spec file.

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 thestatus of the sequence file is maintained in the sequence header in theinformation file. When this session deletes the sequence file, it also sets thestatus of this sequence in the information file as deleted. If the file is removed byany other means, the status is not set and this results in inconsistency.

File locking

When writing the data for a transaction, the audit server can close the currentsequence and start using the next sequence. Thus it can change the currentsequence field in the information file header. It also changes the sequence statusand sequence end time for the current sequence, and changes the status and startdate/time of the next sequence.

Even if the audit server does not switch sequences, it needs to change the currentoffset in the information header and the number of transactions in the sequenceheader. This means that it always changes the information header and thesequence header. Moreover, because the sequence header is maintained in thesequence file and information file, both of these must be changed.

NOTE

Audit management

Technical Manual

14-17

At the start of a transaction termination command for each table and beforewriting buffered data to the audit file, the audit server locks the information fileheader and sequence header in the information file and sequence file. The auditserver puts write locks on, so that no other read or write lock can succeed. Afterthe data for all tables is written, the locks on all tables are released. If there is anerror on any table, the status of transactions for tables already written is changedto 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 informationfile and one sequence file for that table. Once these are opened, they are keptopen for subsequent use even after the end of a transaction. These open files canbe used in all subsequent transactions involving this table.

Having so many files open, however, means that the server can reach theOPERATING SYSTEM limit of maximum open files per process. For example,if a transaction involves 15 tables, 30 files are opened at the end of thattransaction. If the next transaction has 10 different tables, 20 more files areopened. At the end of the second transaction 50 files are open, which is over themaximum limit.

When this limit is reached, the server closes two open files: the information fileand 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 thefollowing paragraph.

The audit server uses a data structure, called a handler, to keep track of the filedescriptors for the information and sequence files on each table. When these filesare opened, the file descriptors are stored in the handler. The handlers of alltables are kept in a linked list in an LRU manner. For example, when files arefirst opened, the handler is allocated and is put in most recently used (MRU)position. As other tables are opened, this handler moves toward the LRUposition. Later on, if this table is involved in another transaction, the samehandler is reused and is again moved to the MRU position. Also, when a file isopen, 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 thattable is guaranteed to stay in MRU position and in no way can it reach LRUposition.

If the audit server reaches the open file limit when opening a new informationfile, sequence file, or overflow file, it picks up the LRU handler in the handlerlist and closes its information file and sequence file. The assumption is thatbecause the table has not recently been used, it is the best choice as a victim forclosing files.

Audit management

Technical Manual

14-18

Opening large number of tables in single session

A session can update a large number of tables. On systems that have a smallmaximum number of open files, this can create a problem. Suppose a sessionwith a limit of 30 open files starts to update 50 tables. After opening theinformation and sequence files for the first 30 tables, the system reaches themaximum limit of open files. When files for table31 are opened, the LRU logic isactivated and files for table1 are closed. But table1 is itself in transaction and itsfiles are locked. When the audit server closes the files, the locks are released andother processes can alter the files. Now the same audit server may again need tooperate on the audit files of table1.

This means that the audit files for table1 need to be opened again. But if the fileswere changed in the meantime, the status is changed to ABORT_DONE. In thiscase, the audit server gives an error and cancels the transaction.

Multisession support

The audit server supports multiple sessions, which means that the same auditserver is used for multiple sessions within the client.

The audit data dictionary of a table is kept globally. The same table/companynumber in multiple sessions shares a single audit data dictionary.

The handlers (one used per table/company number combination) are kept inglobal lists. If multiple sessions operate on the same table/company numbercombination, 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 thatwrite permission is granted only to the Administrator user. Otherwise users otherthan Administrator can change the security parameter in the file, which wouldallow them illegal access.

Audit management

Technical Manual

14-19

Audit server debugging options

For debugging purposes, a code is put in the audit server at appropriate stages toprint useful information. In normal usage, this printing is not enabled. You canenable it by setting an environment variable AUDITLOG. You can print varioustypes of information by setting this variable to different values. The values mustbe set as octals.

0001 General information0002 Print audit rows generated0004 Print audit data dictionary for table0010 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 theserver. This file is created in the current directory of the audit server.

Audit errorsThe audit server uses the following error messages. If you receive one of theseerror messages, refer to $BSE/log/log.audit for more information regarding thecause of the error.

E_AUD_SETUP 251 The audit setup is not correct.This can occur if the specification in $BSE/lib/audit_spec file is not in properformat.

TOSEQ 6 SECURITY 28 MAXSEQSIZE 25K orNo table/company number combination

aa:00a:TOSEQ 6 SECURITY 28 MAXSEQSIZE 25KIncorrect company number.

*:*:TOSEQ 6 SECURITY 28 MAXSEQSIZE 5KThe maximum sequence size limit is less than the specified limits. Refer to thesection “Format of audit files” for details about the format of this file. It can alsomean that the current sequence file was illegally removed or that the sequencefiles were removed without using the 4GL interface. Audit files used during thefirst 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 ofsequence headers in information file and sequence file.

Audit management

Technical Manual

14-20

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 auditfile is locked before it can be modified, and the next user receives an errormessage.

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. Whentoo many files are opened and the maximum limit is reached, the LRU file isclosed. This error can refer to the file used in the transaction. When the file isreopened, the starting date time of the sequence header is checked with memorydata structure. If they are not the same, the E_AUD_ABORT error is returned.

AuthorizationsThe Administrator user grants audit security permissions to users using the AuditAuthorizations (ttaad4562m000) session, on the menu BaanERP Tools, AuditManagement. These permissions determine whether the user is allowed to usethe sessions in the Audit Management business object.

Security permissions assigned to users are checked against previously existingrecords to see if they conflict.

You can assign security permissions for all packages, modules, table numbers,and companies. You can give some permissions for all packages, and disablethese permissions by giving no permissions to a range of packages.

You can use the Specified command to give particular permissions to a specifiedpackage. By using Specified, the highest priority is given to the securitypermissions assigned for that particular package, module, table and company.

You cannot assign security permissions for a range within a range. Suppose youassign some permissions using the All command, then disable permissions for arange between tt—vv. You cannot then enable permissions within this range oran overlapping range. However, you can use the Specified command to enablethe 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 canaccess 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 forreading audit information. The user can have permissions at the user level but notfor reading the audit information. At audit level, the security permissions arestored in the audit information header of the audit information file.

Audit management

Technical Manual

14-21

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 differentcombinations. The Administrator user assigns its own permissions to print andclean audit information through the Audit Authorizations (ttaad4562m000)session, on the menu BaanERP Tools, Audit Management. The only sessionthe Administrator user is allowed to execute without being assigned any securitypermissions, is the maintain session. For example:

None No permissionsAll Print, clean, and maintain permissionsPrint Only print permissionsPrint/Clean Print and clean permissionsPrint/Clean/Maintain Same as All

None and All are mutually exclusive.

At Audit level the permissions can be granted in combinations exceptApplication defined. Only Maintain can be combined with Application-defined.

Print Only print permissionsPrint/Clean Print and clean permissionsPrint/Clean/Maintain Same as all permissionsApplication defined Access to some sessions restrictedMaintain/Application Only Maintain permission, no print and cleandefined permissions

The user is not allowed to print or clean up any audit information. To print,clean, or maintain the audit information from the audit files, the permissionsmust exist at both levels.

Permission at user level Print or print/cleanPermission at audit level Application defined

NOTE

Audit management

Technical Manual

14-22

The user is not allowed to Print or Clean up any audit information in the auditfiles using the sessions in the Audit Management business object. It is possible,however, to run the Audit Information File (ttaad4160s000) session, becausethe user has Maintain permission only at audit file level.

Permission at user level Maintain or Print/Maintain orClean/Maintain

Permission at audit level Maintain/Application defined

If the user is not Administrator and only Application-defined exists at the auditfile level, no session of the Audit Management business object can be executed.The Administrator user can use the maintain session even if no permissions areassigned to the Administrator user. However, the Administrator user cannot useprint and clean sessions unless security permissions are assigned toAdministrator.

If user bsp has Print permission at user level, a further check is made to see thesecurity permissions at audit level. User bsp is only allowed to continue if printpermission is available at the audit level. Otherwise the session is canceled andan appropriate message is displayed.

Format of audit files

auditdef6.2

This file is used to specify the directories in which audit files are created. Thereis one such file for each BSE environment, and it is located in $BSE/lib.

This file has following structure:

<Table Name>:<Company Number>:<Directory Name>

The following section lists the meaning of each field.

Table NameThis indicates the table. This can be in the following formats:

"*" – This means all tables in all packages.

Package – This means all tables in this package. For example tf, td etc.

Package & Module code – All tables in the module. For example, tccom,ttadv.

Package, Module and table number – for example ttadv999, tccom010.

Audit management

Technical Manual

14-23

Company NumberTables can be chosen based on company number. For example:

* – All companies.

100 – Company 100 only.

100,000 – Company 100 and 000.

DirectoryDirectory in which the audit files are stored. Under this directory, anotherdirectory is created, called:

aPackage + Module Code

Information file

There is one information file per table per company number. You can read theinformation 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 thesequence files created.

The format of the information file name, where mmm means module code andnnn 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.

Information headern Version Information

Used to store the version information. This must never be modified by theapplication by any means.Length: 4 bytes

n Table nameThe table for which audit information is stored.Length: 8 bytes.

n Company NumberThe company of the table.Length: 2 bytes.

Audit management

Technical Manual

14-24

n StatusSpecifies whether sequence reuse is allowed or not.Length: 1 byte.

n From Sequence NumberAudit data is stored in sequence files specified from this value.Length: 2 bytes.

n To Sequence NumberThe last sequence file after which sequence reuse is started, or the user musttake appropriate action, such as deleting the existing file before reusing them.Length: 2 bytes.

n End Sequence NumberSpecifies the last sequence written in the information file. This field is forinternal use by Audit Server only! The user must never change this field,otherwise the audit server will not work correctly.Length: 2 bytes.

n Max. Size of 1 audit file in BytesSpecifies the maximum file size of a sequence file.Length: 4 bytes.

n Security LevelThis lists the users who have access to the information in the audit files. Thesecurity permissions regarding access to audit information are stored here.Length: 2 bytes.

n Current Sequence NumberDetermines the current sequence number that is used to write the audit data inthe sequence file.Length: 2 bytes.

n Offset in current sequence file.Specifies the offset in the current sequence file where the audit data iswritten.Length: 4 bytes.

n Reserved spaceSpace that is reserved for future use. Application programs must never usethis space because it might be required for a future release of the audit server.Length: 8 bytes

n Length of following sequence headerLength: 2 bytes

Audit management

Technical Manual

14-25

Sequence HeaderEach sequence file also begins with a sequence header. The information filecontains copies of sequence headers for all sequences created.

n Sequence NumberThis specifies the sequence number of the sequence file.Length: 2 bytes.

n Creation DateThis specifies the creation date of the sequence file.Length: 8 bytes, format: YYYYMMDD.

n Creation TimeThis specifies the creation time of the sequence file.Length: 6 bytes, format: HHMMSS.

n Termination DateThis specifies the termination date of the sequence file.Length: 8 bytes, format: YYYYMMDD.

n Termination TimeThis specifies the termination time of the sequence file.Length: 6 bytes, format: HHMMSS.

n StatusThe status gives information to the user whether the sequence file was userterminated, closed because of a data dictionary change, or closed becausetransaction data could not be accommodated in the sequence file.Length: 2 bytes.

n Number of transactions in the sequenceThis specifies the data of number of transactions present in the sequence file.Length: 2 bytes.

n Application Information – 1Application Information – 2Application Information – 3Application Information – 4

These bytes are reserved for storing data specific to the application. If theapplication needs to store any information in audit files, these fields are usedto store that information.Length: 4 bytes, per application information field.

n Number of fields being auditedThe total number of fields that are being audited.Length: 2 bytes.

Audit management

Technical Manual

14-26

n Number of fields in primary indexIndicates how many fields are in primary key.Length: 1 byte.

n Field Name (Length: 8 bytes), Field Type (Length: 1 byte), Field Depth(Length: 1 byte), and Field Length (Length: 2 bytes)Field information for all fields that are being audited. First, the fields that arepart of the primary index are written in the same sequence as in the primaryindex. Next, all remaining fields are written in the order in which they occurin the table data dictionary.

For example, if fields f1, f2, f3, f4 are being audited and the primary index ison f4, f2, then field information is written first for f4, then for f2, and then forall remaining fields.

n Reserved spaceThis space is reserved for future use.Length: 8 bytes.

n Length of following sequence headerLength: 2 bytes.

Sequence file

Multiple sequence files are used to store audit data for each table/companynumber combination. You can read the sequence files by using the 4GLfunctions or the dictionary programs. The format of the sequence file name,where mmm refers to the module code and nnn means table number, is asfollows:

a mmmnnn company number.sequence file number

For example, these sequence files can exist for table ttadv999, company number0:

aadv999000.000aadv999000.001aadv999000.002aadv999000.003....

The sequence file contains the table name and company number, followed by thesequence header. This is followed by transaction data of multiple transactions.Transaction data is followed by a transaction header and contains multiple auditrows generated for the transaction.

EXAMPLE

Audit management

Technical Manual

14-27

Sequence File Layoutn Table Name

Length: 8 bytes

n Company NumberLength: 2 bytes

n Length of sequence headerLength: 2 bytes

n Sequence Header

n Transaction Header

n Transaction Data (Audit rows)





n ....

Transaction Header FormatYou need to log both the operating system user ID and the BaanERP user name.This is because a user can change the USER environment variable and usedifferent BaanERP user names. Also, different BaanERP users can have differenttable privileges in SQL databases. Programs can find the operating system logonname by using the operating system user ID print.

Operating system user id 4Baan User Name 8Date ( YYYYMMDD ) 8Time ( HHMMSS ) 6Session 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 valuesfor these flags can be found in the audit include file.

PREPARE_DONE

GATI_UTC_FLDS

EXAMPLE

Audit management

Technical Manual

14-28

Transaction Status 1Number of audit rows in the transaction 2

Also since Baan IVc, the following fields are added at this position.

{GATI 0 4GATI 1 4Commit Date ( YYYYMMDD ) 8Commit Time ( HHMMSS ) 6Reserved space 8}

Total bytes of data of this transaction 4

You need to log both the operating system user ID and the BaanERP user name.This is because a user can change the USER environment variable and usedifferent BaanERP user names. Also, different BaanERP users can have differenttable privileges in SQL databases. Programs can find the operating system logonname by using the operating system user ID print.

n Operating system user IDLength: 4 bytes

n BaanERP user nameLength: 8 bytes

n Date (YYYYMMDD)Length: 8 bytes

n Time (HHMMSS)Length: 6 bytes

n Session nameLength: 15 bytes

n Transaction statusLength: 1 byte. The transaction status can have the following values:

COMMIT_DONE

ABORT_DONE

n Number of audit rows in the transactionLength: 2 bytes

n Total bytes of data of this transactionLength: 4 bytes

Audit management

Technical Manual

14-29

Transaction Data FormatThe format of the audit row is as follows:

{Length of the row 2{ SNAT 4}Application Data 4Type of operation 1Row Data ...

}

n Length of the row (Length: 2 bytes)n SNAT (Sequence Number of action in Audit Transaction) (Length: 4 bytes)n Application data (Length: 4 bytes)n Type of operation (Length: 1 byte)n Row data

Four bytes of space are kept in every audit row to store application data. Thisdata 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 ofoperation is a single character field, indicating the database action performed onthe table.

The following characters are used to indicate audited database actions.

n C – Create tablen L – Clear tablen R – Drop (remove) tablen I – Insert rown D – Delete rown U – Update row

In the audit row, the row data is present only for row level actions. The fieldvalues, when stored, are stored in the same format as their data type. This meansthat a value for a long field is stored as a long data type in the audit row. Thelength 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 auditedfields, 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 andof 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 fieldvalues, an identifier is required to specify the field to which this data belongs.

Audit management

Technical Manual

14-30

Field numbers are used for identifying the fields. The field number is its positionin the AUDIT data dictionary, starting with field 0.

An entry for a field contains the following information:

n Field number – 2 bytesn Is the value changed – 1 byte (Y or N).n Old valuen New value

If a field is changed here, both old and new values are stored. If an auditedprimary key field is not changed, only the old value is stored. If other auditedfields are not changed, nothing is stored. For all changes made to all auditedfields, entries are made to the audit data.

n Transaction statusLength: 1 byte. Transaction status can have the following values:

− COMMIT_DONE− ABORT_DONE

n Number of audit rows in the transactionLength: 2 bytes

n Total bytes of data of this transactionLength: 4 bytes

Transaction Data Format:n Length of the row (Length: 2 bytes)n Application data (Length: 4 bytes)n Type of operation (Length: 1 byte)n Row data

Four bytes of space is kept in every audit row to store application data. This datais stored and manipulated by 4GL applications and not by the audit server. Theaudit server keeps the 4 bytes of extra space to be used later. The type ofoperation is a single character field, indicating the database action done on thetable.

The following characters are used to indicate audited database actions.

n C – Create tablen L – Clear tablen R – Drop (remove) tablen I – Insert rown D – Delete rown U – Update row

Audit management

Technical Manual

14-31

In the audit row, the row data is present only for row level actions. The fieldvalues, when stored, are stored in the same format as their data type. This meansthat a value for a long field is stored as a long data type in the audit row. Thelength 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 auditedfields, 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 andof 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 fieldvalues, an identifier is required to specify the field to which this data belongs.Field numbers are used for identifying the fields. The field number is its positionin the AUDIT data dictionary, starting with field 0.

An entry for a field contains the following information:

n Field number – 2 bytesn Is the value changed – 1 byte (Y or N).n Old valuen New value

If a field is changed here, both old and new values are stored. If an auditedprimary key field is not changed, only the old value is stored. If other auditedfields are not changed, nothing is stored. For all changes made to all auditedfields, entries are made to the audit data.

audit_spec file

The audit_spec file is used to specify audit file parameters. There is one such filefor 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.

n Table NameIndicates the table. The table name can have the following formats:

*All tables in all packages.

PackageAll tables in this package, for example tf, td, and so on.

Audit management

Technical Manual

14-32

Package & module codeAll tables in the module, for example tccom, ttadv.

Package, module and table numberFor example ttadv999, tccom010.

n CompanyThis can be in one of following formats.

*All companies.

100Single company for example, company 100 only.

100,000Comma-separated list of companies, for example, company 100 and 000.

n SpecificationsThe following specifications can be put in the file.

Start sequenceThis is specified by the keyword FROMSEQ or fromseq. The start sequenceis always 000. The user cannot change this.

To sequenceThis is specified by the keyword TOSEQ or toseq followed by a sequencenumber. Note that there must be a space between the keyword and thesequence number. For example:

TOSEQ 999 or toseq 999

If the end sequence is not specified for a table/company combination, thedefault is 999.

Maximum sequence file sizeThis is specified by the keyword MAXSEQSIZE or MAXSEQSIZEfollowed by a size specification. Note that there must be a space between thekeyword 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 Mmust be uppercase only and there cannot be a space between the number andthe specification character.

Audit management

Technical Manual

14-33

If the maximum sequence size is not specified for a table/companycombination, the default is 512K.

Whether sequences can be reused or not.If existing sequences can be reused without deleting them first, the keywordSEQREUSE or seqreuse must be put in the specifications. If you do notwant this, do not put the keyword in the specifications. If this is not specifiedfor 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 securitynumber. Note that there must be a space between the keyword and thesecurity specifications. For example:

SECURITY 4 or security 4

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 becombined with Maintain permissions only. Note that these specifications can beput in any order.

The audit_spec file must have a default entry covering all tables/companynumbers. This can be done with an asterisk (*) for table and company numberfields. 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 2Mtt:000:seqreuse toseq 49 maxseqsize 1Mtf: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 permissionfor the Administrator user only. Otherwise users other than Administrator canchange the security parameter in the file, which would allow them illegal access.

CAUTION

NOTE

Audit management

Technical Manual

14-34

Technical Manual

15-1

GeneralOLE Automation is an industry standard that applications use to expose theirOLE objects to development tools, macro languages, and other applications thatsupport OLE Automation. For example, a spreadsheet application can expose aworksheet, chart, cell, or range of cells—all as different types of objects. A wordprocessor can expose objects such as application, document, paragraph, sentence,or selection.

When an application supports OLE Automation, the objects it exposes can beaccessed by Visual Basic. You can use Visual Basic to manipulate these objectsby 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 canwrite 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, theapplication using those objects is called an OLE Automation client.

15 OLE Automation

OLE Automation

Technical Manual

15-2

In fact the OLE Automation interface can be compared to the C Interface ofBaanERP. Where the C Interface offers an interface from other C programs toBaanERP, OLE Automation offers an interface from other MS-Windowsapplications to BaanERP. The implementation is based on the BaanERP 4GLfunction parse_and_exec_function in the same way as the C Interface.

BaanERP as OLE Automation serverIn combination with the BW user interface, BaanERP is also an OLEAutomation server. The BaanERP application exposes an object through whichclients can call BaanERP dynamic link library (DLL) functions. This sectiondescribes how you can create and use this BaanERP object.

The BaanERP application exposes just one object, which is the applicationobject. In Visual Basic this object can be created with:

Set BaanObj = CreateObject("Baan.Application")

This starts BaanERP with the BW user interface invisibly, in other words onlythe 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 toperform a certain action. A property is an attribute that has a value. Propertyvalues can be set and/or retrieved.

The BaanERP application object has the following methods:

n ParseExecFunction “dllname”, “functioncall”n Quit

The BaanERP 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

Technical Manual

15-3

These methods and properties allow Visual Basic programmers to call anyfunction 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 function myfunction in the DLL named mydll. Note howarguments are passed to myfunction. If arguments are passed by reference theycan be changed by the function call, therefore the property ReturnCall containsthe modified arguments after the call.

The property Timeout is used to prevent blocking on erroneous calls. Theproperty Error contains the return status of the ParseExecFunction call, and theproperty ReturnValue is the actual return value of the DLL function. If the DLLfunction 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 totrue. ReturnCall can contain null characters.

Possible values for the property Error are:

n 0 success

n -1 unknown DLL name

n -2 unknown function name

n -3 syntax error in function call

n -10 timer expired

n -11fatal error in function

To end an automation session you can quit a BaanERP application as in thisexample:

Set BaanObj = Nothing

OLE Automation

Technical Manual

15-4

RestrictionsWhen you use the OLE Automation interface, you must consider the followingrestrictions:

n Due to the 3GL function parse_and_exec_function, you cannot supplyarrays as arguments to a DLL function.

n DLL functions with a variable number of arguments or optional argumentsare not supported.

n When a string is passed by reference, the result cannot become longer thanthe input string. When a string must be filled make sure it is initialized withthe same number of spaces as the maximum length that can be returned. Themaximum length is defined in the domain of the variable.

n The maximum size of the FunctionCall string is 4KB (Bshell limit).

n The maximum size of the ReturnValue string is 4KB (Bshell limit).

n Two client applications cannot simultaneously use the same BW to makeDLL function calls.

Example: Import BaanERP usersThis example fills an MS-Excel spreadsheet with the names of all BaanERPusers. To do this, you must:

n Implement DLL functions to obtain the names of the users from the database.n Implement some Visual Basic code in MS-Excel.

OLE Automation

Technical Manual

15-5

DLL function example

The following DLL, called demo.dll, contains two functions that retrieve thenames of the users from the database. One function initiates the query and getsthe first name, and the other gets the next name. When the last record has beenreturned, 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

Technical Manual

15-6

Visual Basic example

MS-Excel contains Visual Basic for Applications (VBA), which allows forscripting to control both the Excel application and other applications throughOLE Automation. The following is the Visual Basic source that calls the DLLfunctions and displays the results in a spreadsheet. The subroutineGetBaanERPUsers is an MS-Excel macro that can be invoked through buttons ormenus on the spreadsheet.

Dim user As String

Dim BaanObject As Object

Sub GetBaanERPUsers()

On Error GoTo CannotConnectToBaanERP

’ run BaanERP

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

Technical Manual

15-7

user = BaanObject.ReturnValue

Wend

’ exit BaanERP

Set BaanObject = Nothing

Exit Sub

’ error handling

CannotConnectToBaanERP:

MsgBox "Unable to connect to BaanERP"

Exit Sub

BaanAutomationError:

MsgBox "A BaanERP automation error occurred"

Set BaanObject = Nothing

Exit Sub

End Sub

Example: Using BaanERP SQLThe following example fills an MS-Excel spreadsheet using BaanERP SQL. Toimplement this, a DLL called ottdllsql_query has been developed to parse andexecute the query. To receive more information about this library, enter thefollowing command:

*> bic_info6.2 –eu ottdllsql_query

DLL information

The DLL ottdllsql_query contains:

n Functions to parse, execute, and stop a query:− olesql_parse− olesql_fetch− olesql_break− olesql_close

n Functions to import query results into Visual Basic:− olesql_getstring− olesql_getint− etc

OLE Automation

Technical Manual

15-8

n A function to convert an Easy SQL query to a string:− easysql_to_olesql

n 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 BaanERP users on thespreadsheet Worksheet Users. To use it, press the button on the Worksheet Usersthat starts this macro. For more information refer to the Visual Basic code inWorksheet Module 1.

The second macro, GetItemCount, shows all item groups in BaanERP with thenumbers of items per item group on the spreadsheet Worksheet Itemcount. Pressthe button on the Worksheet Itemcount to start this macro. To run the macro youhave to insert an Easy SQL query in the BaanERP Application. To insert thequery, start the Query Data (ttadv3580m000) session, insert a record nameditem and choose Maintain Query by Text Manager. In the text editor enter thefollowing query:

select tiitm001.citg, | Item group

count(tiitm001.item) | Item

from tiitm001 | Item data

group by tiitm001.citg

order by tiitm001.citg

For more information refer to the Visual Basic code.

BaanERP Toolsbaansupport.com/docs/Baan5/BaanERP-5.0b-Tools-Technical-Manual.pdf · Oracle 9-2...

Documents

Transcript of BaanERP Toolsbaansupport.com/docs/Baan5/BaanERP-5.0b-Tools-Technical-Manual.pdf · Oracle 9-2...