Return Value Types

There are five RETURN VALUE TYPES for RPCs as shown in the table below. You should choose a return value type that is appropriate to the type of data your RPC needs to return. For example, to return the DUZ, a return value type of SINGLE VALUE would be appropriate.

The RETURN VALUE TYPE you choose then determines what value(s) you should set into the return value parameter of your M entry point.

You should always set some value into the return value parameter of the M entry point, even if your RPC encounters an error condition.

The following RPC settings, combined with your M entry point, determine how data is returned to your client application:



RPC Return
Value Type

How M Entry Point Should
Set the Return Parameter		 RPC Word Wrap On Setting

Value(s) returned in Client Results
Single Value
Set the return parameter to a single value. For example,
TAG(RESULT) ;
 S RESULT="DOE, JOHN"
 Q
 No effect Value of parameter, in Results[0].
Array Set an array of strings into the return parameter, each subscripted one level descendant. For example,
TAG(RESULT) ;
 S RESULT(1)="ONE"
 S RESULT(2)="TWO"
 Q

If your array is large, consider using the GLOBAL ARRAY return value type, to avoid memory allocation errors.

 No effect Array values, each in a Results item.
Word Processing Set the return parameter the same as you set it for the ARRAY type. The only difference is that the WORD WRAP ON setting affects the WORD PROCESSING return value type. True

False

 Array values, each in a Results item.

Array values, all concatenated into Results[0].
Global Array Set the return parameter to a closed global reference in ^TMP. The global's data nodes will be traversed using $QUERY, and all data values on global nodes descendant from the global reference are returned.

This type is especially useful for returning data from VA FileMan word processing fields, where each line is on a 0-subscripted node.

Important: The global reference you pass is killed by the Broker at the end of RPC Execution as part of RPC cleanup. Do not pass a global reference that is not in ^TMP or that should not be killed.

This type is useful for returning large amounts of data to the client, where using the ARRAY type can exceed the symbol table limit and crash your RPC.

For example, to return signon introductory text you could do:

TAG(RESULT);
 M ^TMP("A6A",$J)=
^XTV(8989.3,1,"INTRO")
 ;this node not needed
 K ^TMP("A6A",$J,0)
 S RESULT=$NA(^TMP("A6A",$J))
 Q
 True

False

 Array values, each in a Results item.

Array values, all concatenated into Results[0].
Global Instance Set the return parameter to a closed global reference.
For example the following code returns the whole 0th node from the NEW PERSON file for the current user:
TAG(RESULT) ;
 S RESULT=$NA(^VA(200,DUZ,
0))
 Q
No effect Value of global node, in Results[0].

In the M code called by an RPC, you can use the $$RTRNFMT^XWBLIB function to change the return value type of an RPC on the fly.