An example of how to use the RPC broker in VISTA (this code is in Java)

vistarpc_example.java

package com.smh101.heliopolis.vista.rpc.broker.example;

import java.io.IOException;

import com.chrisuyehara.vista.rpc.RPCClient;
import com.chrisuyehara.vista.rpc.exceptions.ConnectException;
import com.chrisuyehara.vista.rpc.exceptions.LoginException;
import com.chrisuyehara.vista.rpc.parameters.KeyValuePair;
import com.chrisuyehara.vista.rpc.parameters.ListParameter;
import com.chrisuyehara.vista.rpc.parameters.LiteralParameter;
import com.chrisuyehara.vista.rpc.parameters.OrderedList;
import com.chrisuyehara.vista.rpc.procedures.RemoteProcedure;

public class BrokerStart {

	public static void main(String[] args) throws IOException {
		
		// Create a socket
	    RPCClient c = new RPCClient("heliopolis.smh101.com", 9200, 100);
	    
	    /* 
	     1. Open the socket
	     2. Tell VISTA "TCPConnect" and see if it says "accept". This checks 
	        that the system is running and is listening. The code for this is in
	        CONNTYPE^XWBTCPM and everything after that. 
	     3. Invoke XUS SIGNON SETUP. This, in spite of its name, does other 
	        stuff besides Sign-On Set-up:
	        - If AUTO SIGN-ON is set-up, it will try to do that.
	        - If you pass it a special string (this library doesn't), you can 
	          tell it that you are a remote system who already has an 
	          authenticated user and want to get access for the user using the 
	          same access level that they already have on the remote system.
	        The code for that is in SETUP^XUSRB
	    */
	    
	    try 
	    { 
	    	c.connect(); 
	    }
	    catch (java.net.ConnectException e) // We just couldn't connect! 
	    { 
	    	System.out.println("Errror Connecting. Check listener");
	    	return;
	    }
	    catch (ConnectException e) // We connected, but VISTA for some reason can't take our call. The TCPConnect returns "#BYE#"
	    { 
	    	System.out.println(e.getMessage()); 
	    	return;
	    } 
	    catch (IOException e) // This error is just in case the connection is cut off suddenly
	    { 
	    	System.out.println(e.getMessage()); 
	    	return;
	    }
	    
	    // The next thing we usually do is display the introduction text for the user
	    // The code for this is in INTRO^XUS1A
	    RemoteProcedure r = new RemoteProcedure("XUS INTRO MSG");
	    c.call(r);
	    String response = r.getResponse();
	    System.out.println(response);
	    
	    // The next thing we do is try to log-in. The RPC Call made is XUS AV CODE.
	    // The code is in VALIDAV^XUSRB
	    try
	    {
	    	c.login("XXXXXXXXXXXX","XXXXXXXXXXXXXXX");
	    }
	    catch (LoginException ex)
	    {
	    	System.out.println(ex.getMessage());
	    }
	    
	    /* If we don't get any exceptions, we are good to go. There are typically
	    4 different issues that may come up:
	    1. Invalid codes
	    2. Need to change verify code
	    3. Need to select a division
	    4. You are locked out
	    
	    For #2 and #3, you have to invoke RPCs to handle these.
	    
	    To change the verify code, prompt for the new one and then invoke XUS CVC.
	    To select a division, you need to invoke XUS GET DIVISION first, to get
	    the default division for the user, have the user make a selection, then 
	    invoke XUS SET DIVISION.
	    */
	    
	    /* If everything is okay, the next step is to select the context under
	     * which the application will operate. The context is really the security
	     * context. A context is a list of all the RPCs that the user is 
	     * allowed to run. If you try to switch to a context that doesn't exist,
	     * or one to which the user has no access, the context switch will fail.
	     * 
	     * You MUST change contexts before invoking RPC belonging to the other
	     * context. If you don't, you will get an access denied message.
	     * 
	     * A context is a menu option inside of VISTA; all you need to do is
	     * give access to that menu option to the user.
	     * 
	     * NB: If your user holds the key XUPROGMODE, you will have access to 
	     * every RPC, no matter the context. Your context will not be checked.
	     * In the real world, after you are done with development, make sure to
	     * test with a normal user.
	     */
	    
	    c.context("XWB BROKER EXAMPLE");
	    assert(c.getContext() != "");
	    
	    /* In file 19, we can see that the option/context XWB BROKER EXAMPLE has
	     * the following Remote Procedures available
	     * 
	     * RPC: XWB EXAMPLE ECHO STRING
         * RPC: XWB EXAMPLE GET LIST
         * RPC: XWB EXAMPLE SORT NUMBERS
         * RPC: XWB EXAMPLE WPTEXT
         * RPC: XWB GET VARIABLE VALUE
         * RPC: XWB EXAMPLE TRAP PARAMS
         * RPC: XWB EXAMPLE GLOBAL SORT
         * RPC: XWB EXAMPLE BIG TEXT
         * 
         * Let's try them.
         * Code is in this routine: XWBEXMPL
	     */
	    r = new RemoteProcedure("XWB EXAMPLE ECHO STRING");
	    r.addParameter(new LiteralParameter("Hello world"));
	    c.call(r);
	    response = r.getResponse();
	    System.out.println(response);
	    
	    r = new RemoteProcedure("XWB EXAMPLE WPTEXT");
	    c.call(r);
	    response = r.getResponse();
	    System.out.println(response);
	    
	    r = new RemoteProcedure("XWB EXAMPLE SORT NUMBERS");

	    LiteralParameter Direction = new LiteralParameter("LO");
        OrderedList o = new OrderedList();
        o.add(new KeyValuePair("1", "20"));
        o.add(new KeyValuePair("2", "1"));
        o.add(new KeyValuePair("3", "3120513.1724"));
        ListParameter List = new ListParameter(o);
        r.addParameter(Direction);
        r.addParameter(List);
        c.call(r);
        response = r.getResponse();
	    System.out.println(response);
	    
	    /*
	     * I wrote a tiny remote procedure in KBANTCEE, and this just returns
	     * data. There is nothing special about any remote procedure. Once it's
	     * M code, it's just M code.
	     * 
	     * The remote procedure is KBAN TC LOAD DATA:
	     * 
	     * NAME: KBAN TC LOAD DATA                 TAG: LOADDATA
         * ROUTINE: KBANTCEE                     RETURN VALUE TYPE: GLOBAL ARRAY
         * AVAILABILITY: PUBLIC                  WORD WRAP ON: TRUE
	     * 
	     * I then created the menu option KBAN TC RPCS to be the context for my
	     * remote procedure
	     * 
	     * NAME: KBAN TC RPCS                      MENU TEXT: Timecard Remote Procedures
         * TYPE: Broker (Client/Server)          CREATOR: USER,ONE
         * RPC: KBAN TC LOAD DATA
         * UPPERCASE MENU TEXT: TIMECARD REMOTE PROCEDURES
         * 
         * Make sure to assign the user that runs this that menu option.
         * 
	     */
        // Let's switch contexts
	    c.context("KBAN TC RPCS");
	    assert(c.getContext() != "");
	    
	    // Get me all the time entries for June 10 for 12 items
	    r = new RemoteProcedure("KBAN TC LOAD DATA");
	    LiteralParameter FMStart = new LiteralParameter("3150610");
	    LiteralParameter Entries = new LiteralParameter("12");
	    r.addParameter(FMStart);
	    r.addParameter(Entries);
        c.call(r);
        response = r.getResponse();
	    System.out.println(response);
	    
	    /* When you are done talking, you need to tell VISTA that you want to
	     * log out by telling it #BYE#.
	     */
	    c.logout();
	}
}