/deb

Specify Uniface Debugger options.

  • Local debugging (Windows only):

    /deb {=} {ApplicationShell | /tstComponent }

  • Remote debugging:

    /deb{=} TCP:{HostID}+Port{:Command}

    /deb{=} TLS:{HostID}+Port{:TLSProfile}{:Command}

Parameters

  • ApplicationShell—application shell. Starts the application and the Uniface Debugger; the application halts at the first ProcScript statement.
  • Component—component to debug in test mode
  • HostID—TCP host identifier. The format of HostID determines the TCP protocol version to be used. For more information, see TCP Connector.
  • Port—dedicated free port address on the TCP host.
  • Command—command to be executed:
    • create—create a socket for remote debugging on the designated port of the host machine. Note: The application that is started with the create command is considered the network host. The other application attaches to the socket and is considered the network client.

      Note: The application that is started with the create command is considered the network host. The other application attaches to the socket and is considered the network client.

      When used on the command line of the Uniface Debugger, it does nothing until an application connects, then the application is halted and control is passed to the Debugger.

      When used on the command line of an application, the application halts at the first ProcScript statement and waits for the Debugger to connect and take control.

    • wait—designates the application as the network client; the application halts at the first ProcScript statement and waits for the Debugger to become available, then control is passed to the Debugger.
    • nowait—designates the application as the network client; it enables the application for debugging, but does not halt the application if the Uniface Debugger is not yet available. Once the Debugger becomes available, the application halts at the current ProcScript statement and control is passed to the Uniface Debugger.

    If the Debugger is the network client, wait and nowait have no special meaning; you can halt the application manually by choosing Debug > Halt in the Debugger.

    When Command is not specified, the default is create in the Debugger application and nowait in all other applications.

  • TLSProfile—name of a TLS connection profile that is defined in the [NET_SETTINGS] section of the assignment file; applicable only if TLS: is specified in the network connection string. For more information, see TLS Connection Profiles.Note: The name of the TLS profile should not be the same string as a valid command.

Use With

Use /deb on the command line of a Uniface application to run the application and debug it using the Uniface Debugger.

Use /deb when starting the Uniface Debugger (udbg.exe) for remote debugging.

Description

Use the /deb switch to pass configuration options to the Uniface Debugger and the application being debugged.

Local Debugging

For local debugging, the Debugger and application communicate directly with each other on the same machine.

For example:

  • The following command runs a Uniface application, starts the Uniface Debugger, and halts the application at the first ProcScript statement in the Application Execute Trigger in the startup shell:

    uniface.exe /asn=myApp.asn /deb myApp.aps

  • The following command runs a component (form, service, or report) in test mode, starts the Uniface Debugger, and halts the component at the first ProcScript statement:

    ide.exe /asn=myApp.asn /deb /tst myComponent

  • The following command starts the Uniface Debugger and connects to a Uniface application with ProcessID 1234:

    udbg.exe /deb=1234

Remote Debugging

For remote debugging, the Uniface Debugger and the application communicate with each other over a network. They can be running on the same machine or on different machines, and the network protocol can be TCP or TLS.

As partners in the debugging session, the Debugger and application must have compatible configurations, so that one acts as the network server and the other as the network client, and they must use the same network protocol and port number on the host machine.

One partner must be started with the create command. The other must be started with the wait or nowait command. Either partner can be started first, but their configurations must match. This is especially true when using TLS. The TLS profile must define matching client and server settings.

Note the following:

  • Use only one port per debugging session; the Uniface Debugger can debug only one process at a time.
  • Starting an application enabled for remote debugging has an impact on performance, because it needs to poll for the Debugger to become available.

Note: To debug USTs, use the max=1 switch to ensure you connect to only one Uniface Server.

Use the Debugger as Network Server

