Step 4. RPC Routine to List Terminal Types

Now that your application uses an RPC Broker component to connect correctly to an RPC Broker server, you are ready to create custom RPCs that your application can call. For the tutorial, you will create an RPC that retrieves the list of all terminal types from the RPC Broker server.

The first step in creating an RPC is to create the routine that the RPC will execute. You must create its input and output in a defined format that will be compatible with being executed as an RPC.

To do this:

1. Choose the data format that your RPC should return. The type of data that you need to return to your client application determines the format of the routine that your RPC will call. There are five return value types for RPCs:
   • SINGLE VALUE
     
     
   • ARRAY
     
     
   • WORD PROCESSING
     
     
   • GLOBAL ARRAY
     
     
   • GLOBAL INSTANCE

   Since the type of data the tutorial application would like returned is a list of terminal types, and that list could be quite long, use a return value type GLOBAL ARRAY for your RPC. For the routine called by your RPC, this means that:

   • Your routine should return a list of terminal types in a global. Each terminal type should be on an individual data node, subscripted numerically.
     
     
   • The return value of your routine (always returned in the routine's first parameter) should be the global reference of the data global, in closed root form. The data nodes should be one level descendant from the global reference.
2. Create a routine, in the M account that your TRPCBroker component connects to, that outputs a list of terminal types in the format determined above. The format for each data node that is returned for a terminal type could be anything; for the sake of this application, set each data node to "ien^.01 field" for the terminal type in question. Store each node in ^TMP($J,"ZxxxTT",#).

   ZxxxTT   ;ISC-SF/KC TUTORIAL RTN, BRK 1.1; 7/22/97
    ;;1.0;;
   TERMLIST(GLOBREF) ; retrieve list of term types
    ; return list in ^TMP($J,"ZxxxTT")
    ; format of returned results: ien^.01 field
    N %                               ; scratch variable
    K ^TMP($J,"ZxxxTT")               ; clear data return area
    D LIST^DIC(3.2)                   ; retrieve list of termtype entries
    ; now set termtype entries into data global
    I '$D(DIERR) D
    .S %=0 F  S %=$O(^TMP("DILIST",$J,2,%)) Q:%=""  D
    ..S ^TMP($J,"ZxxxTT",%)=$G(^TMP("DILIST",$J,2,%))_"^"_$G(^TMP("DILIST",$J,
   1,%))
    K ^TMP("DILIST",$J)               ; clean up
    S GLOBREF=$NA(^TMP($J,"ZxxxTT"))   ; set return value
    Q

3. Test the routine. Call it like the Broker would:

   > D TERMLIST^ZxxxTT(.RESULT)

   a. Confirm that the return value is the correct global reference:

   > W RESULT
   
     ^TMP(566363396,"ZxxxTT")

   b. Confirm that the data set into the global is in the following format:

   ^TMP(566347920,"ZxxxTT",1) = 1^C-3101
   ^TMP(566347920,"ZxxxTT",2) = 2^C-ADDS
   ^TMP(566347920,"ZxxxTT",3) = 3^C-ADM3
   ^TMP(566347920,"ZxxxTT",4) = 38^C-DATAMEDIA
   ^TMP(566347920,"ZxxxTT",5) = 106^C-DATATREE
   ^TMP(566347920,"ZxxxTT",6) = 4^C-DEC
   ^TMP(566347920,"ZxxxTT",7) = 5^C-DEC132
   ^TMP(566347920,"ZxxxTT",8) = 93^C-FALCO
   ^TMP(566347920,"ZxxxTT",9) = 6^C-H1500
   ^TMP(566347920,"ZxxxTT",10) = 103^C-HINQLINK
   ^TMP(566347920,"ZxxxTT",11) = 132^C-HINQLINK
   ^TMP(566347920,"ZxxxTT",12) = 63^C-HP110
   ^TMP(566347920,"ZxxxTT",13) = 34^C-HP2621

Once you've tested your routine, and confirmed that it returns data correctly, the next step is to create the RPC that will call this routine.