4.3.1 What's On the Disk?

You'll see the following four files on the disk provided with this book:

disk.id

Contains label information (product name and version number)

plvlite.001

Compressed PL/Vision Lite software and online companion reference

read.me

Instructions for acquiring a non-Windows version of PL/Vision Lite

setup.exe

Executable file that installs the PL/Vision Lite program files (contained in plvlite.001).

4.3.2 Storage Requirements

To determine how much space you will need in the SYSTEM tablespace to install the PL/Vision packages, I ran the following script in my own PL/Vision account:

SELECT type, 
       SUM (source_size) source_size, 
       SUM (parsed_size) parsed_size, 
       SUM (code_size) code_size
  FROM user_object_size
 WHERE name LIKE 'PLV%'
    OR name = 'P'
 GROUP BY type
 ORDER BY code_size DESC
/

This script accesses the USER_OBJECT_SIZE data dictionary to sum up the total size of source code (source_size), parsed code (parsed_size), and compiled code (code_size). The results are shown below (and may vary according to the final state of the code at time of publication):

SQL> start plvsize
SEF
TYPE                   SOURCE_SIZE         PARSED_SIZE        CODE_SIZE
--------------- ------------------ ------------------- ----------------
PACKAGE                      57840               92017            28795
PACKAGE BODY                266737                   0           312596
TABLE                            0                2498                0
sum                   ------------         -----------        ---------
                            324577               94515           341391

This output indicates that you will need a total of approximately 750,000 bytes in the SYSTEM tablespace to store PL/Vision.

4.3.3 Beginning the Installation

In a Windows environment, double-click on the setup.exe file to run the installation program. (If you are working in some other environment, see the read.me file for instructions.) The installation scripts will lead you through the necessary steps. The first screen you'll see is the install screen shown in Figure 4.1.

Figure 4.1: PL/Vision Lite install screen

The next screen will prompt you to specify the folder from which you want to be able to invoke PL/Vision. You can accept the default or specify the appropriate folder name (directory) for your own system. Once this step is complete, the icon named PL_Vision Lite Online appears in the folder you've specified. Double-click on it to start using the product. You'll see the main menu shown in Figure 4.2.

Figure 4.2: PL/Vision Lite main menu

At this point, all of the source files PL/Vision needs will be installed on your disk in the following three subdirectories.

install

Contains source code for all of the packages of PL/Vision.

test

Contains test scripts to execute PL/Vision code.

use

Contains additional scripts to execute PL/Vision code more easily or perform other handy tasks.

Section 4.6, "Summary of Files on Disk", later in this chapter, lists these files.

You can now access the PL/Vision Lite Online Reference, as described in the next section. To actually execute PL/Vision code, however, you will need to compile the PL/Vision packages into your database. This process is described in Section 4.3.5, "Creating the PL/Vision Packages".

4.3.4 Using the PL/Vision Lite Online Reference

Now you're ready to use the PL/Vision Lite Online Reference to browse the code. There are two ways to use this reference:

1. Zoom in on the package of interest to obtain a general overview of the package or to find out the syntax for a particular element in the package.

2. View the source code for a PL/Vision package specification or body directly through the Online Reference. As you look at the directory of packages, you can press a button that will let you scroll through the PL/Vision source code.

I would recommend reading the book with the Online Reference up and running on your personal computer. As you come to a chapter about a PL/Vision package, bring up the source code for that package on your screen. That way you will be able to move instantly from a topic in the text to the code being referenced.

4.3.5 Creating the PL/Vision Packages

You can install PL/Vision in three different ways:

1. Install PL/Vision into and use it from a single Oracle account.

2. Install PL/Vision into each Oracle account that is going to take advantage of PL/Vision functionality.

3. Install PL/Vision into a single Oracle account and make its functionality available to other Oracle accounts through GRANTs and the creation of synonyms.

The first option is viable in small development environments. The second option requires lots of maintenance (you will have to reinstall or upgrade PL/Vision in each of the accounts). The third option is the one selected by most development organizations using PL/Vision.

