XCALL Utility

Description

In (V)PRO/5 10.0 and higher, XCALL calls external BBj programs using a syntax similar to the traditional CALL verb. XCALL talks to the BBj XCALL server available in BBj 10.01 and higher.

XCALL Server for BBj

The XCALL server is a BBj program found in <bbj install dir>/utils/xcall/xcallserver.bbj. The default prefix includes that path, so that xcallserver.bbj can usually be invoked without specifying a full path.

Starting the Server

The syntax for starting the server is:

bbj xcallserver.bbj {- <port>}

NOTE: If no port is specified, port 4444 is used.

If BBj is running on a different machine from the client, and the called BBj program is GUI or uses client objects, the xcallserver should be run on the client machine with the following command line:

bbj –TC –RH<host> xcallserver.bbj {- <port>}

where <host> is the name of the machine on which BBjServices is running.

The terminal specified for the server is also used for the called BBj program. For example, the INVISIBLE terminal (T2 in the default config.bbx on Windows) can be specified (-tT2) and both the server and the called BBj program will be run with the Sysconsole hidden.

Stopping the Server

To stop the server, use the following command line:

bbj {–RH<host>} xcallserver.bbj - STOP

XCALL Verb (PRO/5 and Visual PRO/5)

The XCALL verb has a similar syntax to the CALL verb:

XCALL "fileid{::label}{&}"{,MODE=<mode string>}{,ERR=lineref}{,TIM=<timeout>}{,exprlist...}

Most of the options are exactly the same as the CALL verb:

fileid is the name of a BBj program on the host machine
label is an optional label within the BBj program
mode string can contain any of the options that can be specified in the xcall.ini file
ERR= specifies an error branch to take if the XCALL fails
exprlist is any number of literals, variables, or complex expressions that matches the ENTER statement inside the called BBj program

As with CALL, if a parameter in exprlist is the name of a variable and the corresponding variable is changed inside the BBj program, the new value is returned to the calling program. Unlike CALL, an empty ENTER in the BBj program will not cause the called BBj program to inherit the entire workspace from the calling program.

If adding an ampersand "&" to the end of the fileid{::label} string, the XCALL will return immediately. Because XCALL returns immediately, no variables that have been passed by reference will be changed and any TIM= option will be ignored. Some examples of calling a program with the "&" option:

XCALL "gui.bbj&",a,b%,c$
XCALL "gui.bbj::show_chart&",a,b%,c$

XCALL introduces an additional option, TIM, that specifies a timeout for the XCALL verb. Visual PRO/5 or PRO/5 will wait the number of seconds specified in the timeout to get a response from BBj. The timeout does not specify a total time for running, but the time between receiving packets in a response from BBj. If the timeout expires, the XCALL verb will return an "!ERROR=0 (Busy or not ready)". This option allows the calling program to gracefully handle any situation in which the called BBj program becomes unresponsive. The default value for TIM is 0, which indicates there is no timeout and the XCALL verb will wait forever.

Configuration

XCALL server settings can be specified in an xcall.ini file. The location of this file can be specified by adding an XCALL=filename entry to the config.bbx file. In a situation where config.bbx does not have an XCALL= entry, (V)PRO/5 looks for xcall.ini in the current working directory when (V)PRO/5 (PRO/5 and Visual PRO/5) starts up.

The xcall.ini file can have a PortCommand=<string> statement or a RemoteHost=<hostname> and a RemotePort=<port number> statement. The PortCommand=<string> statement tells (V)PRO/5 what to run and how to get the port number before connecting to the XCALL server.

XCALL's default settings allow (V)PRO/5 to XCALL BBj programs in a BBjServices session running on the default port on the local system:

RemoteHost=localhost
RemotePort=4444

It is only necessary to create an xcall.ini file if the XCALL server runs on a different port, remote machine, or PortCommand=<string> statement is needed. If the XCALL server will launch on a remote machine, "RemoteHost" should be changed to that machine's hostname. If the XCALL Server is invoked on the client machine with -RH<remote host>, RemoteHost should be set to localhost. RemotePort should be specified to match the server's port if the "<port>" option was specified for the XCALL Server.

Windows Configuration Example

The xcall.ini file contains:

PortCommand="C:/Program Files/basis/bin/bbj.exe" "-cC:/Program Files/basis/cfg/config.min" -tT2 -q xcallserver.bbj - 0

For Windows-based systems only, this example causes Visual PRO/5 to start a BBj XCALL server before trying to connect to it. The 0 tells the XCALL server to use any available port and tells VPRO/5 what it is. When a BBj XCALL server is already running, that PortCommand will tell Visual PRO/5 what port the existing BBj XCALL server is running on instead of starting another.

