Contents Lab128 - Tools for Advanced Oracler Tuning and Monitoring. Reference Guide.

Installation and Setup

System requirements.

Installation. Option 1 - Portable.

No administrator privilege is required to install Lab128 in this option. To install, just extract files from into some directory and run lab128.exe. That's all! lab128.exe is a digitally signed file; MS Windows automatically checks the integrity of the file when it is invoked. The program does not use the Windows registry, as all settings are stored in text files in the directory where Lab128 was started. It is advisable to create a dedicated directory, for example C:\Program Files\Lab128, and keep files there. This directory should be writeable to allow for the saving of user preferences. To uninstall Lab128, simply delete the Lab128 directory.

Note. In Windows 7 standard users have read-only access to Program Files. If you choose to install Lab128 into C:\Program Files\Lab128 directory, use 'workdir' parameter in the command line when starting Lab128 to indicate a directory with read/write access. For example:

lab128.exe workdir="C:\Documents and Settings\username\lab128"

Of course, if you are going to run Lab128 as administrator (not recommended), there are no such restrictions.

Installation. Option 2 - Traditional.

We also included a traditional way of running setup.exe which installs Lab128 interactively. It also registers Lab128 in the Windows registry and then can be seen in the list of installed software. This installation option may require administrator privilege. However, no administrator privilege is needed to run Lab128. The program can be uninstalled running uninst.exe or from the Control Panel "Add or Remove Programs".

Note. The setup.exe will offer to install Lab128 into C:\Program Files\Lab128 directory. In Windows 7 standard users have read-only access to Program Files. If you choose to install Lab128 into C:\Program Files\Lab128 directory, on the first start Lab128 will offer to create %APPDATA%\lab128 directory and use it as working directory. As alternative, you can manually create a working directory for Lab128 and use 'workdir' parameter in the command line when starting Lab128 to indicate a directory with read/write access. For example:

lab128.exe workdir="C:\Users\username\Application Data\lab128"

Upgrade from previous versions.

Files supplied in this package should overwrite files of the same name from the previous version. All setting files from the 1.5.x version are compatible with the new version. As an alternative, you can install this new version into a new directory and, if you wish, copy all setting files into this directory. This way you can run both versions.

Upgrade from pre- Lab128 on Windows 7.

If you have been running a pre- version of Lab128 on Windows 7, and it was installed in the C:\Program Files\Lab128 directory, you will need to take extra steps. Windows 7 restricts access to the Program Files directory. Many software programs developed before Windows 7, including pre- Lab128, write files (settings, logs, saved state) to restricted locations, such as \Program Files. In order to support legacy software, Microsoft has added a compatibility option. When the application attempts to write into these restricted locations, Windows 7 redirects (virtualizes) access to a per-user location. Therefore, there is a high probability that an older Lab128 version kept its setting files in the VirtualStore folder. Typically, it is "C:\Users\username\AppData\Local\VirtualStore\Program Files (x86)\Lab128".

This restricted access to the program binaries in Windows 7 deserves credit and makes the OS more secure. On the other hand, the compatibility option makes things somewhat unexpected and confusing. Starting from version, lab128.exe includes a UAC (User Account Control) manifest, which indicates that Lab128 is a Win7-aware application, ensuring no compatibility support will be provided. No hidden redirection to the VirtualStore folder will happen.

You will need to create a working directory for Lab128 and manually copy files from the current location in the VirtualStore. Then start Lab128 with the 'workdir' option in the command line pointing to this new directory.

What to do on "Cannot write into this working directory: ..." error

Lab128 stores its settings, state, and log data in the working directory. This directory must have read/write access. First, Lab128 tries to use the directory it started from as a working directory. If this directory doesn't have read/write access, then Lab128 tries to locate %APPDATA%\lab128 directory. If this directory exists, it will be used as a working directory. If it doesn't exist, it will be created with your approval. As alternative, use 'workdir="path" parameter to overwrite the default location.

If you received this error after the upgrade, please read Upgrade from pre- Lab128 on Windows 7 section.

If Oracle client is version 9 or earlier, or no Oracle client installed.

We highly recommend Oracle client version 10 or newer, because older versions had multi-thread related bugs. Oracle client 10g can work with older Oracle servers (from 8.1.7). If you don't want to upgrade Oracle client or there is no Oracle client installed, all that Lab128 needs is two Oracle DLL files copied into Lab128 directory: oci.dll and oraociicus10.dll (or oraociicus11.dll for version 11). We are planning to provide these two files in future packages, please check these files may be already in the directory, in this case you don't need to do anything else. If these files are missing, you can obtain these two DLLs by downloading Oracle Instant Client from Oracle site and then extracting files from the ZIP file, or you can download these DLLs from our site:

