Text parameters for RPCs

A new feature has been added to Adaptive Server Enterprise that provides the ability to send large chunks of data in a single remote procedure call. This is done by treating certain parameters as text pointers, then de-referencing these text pointers to obtain the text values associated with them. The text data is then packaged into 32k chunks and handed to Client Library as parameters to the RPC.

A text pointer is identified as a parameter of type binary(16) or varbinary(16). The text value referenced by each text pointer parameter will be obtained when the RPC is executed, and expanded into 32k chunks, each of which is passed to Client Library as a parameter of type CS_LONGCHAR_TYPE.

This behavior is triggered by a new set command:

set textptr_parameters ON

When an RPC is requested (cis_rpc_handling must be ON), text pointers are de-referenced in the CIS layer, and the text value obtained is used to construct one or more parameters for Client Library.

In order for this to work, the text pointers must be preceded by a pathname argument, which is used to identify the table from which the text pointers have been derived. For example:

declare @pathname varchar(90) 
declare @textptr1 binary(16) 
declare @textptr2 binary(16) 
select @pathname = "mydatabase.dbo.t1", 
		@textptr1 = textptr(c1),
		@textptr2 = textptr(c2)
	from mydatabase.dbo.t1
	where ... (whatever) 
set textptr_parameters ON 
exec NETGW...myrpc @pathname, @textptr1, 		@textptr2 
set textptr_parameters OFF

When the RPC named ’myrpc’ gets sent to server NETGW, the @pathname parameter is not actually sent, but is used to help locate the text values referenced by the textptr’s @textptr1 and @textptr2.

The varchar parameter @pathname must immediately precede the binary(16) parameter, otherwise @textptr1 will be considered an ordinary parameter and will be transmitted to the server NETGW as a normal binary(16) value.

If the text values of a text pointer exceed 32k bytes in size, the text will be broken into 32k chunks, each of which will be a separate parameter of type CS_LONGCHAR_TYPE.

The current value of @@textsize will be ignored.

This scheme is also designed to work with proxy tables mapped to remote procedures. For example:

create existing table myrpctable
(
	id int, 		-- result column 
	crdate datetime, -- result column
	name varchar(30), 	-- result column
	_pathname varchar(90), 	-- parameter column
	_textptr1 binary(16), 	-- parameter column 
	_textptr2 binary(16), 	-- parameter column
) external procedure at ’NETGW...myrpc’
go 
declare @textptr1 binary(16) 
declare @textptr2 binary(16) 
select @textptr1 = textptr(c1), @textptr2 = textptr(c2) 
from mydatabase.dbo.t1 where <whatever>
set textptr_parameters ON
select id, crdate, name 
from myrpctable 
where_pathname = "mydatabase.dbo.t1" and
	_textptr1 = @textptr1 and
	_textptr2 = @textptr2

When the query against the proxy table myrpctable is processed, CIS will send an RPC named ’myrpc’ to the server ’NETGW’. The parameters will be derived from the search arguments contained in the where clause of the query. Since the ’textptr_parameters’ option has been set ON, the textptr’s will be expanded to CS_LONGCHAR_TYPE, just as in the case of the RPC example shown previously.