Running Synergy DBL programs

This topic contains the following information:

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

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

Name

Description

Option

Debug

Debug program while running.

-d

Debug after error

Launch debugger immediately following an untrapped error.

-dz

Detached status

The terminal number associated with this job will have a detached status (TNMBR=-1). The program will not display message boxes on Windows systems. (This feature is considered deprecated.)

-n

Remote debug

Debug program in a client/server configuration, where port is the port number on which the debug server will listen as a Telnet server for the debug client. Valid values are 1024 to 65535. (If the specified port is already in use, the runtime will run without the debugger; no error will occur.)Timeout is the number of seconds that the debug server will wait for a connection from the debug client. The default is 120.

-rd port[:timeout]

Terminal settings

(UNIX only) Do not change terminal (stty) settings.

-r

Terminal settings (program startup)

(UNIX only) Do not change terminal (stty) settings on program startup only.

-x

--

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

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.

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

Utility programs that take their parameters from the command line must be executed without the RUN command, which means that method 1 cannot be used.

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:

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:

Name

Description

Option

Help

Print the help screen.

-h

Register service

Register a new service named service_name, where display_name is the display name associated with the service name, program is the path and filename of the Synergy program to be run when the service is started, and program_args are any arguments to program. (If any of these variables contain spaces, they must be enclosed in quotation marks.) If the optional s option is specified, the new service will be started after it is registered.

-r[s] -c service_name -d display_name program [program_args]

Remove service

Remove the specified service.

-x -c service_name

Stop service

Stop the specified service.

-q -c service_name

Version

Display the current version.

-v

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.

Tip

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.

Note

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.