A couple months ago there was a post on the Partner Forum about Dexterity Oddities. One of the points raised in the post was about passing a text datatype parameter to a procedure called in the background and the fact that the contents of the text variable are lost. The same code called in the foreground works.
So this quick tip is to explain what was happening and provide a warning for those wanting to pass text variable to background code.
When using call background <Procedure> to call a script that includes "text" parameters, the value(s) passed into the text parameters are lost.
The Dexterity SanScript documentation specifically states that you can't use call background with table buffers, because the reference to the buffer might not exist anymore by the time the procedure executes. But there's nothing in the documentation to indicate that text parameters can't be used.
When Dexterity passes parameters in the foreground, it passes them by reference (ie. a pointer to the data). When passing parameters to background processes, Dexterity has to pass a "snapshot" of the current values of the parameters by value (ie. a copy of the data). Table buffers which are large blocks of data can only be passed by reference and so cannot be passed to background processes. Text fields are also handled as pointers to a block of data and so can also only be passed by reference.
Below is the response from the Dexterity Development team when I checked with them:
Normally when we call a script, we pass those parameters by reference. However, when we call a script in the background (or remote), we need to allocate a block of memory for those parameters and copy the values, essentially making them pass by value at that point. The amount of data that we can allocate for script parameters is limited and because of the potential size of text values we cannot convert those to pass them by value. The documentation should probably be updated to mention that text values cannot be passed as well.
Hope this is helpful