[prev in list] [next in list] [prev in thread] [next in thread] 

List:       nsbasic-palm
Subject:    Re: [nsbasic-palm] Applaunch command and example
From:       Douglas Handy <dhandy1 () bellsouth ! net>
Date:       2002-07-31 12:18:21
Message-ID: t8efkus8ajl11ie3bidjb2bbpf09d7n1l5 () 4ax ! com
[Download RAW message or body]

Jeff,

Good news and bad news.

The good news is that it appears the program you want to launch is designed for
doing just that and processing a custom launch code.

The bad news is that it uses features not available (directly) in NSB.

>I'd like to try to AppLaunch a program that returns a string of text 
>(at least I hope it does)  

In terms of a return value per se, a program only "returns" an integer result
value.  However, what NSB calls the final "data" argument passed to AppLaunch
may be modified by the program.  In NSB, the argument is passed as a string.  I
don't know if NSB checks to see if this string has been modified by the caller,
and if so, update its internal storage contents for the variable.  I've never
check with AppLaunch (although NSB does do this for shared lib calls and
SysTraps, so it may with AppLaunch too -- I've just never tested it).

Unfortunately, even if NSB does, that does not solve the problem.  The real
problem is that what NSB calls the "data" string argument can be more complex
than that when called from C.  Here it is known as the cmdPBP, and is a pointer
to a command parameter block and not necessarily a pointer to just a single
string.

The cmdPBP paramter block is C "structure", which is anagous to a UDT in NSB.
It may contain one or more subfields of various types.  Alas, NSB does not
support using a UDT in this manner (yet?), so you are restricted to passing a
single string to a program via AppLaunch.

Depending on the program, that may work fine.  For example, most all calls to
Steven's Creek PalmPrint use just a single string in addition to the "cmd"
integer launch code.

Unfortunately, MyBible is not such a program.  This is because it needs to get
several pieces of information, and the best way to do that from C is by passing
a structure.  

With that as a background, I'll address your specific questions:

>Part II - this is how you call it in C - right?
>-------
>success = LaunchMyBible(CreatorID,MbGotoLaunchCode, pData);

Assuming LaunchMyBible() is a function in the source which ends up calling the
SysAppLaunch() api, yes.  The caveat here from a NSB perspective is the final
argument, pData, which is a pointer to a parameter block structure.

>pData = (GotoDataType *) MemPtrNew(sizeof(GotoDataType)); 'type Goto
>
>-----
>typedef struct GotoDataType
>	{
>	BibleRefType Reference;	// [in] Specifies the book, 
>				// chapter and verse that MyBible
>				// should start at.  If invalid,
>				// it can be ignored.
>				
>	Char Translation[MAXTRANS];// [in][optional] Abbreviation of 
>				// translation to use.  If 
>				// empty or invalid, then it can
>				// be ignored.
>								
>		
>	}
>	GotoDataType;
>-----
>typedef struct BibleRefType
>	{
>	Int16 Book;		// book number (not book name number)
>	Int16 Chapt;		// chapter number
>	Int16 Verse;		// verse number
>	}
>	BibleRefType;

Herein lies the rub.  Memory is being allocated (via MemPtrNew) to hold the
contents of a "GotoDataType" structure.  This structure is comprised of a
"BileRefType" (itself another structure) optionally followed by a character
array (nearly like a string) which identifies which translation to use.

So now we need to back up and see what a "BibleRefType" structure is, and it is
made up of three consecutive 16-bit integers:  one for the book number, the
second for the chapter, and third for the verse number.  These values are placed
next to each other in memory within the GotoDataType structure.  Presuming that
Genesis is what they call book number 1, then Gen 1:1 would equate to the first
six bytes of the GotoDataType structure containing x'000100010001' (eg three
16-bit integers, each containing the value 1).  If the gospel of John is book 43
(as a guess), then John 3:16 would be x'002B00030010' (eg three 16-bit integers
with the values 43, 3, and 16, respectively).

If you could fake the NSB "data" string argument to contain those bytes,
optionally followed by a string with the translation to use, then you could pass
that string.  The problem here is that NSB null-terminates all strings, and you
will *always* have a null in the first byte since there are only 66 books in the
Bible.  Thus you *cannot* (using NSB) create what appears to MyBible to be a
valid GotoDataType structure.

>#define MbGotoLaunchCode	62817

I suspect either this is a typo, or you made one below at 62814.
   
>Type pdata
>    	CreatorID as String
>	Book as Integer
>	Chapter as Integer
>	Verse as Integer
>	Translation as String
>End Type

The right idea, except that CreatorID is not part of the structure, and the
book, chapter, and verse should be defined as Short (ie 16-bit) instead of
Integer (ie 32-bit).

The real problem here, though, is that NSB does not currently support using a
UDT as the "data" argument with AppLaunch -- only a string which terminates with
the first null byte.

>error = AppLaunch(0, "MyBible", 62814, "pdata")

Three problems:
 1) You use 62814 here but 62817 above (one is probably a message typo)
 2) You put quotes around pdata, meaning you are passing the string "pdata"
	rather than the contents of UDT pdata
 3) Even if you leave the quotes off, the UDT pdata will not get passed right
	(This is a NSB limitation)

