String Pointers (Including NULL) For DLLs

;These are the contents of the \Blitz3D\UserLibs\StrPtr.decls file:
;drop the leading semicolons to make active in that file
;------------------------ DECLS FILE ----------------------------------
;.lib "StrPtr.dll"
;StrPtr%(somsstr$) : "StrPtr"
;---------------------- END OF DECLS ----------------------------------

;that is all it takes for Blitz3D to recognize the new command StrPtr().
;However, Blitz3D will fail to load unless there is a file called
;"StrPtr.dll" somewhere along the path that it searches for .DLL
;files. So you have to have created a file with that name, and it has
;to have a StrPtr() procedure set somewhere in it, which has been declared
;as an EXTERN or a DLL procedure.

;This is child's play in PureBasic, where you would create a new source
;file called (guess) "StrPtr.bb", and in it you would put the following
;statements (without leading semicolons):
;------------------ PureBASIC StrPtr Source File ----------------------
;ProcedureDLL.l StrPtr(somestr.s)
;If somestr="*NULL*"
; ProcedureReturn 0
;Else
; ProcedureReturn @somestr
;EndIf
;EndProcedure
;------------------- End of PureBASIC Source File ---------------------

;You just go under PureBasic's Compiler Options and tell it to make it
;a Shared DLL file, and when you create it, you just make sure that it
;is named StrPtr.dll and store it in \Blitz3d\UserLibs.

;The "@somestr" tells PureBasic to return the pointer to somestr.

;In using StrPtr() in calling other declared DLL procedures, each
;instance of an ASCIIZ variable where you want the option of passing
;a NULL, you have to declare it a Int(%) instead, and use StrPtr()
;whenever passing a string in that position.



;This is a test of StrPtr() use For returning a string's pointer

s$="Now is the time"
Print StrPtr(s$) ;this will be the memory address (pointer) for s$

;This is a test of StrPtr() returning a special NULL of zero

s$="*NULL*"
Print StrPtr(s$) ;this will be 0, indicating a NULL for s$

;This is a test of StrPtr() returning a NULL for a constant

Print StrPtr("*NULL*") ;this will be 0, again indicating NULL.

Repeat
Forever

;So that even though s$ is a valid string, it can force a zero pointer
;if the string is set to "*NULL*".

;If you do not have PureBasic (and why not? It's cheap enough!), you
;can create a similar process in a variety of other languages, including
;C, C++, PowerBasic, Assembler, or any language that directly supports
;pointers. This includes many other dialects of BASIC.

This doesn't do anything useful.

The problem is that Blitz does not use C-style, zero-terminated strings.
But a function in a DLL expects such a string. So what does this do?

 
s$ = "Now is the time" 
Print StrPtr(s$)

Blitz builds a temporary C-style string containing s and appends a zero byte.
Then it calls StrPtr, passing the address of the temporary copy.

The DLL returns the passed address, i.e. a pointer to the temporary copy.
This is not the address of s. Examine the addresses displayed here.

s$ = "blitz"
t$ = "basic"

Print StrPtr(s)
Print StrPtr(t)

WaitKey : End

What if a DLL function returns a string, i.e. pointer to C-style string?
When the function returns Blitz immediately builds a new basic-style string.