Insert argument into an existing routine call block
|
WTSupported in traditional Synergy on Windows
|
|
USupported on UNIX
|
VSupported on OpenVMS
|
xcall RCB_INSARG(rcbid, argnum, [data, [type], [length], [prec], [flags], [numdims], & [dim1, ..., dim9]])
Arguments
rcbid
The ID of a routine call block previously created with %RCB_CREATE. (n)
argnum
The one-based index of the argument. (n)
data
(optional) The data area to be referenced by the argument. (a or n)
type
(optional) The type of the argument: (n)
D_TYPE_A = Alpha
D_TYPE_D = Decimal
D_TYPE_ID = Implied-decimal
D_TYPE_I = Integer
D_TYPE_P = Packed
D_TYPE_IP = Implied-packed
D_TYPE_HANDLE = Data is a memory handle that references a variable-length argument whose size may exceed 64K (xfNetLink Synergy only).
D_TYPE_MEMARG = Data is a memory handle that references the argument’s data.
D_TYPE_REF = Address passed by reference
D_TYPE_VAL = Integer passed by value
length
(optional) The length, in bytes, of the argument. (n)
prec
(optional) The precision (decimal places) of the argument. (n)
flags
(optional) A specification of other features: (n)
The data passed cannot be modified. This flag is ignored if type is D_TYPE_VAL. DRCB_READONLY is implied if an arithmetic expression or literal is passed.
The data passed is to be an array according to the numdims and dim1 through dim9 arguments. Numdims and dim1 through dim9 are ignored unless DRCB_ARRAY is specified.
numdims
(optional) The number of dimensions of the argument (if the argument is an array). Valid values are 1 through 9. (n)
dim1 through dim9
(optional) Up to nine dimension specifications (if the argument is an array). (n)
Discussion
If rcbid is invalid, an error is signaled.
If argnum is not passed or is less than or equal to 0, an error is signaled.
The data argument must be passed if any of the other optional arguments are passed, because the other arguments describe the data. If this argument (or any subsequent optional argument) is not passed, the argument is assumed to be a null argument at the time RCB_CALL is executed. If type is D_TYPE_HANDLE or D_TYPE_MEMARG, data is a memory handle.
If type is not passed or has a value of 0, the data type of data is used. If you are using D_TYPE_HANDLE or D_TYPE_MEMARG, the type argument is not optional.
If length or precision is specified, the dimensional qualities of the data variable are lost unless explicitly specified through numdims and dim1 through dim9. If numdims is specified as zero, the array attribute is turned off. If data is a real array, any modifications to the length or dimensions must fall within the bounds of the real array or an “Invalid subscript specified” error ($ERR_SUBSCR) results. If data is a real array and if a different type or length is specified, the resulting argument is not an array unless DRCB_ARRAY has been specified along with the dimensional information. If type is D_TYPE_MEMARG or D_TYPE_HANDLE, data is a memory handle.
If length is not passed or has a value of 0, the length (^SIZE) of data is used. If type is D_TYPE_VAL, length is used only for the source data, and the length of the argument is set to 4 (32 bits). If type is D_TYPE_HANDLE or D_TYPE_MEMARG and length is passed, length must be less than the size of the memory associated with the memory handle.
If prec is not passed, the precision of data is used. This argument is used only when type is D_TYPE_ID or D_TYPE_IP.
If the argument is an array, specify the DRCB_ARRAY flag and the numdims and dim# arguments.
The D_TYPE_MEMARG type is used to specify that the data argument is a memory handle containing the data to be used for the argument. The type of the argument is specified by adding any valid data type (except D_TYPE_HANDLE) to D_TYPE_MEMARG (for example, D_TYPE_MEMARG+D_TYPE_D).
D_TYPE_MEMARG can be used with xfNetLink Synergy or when using the routine call block API locally. The routine receiving the argument should declare the argument in a normal manner.
On 32-bit systems, when D_TYPE_MEMARG is specified, the size of an argument or a single element of an array is limited to 64K. When the scope of an array is larger than 64K, D_TYPE_MEMARG can be used to specify the argument as long as the size of a single element does not exceed 64K.
When passing a memory handle to a Synergy routine, the memory handle must be passed as an integer type, D_TYPE_I. (See xfNetLink Synergy below for information about passing a memory handle when using xfNetLink Synergy.)
The D_TYPE_HANDLE type is used to pass a single non-arrayed argument as a memory handle (in data) when you’re using xfNetLink Synergy. This argument can be larger than 64K. RCB_INSARG looks at the memory handle, which indicates the location of the data on the client, and passes the data to xfServerPlus. xfServerPlus creates a memory area, puts the data in it, and then returns the memory handle for that area to the Synergy server routine. Therefore, your Synergy routine should be written to expect an i4 value. Any return data from xfServerPlus is placed back in the same memory area on the client that it originally came from. If the memory area allocated to the handle is resized within the Synergy routine on the server, it is resized accordingly on the client upon returning from the routine. Trailing blanks are trimmed when the data is returned to the client, so the resized memory area on the client might not be exactly the same size it was on the server. Do not use the D_TYPE_HANDLE type when using the routine call block API locally.
Examples
record
rcbid ,i4
arg_1 ,a3
arg_2 ,d3
arg_3 ,d6.3
arg_4 ,a4
arg_5 ,i4
proc
rcbid = %rcb_create(2) ;Create an RCB block with 2 args
xcall rcb_setarg(rcbid, arg_1, 1) ;Set up arg_1 as argument #1
xcall rcb_setarg(rcbid, arg_3, 2) ;Set up arg_3 as argument #2
xcall rcb_insarg(rcbid, 2, arg_2) ;Expand argument block by
; inserting arg_2 as argument #2
xcall rcb_insarg(rcbid, 4, arg_4, D_TYPE_D) ;Expand argument block by
; inserting arg_4 as decimal
xcall rcb_insarg(rcbid, 5, arg_5,,,, DRCB_READONLY) ;Set up arg_5 as a literal
xcall rcb_setfnc(rcbid, "routine") ;Set function to be called
xcall rcb_call(rcbid) ;Call function as xcall routine(arg_1,
; arg_2, arg_3, ^d(arg_4), arg_5)
xcall rcb_setarg(rcbid,, 3) ;Set up arg_3 as a null argument
xcall rcb_call(rcbid) ;Call function as xcall routine(arg_1,
; arg_2,, ^d(arg_4), arg_5)
xcall rcb_delarg(rcbid, 3) ;Remove argument #3
xcall rcb_call(rcbid) ;Call function as xcall routine(arg_1,
; arg_2, ^d(arg_4), arg_5)
xcall rcb_delete(rcbid) ;Delete RCB block
end
