XCALL Verb

Description

In PRO/5 and Visual PRO/5 10.0 and higher, XCALL calls external BBj programs using a syntax similar to the traditional CALL verb. XCALL communicates with either the BBj XCALL Server available in BBj 19.00 and higher or the BBj XCALL Client Proxy Server available in BBj 10.01 and higher.

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.

Parameter Description

<fileid>

The name of a BBj program on the host machine.

<label>

An optional label within the BBj program.

<mode string>

Can contain any of the options that can be specified in the xcall.ini file (see Configuration below).

Example:

XCALL "myprog.bbj",MODE="RemoteHost=host2,RemotePort=9990,ssl",x$,y,retval$

<lineref>

Specifies an error branch to take if the XCALL fails.

<timeout>

Specifies a timeout for the XCALL verb.

<exprlist>

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.

Usage

As the XCALL verb is the gateway to using BBj language from PRO/5 and Visual PRO/5, the XCALL Server or XCALL Client Proxy Server must be started in order to process the verb and run the BBj program.

The XCALL Server, as part of BBjServices, is configured to run in Enterprise Manager. All that is needed in the client configuration is the host, port, and SSL information.

The XCALL Client Proxy Server should be started by the PRO/5 client using the port command in the client configuration. Both of these configurations are described in the following Configuration section.

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, PRO/5 or Visual PRO/5 looks for xcall.ini in the current working directory when PRO/5 or Visual PRO/5 starts up.

Note that the XCALL Server and XCALL Client Proxy Server receive different configuration options from the xcall.ini file, as outlined in the tables below.

The xcall.ini file can have the following options when connecting to an XCALL Server:

XCALL Server Configuration Description

RemoteHost=<hostname>

The remote host where the XCALL Server is running. Defaults to localhost if not specified in xcall.ini.
Example:

RemoteHost=sparky.basis.cloud

RemotePort=<port number>

The remote port on which the XCALL Server is listening. Defaults to 4444 if not specified in xcall.ini.
Example:

RemotePort=8645

ssl

Specifies whether SSL is required to connect to the XCALL Server. Defaults to False. True if ssl is included in xcall.ini or the MODE string.

Note: This option must be set if the ssl option is set on the XCALL Server.

The xcall.ini file can have the following options when connecting to an XCALL Client Proxy Server:

XCALL Client Proxy Server Configuration Description

PortCommand=<string>

Specifies the command to start and get the port of the XCALL Client Proxy Server.

Windows example:

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

This example causes Visual PRO/5 to start a BBj XCALL Client Proxy Server before trying to connect to it. The 0 tells the server to use any available port and to report to Visual PRO/5 what it is. When a BBj XCALL Client Proxy Server is already running, that PortCommand will tell Visual PRO/5 what port the existing server is running on instead of starting another.

Unix example:

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

For UNIX-based systems with a graphical user interface (GUI), this example causes Visual PRO/5 to start a BBj XCALL Client Proxy Server before trying to connect to it. The 0 tells the XCALL Server to use any available port and tells Visual PRO/5 what it is. When a BBj XCALL Client Proxy Server is already running, that PortCommand will tell Visual PRO/5 what port the existing 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.

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. Remember: when you specify a program in XCALL, it is BBj that needs to be able to find it.

The PRO/5 or Visual PRO/5 program:

BBx XCALL Example 1
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:

BBj XCALL Example 1

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

The output of the PRO/5 or Visual PRO/5 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 PRO/5 or Visual PRO/5 program:

BBx XCALL Example 2

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 
0060 XCALL_ERR: 
0070 IF ERR = 0 THEN RETRY 
0080 PRINT "!ERROR=" + STR(ERR) + " (" + ERRMES(-1) + ")" 
0090 ESCAPE

The BBj program:

BBj XCALL Example 2

REM add.bbj 
add_numbers: 
ENTER A, Y, C
C=A+Y 
EXIT

The output of the PRO/5 or Visual PRO/5 program should appear as:

1+2=3

See Also

XCALL Server

XCALL Client Proxy Server

Data Server Syntax

Verbs - Alphabetical Listing