And even if it support this, you'd still not get back a string with the text of
the verse (which is I presume what you are after).  This launch code appears to
be to *display* the Bible, starting at that verse.  Perhaps this goes back to
the difference between launch codes 62817 and 62814.  One may be for displaying
the Bible starting at that verse, and the other may be for returning the text of
that verse.  But that probably uses a different cmcPBP structure than the one
you quoted.

>Here is the question - how do I pass the string to the external 
>program and how do I retrieve the string from the external program?  

If it only wanted a string, and the string was called pdata, you'd use:

  error = AppLaunch(0, "MyBible", 62814, pdata)

But NSB can't return a string that way.  That's why little AppLaunch programs
like my InputBox.prc (which prompts for text from the user) stuffs the answer in
an "application preference" and then the NSB program must retrieve it from the
preference database.

>I'm sure my datatype above is wrong but how can you pass more than 1 
>argument to the program?  

Use something other than NSB. :(

>Is the arg being passed as an array, or a 
>pointer to some place in memory 

The latter.  But you can't mimic the behavior of this either because although
you can allocate memory with a SysTrap and get the memory pointer, you can't
place values at specific offsets from that pointer or perform pointer
arithmetic.

>Thanks for any and all help.  I've been trying to glean what I can 
>from the examples, but there aren't any other than CSub, right?

There have been posts showing how to use AppLaunch with PalmPrint, and also my
InputBox.prc example.  There may be others; search the archives for AppLaunch.
But they won't help solve your dilemma.  To do that one of three things must
happen:

  1)  NSB enhances AppLaunch to accept a UDT and build a C-compatible structure
  2)  NSBSystemLib is enhanced to let us fake it ourselves by providing routines
	to manipulate memory at offsets from a memory block allocated via SysTraps
	(I've asked for that to be added, but it is probably low priority -- not
	many people would know what to do with it)
  3)  Instead of using AppLaunch you call a shared library which accepts NSB
	compatible arguments, formulates it into MyBible compatible parameters,
	calls SysAppLaunch, then process any return value to send back to NSB

Of the three, the third is the only one under your direct control.  (Well, kinda
anyway, I realize you don't know C...)

I use Olive Tree's BibleReader, so I tried looking up info on MyBible.
Laridian's web site only says "ask for information about the MyBible Development
Kit".

So at this point I can't look at their calls to see if there is one which
actually returns a verse (or range?), and what other calls may be available if a
shared library wrapper was made.

Doug

Community email addresses:
 Post message: nsbasic-palm@yahoogroups.com 
 Subscribe:  nsbasic-palm-subscribe@yahoogroups.com 
 Unsubscribe:  nsbasic-palm-unsubscribe@yahoogroups.com  
 List owner:  nsbasic-palm-owner@yahoogroups.com 

Shortcut URL to this page:
 http://groups.yahoo.com/group/nsbasic-palm  

Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/ 



[prev in list] [next in list] [prev in thread] [next in thread]