UNIX Configuration Example

The xcall.ini contains:

PortCommand=/usr/local/basis/bin/bbj -c/usr/local/basis/cfg/config.min -tT2 -q xcallserver.bbj - 0

For UNIX-based systems with a graphical user interface (GUI), this example causes PRO/5 to start a BBj XCALL server before trying to connect to it. The 0 tells the XCALL server to use any available port and tells PRO/5 what it is. When a BBj XCALL server is already running, that PortCommand will tell PRO/5 what port the existing BBj XCALL server is running on instead of starting another.

Error Handling

XCALL can report the following errors:

!ERROR Value	Error Description
!ERROR=0	Timeout on the XCALL verb.
!ERROR=11	Could not find the specified key in the INI file
!ERROR=12	Could not find the XCALL.ini file, or could not parse the file.
!ERROR=60	Error parsing XCALL Server response, or other network error.
!ERROR=72	Could not contact the XCALL Server
!ERROR=85	Connection was successful, but the XCALL Server returned an error, more information is available in ERRMES(-1)

ERRMES(85) returns the general error message "XCALL error: See ERRMES(-1) for more details". If the remote system has an error, ERRMES(-1) will return a more specific error message. For all other values of ERR, ERRMES(-1) is equivalent to ERRMES(ERR).

Configuration Examples

Running the XCALL Server locally

This is the simplest configuration, since only machine is involved. If the BBj program is GUI-based, uses Client Objects, or otherwise requires user interaction, it will show up on the local machine. BBj should already be installed on this machine and BBjServices should be running. To enable the XCALL verb in PRO/5 or Visual PRO/5, start the XCALL Server with the following line at the command or shell prompt:

bbj xcallserver.bbj

Running the XCALL Server on a different machine

The next scenario is useful for running BBj programs that do not require user interaction and don't make use of client objects that need access to the client's machine. The XCALL Server runs on a different machine than the BBx program that invokes it. BBj only needs to be installed on the server machine. For this example, suppose the server machine's name is "sparky" and the client machine is "fido". To configure XCALL to work this way:

Start the XCALL Server on sparky:
bbj xcallserver.bbj
If the BBj program is not a GUI program, the -tIO option can be passed to BBj to run in IO mode, which is a lot faster than running with the Sysconsole.
Add the following line to the config.bbx on fido's install of PRO/5 or VPRO/5:
XCALL=xcall.ini
Create a the xcall.ini file in the same directory as the config.bbx file and add the following lines:
RemoteHost=sparky
RemotePort=4444
Repeat steps 2 and 3 on any additional clients.

Running the XCALL Server locally from a remote BBj Server

The third scenario is useful if you want to run a BBj program that is a GUI program, a program that uses Client Objects, or a program requiring user interaction, but BBjServices is running on a different machine. Let's call the server "sparky" and the client "fido" once again. Both sparky and fido will need to have BBj installed. BBjServices will need to be running on sparky, but does not need to be run on fido.

Start the XCALL server on fido (the client machine) with the following line:
bbj -RHsparky xcallserver.bbj
Unless you choose to specify a different port for the XCALL Server, there's no need to create the xcall.ini file. The most important thing to remember for this configuration is that if a xcall.ini is used, RemoteHost should be set to "localhost" or "fido" could be used in this example.

Program Examples

Before these programs can be run, XCALL must be fully configured.

Program 1

This program demonstrates passing a string into a BBj program by reference and having it changed. Note that BBj needs to be able to find hello.bbj. hello.bbj needs to be accessible from the machine that BBjServices is running on. If hello.bbj will be specified without a full path, hello.bbj needs to be in BBj's PREFIX, which is specified in <bbj install dir>/cfg/config.bbx. Otherwise, XCALL will need the full path to hello.bbj specified. It's important to remember that when you specify a program in XCALL, it's BBj that needs to be able to find it.

The BBx program

0005 REM Hello_caller.bbx (compile with pro5cpl)
0010 LET NAME$="Nico"
0020 LET RESPONSE$=""
0030 XCALL "hello.bbj",NAME$,RESPONSE$
0040 PRINT "Response was: ",RESPONSE$
0050 END

The BBj program

REM hello.bbj
ENTER who$, greeting$
greeting$="Well, hello "+who$+"!"
EXIT

The output of the BBx program should appear as:

Response was: Well, hello Nico!

Program 2

This program demonstrates passing two numbers to BBj to be added together. The same notes apply to add.bbj as hello.bbj in Program 1.