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.
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.
So if you are looking for special information, here is a short overview on what to find where:
- Code formatting hints are covered in CodeArrangement
- OracleForms deals with specifica of Oracle Forms
- Details on how to use Javadoc best can be found in JavaDoc
- Configuration issues are handled in Configuration
If you feel some information missing here, please let me know. The easiest (and best) way to do this is to open a ticket.
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.
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.inifile for [[Configuration]. Optionally make a copy, and adjust it to your needs
HyperSQL.pywithout any parameter (uses
HyperSQL.inilocated 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
HyperSQL.pywith the name of your project as only parameter, like
HyperSQL.py myProject. This would use
myProject.iniif found, otherwise
myproject.ini– and if that's not found either, fall back to HyperSQL.ini
HyperSQL.py --helpto find out about more command line options (version 2.9 and higher)
That's it - enjoy!
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?
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.
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.
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.
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.