Hi,
one only has to pass the calls to functions in the library "PDFlib Lite 7", to do that?
...heck, how am I supposed to know? :-P
I only went thru the documentation halfway...
Please provide the link to the actual library again.
http://www.pdflib.com/en/download/free-software/pdflib-lite-7/ (PDFLib 7 Lite sources)
http://www.pdflib.com/developer/technical-documentation/manuals/ (PDFLib manuals, i.e. version 7)
http://hobbes.nmsu.edu/download/pub/os2/dev/pdflib302.zip (port of -vintage- PDFLib 3.0.2 on hobbes)
How should each function behave when the user doesn't follow the exact schoolbook example?
e.g. one doesn't want to provide all the info, in the function pdfStartDoc( title, author, comments, keywords ).
How should it handle situation where the user just provide 1, 2 or 3 of the parameters?
What if no parameter will be provided?
Should it return a list of taken handles then?
Can we reuse some of the functions to behave differently if the input contain fewer/more parameters?
e.g. return information in some situations, default to something (next "row") etc.
Well, we can argue about the meaningfulness of making parameters mandatory if that comes at the price of having to deal with error-handling of missing mandatory parameters.

I prefer a very "relaxed" handling here: Something is missing or doesn't make sense? Use internal/override defaults! This means that if we have missing parameter values, the DLL will use an internal value where it makes sense.
(Of course, we cannot use "defaults" for print coordinates - this doesn't make sense - but for "author" we could use the literal "SYSTEM" or "NOT SPECIFIED" when missing. Same for title: "UNNAMED" or whatever.)
Keep in mind that the focus of this DLL would be the creation of PDFs - not the validation of syntactical and semantical correctness of parameters.

Should some functions allow for input of stems as well?
Especially those functions that contain coordinates.
Keep it simple and stupid!

I don't think stems are required at this point... if you have a list of coordinates, you would have to iterate it and pass one x/y pair at a time.
I prefer simple function syntax and greater flexibility. I hate the unix'ish style of making things more and more complex because it shows how cool you are "Hey, look what I can do with *1* call only, if I use these 475 parameters along with it!".
That crap was introduced by spot-faced, highly intelligent nerds which have the time to explore and tweak 1 algorithm over 4 weeks...(because they don't have girl friends) - but not by people who have to solve programming tasks in a quick and easy way.
Possible to manipulate more than one PDF at the time as you indicate that the function pdfStartDoc( title, author, comments, keywords ) should return a handle?
Should the user be able to specify an associated "name" for the handle as an option as the actual handle anyway will be passed around internally by the rexx library?
(rexx only use plain text to represent variables, so "handles" and other non-integer/non-character parameters has to be either converted or associated with a "name")
pdfStartDoc( title, author, comments, keywords[, doc_handle ] ) RETURNS doc_handle
Well, when I said "handle" I had an integer value in my mind which is used for reference between rexx and the DLL. Do as you please. A name? Sounds good. I'll take what I can get as long as it does what I want.

Let's say the script take a long time to complete adding data because it wait for information from ... somewhere.
Does the underlying library allow that or should all data be provided before the actual output?
If so, can you add a pdfPrint( doc_handle ) or pdfCreate( doc_handle ) that does the actual printout/creation.
Oh, pretty easy:
We have to distinguish between
- sending commands to the DLL
- writing of a PDF file
- sending something to a printer
Output on paper is clearly out of scope. The solution creates a PDF file.
First, we send a couple (or bunch) of commands to the DLL. The DLL internally creates a "context". Imagine this like a in-memory representation of a picture. This picture has one or more pages containing text and graphics. This context is open and available until the PC crashes, the DLL crashes, or the document is closed.
Once the document is closed, the DLL will start writing the PDF file to disc.
Paper Size?
Do we always assume A4 and in Portrait mode?
No, we don't assume anything.
"Unfortunately" this will be in the responsibility of the rexx-developer using the DLL. We will write a manual explaining how to create a PDF that fits A4, legal, whatever... and perhaps we can "tailor" some mnemonics for simple useage, but basically (technically-speaking) the DLL will create a document based on the paper size specified by height and width. Which units to use - I don't know. Points? Inches? Millimeters? Perhaps the unit to be used can be specified? Not sure what PDF uses internally.
We could do two functions that create a document:
- PDFStartPage (Size, Orientation) -> where "size" is "A4", "Legal", ...
e.g. PDFStartPage("A4", "P") to create an A4 in Portrait Mode
- PDFStartPageEx (Unit, Height, Width, Orientation) to make it fully flexible
e.g. PDFStartPageEx("MM", "297", "210", "P") to create an A4 in Portrait by millimeters
Hmm... I guess we also need some function like
PDFSetPageMargins (Top, Right, Bottom, Left) ... or should we combine this as optional parameters (default: 1.5 cm) into the "StartPage" function? :-P
Error handling in general:
Each function should actually return a value to show if it was successfully executed or not.
Using this to check if errors occurred however is in the responsibility of the developer. If he/she doesn't check if some call went wrong - well, too bad. Example:
/* start document without using RC... */
call PDFStartDoc "My PDF", "Thomas", "no comment..."
/* start document WITH using the RC... */
myrc = PDFStartDoc("My PDF", "Thomas", "no comment...")
You know what I mean?
If this is too difficult to support, the DLL could also make use of a generic variable "PDFRC" which is provided automatically to REXX once the DLL is loaded. This RC will be updated with the respective return code on each function call like this:
/* start document and use internal RC... */
call PDFStartDoc "My PDF", "Thomas", "no comment..."
if PDFRC \= 0 ...
Glad you provided some feedback, cheers,
Thomas