If you do want to install PL/Vision into a single account and then share it across Oracle accounts, you should grant the SELECT ANY TABLE privilege to the PL/Vision account (a.k.a., PLVISION). If you do not take this step (shown below), you will find that several PL/Vision utilities will not work as desired.

Specifically, utilities like PLVvu.err (to display compile errors), PLVvu.code (to display stored code) and the PLVddd package (to reverse engineer DDL) will not return the desired results because of the way Oracle data dictionary views are defined. A number of the ALL_* views upon which the standard PL/Vision packages are defined restrict access to information about other accounts. The only way that PL/Vision can retrieve and display the information you will want from a shared perspective is by accessing the DBA_* data dictionary views.

So before you install PL/Vision, decide how you plan to use and share this product and grant privileges accordingly. Then take the following steps:

1. Choose or create an Oracle user account into which the PL/Vision packages and tables will be installed (hereafter referred to as the PL/Vision account). You can use a preexisting account, but you are probably better off installing all software in a "fresh" account. The recommended name for the PL/Vision account is PLVISION. You should not use PLV or any other name which is also a PL/Vision package name. Any of those names could cause compile errors and inconsistent behavior.

   To install and execute PL/Vision properly you will need to able to create tables, indexes, and synonyms, create packages, and read the DBA_* data dictionary views. You can grant these roles and privileges from SQL*Plus or you can use products like Oracle Navigator in Personal Oracle7.

   At a minimum, the PL/Vision account should be granted the CONNECT and RESOURCE roles. If you are going to share PL/Vision across accounts, you will also want to grant the SELECT ANY TABLE privilege. For example, if the SYSTEM account is a DBA account with a password of MANAGER, you would take these steps in SQL*Plus:

   SQL> connect system/manager
   SQL> grant select any table to PLVISION;

   You also need to make sure that the PL/Vision account has EXECUTE authority on DBMS_LOCK. To accomplish this, connect to your SYS account and issue this command:

   GRANT EXECUTE ON DBMS_LOCK TO PLVISION;

   where PLVISION is the name of your PL/Vision account.

2. Set the default directory in SQL*Plus to the directory containing the PL/Vision software. Connect through SQL*Plus to the PLV account.

3. Run the PL/Vision package installation script. If you are running an Oracle Server Release 7.2 or below, run the plvinst.sql file as follows:

   SQL> @plvinst

   This script will create all packages and write the log of this activity to the plvinst.log file. If you are running Oracle Server Release 7.3 or above, run the plvins23.sql script as follows:

   SQL> @plvins23

   The installation script will create all packages and write the log of this activity to the plvins23.log file.

The version of PL/Vision Lite installed with plvins23.sql recognizes and makes use of the UTL_FILE package to perform operating system file I/O.

The remaining installation steps apply to installing PL/Vision for use by other users in your database.

4.3.6 Granting Access to PL/Vision

If you want to share PL/Vision among other users, run the plvgrant.sql script to grant execute authority on the PL/Vision packages. To grant execute authority to all users, execute the following command:

SQL> @plvgrant public

To grant execute authority to a particular user, execute the following command:

SQL> @plvgrant user

where user is the name of the user to whom you want access granted. Once you have granted access to PL/Vision packages from outside the PLV account, you will also probably want to create synonyms so you don't have to reference the PLV account by name when you call a PL/Vision program.

To create public synonyms for each of the PL/Vision packages, execute the plvpsyn.sql script from the PLV account as follows:

SQL> @plvpsyn connect_string

where connect_string is the connect string of a DBA account from which public synonyms can be created. The string may consist of the user name or user name/password combination. The plvpsyn.sql script will connect into that account and run a generated script of CREATE PUBLIC SYNONYM statements.

To create private synonyms for each of the PL/Vision packages, execute the plvsyn.sql script from the PLV account as follows:

SQL> @plvsyn connect_string

where connect_string is the connect string of the account for which private synonyms will be created. The string may consist of the user name or user name/password combination. The plvsyn.sql script will connect into that account and run a generated script of CREATE SYNONYM statements for that user.