SERVEREXEC

Usage

TIBCO iProcess Workspace (Browser)

TIBCO iProcess Workspace (Windows)

Warning: (iProcess only) This expression is not available to the TIBCO iProcess Script Server Plug-in. Therefore, even though you can successfully enter the expression in your iProcess Script plug-in definition, it will not be processed by the iProcess Engine. It will return SW_NA.

Run a program on the server machine on behalf of the current user.

In addition to running the server program, any abox file that is present is processed.

Note: SERVEREXEC and SERVERRUN work identically, except that SERVEREXEC does not start up a program shell; this should be more efficient. However, make sure that the shell program specifier, for example #!/bin/sh is added to the script so that the operating system treats the script as a shell script rather than a text file. If the shell program specifier is not added, this can cause the script to fail on some operating systems.

The SERVERRUN, UNIXEXEC, and UNIXRUN functions are retained to ensure compatibility with earlier applications.

Syntax

SERVEREXEC (cmdline, async)

where:

• cmdline is a text string specifying the command line to run the server program (including any parameters).
Note: Don't forget the extension for programs in DOS or Windows.

The command line may be defined as any other text expression, for example:

SERVEREXEC("\bin\myprog param1", 0)

or 

SERVEREXEC("\bin\myprog " + text, 0)

Maximum length of the command line is 255 characters.

Alternatively, fields may be specified by enclosing them in ampersands (“&...&”), for example:

SERVEREXEC("\bin\myprog &text&", 0)

In this case, the current value of field TEXT will be substituted for &text&. If the field is SW_NA, the value passed is a hyphen surrounded by single quotes ('-'). If the field does not exist, the parameter is interpreted literally.

The maximum length of the command line using ampersands is 990 characters (after expanding fields).

Whichever method is used to specify a field, if the fieldname refers to a memo field, the program receives the full pathname of a file containing the memo text. If it refers to an attachment field, the program receives the full path of the attachment file.

Note: You must use the full pathname with SERVEREXC. If you do not, SERVEREXEC returns a -5 error.
• async is a numeric value specifying whether the server program should be run asynchronously or synchronously.

Value

Program behavior

non-0

iProcess does not wait for the program to exit before continuing.

0

iProcess does wait for the program to exit before continuing. In this case, after the server program has exited, the abox file in the SWDIR\queues\username directory (if present), is processed.

If the SERVEREXEC function is evaluated on iProcess Workspace (Windows), it is treated as if the value of async is always 0.

It is not possible to invoke an interactive server program using SERVEREXEC on iProcess Workspace (Windows).

‘abox’ File Processing

This section applies to Field or Form Commands only.

This file is created by the external program to pass data, and certain special instructions, back to iProcess. It must be called abox and be located in the SWDIR\queues\username directory on return from the external program. (This directory will be current when the program is called.)

To pass data back to iProcess the file should contain one or more ASCII text lines consisting of the name of the field (in capitals), followed by a comma, followed by the data, for example:

CUST_NAME,William Hoycliffe
CUST_BALANCE,153.54

If there is no text after the comma, the field is set to SW_NA.

Note: Text data is NOT enclosed in quote marks; also delimiters are NOT used for date or time data - just enter the figures with the appropriate separators, i.e. DD/MM/YYYY for dates and HH:MM for times.

Returns

One of the following numeric values:

• On a UNIX server:

Value

Description

‑6

cmdline too long to run the program

‑5

Could not write request to SERVEREXEC daemon

‑4

cmdline is blank or SW_NA

‑3

Timed-out waiting for SERVEREXEC daemon response. The time out period is defined in the SWDIR\etc\staffcfg configuration file on the server by the item FGLITO.

‑2

Could not execute server program

‑1

Problem during execution of server program

Greater than 0

Server program’s exit code
• On a Windows server:

Value

Description

‑5

Could not write request to SERVEREXEC daemon

‑2

Could not execute server program

‑1

Problem during execution of server program.

Note: When SERVEREXEC is run on iProcess Workspace (Windows), 1 is returned if the program cannot be executed, not -2 or -1.

Other

Server program’s exit code

Examples

TIBCO iProcess Modeler:

The following examples are all equivalent (although the third example is only possible as a Field or Form Command):

SERVEREXEC("\usr\bin\dbupdate CUST &fld1&&fld2&", 0)
SERVEREXEC("\usr\bin\dbupdate CUST " + fld1 + fld2, 0)
dbupdate CUST &fld1&&fld2&

TIBCO Business Studio:

IPEExternalUtil.SERVEREXEC("\\usr\\bin\\dbupdate CUST &fld1&&fld2&", 0);
IPEExternalUtil.SERVEREXEC("\\usr\\bin\\dbupdate  CUST " + fld1 + fld2, 0);