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.

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:

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

Error Handling

XCALL can report the following errors:

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:

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

The BBj program:

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:

REM add_caller.bbx (Compile with pro5cpl) 
LET A=1 
LET B=2 
XCALL "add.bbj::add_numbers",ERR=XCALL_ERR,A,B,C 
PRINT STR(A),"+",STR(B),"=",STR(C) 
STOP 
XCALL_ERR: 
IF ERR = 0 THEN RETRY 
PRINT "!ERROR=" + STR(ERR) + " (" + ERRMES(-1) + ")" 
ESCAPE

The BBj program:

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