Running Synergy DBL programs

This topic contains the following information:

• Running programs on Windows and UNIX (dbr)
• Running programs on OpenVMS
• Non-interactive runtimes
• Using dbr or dbs as a scheduled task
• Determining your Synergy runtime version

Running programs on Windows and UNIX (dbr)

After you’ve compiled the sources and linked them into one executable file, use the Synergy runtime to execute your program. The dbr command starts the Synergy runtime. (Additional methods you can use in a Windows environment to invoke the dbr command are explained in Methods for invoking commands on Windows.)

The dbr command has the following format:

dbr [options] [--] program [<input_file] [>output_file]

Options

options

(optional) One or more of the following runtime options. You must precede each individual option with a minus sign (for example, -d -n). In Windows environments, if system option #34 is set, you must use a slash (/) instead of a minus sign before each runtime option or group of options.

--

(optional) Included for consistency with other Synergy DBL command lines but serves no function here.

program

The name of the compiled and linked Synergy program. The default filename extension is .dbr.

input_file

The name of the file from which input will be redirected.

output_file

The name of the file to which output, including any error messages, will be redirected.

Discussion

The runtime executes the program you specify.

See Debugging Synergy Programs for more information about the debugger.

On Windows, input from input_file is not available using the Synergy windowing API (W_) or Toolkit routines. READS and ACCEPT do work. If both input and output are redirected, the application runs as if XSHOW=hide is specified.

Examples

The following example debugs the program while running in a client/server configuration. The debug server listens on port 49151 and waits for a connection from the debug client for 60 seconds.

dbr -rd 49151:60 fred.dbr

Running applications that require elevated privileges (Windows)

If you have Synergy programs that require elevated privileges because they write to protected locations, such as Program Files or the registry, you must use the dbrpriv runtime. (If you’re using a non-interactive runtime, use dbspriv; see The dbspriv runtime.) This version of the runtime has the correct embedded manifest, which will prompt for UAC elevation as required.

The dbrpriv command has the same format as dbr.

Running programs on OpenVMS

After compiling the sources, and linking them into one executable file, there are several ways to execute the file.

1.

Use the DCL RUN command:

$ RUN filename

2.

Include the location of the program in the DCL$PATH logical. For example, if the program executable is in your home directory (SYS$LOGIN), you could run the program as follows:

$ DEFINE DCL$PATH DBLDIR:,SYS$LOGIN:,SYS$DISK:[],UTILS:
$ filename

Note that SYS$DISK:[ ] always refers to the current working directory.

3.

Define a DCL global symbol to be a foreign command to invoke the program. You must prefix the program name with a dollar sign ($), even if the disk name used as part of the full program specification already begins with a dollar sign.

$ MYCOM*MAND:=="$SYS$LOGIN:filename"
$ mycom

Note that an asterisk in the definition of a foreign command indicates the shortest possible abbreviation of that command.

4.

Use a command definition file to define a DCL verb to invoke the program. See your OpenVMS documentation set for information about command definition language.

Non-interactive runtimes

Synergy DBL provides reduced-size, non-interactive runtimes that start up faster than the regular (dbr) runtime because the functions required to control an application’s display and debugging capabilities—which by nature are only available to an interactive session—are minimized. A non-interactive runtime can be used to run cron jobs on UNIX or scheduled tasks on Windows, or to spawn background tasks from a dbr.

There are three non-interactive runtimes:

• dbs (Windows and UNIX)
• dbssvc, which is the service form of dbs (Windows only)
• dbspriv, which is the privileged form of dbs (Windows only)

The dbs runtime

The dbs runtime is intended for detached programs, including xfServerPlus services, on Windows and UNIX. The dbs command has the following format:

dbs [options] [--] program [<input_file] [>output_file]

See Options for a description of the options. The -n option (detached status) is set by default. The -rd option is not available to the dbs runtime.

