Handling variable-length and large data

Normally, you must define the size of each parameter in your Synergy server routines in the Synergy Method Catalog (SMC) so that xfServerPlus knows what to expect. (See Defining Your Synergy Methods for details on defining data in the SMC.) Sometimes, though, you may not know exactly what size the data will be, or you may know that it will vary in size, or your application may need to handle data that exceeds the usual size limits. If your application needs to support such cases, you may be able to use one of the following methods:

Passing a single parameter as a memory handle

Use this method to pass a non-array parameter that is of variable length and/or larger than 64K (65,535 bytes) in size. This method is supported on all xfNetLink clients.

Your Synergy server routine must declare the argument that receives the data as a memory handle (i4; do not use int). xfServerPlus will place the data in a memory area and pass the memory handle allocated to that area to your Synergy server routine. (You must use the memory handle provided by xfServerPlus; do not attempt to allocate your own.) After the data has been returned to xfNetLink, xfServerPlus will free the memory area.

Note the following:

Passing a System.String parameter

When using a Java or .NET client, you can use a Synergy System.String to pass a parameter that is of variable length and/or larger than 64K. This method is an alternative to using a memory handle, as described above. System.String can also be used as a function return value.

In the Synergy server routine, the parameter is declared as @System.String. For more information on using string data in Synergy DBL see Data types and System.String.

Note the following:

Returning a collection of structures

When using a Java or .NET client, you can return a structure collection parameter to the client from Synergy. A structure collection is an array of structures with a variable number of elements. The structure collection can only be used to send data from Synergy to the client.

On the client side, the structure collection is handled as an ArrayList; on the xfServerPlus side, the data is placed in a memory area. When the call returns from xfServerPlus, the ArrayList will be filled with structures and will know its own size (number of elements).

The Synergy server routine must declare the argument that will return the structure collection as a memory handle (i4; do not use int). xfServerPlus will create an empty memory area and pass the memory handle allocated to that area to your Synergy server routine. (You must use the memory handle provided by xfServerPlus; do not attempt to allocate your own.) Your routine must resize the area and place the structures in it. After the data has been sent to xfNetLink, xfServerPlus will free the memory area.

Note the following:

If you have defined a structure collection parameter in the SMC for use with a Java or .NET client, and you want to also use a Synergy client with your server-side code, write your Synergy client code as though you were passing variable length data. That is, create a memory area on the client and pass the memory handle (as the parameter that is defined as a structure collection in the SMC) to xfServerPlus using the RCB_xxx routines. (See Passing a single parameter as a memory handle.) Do not alter the method definition in the SMC. When xfServerPlus receives the call from the Synergy client, it will not give a “parameter mismatch” error because it has been programmed to permit a mismatch when a Synergy client passes a memory handle to a parameter that is defined as a structure collection in the SMC.

Passing a System.Collections.ArrayList parameter

When using a Java or .NET client, you can use a Synergy System.Collections.ArrayList class to pass an ArrayList parameter either from Synergy to the client or from the client to Synergy. This method is an alternative to the one described in Returning a collection of structures. In addition to allowing data to be passed in either direction, the other advantage to this method is that the elements in the ArrayList are not limited to structures. You may also pass data defined as alpha, decimal, implied-decimal, integer, or System.String data types. The ArrayList may vary in the number of elements it contains.

In the Synergy server routine, declare the parameter as @System.Collections.ArrayList. See System.Collections.ArrayList for details.

If the ArrayList contains structures and is being sent from the client to the server, in your Synergy server routine use a FOREACH loop to extract data from the ArrayList and declare the loop counter variable as a boxed alpha. (See Synergex KnowledgeBase article 2224 for an example.)

Note the following:

Passing arrays larger than 64K

You can pass an array parameter larger than 64K (65,535 bytes) as long as no element in the array exceeds 64K. The maximum size for an arrayed field in Synergy DBL is 256 MB. This feature is supported on all clients.

Your Synergy server routine should declare the argument that receives the array in the normal manner (that is, as an array argument of a particular data type).

Note the following: