I am attempting to more fully document our database packages as an API. What we would like is something like JavaDocs for PL/SQL. I have seen a couple tools out there (pldoc, plsqldoc) but would like to know from people who use them how they compare.
I have used PlDoc and find it really good. I haven't used any other tools so can't compare. I found PlDoc did the basics well. I wanted some more advanced features so I built our own tool that added extensions to PlDoc for more tags. Also I don't just do documentation with it I also generate our package headers using some PlDoc tags (e.g #private).
I recommend you try PlDoc then tweak whatever doesn't meet your needs. It doesn't take that long to set up so its not a huge time investment to try it.
I've been using NaturalDocs for a few years now and have found it easy to install and use.
It's pretty much like JavaDocs and supports multiple languages although I've only used it with PL/SQL.
Very configurable although I've not found it necessary to fiddle with that.
Related
I am trying to learn some more about GitLab CI/CD and wanna write a specific Stage like "wrap_packages", where a specific list of .sql-Files is given and these scripts should be wrapped to .plb, to copy&paste them into a specific folder.
Everything is working so far, but now i have to implement the wrapping. I guess i have to use an image, with Oracle Middleware, to use the wrap-command? Or is there a better way to do this? Because i cant find anything that helps me with this.
I hope you can help me with this.
The wrap utility either exists in the full OCI client installation (not instant client), or within the actual database as an API. The simplest way to wrap your code is using the database API, after it is installed, as demonstrated here: https://github.com/pmdba/code-obfuscation-toolkit. There are a variety of ways that this could be incorporated into your CI/CD pipeline.
If you're looking for a more robust commercial (licensed $$$) solution, consider PCFLObfuscate (http://www.petefinnigan.com/products/pfclobfuscate.htm). It has a command-line option that integrates well with CI/CD.
A question that must also be asked is why you want to obfuscate your code with "wrap"? At best obfuscation only slows down someone who wants to see your code, as it is rather easily undone (at least the wrapping part). Deeper obfuscation (as provided by PFCLObfuscate, for example) actually changes the formatting of your code, your variable names, etc. before wrapping to make it much harder to tell what is going on even after it is unwrapped.
It is important to understand that there is no level of protection available for PL/SQL that can prevent someone with access to the wrapped code from unwrapping it and seeing the actual PL/SQL.
Is there something similar to a standard library for modern ABAP (maybe even OO-Abap)? For example a curated list of objects that address some of the most common programming tasks like
high-level data structures (not just plain internal tables)
working with file paths and directories
working with files (reading, saving, ...)
working with different file types (text, csv, xml, ...)
regular expressions
working with the environment (client, application server)
...
My current workflow is to stumble upon a problem like getting the extension of a file from a filename (or something fairly similar and easy). Then I have three options:
Dig through a ton of (mostly old and lacking) posts on SDN until i maybe find a pointer to solve the problem
Hack away and create a one-off solution to the problem
Take my time and implement a good and well documented solution
Many times I feel a bit lost. A lot of the available information is old, bad or both. Is there a more structured approach to tackle the problem of finding a suitable abstraction in the ABAP-world?
To answer your first question no, unlike C, C#, Java, there is no need to include a library since all the functions are always available to you, so in that regards it might be simpler. What you are asking though is a great question, I am sure you probably see tons of queries in SDN for "Is there a Function module for?" etc.
There isn't an easy answer but In SAP ABAP I think the easiest way might be to find this is by looking at packages. Similar to a library by looking at a package for the type of function your looking for might get you there. For example if I am looking for handling files I might look for the control framework package and there I can see all the available functions/classes/methods/BAPIs etc. that are related to front end controls/file handling etc. and might be able to find what I am looking for. Note its not perfect as the way packages are used has changed from time to time so its actually better for finding functions related to for example purchasing or sales etc. but its one way that we use.
Like other languages in that we still need to know what library to link in to get the function you need, in ABAP you just have to find the related package. Hope it helps a little, I know its not perfect. Example package for front end controls
For working with the environment:
If you have access to SAP there is a transaction code called BAPI
Here you could find a hierarchical list of all the main objects in SAP (i.e. Material, Purchase Order, etc)
In this list you could find documentation, the function modules used for the object (i.e. créate/get detail/update etc)
And digging into the function modules could take a look to the structures, receiving parameters, etc
The other questions are a little bit complex, I am not aware of any comprehensive list but digging into SCN usually is easy to find a solution for the most common things like handling files, etc
In the particular case of regular expressions, SAP native language, ABAP, has keywords for handling them, but you also have a class in SAP called CL_JAVA_SCRIPT which you could use for doing thigs in "JavaScript way"
For example I used this class in the past to evaluate a simple formula provided in a string (i.e 3 + 2 * 5 )
This is an operation really complex to do in ABAP but easy to do in JS.
Hope it helps
SAP Reuse Library (SE83) is the most close thing to what you are looking for. It provides common development tasks grouped in hierarchy (UI controls, standard dialogs, confirmation prompts) and contains code snippets for each with commonly used classes/modules:
Though, it is incomplete and lacks many popular things.
Consider also DWDM, BIBS, LIBS transactions and other packages in this link.
we can generate ER diagram in SQL developer which help us in understanding of tables in a better way.
Like this Is it possible we can generate some kind of document which can give us overview of what a package/procedure/function is doing?
I'm asking this because in my project we have very long packages like 10000 lines and to read them consume lot of time. If we can generate some kind of document for understanding it will be very helpful.
As far as my experience is concerned there is no tool available which will generate documentation out of PLSQL code (just by reading the code without any comments).
However, I would like to mention the following tools and you can consider using them if they are of any help.
Pldoc
Pldoc is an open-source utility for generating HTML documentation of code written in Oracle PL/SQL.
http://pldoc.sourceforge.net/maven-site/
However, you will have to provide comments in your packages and functions in PLdoc style to ensure that documentation gets created.
Toad's Code Xpert
http://www.toadworld.com/products/toad-for-oracle/w/toad_for_oracle_wiki/11088.code-complexity-analysis-using-toad
This tool will perform an automated review on your code and provide a report. It will also provide a CRUD matrix which you might find useful.
PLSQL Doc Plugin
https://www.allroundautomations.com/plsplsqldoc.html
Similar to PLdoc.
Natural Docs
http://www.naturaldocs.org/
Open-source documentation generator for multiple programming languages.
There is no silver bullet - you cannot automagically create documentation for code.
Worse - the "auto-doc" tools typically look at comments, but there's no guarantee the comments match the code.
However, "working with legacy code" is a common problem. You might want to read this answer, and the book it refers to.
I'm happy with this (new) tool: https://github.com/teotiger/pldocu
It's limited and I miss some automatic export formats (e.g. html), but you can try to do this by yourself. For me it's okay.
If there is some sort of debugging API that would allow someone to write his own code coverage analysis tools that would be acceptable as well. I don't believe this is a poll question because the exhaustive list of such tools is probably quite small.
There are no readymade coverage tools (afaik). However, you might be able to utilize the MONLBL facilities (here). These were introduced to be able to identify performance hotspots.
It would be interesting to look into the code of these, as the necessary hooks to create a code coverage tool are quite similar to the ones you need to create the performance monitoring. If you have access to the WRC I strongly recommend to raise this with ISC, it definitely sounds like something many people could use!
HTH
edit: come to think of it, since monlbl gives you the # of times a line is executed, it's a code coverage with benefits ;) So, the answer is: yes, there are
debuging in Cache' Studio.
there is also ^PERFMON
I was wondering if anyone has seen a library that abstracts away SQLite and Tokyo-Cabinet to the same API. Basically I'm looking for something that will allow me to test and dev with SQLite, and later move to TC for production.
Anyways the language I'm using specifically is Lua, but I'm sure such a library doesn't exist for Lua, so a Library that does this in any other language is also ok since I can develop something similar for Lua based on that.
DataMapper, the default ORM for Merb (written in Ruby), might help. Take a look at an experimental DataMapper adapter for Tokyo-Cabinet. DataMapper's already got SQLite3 support so you may be able to compare the two.
I don't know for sure, but since Carbonado supports RDBMSs (Oracle) and "persisted b-trees" (BDB), it could definitely support both.