See Functionality limitations of the non-interactive runtimes for a list of functions that are unavailable or limited in the dbs runtime.

To display version information, press Enter at the dbs> prompt.

The dbssvc runtime

The dbssvc runtime is intended for Synergy programs run as services on Windows. The dbssvc command has the following format:

dbssvc option

option

One of the following options:

The service name appears as a registry key in the Windows registry. The display name will appear in the Services dialog box. The Synergy program to be run must reside on a local drive (not a mapped drive), a UNC path, or a drive that has been mapped via subst.

See Functionality limitations of the non-interactive runtimes for a list of functions that are unavailable or limited in the dbssvc service runtime.

If you want to register a routine to be called when the program executed by dbssvc is stopped, use the %SYN_ATEXIT function.

We recommend that you include an outer TRY/CATCH or ONERROR with an $ERR_CATCH literal in programs that use the service runtime so you can trap any unhandled error, write it to the event log, and then issue a STOP statement.

Dbssvc checks for the existence of the Synergy License Manager service. If it exists, the services running under dbssvc will be made dependent on the License Manager service. If the machine is no longer a license server or if the License Manager service is not started, the services must be re-registered or they won’t start.

The dbspriv runtime

The dbspriv runtime is intended for applications that require elevated privileges on Windows. Dbspriv has the same format as dbs. (See The dbs runtime for syntax.) This version of the runtime has the correct embedded manifest, which will prompt for UAC elevation as required.

Functionality limitations of the non-interactive runtimes

The functions below are unavailable or limited in the dbs, dbssvc, and dbspriv runtimes, which implement limited I/O. If you need to use these functions with xfServerPlus, set the XFPL_DBR environment variable, which causes xfServerPlus to use dbr instead of dbs.

Function	Additional information
/guiwnd option for OPTIONS qualifier	If OPTIONS:"/guiwnd" is specified when code is run with a non-interactive runtime, an error will occur.
MASK qualifier	MASK will not work on a detached program.
Message SEND/RECV
Synergy DBL Profiler	Profiling of code is not available.
Synergy debugger
synergy.ini file	Read only when SFWINIPATH is set.
synuser.ini file	Ignored.
Terminal I/O	Only very minimal terminal I/O is available (ACCEPT, DISPLAY, READS, and WRITES to stdin/stdout for limited debugging).
%TNMBR routine (deprecated)	The terminal number is always -1.
TTSTS routine	TTSTS on TT: is not available.
W_ routines
WAIT routine	WAIT will not work on a detached program.
UI Toolkit	Use of Toolkit is limited to U_START, U_OPEN, U_FINISH, and similar routines that perform no terminal I/O and do not create or use windows.

Using dbr or dbs as a scheduled task

You can use dbr or dbs as a scheduled task to emulate a batch job on Windows.

Scheduled tasks using dbr that are run while a user is logged in will operate and display windows as if run from a command prompt. To disable this behavior, set XSHOW=hide in your batch file.

Scheduled tasks that are run while no user is logged in will operate as if the TNMBR environment variable is set to -1 (detached). In this mode there is no user interface, and UI Toolkit user interface calls should not be made. You can test for %TNMBR.lt.0 to detect this condition.

If you use a scheduled task and want to review any error log that is output when the user is not logged in, redirect stdout to a file. For example:

dbr my_prog > my_out.log

Determining your Synergy runtime version

To display the runtime version you’re using,

1. From a command prompt or the command line, navigate to your dbl\bin directory.

2. Type dbs and press Enter twice.

This command executes the non-interactive Synergy dbs runtime and will display “Synergy DBL Runtime for platform version,” e.g., “Synergy DBL Runtime for MS-Windows X64 v11.1.1f.”

An alternate method on Windows is to look at the listing for Synergy/DE in Control Panel’s Programs and Features, which includes the installed version number. You can also watch our “Check your version of Synergy” Quick Tips video for some additional options on Windows.