XCALL Utility


In PRO/5 10.0 and higher, XCALL calls external BBj programs using a syntax similar to the traditional CALL verb. XCALL communicates with 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> ssl bind_address=<address string> debug heartbeat=<X>}

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

In BBj 14.0 and higher, the debug option, specified as a case insensitive string, turns on debug for the XCALL server. This debug will be written to the <bbj>/log/Debug.log* file. Debug can also be activated and deactivated dynamically by setting the global namespace xcallserver.debug variable.

gns! = BBjAPI().getGlobalNamespace(); gns!.setValue("xcallserver.debug",1)

In BBj 15.0 and higher, the heartbeat=<X> option, specified as a case insensitive string, sets the heartbeat interval between the BBj and Java components which comprise the XCALL server. The value of X is as follows:

< 0 : No heartbeat

= 0 : Use the default interval, 60 seconds.

> 0 : Number of seconds for the heartbeat interval.

When the interval is greater than zero, the server will exit if the heartbeat is not received in that interval.

In BBj 17.0 and higher, the server will continue to run if the heartbeat interval is < 0.

In BBj 19.0 and higher, the ssl option can be specified to use SSL Encrypted communication.

In BBj 19.0 and higher, the bind_address=<address string> option can be specified to bind communication to a specific network interface. The default option is (localhost), which only permits connections to the XCALL Server from the same machine. If is specified, any machine can connect to the XCALL Server.

Here are some examples of running the XCALL server:

bbj xcallserver.bbj - 4444

bbj xcallserver.bbj - debug

bbj xcallserver.bbj - 3333 debug heartbeat=30

bbj -tT2 xcallserver.bbj - ssl bind_address= 4444

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> debug}

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, from the same client that started the server, use the following command line:

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

To stop all XCALL servers, regardless of the client that started the server, use the following command line:

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

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...>}

Many 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.
  • <lineref> specifies an error branch to take if the XCALL fails.
  • <timeout> specifies a timeout for the XCALL verb.
  • <exprlist> is any number of literals, variables, or complex expressions that match 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.


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, PRO/5 looks for xcall.ini in the current working directory when 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 PRO/5 what to run and how to get the port number before connecting to the XCALL server.

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


It is only necessary to create an xcall.ini file if the XCALL server runs on a different port or remote machine, or if a 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 one 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:

  1. 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.
  2. On fido, add the following line to the config.bbx of the install of PRO/5 or VPRO/5:
  3. Create the xcall.ini file in the same directory as the config.bbx file and add the following lines:

    The ssl option may be included if SSL encryption is required, and omitted otherwise.
  4. 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.

  1. Start the XCALL server on fido (the client machine) with the following line:
       bbj -RHsparky xcallserver.bbj
  2. 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 an 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, so the file needs to be accessible from the machine that BBjServices is running on. If hello.bbj will be specified without a full path, it 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 is BBj that needs to be able to find it.

The BBx program:

0005 REM Hello_caller.bbx (compile with pro5cpl)

0010 LET NAME$="Nico"
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$+"!"

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.

The BBx program:

0005 REM add_caller.bbx (Compile with pro5cpl)

0010 LET A=1
0020 LET B=2
0030 XCALL "add.bbj::add_numbers",ERR=XCALL_ERR,A,B,C
0040 PRINT STR(A),"+",STR(B),"=",STR(C)
0050 STOP
0080 PRINT "!ERROR=" + STR(ERR) + " (" + ERRMES(-1) + ")"

The BBj program:

REM add.bbj


The output of the BBx program should appear as:


See Also

Data Server Syntax

Verbs - Alphabetical Listing


Copyright BASIS International Ltd. BBj®, Visual PRO/5®, PRO/5®, and BBx® are registered trademarks.