Skip to content
This repository has been archived by the owner on Aug 1, 2019. It is now read-only.

Usage

Jump to bottom
Izzy edited this page Jan 29, 2018 · 1 revision

This part of the documentation will give some hints on how to use HyperSQL. Topics like Installation, Configuration, JavaDoc, Syntax Highlighting and Localization are dealt with in the other parts of the documentation.

Background

First some background information, which should help you to better and easier understand the details following.

HyperSQL was originally developed by Randy Phillips back in 2001. After its release in the very same year, there have been no updates until I continued development in 2010 (take it binary, and it's just the next number), Randy handing me over all resources. He might have had different ideas of the final state of the program, such using approaches which where perfect for those but might be a bit hindering now. Nevertheless, it would mean a complete rewrite to change them – so for now I chose to live with the possible limitations caused by those rather than spending long time to re-organize everything (time which I don't have).

One of these things is the linewise processing of code: HyperSQL does no complete SQL syntax analyzis. To find objects, it simply walks the code files line by line looking out for declarations such as e.g. CREATE TABLE xxx. Obviously all code Randy was concerned about was bundled in packages – so functions and procedures were only looked for if a package declaration was met. No stand-alone functions/procedures were expected. They are still not handled today (at version 3.4.5) – the special problems with those stand-alone objects are described in Object Order.

At another task, this linewise processing has already been replaced by a full file scan: Looking where objects are used. While switching to regular expression search for more accuracy considerably slowed down this process, switching from walking line-by-line to a full file scan fully compensated for the loss.

And before you ask (you might already have guessed that): The naming conventions for the generated HTML files of objects are bound to historic reasons as well. I know, this makes it almost impossible to have "steady links" to the page describing an object (and I don't like that idea either) – but currently it is the way it is. At least this is an issue I hope to address in a later version.

Overview

So if you are looking for special information, here is a short overview on what to find where:

If you feel some information missing here, please let me know. The easiest (and best) way to do this is to open a ticket.

Oracle Forms

What is done?

Support for Oracle Forms in HyperSQL is limited, and mostly to PL/SQL code fragments stored within. The goal here is to cater for dependencies (what other database objects are addressed by Forms – i.e. for the forms themselves, only the what_used pages and info will be generated), to make identification of unused non-Form elements easier. But as for the PL/SQL code contained within the forms, it will otherwise be processed almost the same as any other SQL – which especially means it can be hyperlinked, highlighted, and included in your pages, plus JavaDoc markup is possible and will be interpreted. For non-PL/SQL-code objects, only some raw statistics will be gathered and printed along with the form details.

Speaking of statistics: The statistics page will currently ignore Oracle Forms completely. This might change in the future – but for now, there was not yet decided on a strategy: How to let the forms be presented in "lines of code"? How to count their lines after all (only PL/SQL code lines, or the lines of the XML document)? Should there rather be a separate section for file sizes (as forms are usually much larger than other code fragments)? These are just some of the questions still open.

Preparations

HyperSQL cannot process any binary Oracle Forms files directly, but requires them to be converted to XML first. For *NIX users, it ships with a small Shell script for this purpose – which you can find in doc/frmf2xml.sh. Windows users usually find a similar batch file (frmf2xml.bat) shipped with their Oracle Forms installation. Both scripts require a valid Oracle Forms installation to run. Basically, they can simply be called with the binary forms file to process as only parameter - for additional parameters, please see your Oracle Forms manual.

Concerning basic coding conventions (and what is the best way to ensure HyperSQL should handle your code correctly), the same rules mentioned in code arrangement apply. For Javadoc, please see the corresponding page as well.

That's it – now you just need to enable forms processing in your *.ini file, and make sure the generated XML files are found to be processed.

Running the script

There's not much to say about:

  • Check the HyperSQL.ini file for [[Configuration]. Optionally make a copy, and adjust it to your needs
  • Run HyperSQL.py without any parameter (uses HyperSQL.ini located in the directory you are in) to parse the code from below the directory you specified in HyperSQL.ini, and generates HTML in the specified output directory
  • Run HyperSQL.py with the name of your project as only parameter, like HyperSQL.py myProject. This would use myProject.ini if found, otherwise myproject.ini – and if that's not found either, fall back to HyperSQL.ini
  • Run HyperSQL.py --help to find out about more command line options (version 2.9 and higher)

That's it - enjoy!

CodeArrangement

Of course you are free to write your code in any way you like – still it is best practice to follow at least some basic coding guidelines. Which ones apply, may differ a lot. So here only details important to HyperSQL will be explained.

Keywords and non-keywords

Whether uppercase, lowercase or mixed doesn't really matter for HyperSQL to identify objects – as for this task all comparision is done case insensitive. Still, common use has at least keywords written UPPERCASE – while others are not. These others may be lowercase or mixed, which is all up to you.

So if I just say it's all up to you – why to use that many words? There is a case where this is important for HyperSQL: Syntax highlighting. Keywords will only be identified if they are spelled UPPERCASE. I hope you don't mind me forcing you a bit to a clean coding style?

Line breaks

Put them in as much as you like and were you feel them convenient. A good idea is to use them to emphasize logical units (such as functions and procedures, or even loops and conditionals). But one place where you better not put them is in the middle of a declaration. Giving an example:

/** Synonym FOOUTIL for the function FOO.UTIL
 * @synonym fooutil
 * @author John Doe
 */
CREATE OR REPLACE SYNONYM fooutil
   FOR foo.util;

This is quite well formatted and easy to read. What I say – it's perfect to be processed by HyperSQL! But a bad habit would be to introduce additional line breaks after CREATE and after REPLACE - this would ensure HyperSQL to not recognize it (remember it processes your file linewise). So for HyperSQL, it is best to keep everything from CREATE up to the objects name on one line.

Object Naming

Again, case sensitivity does not matter. Nor do parenthesis e.g. around table names. Just the naming OWNER.OBJECT is currently not handled by HyperSQL – this may or may not be added in the future.

Object Order

In general, this is not important – but there are special cases when packages come into play: As already noted, HyperSQL does no complete syntactical analyzis of the code – but simply walks it line by line, scanning for declarations. Thus elements of a package, say e.g. a function, is counted as member of the package last declared.

This means, if you would declare a stand-alone function following a package within the same file, HyperSQL would add it to the package. Sure that is wrong, but HyperSQL cannot tell this. So if you have to keep those objects within the same file, packages should come last after all other objects.

Even better organization would mean to spread objects over multiple files, as many/most larger projects are either do - up to the extent of having only one object (function, procedure, package...) per file.

Oracle Forms

Here it is much easier to tell objects apart, since they are usually encapsulated within separate units (<ProgramUnit> tags). Code within each unit, as you write it, should follow the other rules above (keywords, line breaks) though.

For more details on Oracle Forms, please see OracleForms.

Clone this wiki locally