RCB_SETARG

Set an argument in the routine call block

xcall RCB_SETARG(rcbid, [data], argnum, [type], [length], [precision], [flags], [numdims], 
&     [dim1, ..., dim9])

Arguments

rcbid

The ID of a routine call block previously created with %RCB_CREATE. (n)

data

(optional) The data area to be referenced by the argument. (a or n)

argnum

The one-based index of the argument. (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)

precision

(optional) The precision (decimal places) of the argument. (n)

flags

(optional) A specification of other features: (n)

DRCB_READONLY

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.

DRCB_ARRAY

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.

To specify a read-only array, include both DRCB_READONLY and DRCB_ARRAY, separated by a plus sign (+): DRCB_READONLY+DRCB_ARRAY.

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

Using this routine, you can create routine call block argument entries for any data type, including ^REF and ^VAL arguments.

If argnum is not passed, or if it is less than or equal to 0, or greater than the current number of arguments (%RCB_CREATE’s arguments plus %RCB_INSARG’s arguments minus %RCB_DELARG’s arguments), a “Value out of range” error ($ERR_OUTRNG) is signaled.

If data is not passed, the argument is set to a null argument and is not passed.

Unless they’re explicitly overridden by the RCB_SETARG arguments, all other features of the argument (for example, length, type, and whether it’s global or temporary) are derived from the features of data. The data referenced by the argument at the time of the RCB_CALL is the data passed to the subroutine, with the exception of ^VAL arguments that are determined at the time of the RCB_SETARG call.

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 type is not passed or has a value of 0, the data type of data is used. If you are using D_TYPE_MEMARG or D_TYPE_HANDLE, the type argument is not optional.

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_MEMARG or D_TYPE_HANDLE and length is passed, length must be less than the size of the memory associated with the memory handle.

If precision 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.

If you pass the same data reference on multiple calls to RCB_SETARG, all of the arguments reference the same data. The exception to this rule is if the type is D_TYPE_VAL, in which case the value of data at the time of the call to RCB_SETARG is used.

You may use this routine to overwrite an argument that was previously specified in another call to RCB_SETARG.

The D_TYPE_MEMARG type is used to specify that data is a memory handle referencing the data to be used for the argument. The data type to be applied to the argument when it is passed is specified by adding one or more of the type qualifiers (except D_TYPE_HANDLE) to D_TYPE_MEMARG (for example, D_TYPE_MEMARG + D_TYPE_D). The other RCB_SETARG arguments can be specified to customize the argument. The scope of the argument is limited to the size of the data associated with the memory handle. When using D_TYPE_MEMARG on 32-bit systems, the size of an argument or single array element is limited to 64K. The entire array, however, may be larger than 64K. 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.

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.)

xfNetLink Synergy

The D_TYPE_HANDLE type is used to pass a variable-length argument as a memory handle (in data) when you’re using xfNetLink Synergy. This argument can be larger than 64K. RCB_SETARG 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 passes 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 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 may be smaller than it was on the server. Do not use D_TYPE_HANDLE 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(5)               ;Create an RCB block with 5 args
    xcall rcb_setarg(rcbid, arg_1, 1)    ;Set up arg_1 as argument #1
    xcall rcb_setarg(rcbid, arg_3, 3)    ;Set up arg_3 as argument #3
    xcall rcb_setarg(rcbid, arg_5, 5)    ;Set up arg_5 as argument #5
    xcall rcb_setarg(rcbid, arg_4, 4)    ;Set up arg_4 as argument #4
    xcall rcb_setarg(rcbid, arg_2, 2)    ;Set up arg_2 as argument #2
    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, arg_4, arg_5)
    xcall rcb_delete(rcbid)              ;Delete RCB block
end