RPC HELP BROKER RETURN VALUE TYPES

RPC Broker Help Home

Return Value Types

There are five RETURN VALUE TYPEs for RPCs as shown 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:

Return Value Types -- Single Value

• How M Entry Point Should Set the Return Parameter: Set the return parameter to a single value. For example:

   TAG(RESULT) ;
     SET RESULT="DOE, JOHN"
     QUIT

• RPC Word Wrap On Setting: No effect
• Value(s) returned in Client Results: Value of parameter, in Results[0].

Return Value Types -- Array

• How M Entry Point Should Set the Return Parameter: Set an array of strings into the return parameter, each subscripted one level descendant. If your array is large, consider using the GLOBAL ARRAY return value type, to avoid memory allocation errors. For example:

   TAG(RESULT) ;
     SET RESULT(1)="ONE"
     SET RESULT(2)="TWO"
     QUIT

• RPC Word Wrap On Setting: No effect
• Value(s) returned in Client Results: Array values, each in a Results item.

Return Value Types -- Word Processing

• How M Entry Point Should Set the Return Parameter: 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.
• RPC Word Wrap On Setting:
  • If TRUE: Array values, each in a Results item.
  • If FALSE: Array values, all concatenated into Results[0].

Return Value Types -- Global Array

• How M Entry Point Should Set the Return Parameter:
  • 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 type fields, where each line is on a 0-subscripted node.
  • WARNING: 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);
     MERGE ^TMP("A6A",$J)=^XTV(8989.3,1,"INTRO")
     ;this node not needed
     KILL ^TMP("A6A",$J,0)
     SET RESULT=$NA(^TMP("A6A",$J))
     QUIT

• RPC Word Wrap On Setting:
  • If TRUE: Array values, each in a Results item.
  • If FALSE: Array values, all concatenated into Results[0].

Return Value Types -- Global Instance

• How M Entry Point Should Set the Return Parameter:
  • Set the return parameter to a closed global reference.
  • For example the following code returns the whole 0th node from the NEW PERSON file (#200) for the current user:

   TAG(RESULT) ;
     SET RESULT=$NA(^VA(200,DUZ,0))
     QUIT

• RPC Word Wrap On Setting: No effect
• Value(s) returned in Client Results: 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.