Version - 6,635,306 bytes -
Version - 10,283,780 bytes -

Required minimum privileges.

You can use an existing account to connect to Oracle or you can create a new account dedicated to Lab128. In both cases, the account should be granted SELECT ANY DICTIONARY role (Oracle 9+), or an equivalent set of grants in earlier Oracle versions. The account should be able to query v$, dba_, and$ tables (such as sys.fet$ etc.). A dedicated account is recommended for security reasons to make it is easier to grant a bare minimum of required privileges.

If you monitor Oracle 10g and later, and wish to run Automatic Workload Repository (AWR) reports - 10g equivalent of Statspack reports, and Active Session History (ASH) reports, then grant OEM_MONITOR role to the account used by Lab128. If you decide to grant DBA role to this account, then DBA role already has all needed privileges and there is no need to grant any other roles.

Here is a script that creates an Oracle account:
create user LAB128
identified by <password>
default tablespace <TS_NAME>
temporary tablespace <TEMP TS_NAME>;
grant CONNECT to LAB128;
grant OEM_MONITOR to LAB128;      -- for 10g and later, see comments above.
grant ALTER SYSTEM to LAB128;     -- only if this account should be able to kill a session.
grant SELECT ANY TABLE to LAB128; -- this is needed for EXPLAIN PLAN 
                                  -- for queries on tables in other schemas.

Plan Table.

Note. Most of Oracle 10g or later installations don't need this step. You can check that by running select * from plan_table query. If you don't get an error, then PLAN_TABLE is already created.

If you plan to use Explain Plan for SQL statements, the Oracle user should have PLAN_TABLE table created in its own schema. Use the script below or $ORACLE_HOME/rdbms/admin/utlxplan.sql script to create this table:

alter user LAB128 quota 10M on <TS_NAME>;
create table LAB128.PLAN_TABLE (
  statement_id varchar2(30),
  timestamp    date,
  remarks      varchar2(80),
  operation    varchar2(30),
  options       varchar2(255),
  object_node  varchar2(128),
  object_owner varchar2(30),
  object_name  varchar2(30),
  object_instance number,
  object_type varchar2(30),
  optimizer varchar2(255),
  search_columns number,
  other_tag       varchar2(255),
  partition_start varchar2(255),
  partition_stop varchar2(255),
  partition_id number,
  other long,
  distribution varchar2(30),
  cpu_cost number,
  io_cost number,
  temp_space number,
  access_predicates varchar2(4000),
  filter_predicates varchar2(4000),
  projection varchar2(4000),
  time number
tablespace <TS_NAME>;

Session Tracing.

If you plan to use the "Trace On / Off selected session" feature in the Session Details window, grant the 'execute' privilege on the SYS.DBMS_SYSTEM package. This grant must be done by the SYS user:

grant execute on DBMS_SYSTEM to LAB128;

Suggested x$ views.

Although it is optional, we suggest making some fixed tables available for Lab128. Below is the script that creates views and grants 'select' privilege on them to the PUBLIC user. This script should be run by SYS user:

-- This part needs to be executed by SYS. 
-- In case when you are re-creating these views, use "create or replace view" variation:

create view sys.x_$ksled as select * from x$ksled;
grant select on sys.x_$ksled to PUBLIC;
create public synonym x$ksled for sys.x_$ksled;

create view sys.x_$kslei as select * from x$kslei;
grant select on sys.x_$kslei to PUBLIC;
create public synonym x$kslei for sys.x_$kslei;

create view sys.x_$bh as select * from x$bh;
grant select on sys.x_$bh to PUBLIC;
create public synonym x$bh for sys.x_$bh;

create view sys.x_$kcbwds as select * from x$kcbwds;
grant select on sys.x_$kcbwds to PUBLIC;
create public synonym x$kcbwds for sys.x_$kcbwds;

create view sys.x_$ktfbue as select * from x$ktfbue;
grant select on sys.x_$ktfbue to PUBLIC;
create public synonym x$ktfbue for sys.x_$ktfbue;

create view sys.x_$ktsso as select * from x$ktsso;
grant select on sys.x_$ktsso to PUBLIC;
create public synonym x$ktsso for sys.x_$ktsso;

-- X$KSUSECST - this view is not needed for Oracle 10g and up
create view sys.x_$ksusecst as select * from x$ksusecst;
grant select on sys.x_$ksusecst to PUBLIC;
create public synonym x$ksusecst for sys.x_$ksusecst;