You can have the Debugger act as the network server and the application function as the network client. To do so:

  1. Start the Debugger as the network server on your local machine:

    udbg.exe /deb=tcp:+13010:create

    The Uniface Debugger starts, and listens for the application on the specified port. The create command causes the Debugger to create a socket on the specified port and act as the network server.

  2. On the other machine (or the same machine), start the application (MyApp) as the network client. You can use the wait or nowait command to instruct the application what to do until the network server, the Debugger, is available.

    For example, if the Debugger was started on a machine whose IP address was 172.16.35.94:

    uniface.exe /asn=MyApp.asn /deb=tcp:172.16.35.94+13010:wait MyApp.aps

    The MyApp application starts and connects to the Debugger, which takes control and halts the application at the first ProcScript statement. You can now proceed to use the Debugger to step through the code.

    Note: If you omit the wait command or specify nowait, it enables the application for debugging, but does not halt the application if the Uniface Debugger is not yet available. Once the Debugger becomes available, the application halts at the current ProcScript statement and control is passed to the Uniface Debugger.

Use the Application as Network Server

You can have the application function as the network server and the Debugger as the network client. However, this has an impact on performance, because it needs to poll for the Debugger to become available.

  1. On one machine, start the Uniface application (MyApp) using the following arguments:

    uniface.exe /asn=myApp.asn /deb=tcp:localhost+13010:create myApp.aps

    This starts the MyApp application, which then stops at the first ProcScript statement and waits for the Uniface Debugger to connect on the specified port and take control. It is possible that the application will not yet be visible on your screen.

  2. On another machine (or the same machine), start the Uniface Debugger with the following arguments, where remotehost is the name of the machine where MyApp is running:

    udbg.exe /deb=tcp:remotehost+13010:wait

    The Uniface Debugger starts, connects to the MyApp application, and displays the halted application's first ProcScript statement. You can now proceed to use the Debugger to step through the code.

Note: When the application is the network host, closing the Uniface Debugger will not close the application. If the application is halted, it will be in an endless idle state.

Once the connection is broken between the Uniface Debugger and the application, it cannot be re-established without restarting both the application and the Uniface Debugger.

Use TLS for Remote Debugging

Using TLS provides extra security when communicating over a network. To use TLS, you need to edit the assignment files to configure the TLS connector and define TLS profiles, and then specify the TLS profile in the /deb options.

For example, to use a pre-shared key for authentication:

  • Add the following to the assignment files of both the Debugger (udbg.asn) and the application (MyApp.asn):
    [DRIVER_SETTINGS]
USYS$TLS_PARAMS=shared_key=V6rySecret! ; this is the default profile

[NET_SETTINGS]
DbgProfile shared_key=V6rySecret!
  • Start the Uniface Debugger on its local machine ( host1):

    udbg.exe /adm=D:\Uniface\uniface\adm /deb=tls:+13020:DbgProfile:create

  • On another machine, start the application:

    uniface.exe /asn=myApp.asn /deb=tls:host1+13020:DbgProfile:wait myApp.aps

If you do not specify a TLS profile, the default profile is used. For example, the following command uses the default TLS profile as specified by USYS$TLS_PARAMS in the assignment file:

udbg.exe /adm=D:\Uniface\uniface\adm /deb=tls:+13020:create

For more information on configuring the TLS connector, see Configure the TLS Connector with a Pre-Shared Key and Configure the TLS Connector to Use Certificates.

Remote Debugging for Web Applications

Uniface provides a pre-configured remote debugging environment for debugging dynamic and static web components, in which the Server Debug shortcut starts the Debugger and a Web Application Server called debug is used to connect to the Debugger when an appropriate URL is used, for example:

http://localhost:8080/uniface/debug/ServerPageName

For more information, see Debugging a Web Application.

Protecting ProcScript from Being Debugged

If the /nodebug command line switch is used when you start the Uniface IDE to compile an application's application shell and components, they cannot be debugged until they are recompiled with debugging enabled, that is, without the /nodebug command line switch.

Related Topics