[
http://issues.apache.org/jira/browse/DERBY-879?page=comments#action_12364154 ]
Stan Bradbury commented on DERBY-879:
-------------------------------------
The following email prompted the filing of this JIRA entry:
===== Feedback on the initial Derby experience ====
Here are my UCD [User Centered Design] comments on getting started with
Cloudscape 10.1.
My Cloudscape 10.1 installation experience
I downloaded the .exe install program for Windows, ran it, read the release
notes, and even read the installation instructions on the download page. So as
far as I know, Cloudscape is installed successfully on my machine.
Now what? The installation instructions from the download page say that "You
should also review Getting Started with Cloudscape in the user documentation.
This information is especially important in helping you use Cloudscape 10.1"
But they don't point me anywhere specifically. So I'm stalled with nothing to
read, and nothing to run.
I don't think that I should need to do research to use Cloudscape. The
instructions should flow linearly until I'm creating tables, inserting data,
and running queries. I know what relational databases can do, so how do I do
those things with Cloudscape? Don't know.
So with enough searching on the web, I found the Getting Started guide. The
first thing it wants me to is to see if the Java executable is in my path. It's
not. It wants me to update the path, but isn't telling me how. I can never
remember this sort of thing so more research required ... thank goodness for
Google.
OK, my path is now set and the java -version test works correctly.
The documentation wants me to run sysinfo. It also says that I need the /bin
directory in my path. I had just included the JVM's bin directory in my path,
but the command fails anyway:
'sysinfo' is not recognized as an internal or external command,
so it must mean some other /bin directory. But it doesn't say which one, so
time to start guessing...
Hey, look at that. I found a bin directory - and a sysinfo.bat file - way down
in the subdirectory:
C:\Program Files\IBM\Cloudscape_10.1\frameworks\NetworkServer\bin
I don't know what a "framework" or a "NetworkServer" is, but I'll guess that
this is the right directory. (Since I took the default location during
installation, it might have been helpful if the docs suggested a location. Or
even a relative location.)
So I'll add another directory to my path - it's getting long - and then try it
again.
Well, something changed. When I run sysinfo now, it says:
Could not connect to Derby Network Server on host localhost, port 1527.
and appears to hang. Oh, it just returned to the prompt. Hmm, back to the
Getting Started guide...
Let's try the "ij" command instead. Whoah, it didn't like that. I got a twenty
line error message from that one. I'll skip the rest of this "ij" section and
scroll down in the Guide.
Scrolling down farther, I find the section on manually setting environment
variables and paths. The previous automatic (?) method didn't work for me, so
I'll try manual.
The book says that a base directory was created during install, for example
"Derby_10". Nope, no such directory on my computer. There is a directory
"Cloudscape_10.1" on my computer. That must be it.
Wait a minute. It says I should do the following
set DERBY_INSTALL=c:\Derby_10
Should I set DERBY_INSTALL to the Cloudscape_10.1 directory or should I create
CLOUDSCAPE_INSTALL instead? I'll split the difference, and set DERBY_INSTALL to
the Cloudscape directory. There's nothing to test, so I'll go onto the next
section.
OK, the Set the Classpath section is confusing. It suggests I use scripts - and
gives me a directory location - but it doesn't actually say which scripts. Then
it immediately shows me how to do it manually. So which should I do? Since I
don't know what the script files are named, I'll try the manual command:
C:\>set
CLASSPATH=%DERBY_INSTALL%\lib\derby.jar;%DERBY_INSTALL%\lib\derbytools.jar;%CLASSPATH%
What does my CLASSPATH look like?
C:\>echo %classpath%
"C:\Program Files\IBM\Cloudscape_10.1"\lib\derby.jar;"C:\Program
Files\IBM\Cloudscape_10.1"\lib\derbytools.jar;%CLASSPATH%
That's odd. I've got a trailing %CLASSPATH% string in my classpath definition.
I'll ignore it.
Now let's try sysinfo again:
C:\>java org.apache.derby.tools.sysinfo
OK, a whole bunch of output. I'll declare success and move on to the "ij"
command.
The documentation is telling me to run the following command:
ij> connect 'jdbc:derby:<dbname>;create=true';
where <dbname> is "the name of the database you are connecting to". Huh? What
database? Cloudscape? I thought that I was using Cloudscape. And what does it
mean by "connecting to"? I'm afraid to run this command. Who cares anyway, this
command apparently doesn't do anything useful.
ij> exit
hey, it's just hanging there. Oh, forgot the semi-colon.
ij> exit
;
now it exited.
I still want to create some tables, insert some data, and run a couple of
queries. But as I read the rest of the book, I don't find any instructions on
how to do that. I can only find instructions on how to use JDBC. Pity, I'd have
hoped that Cloudscape would have allowed me to issue interactive SQL commands.
Guess it doesn't have that capability.
OK, it's the next day, and I'm rereading the Getting Started guide again. I
found the description of what you can do with "ij" in terms of creating
databases and executing SQL statements. Yea! So I'm going to try that:
java org.apache.derby.tools.ij
ij> connect 'jdbc:derby:rollerdb;create=true';
And that's as far as the Getting Started guide takes me.
I have a long script file, and I need to see which SQL statements in the script
fail. The manual says that I can redirect output to a file. Good.
By redirecting output to a file:
java -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver
org.apache.derby.tools.ij <myscript.sql> <myoutput.txt>
So I'll do the command
C:\Roller data>java -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver
org.apache.derby.tools.ij createderbydb.sql output.txt
Usage: java org.apache.derby.tools.ij [-p propertyfile] [-ca connectionAttribute
PropertyFile] [inputfile]
Bummer, didn't work. According to the error message, I can't have an output
file?
I did finally get to the point where I could execute SQL statements and even
run a script file. But considering that I came into this already knowing SQL,
I'd argue that it took me longer than it should have. Very possibly due to my
lack of Java or other skills, but that will still impact Cloudscape/Derby
adoption.
> The Getting Started Guide is incomplete (section: Installing and working with
> Derby) and so not helpful to new users
> --------------------------------------------------------------------------------------------------------------------
>
> Key: DERBY-879
> URL: http://issues.apache.org/jira/browse/DERBY-879
> Project: Derby
> Type: Bug
> Components: Documentation
> Reporter: Stan Bradbury
>
> The "Installing and working with Derby" chapter of the Getting Started Guide
> is incomplete and so not useful to a new Derby user (see user feedback
> attached in the comments). This entry contains documents for each section
> (html page) of this Chapter what needs to be changed (marked PROBLEM) and
> things that would be helpful to add (ENHANCEMENT). The items marked PROBLEM
> should be addressed ASAP.
> Chapter "Installing and working with Derby" - First page
> >> http://db.apache.org/derby/docs/dev/getstart/cgsinsta.html
> Describes the sections in the Chapter. Update as necessary to reflect
> changes in section titles and order.
> SECTION: Installing Derby
> >> http://db.apache.org/derby/docs/dev/getstart/cgsinstallingderby.html
> No major problems
> ENHANCEMENT: example showing the naming convention of a bin archive is needed.
> SECTION: Setting up your Java environment
> >> http://db.apache.org/derby/docs/dev/getstart/tgssetupjavaenvir.html
> OK if java is setup properly in the PATH.
> PROBLEM: Command examples need to be added to Item 2 to resolve problems with
> the PATH.
> PROBLEM: The problem of not having a JDK installed is not covered.
> PROBLEM: Under Related Topics - remove the link to: "Manually setting
> environment variables and paths"
> SECTION:Using the tools and startup utilities
> >> http://db.apache.org/derby/docs/dev/getstart/cgsusingtoolsutils.html
> This is not a Getting Started subject. Reduce the scope of this to IJ and
> SYSINFO
> PROBLEM: Title is not accurate
> PROBLEM: dblook, export/import, database class utilities are not Getting
> Started Topics - remove references
> PROBLEM: the scripts listed require DERBY_INSTALL be set in order to work as
> shown in the following sections
> PROBLEM: /frameworks/embedded/bin is not a valid directory (need
> DERBY_INSTALL)
> PROBLEM: Only setting PATH for UNIX is identified - this is required for
> WINDOWS in order for the scripts to work as shown in the following sections
> PROBLEM: the /bin directory does not exist, be explicit
> (DERBY_INSTAALL/frameworks/embedded/bin)
> SECTION: Using sysinfo
> >> http://db.apache.org/derby/docs/dev/getstart/cgsusingsysinfo.html
> PROBLEM: In the standard distribution of Derby (the 'bin' distribution) the
> script DOES NOT set the appropriate environment as stated on this page.
> ENHANCEMENT: An example and explanation of the output is needed.
> SECTION: Running ij
> >> http://db.apache.org/derby/docs/dev/getstart/tgsrunningij.html
> PROBLEM: In the standard distribution of Derby (the 'bin' distribution) the
> script DOES NOT set the appropriate environment as stated on this page.
> PROBLEM: Incorrect statement: "You must include the /bin directory in your
> PATH environment variable to run ij." This refers to running the IJ script.
> ENHANCEMENT: An example of a simple select is needed.
> ENHANCEMENT: State that the command will not execute until a semicolon is
> typed.
> SECTION: Manually setting environment variables and paths
> >> http://db.apache.org/derby/docs/dev/getstart/cgsmanuallysetting.html
> PROBLEM: DERBY_INSTALL and CLASSPATH are key variables and should be
> discussed before SYSINFO and IJ.
> PROBLEM: This statement is very confusing: "This document assumes that
> directory is named Derby_10" . Also it is not good to use a version number
> here, what about the next release?
> PROBLEM: This is incorrect: "The classpath is a list of the class libraries
> needed by the JVM " reword as something like 'libraries available to' or
> 'known to' or something.
> ENHANCEMENT: Introduce NoClassDefFoundError exception here
> ENHANCEMENT: Better title needed
> SECTION: Set the DERBY_INSTALL environment variable
> >> http://db.apache.org/derby/docs/dev/getstart/tgs36360.html
> PROBLEM: /frameworks/embedded/bin does not exist (need DERBY_INSTALL).
> PROBLEM: Unix command example not provided to set variable
> ENHANCEMENT: use full path names for directories (e.g. C:\Derby_10)
> SECTION: Set the classpath
> >> http://db.apache.org/derby/docs/dev/getstart/tgs26250.html
> PROBLEM: This is incorrect: "The classpath is a list of the class libraries
> needed by the JVM " reword as something like 'libraries available to' or
> 'known to' or something.
> PROBLEM: /frameworks/embedded/bin directory and /frameworks/NetworkServer/bin
> do not exist (need DERBY_INSTALL).
> PROBLEM: Unix command example not provided to set variable
> PROBLEM: Though nice, the bullets about manually running SYSINFO and IJ are
> not tied into the topic of CLASSPATH.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
