Uniface Installation and Configuration Guide

for Windows

Release 9.7.03
 Please direct questions about Uniface to uniface.info or [email protected].

For comments or questions about this document, you can email [email protected].

Copyright © 2016 Uniface B.V.. All rights reserved.

U.S. GOVERNMENT RIGHTS-Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in
applicable license agreement with Uniface B.V. and/or its predecessor in interest and as provided in DFARS 227.7202-1(a) and
227.7202-3(a) (1995), DFARS 252.227-7013(c)(1)(ii)(OCT 1988), FAR 12.212(a)(1995), FAR 52.227-19, or FAR 52.227-14(ALT
III), as applicable. Uniface B.V.

This product contains confidential information and trade secrets of Uniface B.V. Use, disclosure, or reproduction is prohibited
without the prior express written permission of Uniface B.V.

Uniface is a registered trademark of Uniface B.V.

Adobe® Reader® is a registered trademark of Adobe Systems Incorporated in the United States and/or other countries.

All other company and product names are trademarks or registered trademarks of their respective owners.

Local Build: September 9, 2016, 15:50

 Contents

Contents

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 1 ∙ Installing and Configuring Uniface . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

System Requirements for Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Uniface Installer for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Installing Uniface on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Silently Installing Uniface on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Upgrading From a Previous Release of Uniface 9 . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Installed Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Uniface Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Uniface Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Uniface Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Apache Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Java Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Configuring Uniface to Use a Specific JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Uniface Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 2 ∙ Configuring Uniface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Assignment Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Assignment Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
USYS Path Logicals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Paths and Path Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Paths Available After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Two-Path Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Path-to-Connector Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Configuring a Different Database as the Repository . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 3 ∙ Configuring the Uniface Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Uniface Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Configuring the Uniface Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Define Uniface Server Types (USTs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Pre-Start Uniface Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Uniface Installation and Configuration Guide for Windows 3

Contents

Stop and Start the Uniface Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Registering Clients with the Uniface Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Configure Uniface Router Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 4 ∙ Configuring the Uniface Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Uniface Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Configuring the Uniface Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 5 ∙ Configuring the Web Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Uniface Web Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Web Request Dispatcher (WRD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
SOAP Request Dispatcher (SRD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Configuring the Web Environment on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Configuring a Web Server for Uniface Applications . . . . . . . . . . . . . . . . . . . . . . . . 50
Configuring the Uniface Web Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Configuring Microsoft IIS to Use Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Configuring the Tomcat SecurityManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Configuring the SOAP Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Appendix A ∙ Assignment Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

urouter.asn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
[SETTINGS] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
[SERVERS] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
[PRE_START] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
usys.asn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
wasv.asn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Common Assignment Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
$DEFAULT_NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
$DEFAULT_TCP_HOST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
$DNP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
$MAX_CLIENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
$MAX_SERVERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
$MAX_MONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
$NET_TIMEOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
$PUTMESS_LOG_FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Appendix B ∙ Web Configuration Files and Settings . . . . . . . . . . . . . . . . . . . . . . . . 77

web.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Configuration Settings: Uniface Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
SRD Servlet Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
WRD Servlet Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
ASVTIMEOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
AUTHORIZATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
DEFAULTENCODING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
ERRORDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
MAXFILEUPLOADS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
MAXFILEUPLOADSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
MIDDLEWARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

4 Uniface Installation and Configuration Guide for Windows

 Contents

RESOURCEDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
RESOURCETIMEOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
SESSIONCOOKIE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
TESTABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
UseRunPrefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
WEBAPPURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Appendix C ∙ Executables and Command Line Switches . . . . . . . . . . . . . . . . . . . . 87

Server Executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
urouter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
userver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Command Line Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
/adm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
/asn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
/delacc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
/dnp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
/dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
/drv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
/ex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
/gates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
/hostrc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
/max . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
/maxidle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
/maxreq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
/newacc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
/passwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
/pri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
/shr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
/ust . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Uniface Installation and Configuration Guide for Windows 5

Contents

6 Uniface Installation and Configuration Guide for Windows

INTRODUCTION

This guide describes how to install and configure Uniface on Microsoft Windows platforms.
The Uniface installation includes the Uniface Development Environment, Uniface Router,
Uniface Server and various utilities and connectors for accessing databases, networks, and
applications. Your Uniface license determines which products and features you can actually
use.
The information in this guide is also available in the Uniface Library, which is the main
documentation for Uniface. It contains additional information on configuring database connectors,
network connectors, and third-party integration support. The Uniface Library is provided on
the Uniface installation CD-ROM, and on the Documentation page on the FrontLine Uniface
Web site, where it is updated on a regular basis.

Who Should Read This Guide

This guide is intended for systems administrators and developers who need to install and
configure Uniface products on a Microsoft Windows platform.

Related Documentation
Information in this guide is also available in the Uniface Library, which contains the complete
Uniface documentation as easily searchable HTML Help. For system administrators, it contains
information on configuring database connectors, network connectors, and third-party integration
support.
The following resources provide additional information on configuring and using the Uniface
products:
• Uniface Migration Guide—summarizes what’s new in Uniface APS products and describes
how to migrate or upgrade from an earlier version of the products.
• Uniface DLM Installation and Configuration Guide—provides information and procedures
for obtaining and installing licenses for Uniface products and features.
• Uniface JTi Administrator Guide—provides information on installing and configuring
Uniface JTi, and managing JTi sessions.

Uniface Installation and Configuration Guide for Windows 7

Introduction

Documentation Conventions
The Uniface documentation employs a number of conventions for documenting the syntax and
user interface of Uniface products.

Table 1. Typographic Conventions

Convention Description Used for

Citation Italic font References to other documents.

Emphasis Italic font Emphasizing or introducing a word.

^FUNCTION Caret (^) preceding upper case word Names of structure editor functions, such as
^ADD_OCC

Keystroke Keystrokes in bold. Function keys, key combinations, such as F1

Keys that must be pressed sequentially GOLD key combinations, such as GOLD R.
have a space between them. accelerator and access keys, such as Alt+F4
Keys that must be pressed simultaneously
have a + between them.

Window and Property Bold font Names of windows, fields, and properties in
names the user interface.

Values Monospace font Values of fields, variables, and properties

Proc instructions, Monospace font Proc language instructions and APIs

configuration Assignment settings, initialization settings
settings

FilePath Monospace font Names of directories and files

Syntax Descriptions
The following conventions are used in syntax descriptions, such as Proc statements and functions,
configuration and assignment settings, API operations, and so on.

Table 2. Syntax Conventions

Convention Description Used for

Exact String Information in monospace font must be Commands, options, switches

provided as shown.

VariableContent Information in italics must be replaced by Parameters, values, variables

actual data.

{ ... } Braces ( { } ) are used to show optional Optional arguments, parameters, options, values,
information. or switches

| Vertical bars ( | ) are used to separate a list of Mutually exclusive arguments, parameters,
options where only one item can be entered. options, values, or switches

8 Uniface Installation and Configuration Guide for Windows

 Introduction

Table 2. Syntax Conventions (continued)

Convention Description Used for

;! Underlined punctuation in lists represents Strings containing lists and sublists

GOLD separators such as GOLD ; or GOLD
!

For example, the following syntax description indicates that the rollback instruction can occur
with no following arguments, or with either of the two optional arguments:
rollback {"Connector" | "$Path"}
According to this syntax description, the following forms of the rollback statement are allowed:
rollback
rollback "SYB"
rollback "$MYPATH"

Uniface Installation and Configuration Guide for Windows 9

Introduction

10 Uniface Installation and Configuration Guide for Windows

CHAPTER 1
Installing and Configuring Uniface

The installation program copies the directories, files, and executables required for the Uniface
product components.

NOTE
Always install Uniface into a clean directory or library. Do not install over an existing Uniface
installation.

Uniface supports many different platforms, but not all products and functionality are available
on each platform, so check the installation requirements for each product.
The products installed depend on the platform and the license that you have. For details on
supported platforms and products, see the Platform Availability Matrix.
For products that work with Uniface, such as databases, Web servers, transaction monitors, and
so on, see the documentation supplied for the product. For other products supplied with Uniface,
consult the instructions provided in the Uniface distribution.
After installation, most Uniface products must be configured before they can be used. For more
information, see Configuring Applications in the Uniface Library 9.7.03. For information on
configuring database and network connectors, and other integration support, see documentation
on the specific product.
The readme file contains additional information about installation and configuration. This
information takes precedence over the current documentation.

System Requirements for Microsoft Windows

Uniface supports many different platforms and databases, but not all products and functionality
are available on each platform.
For the supported platforms and databases, consult the readme.htm file or the Platform
Availability Matrix.

Hardware
For the hardware requirements of the Uniface Development Environment, see the readme.htm
file in the Uniface installation directory.

Uniface Installation and Configuration Guide for Windows 11

Chapter 1 ∙ Installing and Configuring Uniface

Installation Directories and Administrator Rights

To install Uniface in the default location under C:\Program Files\, you need administrator
rights.
By default, Uniface creates the following directories:
• C:\Program Files(x86)\Uniface\Uniface Version—Uniface application files
• C:\Users\UserAccount\Documents\Uniface Version Development—default location
for user data, including the Repository, log files, export files, and other application data
files that can be edited by the user.

During installation you can specify different directories for the program files and user data.

Database
SQLite is automatically installed when you install Uniface.
If you want to use another DBMS for the Repository, you must configure Uniface after
installation to use another supported database.

Licenses
During installation, the Dynamic License Manager (DLM) is automatically installed if it is not
already available. If you prefer, you can install it separately prior to installing Uniface.

NOTE
Licenses are not required to install Uniface, but they do need to be available to run Uniface
applications after they have been installed. It is therefore possible for Uniface to be installed
successfully, but to encounter license problems at runtime.

Web Servers and Servlet Engines

The default installation includes a fully-configured Apache Tomcat HTTP Server and servlet
engine. If you already have your own web server, you can configure it to run Uniface applications
after installation.
Uniface web-based applications can be used with any web server capable of connecting to a
servlet engine that is compliant with the 2.3 or 3.0 Java servlet specification. These include:
• Apache Tomcat HTTP Server and servlet engine
• Internet Information Server (IIS)
• IBM WebSphere
• IBM HTTP Server

LDAP Servers
LDAP servers, including Active Directory servers, can be used as sources for registration
information. Uniface support for LDAP servers includes user authentication, user registration,
and user and group synchronization.

12 Uniface Installation and Configuration Guide for Windows

 Chapter 1 ∙ Installing and Configuring Uniface

For LDAP server support, the following assumptions and requirements are made about the
LDAP organizational structure:
• Groups, users, and organizational units can only be placed in organizational units.
• Data is synchronized only for assigned user membership to groups and Uniface-defined
user data; any other membership or data is not synchronized.

Uniface Installer for Windows

The Uniface installer prompts you for the information it needs, and provides on-screen guidance
to help you make the appropriate choices.
The information you are asked to provide includes:
Requested Information Description

Installation Folder File system location where Uniface should be installed.

NOTE
It is not possible to install over an existing installation.

Suite Choose whether to install the Development suite or the Deployment

suite. If you install the Development suite, all products are automatically
installed. If you install the Deployment suite, you can choose the
products and tools that you want to install.

Features If you chose the Deployment suite, select the products you want to install

Program Folder Name of the program folder in the Windows Start menu.

User Data Location for the default SQLite databases created for the Uniface
Repository and user data.

Java Runtime Environment Choose whether to use the JRE provided by Uniface or an existing JRE
(JRE) Configuration installation.

Character Set Choose the character set or code page appropriate for your language.

Service names and port Specify the names and port number to be used for the Uniface Router
numbers and Tomcat services. During installation, these server processes are
installed as Windows services.
The installer checks whether the default port numbers are already in use
and suggests the next available port numbers.

It is possible to install Uniface without user interaction by running setup.exe with command
line parameters. This can be useful when you are deploying Uniface applications to multiple
users.

Uniface Installation and Configuration Guide for Windows 13

Chapter 1 ∙ Installing and Configuring Uniface

Installing Uniface on Windows

Before You Begin
Administrator rights are required to install Uniface.

NOTE
Install Uniface into a clean directory. Do not install over a Uniface APS installation.

1. Run the main setup.exe program from the E-Distribution, as Administrator. (Right-click
and choose Run as administrator).

TIP
If the path to the setup.exe program is long, consider mapping a drive to the location to
make it shorter. The installation may fail if the complete path and file name of a file being
copied exceeds 255 characters, either of the source file or the destination file.

2. Choose Install Uniface and follow the prompts.

The installation program itself includes on-screen information on the meaning and
consequences of the choices you make.

NOTE
Among the information you are prompted for are the Windows user accounts under which
to run the Uniface Server and Uniface Router. The default account names (and passwords)
are userver and urouter. If you don't change these values, the installer will try to create
these accounts.
If these accounts are new, you will probably need to choose better passwords that comply
with your system password policy. If the userver and urouter accounts already exist,
specify their existing passwords.
If it is not possible to add these user accounts, specify an existing Windows account under
which these services can run.

During installation, the Uniface Distributed License Management (Uniface DLM) is installed
(if it is not already available), as well as Uniface.
3. Restart your computer to ensure that all services, libraries, and settings are applied.
4. After installing and restarting your machine, modify the permissions on the Uniface
installation folder so that you can modify configuration files (in \common\adm and
\uniface\adm), add files to the virtual web directory (\uniface\webapps), arite log files,
and so on.
5. If required, install the licenses using Uniface DLM.

NOTE
You will need to run Uniface DLM as administrator.

14 Uniface Installation and Configuration Guide for Windows

 Chapter 1 ∙ Installing and Configuring Uniface

For details, refer to Configuring the License Environment on Windows in the Distributed
License Management Licensing Guide, available as a PDF on the distribution medium.

After installation, Uniface is installed and configured according to the settings you selected.
For example, if you chose the default settings for the development suite:
• Uniface is installed in the specified directory, By default, this is C:\Program
Files(86)\Uniface\Uniface Version.
• The Repository is located in the specified user data directory. By default, this is
C:\Users\UserAccount\Documents\Uniface Version Development\project\dbms.

NOTE
By default, Uniface defines the user data directory under your user account. The directory
Uniface Version Development is visible under My Documents in the Documents
Library.

• The Uniface Router and Tomcat Web Server are automatically started as services with the
specified port ranges.

What to Do Next
If you want to change the configuration, for example, to use a different database or another web
server, refer to the configuration documentation in the Uniface Library.

Silently Installing Uniface on Windows

It is possible to install Uniface products without user interaction by running setup.exe from
the command line with command line parameters. This can be useful when you are deploying
Uniface applications to multiple users.
Syntax: Path setup.exe -r | -s -f1InstallParamsFile
• Path—complete path to the Uniface setup.exe program on the distribution medium. For
example, if you have mapped the E: drive to the location of your unzipped Uniface
installation files, it would be E:\uniface_setup\w32\
• -r —record the installation parameters in a specified file
• -s —silently install the product using the specified parameter file
• -f1InstallParamsFile—complete path and file name to which the installation data is
written during the recording, or from which it is read during the silent installation.

CAUTION
Although the setup parameters file can be edited, this requires knowledge of the format
and is not recommended.

1. Create an installation parameters file. Run the uniface_setup\w32\setup.exe program

from the command line, with the -r (record) options.

Uniface Installation and Configuration Guide for Windows 15

Chapter 1 ∙ Installing and Configuring Uniface

For example, if E is a network drive letter where the Uniface distribution medium is
available:
E:\uniface_setup\w32\setup.exe -r -f1D:\setup.iss

As you follow the prompts of the setup program, these options create a file called
setup.iss.

2. To silently install the product on another machine, run the setup program with the -s (silent)
options.
For example, to install using the previously-created setup.iss file:
E:\uniface_setup\w32\setup.exe -s -f1D:\setup.iss

Upgrading From a Previous Release of Uniface 9

Existing users of Uniface products can upgrade to the current release if they are using a previous
release (such as 9.6) of the same version (Uniface 9).
If you want to upgrade an existing installation of Uniface, you need to be aware of the following:
• As of 9.7.01, Uniface Flow is no longer delivered, so the Workflow workspace, Process
Studio, and test environment have been removed from the Uniface Development
Environment. If you need to maintain Uniface Flow applications, you should continue to
use the Uniface 9.6 Development Environment.
• As of 9.7.01, the default implementation of many widgets for dynamic server pages has
changed from Dojo JavaScript widgets to HTML 5 controls. Depending on the browser,
the HTML controls differ slightly in behavior and appearance from the JavaScript controls.
• As of 9.6.05, SQLite is the default Repository database. If you previously used solidDB,
you can continue to do so but it is not included with the installation media.

Upgrading an Existing Installation

To upgrade an existing installation, you need to install Uniface using the default database, and
then configure Uniface to use your existing (version 9) Repository and environment. It is not
possible to install Uniface over an existing installation if it included Uniface Flow.

Installed Products
Uniface Development Environment
During installation, you can choose either the Development or the Deployment installation.
These are largely the same, but the Development installation includes the Uniface Development
Environment.
The Uniface Development Environment is Windows application for building and maintaining
Uniface applications. It is itself a Uniface application, and is delivered with a pre-configured
runtime environment in which applications can be locally deployed and tested. For more
information, see Uniface Runtime Environment [p. 17].
Application definitions created with the Development Environment are stored in the Uniface
Repository, an SQL-enabled database. For more information, see Uniface Repository [p. 17].

16 Uniface Installation and Configuration Guide for Windows

 Chapter 1 ∙ Installing and Configuring Uniface

Uniface Repository
The Uniface Repository is an SQL-capable database used to store definitions and properties of
development objects, process and organization models, and portals for Uniface applications.
By default, an SQLite database is installed and configured as the Repository. However, it is
possible to use another supported DBMS, Microsoft SQL Server, MySQL, or PostgreSQL. For
the supported databases, see the Platform Availability Matrix.
Uniface includes DBMS connectors for all supported databases. After installation, you can
configure Uniface to use another supported database. For more information, see Configuring
the Database Connector in the Uniface Library 9.7.03. For more information on configuring
and using a specific database for the Repository, consult the Uniface Database Connector
documentation for your database.
Definitions in the Repository can be created, viewed, and maintained using the Uniface
Development Environment. Each object in the Repository is defined once and used often,
which promotes reusability of definitions and the inheritance of properties between parent and
child objects.

Uniface Runtime Environment

The Uniface runtime environment includes executables, servers, and drivers that enable Uniface
to run on almost all platforms and deployment environments. It also includes tools for deploying
Uniface applications into the runtime environment.
The runtime environment can be configured to run on a large number of platform and database
configurations, which constitute the deployment environment. For details of the platforms and
databases that Uniface supports, see the Platform Availability Matrix.

Table 3. Uniface Runtime Environment

Product Component Description

Interpreter A platform-specific process that interprets and executes compiled

application components and libraries.

Application Resources Runtime objects (compiled components and startup shells, global
objects, descriptors), HTML files, images, and other files that make
up an application. They are normally deployed in Uniface archive
files (UAR).

Uniface Server A server-based process that enables Uniface clients to access remote
resources or execute remote components.

Uniface Router A multithreaded process that manages Uniface Servers, including

starting and stopping them, load balancing, and message handling
between processes.

Uniface Router Monitor A Uniface application used to monitor and fine-tune the performance
of the Uniface Router.

Database Connectors Drivers that handle the connection between Uniface and a variety of
DBMSs. Uniface provides a specific connector for each DBMS that
it supports.

Uniface Installation and Configuration Guide for Windows 17

Chapter 1 ∙ Installing and Configuring Uniface

Table 3. Uniface Runtime Environment (continued)

Product Component Description

Uniface WebApplication Server A deployment engine that enables you to deploy Uniface applications
(WASV) on the Web. It integrates a web server, with the Uniface Server,
Uniface Router, and WRD.

Uniface Web Request A Java servlet responsible for brokering requests and maintaining
Dispatcher Web Request connections between Web servers and the Uniface Router.
Dispatcher (WRD) [p. 47]

Uniface SOAP Request A Java servlet responsible for brokering SOAP requests and WSDL
Dispatcher requests.

Uniface Anywhere A platform for Web computing that delivers Uniface applications to
virtually any computer connected to the Internet.

Apache Tomcat
Apache Tomcat is an open-source HTTP web server and servlet engine. It is delivered with
Uniface as part of both its development and deployment installation suites.
The Tomcat server delivered with Uniface is automatically installed and configured during
installation so that you can use Uniface from the initial installation—you can test, debug, and
deploy web applications without first having to install and configure a separate web server and
servlet engine.
However, you can configure another servlet engine that meets your own requirements to run
the Uniface web applications. Uniface servlets run in web servers that support the Java™ Servlet
API, versions 2.3 through 3.1, and require JRE 1.5 or higher.
Tomcat uses the Java Runtime Environment, which must be installed either as part of the Uniface
installation or elsewhere on the machine.
By default, Tomcat is installed as a service with the SecurityManager enabled. The
SecurityManager uses the privileges set in the file ../common/tomcat/conf/catalina.policy
to protect the web server from unauthorized access.
The Tomcat service is started automatically after installation, and when the machine is started.
For more information about Tomcat, see tomcat.apache.org.

Java Runtime Environment

Uniface uses the Java Runtime Environment (JRE) for selected functionality, including running
Java servlets for Uniface web applications, parsing XML, and for Java call-in.
During installation, you can choose to install the JRE provided with Uniface or you can have
Uniface use an existing JRE installation. The installer configures Uniface to use the jvm.dll
provided by the specified JRE, and sets the JAVA_HOME variable of the Apache Tomcat web
server to the selected JRE location.

18 Uniface Installation and Configuration Guide for Windows

 Chapter 1 ∙ Installing and Configuring Uniface

Configuring Uniface to Use a Specific JRE

You can configure Uniface to use a different Java Runtime Environment (JRE) than the one
selected during installation.
To manually configure Uniface to use a specific JRE:

1. Stop Uniface and the Tomcat web server, if they are running.
On Windows, choose Web Server ➤ Stop Tomcat Service from the Uniface program
group.
2. Edit the service.bat file located in UnifaceInstall\common\tomcat\bin, and set the
JAVA_HOME variable to the location of your Java installation's JRE directory:

NOTE
The JRE used by Tomcat must be version 1.5 or higher; otherwise the Tomcat service will
not start.

For example:
@echo off
chcp 1252
set CATALINA_HOME=D:\Uniface 9.6.05\common\tomcat
;set JAVA_HOME=D:\Uniface 9.6.05\common
set JAVA_HOME=C:\Progra~1\Java\jre1.6.0_12

3. Specify the location of the jvm.dll in the [ USER_3GL] section of the usys.asn file,
located in UnifaceInstall\common.
For example:
[USER_3GL]
;D:\Uniface 9.6.05\common\jre\bin\client\jvm.dll(JNI_CreateJavaVM)
C:\Progra~1\Java\jre1.6.0_12\bin\client\jvm.dll(JNI_CreateJavaVM)

4. Rerun services.bat to use the JRE.

5. Restart Tomcat, then restart Uniface.

Uniface Directory Structure

After installation, the Uniface product directory contains the software for the Uniface
Development Environment, and the servers and connectors that support it and the applications
you develop with it.
The Uniface product directory contains the following main subdirectories:
• common—includes common components, executable and binary files, configuration files,
and a single Tomcat web server.
• uniface—contain all files that are specific to the Development Environment

Both directories contain a number of subdirectories, including:

• \common\adm and \uniface\adm—configuration files.
• \common\components and \uniface\components—application components
• \common\usys—UAR, URR, and DIS files containing the runtime components required
for deployment

Uniface Installation and Configuration Guide for Windows 19

Chapter 1 ∙ Installing and Configuring Uniface

• \uniface\sql—SQL scripts for creating Repository tables in supported databases

• \uniface\webapps—virtual root directory for the product's Web applications. The Tomcat
Web server (located in common) is configured to use these directory locations.

On Windows, the default location of the data directory is

C:\Users\UserAccount\Documents\Uniface Version. It contains the data outputs created
with the Uniface Development Environment, including the Repository, compiled components,
log files, and other files required by your application.
A number of these directories are specified in predefined USYS path logicals, ensuring that
each Uniface product or application can locate the files appropriate to its environment.

20 Uniface Installation and Configuration Guide for Windows

CHAPTER 2
Configuring Uniface

After installation, Uniface can be configured to work with the preferred databases and web
servers, or to run in a distributed environment.
Deploying any Uniface application is largely a matter of configuring the environment to ensure
that all components are running in the appropriate locations and that Uniface is able to find
them. Configuration files ensure that the Uniface runtime environment can locate and initialize
the application components correctly.
The complexity of the environment determines the complexity of the configuration process. To
configure Uniface on a standalone machine is much simpler than to configure a client/server
environment with the Uniface Router, Uniface Server, and multiple databases.
Configuring Uniface products relies heavily on assignment files to specify paths and protocols,
and on initialization or configuration files to customize the application.

Configuration Files
Uniface configuration files include assignment files, initialization files, and web application
files.
• Assignment files (*.asn) contain settings that establish the location, language, and defaults
for the application. Usually, each Uniface application has its own assignment file, but files
can be named, organized, and chained to suit organization's requirements.
• Initialization files (*.ini) contain settings that determine the GUI resources and language
settings to use for the client application. Some GUI features are dependent on the current
operating system. They enable the user to set user interface defaults.
• Web application files (web.xml) contain settings that configure the WRD servlet used to
execute Uniface Web applications.

NOTE
The Uniface Development Environment is a Uniface application, so you can use its assignment
and initialization files to customize your development environment.

Uniface Installation and Configuration Guide for Windows 21

Chapter 2 ∙ Configuring Uniface

By default, most configuration files are located in the \common\adm and \uniface\adm
directories of the Uniface installation.

Uniface Configuration Files

The following tables list the most commonly used assignment files. These can edited to suit
your own environment or used as a model for creating the configuration files required for your
application.
When starting Uniface applications, you need to specify the location of its configuration files
using the /adm command line switch.

Table 4. General Configuration Files

The following files are located in the UnifaceInstallDir\common\adm directory.

File Purpose

dbms.asn Defines the database driver and default paths for the Development
Repository

usys.asn Defines the language and the location of components used by the Uniface
via the USYS environment variable.

urouter.asn Defines the Uniface servers that the Uniface Router is responsible for.

usys.ini Defines logical paths and Windows-specific initialization settings for the
Uniface applications and servers.

Table 5. Development Environment Files

The following files are located in the UnifaceInstallDir\uniface\adm directory.

File Purpose

idf.asn Defines the settings and logicals for the Uniface Development
Environment

udbg.asn Defines the settings for the Uniface Debugger.

userver.asn Defines the settings for the Uniface Server.

wasv.asn Defines the settings for the Uniface Web Application Server used for
testing.

uproperties.ini Defines the logical to physical widget mappings for Dynamic Server Page
widgets.

usys.ini Defines logical paths and Windows-specific initialization settings for the
Uniface IDE.

Assignment Files
A Uniface assignment file contains one or more assignment settings, which determine the
environment of a Uniface application and control aspects of its behavior. Assignment settings

22 Uniface Installation and Configuration Guide for Windows

 Chapter 2 ∙ Configuring Uniface

can determine the location of application resources and servers, set environment variables,
define application logicals, and set Uniface system settings to influence runtime behavior.
Each application and Uniface product has its own assignment file, usually with the same name
as its startup shell or executable. When you start an application, Uniface builds an internal
assignment file from a global assignment file (usys.asn) followed by a local assignment file
(for example, myapp.asn). Settings in the local assignment file take precedence over those in
the global assignment file.
In fact, it is possible to have multiple global and local assignment files, because one assignment
file can reference another assignment file using the #FILE directive. This makes it possible
name and organize assignment files to suit your requirements.
An assignment file is an ASCII or EBCDIC text file (depending on the platform) with the
extension .asn, so you can use any ASCII file editor to create or edit assignment files.

NOTE
If you use non-ASCII characters in an assignment file, you need to save it in the Unicode
(UTF-16 or UTF-8) encoding.

Assignment File Syntax

An assignment file is divided into sections, which organize assignment settings and allow
Uniface to check the syntax of your assignments. For more information, see Assignment File
Sections [p. 24].
The assignment settings themselves typically have the format :
Setting {=} Value
For more information, see Assignment Settings [p. 25].
In addition to section headers and settings, an assignment file can include:
• Comment lines—denoted by a semicolon (;). The semicolon can be preceded by spaces
and tab characters, but not by other characters.

NOTE
Comments must be defined on separate lines. They cannot be defined on the same line as
an assignment setting.

• #FILE directives—used to include the contents of another assignment file. For more
information, see Including Assignment Files in the Uniface Library 9.7.03.
• Blank lines—to enhance readability by separating groups of related assignments.

Sample Assignment File

;sample assignment file
#file D:\Uniface 9.6.05\common\adm\dbms.asn

[SETTINGS]
$putmess_logfile = D:\Uniface 96 Data\log\mylog.log

[FILES]
my*.frm D:\myapp\components\my*.frm

Uniface Installation and Configuration Guide for Windows 23

Chapter 2 ∙ Configuring Uniface

Assignment File Sections

All assignments that follow a section header belong to that section, until another section header
is found, or until the end of the file.

Table 6. Assignment File Sections

Section Description

[SETTINGS] Settings that control your Uniface application, such as application

appearance, I/O behavior, application environment settings, testing,
compatibility settings, and so forth.

[DRIVER_SETTINGS] Connector-specific settings, such as the connector version and

connector-specific parameters. The parameters available depend on which
connector is in use.

[SERVERS] Server names (USTs) of Uniface servers; used only in the Uniface Router
assignment file (urouter.asn).

[PRE_START] USTs of Uniface servers that the Uniface Router should automatically
start when the Router starts; used only in the Uniface Router assignment
file (urouter.asn).

[PATHS] Paths to DBMS, network, or GUI drivers. Path assignments can include
path-to-connector assignments and path-to-path assignments.

[RESOURCES] Paths to the locations where Uniface must look for Uniface objects. These
are usually .uar files but can also be directory paths. Uniface applications
use this section to locate all the objects they need.

[FILES] Paths to non-DBMS files.

[ENTITIES] Paths to individual entities, giving the target database table a different
name than the name of the entity, or specifying the physical file name for
database tables for record-level databases.

[LOGICALS] Logical value definitions that you can access in your application using the
$logical Proc function.

[SERVICES_EXEC] Direct the execution of service components to a network path, COM

connector, or SOAP connector.

[REPORTS_EXEC] Direct the execution of report components to a network path specified in

the [PATHS] section. The report component is then executed by the
Uniface server identified by the UST in the path definition.

[WIDGETS] Logical to physical widget mappings in character mode

[PROXY_SETTINGS] Proxy settings used by the UHTTP component

[USER_3GL] Uniface 3GL extensions to be made available to the application

[XLOGIN] Network paths requiring extended logon

[META_CHARSET] Defining your own mappings between Unicode and the character set
specified in LANGUAGE.

24 Uniface Installation and Configuration Guide for Windows

 Chapter 2 ∙ Configuring Uniface

Assignment Settings
An assignment setting is a setting or definition in an assignment file that determines one aspect
of the behavior or environment of a Uniface application. Assignment settings can specify the
location of application resources and servers, set environment variables, define application
logicals, and set Uniface system settings to influence runtime behavior.
For example, assignment settings can:
• Define the location of DBMS tables referenced by the application
• Define the location of non-DBMS files accessed by an application
• Specify where components are executed
• Set environment variables for the development, testing, and production of the application
behavior
• Specify the language to be used for messages and help texts
• Define application logicals that can be accessed with the $logical Proc function
• Define any Uniface system setting, to influence runtime behavior
• Specify the keyboard translation table and device translation table to be used

By changing the settings in an assignment file, you can change the language or appearance of
your application, or change the location of tables or files associated with your entities, without
changing entity definitions, and without recompiling the application and its components. For
example, you can configure distinct environments for the development, testing, and production
of your applications. To change from a Development Environment to a production environment,
you only need to change the assignment file so that it refers to data in your production
environment.

Syntax
With a few exceptions, assignment settings have the following syntax:
Setting {=} Value

• Setting—name as used by Uniface; this can be a setting name, a logical name used by
Uniface to locate a non-DBMS file, a DBMS table or file, and so forth.
• Value—assignment for Setting; this can be one or more values for a setting, the name
of the non-DBMS file, a target for a DBMS file, and so forth.

An assignment setting:
• Must occur on a single line
• Must be located in the section to which it belongs
• Cannot be continued onto following lines
• Cannot be followed by a comment

The two parts of an assignment can be separated by multiple spaces, tabs, and/or a single equal
sign (=).

Uniface Installation and Configuration Guide for Windows 25

Chapter 2 ∙ Configuring Uniface

Uppercase and Lowercase

Uniface system settings, parameters, path names, and connector mnemonics are not case-sensitive;
by convention, uppercase is usually used. You can use either uppercase or lowercase, although
it is advisable to use one convention.
The case used for tables, files, and logon specifications depends on the operating system, or
DBMS, or both. Unix, for example, is case-sensitive, while Microsoft Windows is not.
As a simple rule, the left side of an assignment is not case-sensitive, but the value or (right-hand
side) may be case-sensitive, depending on the context.

Wildcards
Use the asterisk (*) as the wildcard character in assignment files.
When using wildcards in path assignments:
• Place assignments specific to an application in a local assignment file, not the global
assignment file.
When the application looks for an assignment to locate a specific entity, it searches the
global assignments before local assignments. For example, if it needs to locate
ENT2.MYMODEL and finds the assignment *.MYMODEL = $SOL as a global assignment,
it uses that instead of the more specific local assignment ENT2.MYMODEL = $ORA
• Place wildcard assignments after specific assignments, since Uniface uses the first
specification that matches the criteria.

Referring to the Installation Directory

In assignment files, Uniface recognizes USYS: as a special symbol for the \usys subdirectory
of the Uniface installation directory. Similarly, it recognizes USYSADM, USYSBIN, and USYSLIB
as special symbols for the \adm, \bin, and \lib subdirectories.
Uniface adds this as a prefix to the logical names of files it expects to find in the installation
directory (for example, USYSADM:usys.asn). In the right-hand part of assignments, you can
use USYS:, USYSADM:, and so on, rather than repeatedly specifying the exact directory name
for the installation directory.
The location of the installation directory is determined differently on each platform. For example,
on Unix an environment variable, $USYS, defines the location, whereas on Microsoft Windows,
an .ini file setting is used.
For more information, see USYS Path Logicals [p. 26].

USYS Path Logicals

USYS path logicals can be used in assignment files and Proc to direct files to specific locations,
without having to explicitly specify the complete path each time.

26 Uniface Installation and Configuration Guide for Windows

 Chapter 2 ∙ Configuring Uniface

Table 7. USYS Path Logicals

Logical Description

USYSINS: Full path specification of the Uniface installation directory, for

example: D:\Uniface\Uniface 9.7.

USYSADM: Full path specification of the \adm directory containing assignment

and initialization files. Both the \common and \uniface
subdirectories contain an \adm directory.

USYSBIN: Full path specification of the USYSINS:\common\bin directory

containing executables and libraries.

USYSCOM: Full path specification of the Uniface USYSINS:\common directory.

USYSUNIFACE: Full path specification of the USYSINS:\uniface product directory,

which contains the Uniface application files

USYS Full path specification of the USYSINS:\common\usys (Uniface

system) directory for the application.

USYSxxx User-defined logical to define a specific directory for a Uniface

application, for example, USYSMYFILES.

With the exception of user-defined USYSxxx, the values of these logicals are automatically set
during the installation process. The way in which the logicals are defined and set depends on
the platform:
• Windows—settings in the [paths] section of usys.ini, or environment variables
• Windows Mobile—registry settings

USYS path logicals make it easier to redirect files, because the exact path need only be specified
once. Files can then be directed to a location relative to that path by referencing the logical.

For example, the usys.ini file for Uniface (located in the \uniface\adm subdirectory) specifies
the USYSUNIFACE logical (among others):
[paths]
helpdir=D:\Uniface\Uniface97\common\doc\help
usys=D:\Uniface\Uniface97\common\usys
usysbin=D:\Uniface\Uniface97\common\bin
usysins=D:\Uniface\Uniface97
usyscom=D:\Uniface\Uniface97\common
usysuniface=D:\Uniface\Uniface97\uniface
javascript=D:\Uniface\Uniface97\uniface\webapps\uniface\dspjs
usysadm=D:\Uniface\Uniface97\uniface\adm

The startup shell and other files required by the Uniface Development Environment are directed
to a path that is relative to the Uniface product directory stored in the USYSUNIFACE logical:
[FILES]
usys:idf.aps usysuniface:components\idf.aps

usys:uu*.frm usysuniface:components\uu*.frm
usys:uu*.svc usysuniface:components\uu*.svc
qrcode.frm usysuniface:components\qrcode.frm

Uniface Installation and Configuration Guide for Windows 27

Chapter 2 ∙ Configuring Uniface

Paths and Path Assignments

A path is a named route to a resource required by the application. A path can be to a DBMS
connector, a network connector, a remote server, a GUI connector, or to another path. A path
assignment is a setting that maps a path to the resource. Paths can be redirected to other paths,
providing flexibility in configuration.
You can use the path mechanism to create as many routes to underlying databases as each DBMS
can handle. The advantage of multiple routes is that system administrators can easily change
from one DBMS to another, or redirect I/O from one database to another in the same DBMS,
or apply varying degrees of operator privileges. The path mechanism is useful, for example,
when going ‘live’ with an application and changing database I/O from test data to production
data.

Path Assignments
Path assignments typically define the route to a database. For example, the following path
assignment goes to the SOLID DBMS connector and a physical database:
$SOL SOL:nmpipe MyDatabase:|DBUsername|DBPassword

NOTE
To prevent sensitive logon information from being visible in assignment files, you can use the
Pathscrambler utility. For more information, see Encrypting Path Definitions in the Uniface
Library 9.7.03..

There different types DBMS path assignments for different purposes:

• Path-to-connector assignments to provide logon information for DBMS or network
connectors. For more information, see Path-to-Connector Assignments [p. 30].
• Path-to-path assignments to direct application model entities on one path to another path.
For more information, see Path-to-Path Assignments in the Uniface Library 9.7.03.
• Entity-to-path assignments:
◦ To direct an entity or group of entities to another path
◦ To change the name of the target table for an entity or group of entities
◦ To specify the target directory when the path leads to a record- level DBMS

For more information, see Entity-to-Path Assignments in the Uniface Library 9.7.03.

In addition, file-to-path assignments refer to server-based files and file-to-file assignments can
assign or rename a file.
In path assignments, USYS path logicals can be used to direct files to specific locations, without
having to explicitly specify the complete path each time. For more information, see USYS Path
Logicals [p. 26].

28 Uniface Installation and Configuration Guide for Windows

 Chapter 2 ∙ Configuring Uniface

Logical and Physical Paths

There are physical paths and logical paths to databases. A physical path leads to a DBMS or
network driver and can include a node name or a database name and logon information. For
example:
$DBMS = sol:nmpipe userdata:|HarryJoe|hispw

A logical path is created by assigning one path to another path. For example:
$MyDB = $DBMS

Any name can be used for a logical path.

Paths Available After Installation

After you have installed Uniface, a number of paths are automatically available.

Table 8. Paths Available after Installation

Path Description

DBMS, Network, and GUI Paths

$xyz A default path, such as $SYB, $TCP

$INS_ xyz An installation path, such as $INS_SYB, $INS_TCP

Repository Paths

$DEF Path to the DBMS chosen as the default at installation.

$IDF Path to the DBMS containing the application model DICT of the Repository
.

$SYS Path to the DBMS containing the application models PRINTER and SYSENV
of the Repository

$UUU Path to the DBMS containing the application model TEXT of the Repository

Runtime Paths

$SRU Path to the remote server used for executing Uniface service and report
components

$RES Path to the deployed runtime objects.

Development Paths

$RSO Path to runtime objects under development. This can be to resource files located
on the file system (as specified in the $RESOURCES_OUTPUT assignment setting),
or to various files and repository tables (component files, DOL and URR files,
UOBJ and ULANA repository tables).

Two-Path Structure
For each connector that you include in your Uniface installation, the installation procedure
creates a two-path structure leading to that connector. The default path is directed to the
installation path and the installation path is directed to the connector itself.

Uniface Installation and Configuration Guide for Windows 29

Chapter 2 ∙ Configuring Uniface

For example, if you include a connector for Sybase in your installation, you automatically have:
• The default path $SYB
• The installation path $INS_SYB
• The connector itself, SYB
• An assignment that directs the default path, $SYB, onto the installation path, $INS_SYB
• An assignment that directs the installation path, $INS_SYB, to the connector, SYB

This structure is used for each DBMS, network, and GUI connector that you include in your
installation. Each connector is identified using the three-letter connector code. For example, if
you include the network connector for TCP/IP, the default assignment file automatically includes
the default path $TCP, the installation path $INS_TCP, and the connector TCP.
Uniface creates this two-path structure so that you can channel a number of paths, such as $SYB,
$DEF, $IDF, and so on, into a single path such as $INS_SYB.
This two-path structure:
• Minimizes the number of paths to the DBMS that are open at any one time. This can be
important for a DBMS that has a limited number of open ‘channels’ or logons available.
• Allows you to switch several paths to another DBMS or network with only one assignment,
for example, by changing $DEF from $INS_CIS to $INS_SYB or by changing $SYB from
$INS_SYB to $INS_CIS.

Although this two-path structure is present after installation, it is possible that it is not necessary
in your situation. In any case, you can use your own assignments to define your environment.

Path-to-Connector Assignments
Path-to-connector assignments are used in client assignment files to provide logon information
for local database connectors, network connectors, and Uniface Servers.
• A database connector path references a local database connector.
• A network connector path references one or more networks, and is ordinarily terminated
by a Uniface Server reference.
• A Uniface Server connector path references a database server, file server, application server,
component server, or ANY server. It must be preceded by one or more network references.

Database Connector Path

A database connector path references a local database connector, which must be the only
connector referenced in the path assignment.
Syntax:
$Path {=} DatabaseConnectionString
The syntax of the DatabaseConnectionString is:
DBmnemonic: { DBMS } | { UserName|Password }

• $Path—name of a default path (for example $SOL) or an installation path (for example
$INS_SOL),

30 Uniface Installation and Configuration Guide for Windows

 Chapter 2 ∙ Configuring Uniface

• DBmnemonic—three-letter Uniface mnemonic for a database connector, for example SOL

• DBMS—database name, when appropriate; for example, usys.db.
• UserName— DBMS logon name
• Password—password for UserName

For example:
;Path to local database
$DBMS SLE:D:\Uniface\Uniface Data\project\dbms\usys.db

NOTE
The DBmnemonic, UserName, and Password may each be replaced by a question mark (?) or
completely omitted. If the target connector requires the missing information, a Logon dialog
box for the database is displayed.

Network Connector Path

A network connector path references one or more networks. Uniface only supports the TCP/IP
network protocol.

NOTE
A network connector path is ordinarily terminated by a UST, which references a Uniface Server.

Syntax:
$Path {=} NetworkConnectionString{+...NetworkConnectionString}{|UST} {/ex}
The syntax of NetworkConnectionString is:
TCP:{HostID}{+Port}|{UserName}|{Password}

• $Path—user-defined path name.

• TCP—three-letter Uniface mnemonic for the TCP/IP network connector.
• HostID—network node name for the host, for example SERVERHOST or 127.0.0.1
The format of HostID determines the TCP protocol version to be used. For more information,
see TCP/IP and IPv6 Connector in the Uniface Library 9.7.03..
• Port——port number on HostID on which the Uniface Router process is listening.
• UserName—logon name and additional (operating system-specific) information to log on
to HostID. Additional information might be, for example, a domain name used by HostID
to validate UserName.
For example, Marketing\JohnDoe is used on Windows platforms, where Marketing is
the domain name and JohnDoe is the user name, separated with a backslash (\).
• Password—password of UserName to log on to HostID.

NOTE
HostID (including Port), UserName, and Password may each be replaced by a question
mark (?) or completely omitted. If the target connector requires the missing information,
a Logon dialog box for the network is displayed.

Uniface Installation and Configuration Guide for Windows 31

Chapter 2 ∙ Configuring Uniface

• UST—Uniface Server Type; name of a specific Uniface Server configuration that is declared
in the [SERVERS] section of the Uniface Router assignment file urouter.asn on HostID.
If the UST is omitted, the default UST is used (called DEFAULT).
• /ex—Uniface Server running on HostID is exclusive for this client session. The Uniface
Server will not be shared with other client sessions. The /ex switch is allowed only after
the last network connector reference in the list. For more information, see /ex [p. 93].

For example:
;Path to a server specified by the UST "gen"
$TCP = TCP:host|user|password|gen

Server Connector Path

A server connector path references a Uniface Server that is acting in a specific role. It is not
needed if the Uniface Server can act in ANY role.
A server connector path must always be preceded by one or more network references. It is
therefore only found in the following path constructions:
$Path {=} NetworkPath + UnifaceServerRole:||
$Path {=} NetworkPath + DatabaseConnectorString

• $Path—user-defined path name

• NetworkConnectorString—see Network Connector Path [p. 31]. The network path
usually terminates with the UST that identifies the Uniface Server.
• UnifaceServerRole—three-character code specifying the role that the Uniface Server is
performing.

Table 9. Uniface Server Roles

Code Server Role Description

ANY (or blank) ANY server Performs all Uniface Server functions. User
name and password are not required, but you
can have multiple database paths or logins.

Database connector code Database Server Connects to the database connector.

(such as SOL, DB2, ORA)

FIL File Server Locates Uniface resources files

SRU Application Server Executes the remote components of a Uniface

application, such as services and reports.

S3C Component Server Calls non-Uniface components that the

Uniface application needs

• DatabaseConnectorString—see Database Connector Path [p. 30]. There is only one

database path or login.

32 Uniface Installation and Configuration Guide for Windows

 Chapter 2 ∙ Configuring Uniface

For example:
;Path to database server on host
$DATA = TCP:host|user|password|data + ORA:ORAUSYS:|dbuser|dbpassword
;Path to file server on host
$FILESERVER = TCP:host|user|password|files + FIL:||

Router Hopping
If more than one network connector is specified, Uniface hops via the Uniface Routers to the
last one. The last Uniface Router needs logon information using UserName and Password; all
other Uniface Routers accept any client. You can chain Uniface Routers up to the maximum of
8 Routers.
For example:
;Path to SOLID server on host2 behind a firewall
$DATA = TCP:host1||| + TCP:host2|user|password|hop + ORA:ORAUSYS:|dbuser|dbpassword

NOTE
You cannot use this path syntax for postmesssages or for DNP registration. You can register
only to one Uniface Router and never via another Uniface Router. For more information, see
Inter-Component Messaging in the Uniface Library 9.7.03.

DBMS Channels
For many field-level DBMSs, each path to a connector results in a channel to that DBMS, in
other words, a different logon. In most cases, Uniface supports as many open channels to the
DBMS as the DBMS can handle. However, not all DBMSs support more than one logon.

Logon Information
When a path to a connector that requires logon information is accessed for the first time, the
user must supply this information on a database or network logon dialog box, unless the required
information is already available.

Typical Path Assignments on the Client

The following are examples of typical path assignments you might use in your client assignment
files:
;Path to file server on host
$FILESERVER = TCP:host|user|password|files + FIL:||
;Path to application server on host
$APPLICATIONSERVER = TCP:host|user|password|services + SRU:||
;Path to component server on host
$COMPONENTSERVER = TCP:host|user|password|components + S3C:||
;Path to ANY server on host
$TCP = TCP:host+13001|user|?|ust + ANY:||
;Path to ANY server on host
$TCP = TCP:host|user|password
;Path to exclusive database server on host
$DATA = TCP:host|user|password|data /ex + SOL:SOLID:|dbuser|dbpassword
;Path to exclusive ANY server on host
$TCP = TCP:host+13001|user|?|ust /ex

Uniface Installation and Configuration Guide for Windows 33

Chapter 2 ∙ Configuring Uniface

Configuring a Different Database as the Repository

Uniface uses SQLite as its default Repository. To use another database, you need to configure
the Uniface Development Environment after it is installed.

Before You Begin

You must have administrator privileges to create the database and the tables.
Ensure that the database you want to use is supported as a Uniface Repository. See the Platform
Availability Matrix.

1. Create a new database. For database servers, create a new database in your target database
environment. For more information, consult your database product documentation, or
contact your database administrator for assistance.
2. Create the database tables in the target database environment using the appropriate SQL
script file for your database.
The Uniface repository scripts are located in \uniface\sql subdirectory of the Uniface
installation.
3. Edit the dbms.asn assignment file in UnifaceDis\common\adm to set the correct database
connector and parameters.
Alternatively, you can edit another assignment file to override the default specified in
UnifaceDis\common\adm\dbms.asn. For example, UnifaceDis\uniface\adm\ide.asn.
Follow the instructions and settings in these files to direct the Uniface applications to use
your newly created database. For more information, see the Uniface database connector
documentation for your database.
For more information, see Configuring the Database Connector in the Uniface Library
9.7.03.

34 Uniface Installation and Configuration Guide for Windows

CHAPTER 3
Configuring the Uniface Router

The Uniface Router is responsible for interprocess communication in Uniface applications. To

configure the Uniface Router, you need to edit its assignment file.

Uniface Router
The Uniface Router is a multithreaded process responsible for interprocess communication in
Uniface applications. It listens for requests from Uniface client applications and routes them to
the appropriate Uniface Server (starting and stopping Uniface Servers as required), and passes
messages between various Uniface applications.
The Uniface Router sits between the Uniface client applications and the Uniface Servers that
execute the client requests and performs the following tasks:
• Starts and stops Uniface Server processes—upon client request, the Uniface Router starts
a Uniface Server that can be used by multiple clients. The Uniface Router can also
automatically pre-start servers (Uniface Server instances) when the Uniface Router starts.
• Load balancing—the Uniface Router determines how many Uniface Servers can be started
and directs individual client requests to a particular Server. The Uniface Router is responsible
for load balancing the overall application.
• Message passing—the Uniface Router can pass (post-) messages between various Uniface
processes.

Architecture
The Uniface Router maintains a thread for each client and a linked list of all known Uniface
Servers, including the connection setup information and parameters.
At startup, the Uniface Router initiates a network listen thread on a configurable port number
for up to four different networks. You can specify four different network protocols, or the same
protocols with different port numbers, or a combination. The port numbers are used by both
clients and servers to connect to the Uniface Router. For example, the following instruction
starts a Uniface Router with three listen threads:
urouter tcp:+13001 tcp:+13002 tcp:fringe+13003

Uniface Installation and Configuration Guide for Windows 35

Chapter 3 ∙ Configuring the Uniface Router

NOTE
If you do not specify a network on the command line, the value of the $DEFAULT_NET assignment
setting is used. If $DEFAULT_NET is not defined, the default protocol is TCP and the default port
number is 13001 (or the port number that was assigned during installation, if 13001 was not
available).

Every client sends its requests to the Uniface Router process via the port it is listening to, and
the Uniface Router determines which Uniface Server is most appropriate to handle each request.
The Uniface Server is a general server that can deliver both data services and application services
to Uniface clients. The Uniface Router can start Uniface Server, and Uniface Servers that have
been started elsewhere can register with a particular Uniface Router.
Uniface Servers typically run on the same machine as the Uniface Router. However, you can
configure a Uniface Server to run on a separate machine if you start it manually. In this case
you must specify the Uniface Router address in the /dnp switch, for example,
/dnp=tcp:fringe+13001.
On Microsoft Windows platforms that support services, you can install multiple Uniface Routers
as separate services, making it possible to have multiple Uniface Router processes, each listening
on different ports. For more information, see Uniface Routers as Services on Microsoft Windows
in the Uniface Library 9.7.03.

Multiple Threads
The Uniface Router is a multi-threaded process. You can calculate the number of threads that
each Uniface Router process consumes at a particular moment:
• One main thread.
• One additional thread for each TCP port to which the Uniface Router listens.
• One additional thread for each client connection. Potentially, there could be one thread per
path, but some threads might handle multiple paths coming from the same client.
• One additional thread for each asynchronous activate, for the duration of the activate;
when finished, the thread disappears.
• One additional thread for each Uniface Server that is being started; it disappears as soon
as the Uniface Server is ready to receive requests

Monitoring and Administering Uniface Routers

The Uniface Router has no user interface, therefore information about its performance is not
shown. The Uniface Router Monitor is provided for this purpose. This utility displays
information about the Uniface Router and enables you to fine-tune its performance.
The Uniface Router Monitor is a Windows application, but it can connect to Uniface Routers
running on other platforms.

Failure Recovery
If the Uniface Router fails for some reason, it is automatically restarted.

36 Uniface Installation and Configuration Guide for Windows

 Chapter 3 ∙ Configuring the Uniface Router

On Microsoft Windows, the Uniface Router runs as a service which is configured to automatically
restart. If it stops again within 60 seconds, it is restarted after 30 seconds. If it crashes a second
time in 60 seconds, it is not restarted.
On iSeries, the Uniface Router is not automatically restarted if it fails.

Configuring the Uniface Router

To configure the Uniface Router, you need to edit its assignment file, where you can define the
Uniface Servers that the Uniface Router can start, and their configuration parameters.
The default assignment file is urouter.asn, located in the common\adm directory of the Uniface
installation.

Define the Uniface Server Types (USTs)

The Uniface Router starts Uniface Servers when it receives requests from clients. The UST
definitions define how to start each Uniface Server.
Each UST identifies a specific Uniface Server configuration. It can be defined in the assignment
file of the Uniface Router, or it can be provided to the Uniface Router by a Uniface Server that
has been started manually.
1. In the [SERVERS] section of the Uniface Router assignment file, define the USTs of the
Uniface Servers to be accessed by the Uniface Router using the following format:
UST {=} Executable {/CommandLineOption1 /CommandLineSwitchn}
{ApplicationShell}
For example:
[SERVERS]
sales = "c:\Uniface\Uniface 9.6\common\bin\userver.exe" /asn=\usr\sales\sales.asn
/maxreq=100

For more information, see [SERVERS] [p. 63].

2. Optionally, in the [PRE_START] section, define Uniface Servers that the Uniface Router
should automatically pre-start. For more information, see [PRE_START] [p. 64] and
Pre-Start Uniface Servers [p. 39].
Configure the Listener Port and Constraints
The Uniface Router listens to port specified during installation.
3. If the listener port for the Uniface Router is different than the port number selected during
installation, set the $DEFAULT_NET assignment setting.
[SETTINGS]
$DEFAULT_NET =Protocol:Node+PortNum|User|Password|UST

Not all parts of this assignment are required. To change the port number, the following
setting is sufficient:
For example, to change the port number to 14002:
$DEFAULT_NET = +14002|||

NOTE
Ensure that the port number is also changed in path assignments in any assignment files
that map database paths across the network.

Uniface Installation and Configuration Guide for Windows 37

Chapter 3 ∙ Configuring the Uniface Router

For more information, see $DEFAULT_NET [p. 66].

4. Optionally, in the [SETTINGS] section, specify the default settings to constrain the number
of clients, Uniface Servers, and Uniface Router Monitors.
• $MAX_SERVERS [p. 69]
• $MAX_CLIENTS [p. 68]
• $MAX_MONS [p. 69]
• $NET_TIMEOUT [p. 69]

Configure for Postmessages

For each message arriving at the Uniface Router, it makes a new TCP connection and a new
thread to handle that connection. If servers are slow or there is a high volume of messages, it
can be useful to change some configuration settings. For more information, see Inter-Component
Messaging in the Uniface Library 9.7.03.
5. To prevent the Uniface Router from running out of system resources, use the $USE_PMQ
setting.
This causes the Uniface Router to create a queue for each target application. Messages are
deposited in the queue and the connection and handling thread are quickly released. Messages
are then forwarded from the queue to the target application at the rate that it can read them.
6. To ensure that TCP sockets close instantly without going to the TIMED_WAIT state, use the
TCP connector option nl (no linger). .
USYS$TCP_PARAMS = nl
This can be useful when there is a high volume of messages.
7. Save your changes and restart the Uniface Router. For more information, see Stop and Start
the Uniface Router [p. 40].
On Specific Platforms
8. On Windows, you can install multiple Uniface Routers and configure the way the Uniface
Router recovers from unexpected failure. For more information, see Installing the Uniface
Router as a Service in the Uniface Library 9.7.03.
9. On Windows and Unix, you can change the way the Uniface Router recovers from
unexpected failure. For more information, see Configure Uniface Router Recovery [p. 41]
and Configure Uniface Router Recovery on Unix in the Uniface Library 9.7.03.

Windows
[SETTINGS]
$putmess_log_file = urouter.log
$MAXSERVERS = 500
; number of Uniface Application Servers allowed
$MAXMONS = 3
; number of Uniface Router Monitors allowed

[SERVERS]
DEFAULT = userver.exe /maxidle=2h /dir=..\home\guest
SALES = userver.exe /max=10 /asn=..\usr\local\sales\asv.asn /dir=..\home\kees
HR = userver.exe /max=50 /maxreq=100 /asn=..\usr\local\hr\asv.asn
PAYROLL = userver.exe /ex /gates=3800-3999 /asn=..\usr\secure\payrollasv.asn

38 Uniface Installation and Configuration Guide for Windows

 Chapter 3 ∙ Configuring the Uniface Router

Define Uniface Server Types (USTs)

Each UST identifies a specific Uniface Server configuration. It can be defined in the assignment
file of the Uniface Router, or it can be provided to the Uniface Router by a Uniface Server that
has been started manually.

1. To define a UST in the Uniface Router assignment file, add UST definitions to the
[SERVERS] section.
2. Create an assignment file for each UST declared in urouter.asn, for example, sales.asn.
3. To specify the UST of a manually-started Uniface Server, use the /ust command line
switch when starting it.

Pre-Start Uniface Servers

It is possible for the Uniface Router to automatically start Uniface Servers when the Uniface
Router itself starts.
This can be useful when:
• The server to be started is effectively a service that should always be available and that has
no direct client connection
• You want to have a server already available for a client the moment the client connects to
the server

Pre-starting servers ensures that they are available directly after rebooting the machine.

NOTE
Pre-starting a server is a one-time action. The Uniface Router does not restart them if they
unexpectedly exit. Such servers can be re-started by using the Uniface Router Monitor.

The Uniface Router requires the username and password when starting a server. This information
is normally supplied by the client request and is defined in the path in the client assignment file.
To configure the Uniface Router to automatically start Uniface Servers:

1. Update urouter.asn.
a. Add or edit the [PRE_START] section.
It contains path definitions similar to those used in a client assignment file to specify
an ANY server.
b. Enter the servers to be started, one per line, and each line unique.
Observe the following:
• Each line must specify the UST of a single server as given in the [SERVERS] section,
because each line causes the Uniface Router to pre-start a single server, for example:
[PRE_START]
tcp:host|user1|pass1|ust1
tcp:host|user2|pass2|ust1
tcp:host|user2|pass2|ust2

[SERVERS]
ust1 = userver /asn=asn1.asn /dir=d:\dir1
ust2 = userver /asn=asn2.asn /dir=d:\dir2

Uniface Installation and Configuration Guide for Windows 39

Chapter 3 ∙ Configuring the Uniface Router

• To pre-start two identical servers on the same machine, while still adhering to the
uniqueness rule, specify unique host names on two lines, for example:
[PRE_START]
tcp:host1|user1|pass1|ust1
tcp:host2|user1|pass1|ust1

• The host field is optional and may be left empty, but the pipe symbol is required, for
example: tcp:|user1|pass1|ust1. The host name field is not actually used, because
the Uniface Router determines this information from its own administration.
• Servers are started in the order they are specified in the [PRE_START] section, without
exceeding the $MAXSERVERS or /max limit specified for the UST.
• The protocol, user, password, and UST parameters are mandatory.
• The /ex switch can be specified in the [PRE_START] line after the UST, or in the
UST definition in the [SERVERS] section.
• All other switches are supported and may be specified only in the UST definition in
the [SERVERS] section
• Only ANY servers are supported for pre-start
• There is no provision for scrambling the username and password in the Uniface Router
assignment file.

2. Stop and restart the Uniface Router. For more information, see Stop and Start the Uniface
Router [p. 40].

For the example given above, the Uniface Router will start three servers, one for each of the
three lines in the [PRE_START] section. Two of these are started using the [SERVERS] section
ust1 definition for user1 and user2, and the third server using the ust2 definition for user2.

Stop and Start the Uniface Router

There may be occasions when you need to stop and restart the Uniface Router for system
administrative purposes.

NOTE
Before stopping the Uniface Router, it is recommended that you stop all client applications
registered to it. Failure to do so causes these applications to stop responding.

When the Uniface Router is stopped, it automatically stops all server processes it started, but it
cannot stop the client/server applications.
On Microsoft Windows, /stop stops the Uniface Router service, which is automatically installed
during installation.

• On Windows, in the Uniface program group, choose URouter ➤ Start Service or Stop
Service.

40 Uniface Installation and Configuration Guide for Windows

 Chapter 3 ∙ Configuring the Uniface Router

Registering Clients with the Uniface Router

For a Uniface client application to receive messages from another Uniface application (client
or server), it needs to be registered with the Uniface Router. You can register a client application
from the command line, in the client assignment file, or in Proc.
The Uniface Router maintains a table of registered clients and their paths, and the user name
under which they registered. This enables the Uniface Router to send a message to any registered
client. The user name is not explicitly provided when registering, but it is captured and stored
along with the symbolic name. It is not possible to register under another user name.
The combination of user name and symbolic name must be unique, otherwise the registration
will fail.

NOTE
A client can only maintain one registration at a time. However, by using the open statement it
can repeatedly open the $DNP path and register itself with a different name or with a different
Uniface Router.

To register a client with the Uniface Router, do one of the following:

• Register from the command line using the /dnp and /ust command line switches.
The only difference between these switches is that /dnp specifies the complete network
connection string, whereas /ust relies on this being defined by /dnp or $DNP.
uniface.exe /dnp=TCP:HostID+Port|||ClientID StartUpShell
or
uniface.exe /dnp=TCP:HostID+Port /ust=ClientID StartUpShell
For more information, see /dnp [p. 90] and /ust [p. 101].
◦ HostID—is the identifier of the host machine on which the Uniface Router is running.
The format of HostID determines the TCP protocol version to be used.
The HostID field may be left empty, but the pipe symbol is required, for example:
tcp:|user1|pass1|ust1
◦ Port—is the TCP port number on the host machine that the client will use for
communication with the Uniface Router.
◦ ClientID—is the ID that the client will use to identify itself to the Uniface Router.
This name is not case-sensitive.
◦ StartUpShell—is the name of the application startup shell on the client.

• Register using the client assignment file. Specify the client path in the $DNP setting
$DNP TCP:HostID+Port|||ClientID
• Register using the Proc open command.
open "HostID|||ClientID","$DNP"

Configure Uniface Router Recovery

If the Uniface Router fails for some reason, it is automatically restarted.

Uniface Installation and Configuration Guide for Windows 41

Chapter 3 ∙ Configuring the Uniface Router

To configure Uniface Router recovery on Microsoft Windows:

1. From the Start menu, choose Program Files ➤ Administrative Tools ➤ Services.
2. Select the Uniface Router service (Uniface9 URouter), right-click and choose Properties.
3. In the Recovery tab, set the properties as desired.
By default, the properties are set as follows:
Property Value

First Failure Restart the Service

Second Failure Restart the Service

Subsequent Failures Take No Action

These settings ensure that if the Uniface Router stops again within 60 seconds, it is restarted
after 30 seconds. If it crashes a second time in 60 seconds, it is not restarted.

42 Uniface Installation and Configuration Guide for Windows

CHAPTER 4
Configuring the Uniface Server

The Uniface Server enables Uniface clients to access remote resources and execute remote
components. You need to configure the Uniface Server so that it can find the databases and
Uniface files, entities, and components that it needs.

Uniface Server
The Uniface Server is a server-based process that enables Uniface clients to access remote
resources or execute remote components. It can act as a data server, a file server, or an application
server, and also provides web application support.
The Uniface Server provides the following functionality:
• Remote data access—accesses application data, and reads and writes server-based application
files
• Uniface Virtual Machine—executes remote Uniface components (services and reports)
• Remote application invocation—executes other remote components via application
integration connectors such as COM, 3GL call-out, and OS-command call-out.
• Web application server—in combination with the Web Request Dispatcher (WRD), a Java
servlet running in a web server, the Uniface Server executes Uniface server page
components.

A Uniface Server accesses databases, files, or application components that are available on the
same host as itself. To access data and services on other hosts, you can connect two or more
Uniface Servers via the Uniface Router. The Uniface Router is responsible for all communication
between the client and server, and between servers on different hosts.

Roles
By default, the Uniface Server fulfills multiple roles, but you can also use the Uniface Server
as a dedicated server that fulfills only one role.

Uniface Installation and Configuration Guide for Windows 43

Chapter 4 ∙ Configuring the Uniface Server

Table 10. Uniface Server Roles

Code Server Role Description

ANY (or blank) ANY server Performs all Uniface Server functions. User name
and password are not required, but you can have
multiple database paths or logins.

Database connector code Database Server Connects to the database connector.

(such as SOL, DB2, ORA)

FIL File Server Locates Uniface resources files

SRU Application Server Executes the remote components of a Uniface

application, such as services and reports.

S3C Component Server Calls non-Uniface components that the Uniface

application needs

To assign a specific role to a Uniface Server, you can do so in a connector path assignment, in
the UST definition, or on the userver command line using /drv. For more information, see
Server Connector Path [p. 32], Uniface Server Types (UST) in the Uniface Library 9.7.03, and
/drv [p. 92].

Shared and Exclusive Uniface Servers

By default, a Uniface Server is a shared server, which can process requests from multiple clients.
The Uniface Router makes the connection between the client and one or more Uniface Servers.
It is also possible for a Uniface client to establish an exclusive connection via TCP to a Uniface
Server. In this case, the Uniface Router only starts the server; the client then disconnects from
the Uniface Router and reconnects to the started server directly—the Uniface Router no longer
routes requests from the client. For more information, see /ex [p. 93].

NOTE
When defining entities during application development, it is recommended that you use an
exclusive server (using the /ex switch) until you have finished adding and modifying entity
definitions; then you can use a shared server.

Configuring the Uniface Server

You need to configure the Uniface Server so that it can find the databases and Uniface files,
entities, and components that it needs.
The Uniface Server is usually started by the Uniface Router in response to a request from a
Uniface client application. There can be settings in assignments files of the Uniface Server, the
Uniface Router, and the client application that affect how a Uniface Server is run.
• Uniface Server assignment file—contains default paths for locating databases, files, and
components.
• Uniface Router assignment file—defines the names and startup options for Uniface Servers.
For more information, see Configuring the Uniface Router [p. 37].

44 Uniface Installation and Configuration Guide for Windows

 Chapter 4 ∙ Configuring the Uniface Server

• Client assignment file—defines the role of a Uniface Server, and whether it is shared or
exclusive. The role of the Uniface Server determines the objects it needs.

1. Create a separate assignment file for each Uniface Server Type (UST) you plan to use.
The name of the file should match the name of the UST. For example, for a UST named
DATA, create a file called data.asn.

NOTE
A default assignment file (userver.asn) is provided in the uniface\adm directory of
your installation.

For more information, see Uniface Server Types (UST) in the Uniface Library 9.7.03.
2. In each Uniface Server assignment file, define the default paths for locating databases,
files, and components.
The resources and locations you define depend on the roles this server is expected to fulfill.
Uniface Server Role Configuration Requirements Field Section

Database server Specify the DBMS path, as well as certain database driver [PATHS]
settings

Redirect entities to database table names, if required [ENTITIES]

File server (FIL) Specify the locations of Uniface resources files. [RESOURCES]

Application server Specify the component locations [RESOURCES]

(SRU)
Specify the database paths for the data accessed by the [PATHS]
components

Component server Specify the shared libraries and DLLs of non-Uniface [USER_3GL]
(S3C) components.
You can also specify these when setting the implementation
details for a C call-out in the Signature Editor.

ANY Specify all of the above, as required by your application.

For more information, see Paths and Path Assignments [p. 28].
For example, for a database server, specify the DBMS path and database connector, and if
necessary, redirect entities to database table names:
[PATHS]
$DATA = SOL:nmpipe SOLID|user|pass
[ENTITIES]
*.* = $DATA:*.*

NOTE
It is not allowed to redirect database paths to network paths. Use Uniface Router hopping
instead. For more information, see Path-to-Connector Assignments [p. 30]..

3. Optionally, specify the role of the Uniface Server. You can do this in the client assignment
file or using the /drv command line switch.

Uniface Installation and Configuration Guide for Windows 45

Chapter 4 ∙ Configuring the Uniface Server

For example:
;Path to database server on host
$DATA = TCP:host|user|password|data + SOL:SOLID:|dbuser|dbpassword
;Path to file server on host
$FILESERVER = TCP:host|user|password|files + FIL:||

For more information, see /drv [p. 92].

46 Uniface Installation and Configuration Guide for Windows

CHAPTER 5
Configuring the Web Environment

Uniface Web-based applications can run under any Web server capable of connecting to a servlet
engine that is compliant with the 2.3 Java servlet specification.

Uniface Web Application Server

The Uniface Web Application Server (WASV) is the Uniface backend of a web application.
It consists of the following:
• Uniface Server running under the name wasv. For more information, see Uniface Server
[p. 43].
• Uniface Router. For more information, see Uniface Router [p. 35].
• Web Request Dispatcher, a Java servlet running in a servlet engine of a web server. For
more information, see Web Request Dispatcher (WRD) [p. 47].
Uniface also provides a SOAP Request Dispatcher for web services. SOAP Request
Dispatcher (SRD) [p. 48]

The WASV can be integrated with any web server capable of connecting to a servlet engine
that is compliant with the Java servlet specification. The default installation includes the Apache
Tomcat HTTP Server and servlet engine, but if you already have your own web server, you can
configure it to run Uniface applications after installation.

Web Request Dispatcher (WRD)

The Uniface Web Request Dispatcher (WRD) is a Java servlet that is responsible for brokering
requests and maintaining connections between web servers and the Uniface Router. The WRD
communicates with the Uniface Server via the Uniface Router.
The WRD receives requests from a client browser via the Web server and dispatches these
requests to Uniface via a middleware module. A connection is established to the Uniface Router,
that assigns the request to the Uniface Server for processing.
The internal structure of the WRD includes a middleware module for Uniface TCP/IP that
creates the connection to the Uniface Server (via the Uniface Router).

Uniface Installation and Configuration Guide for Windows 47

Chapter 5 ∙ Configuring the Web Environment

The WRD Java servlet runs in web servers that support the Java™ Servlet API, versions 2.3
through 3.0, and requires J2SE 1.6 or higher. The WRD servlet makes it possible to deploy
Uniface web applications on any platform.
The WRD servlet is delivered, together with the SOAP Request Dispatcher (SRD) servlet, as
part of the WRD Java archive file wrd.jar.

Servlet Engine
Some web servers cannot directly invoke servlets, so you must configure them with a servlet
engine. To integrate the WRD with a web server, you must configure a servlet engine (such as
Tomcat) with the WRD. The servlet engine handles a pool of WRD servlet instances and typically
limits their number. All servlet instances communicate with the Uniface Router that handles
the Uniface Server pools.

SOAP Request Dispatcher (SRD)

The Uniface SOAP Request Dispatcher (SRD) is a Java servlet that is responsible for brokering
SOAP requests and WSDL requests.
The SRD Java servlet supports the Java™ Servlet API 2.1. It is easily configured for any Web
server that supports the Java Servlet API. Because Java is a platform-independent language, the
SRD Java servlet makes it possible to deploy, for example, Uniface Web services on any
platform. The SRD servlet is delivered, together with the WRD servlet, as part of the WRD
Java archive file wrd.jar.
The following illustration shows how the SOAP Request Dispatcher works:

Figure 1. Uniface SOAP Request Dispatcher

For SOAP requests, the SRD communicates, via the Uniface Router and the SOAP driver, with
the Uniface Application Server (UServer). The SRD is also capable of handling WSDL requests,
which are handled by the SRD without the interaction of the Uniface Application Server.

48 Uniface Installation and Configuration Guide for Windows

 Chapter 5 ∙ Configuring the Web Environment

WSDL Requests
WSDL requests are handled by the SRD without intervention by any other product. It retrieves
the WSDL from disk, dynamically adds the HTTP server address of the Web server, and returns
the data. For the SRD to handle WSDL requests, the WSDL files, and all referenced XSD files,
must exist in the directory WEB-INF/wsdl of the Web application.

SOAP Requests
SOAP requests are dispatched to Uniface via a middleware module. A connection is established
to the Uniface Router, that assigns the request to the Uniface Application Server (UServer) for
processing. The Uniface Application Server detects that the request is a SOAP request and
passes it to the SOAP driver for conversion.

Servlet Engine
Some Web servers cannot directly invoke servlets, so you must configure them with a servlet
engine. To integrate the Uniface SOAP Request Dispatcher with a Web server, you must
configure a servlet engine (such as Tomcat) with the SRD. The servlet engine handles a pool
of servlet instances and typically limits their number. All servlet instances communicate with
the Uniface Router that handles the Uniface Application Server pools.

Configuring the Web Environment on Windows

Uniface provides a complete web deployment environment for testing and deploying web
applications and web services. The default installation includes a fully-configured Apache
Tomcat HTTP Server and servlet engine. However, after installation, you can configure another
web server and servlet engine to work with Uniface.

Before You Begin

To configure your own web environment for Uniface, you need:
• Web server capable of connecting to a servlet engine that is compliant with the 2.3 Java
servlet specification.
• Uniface Web Application Server (WASV), consisting of the Uniface Server, the Uniface
Router, and the Uniface Web Request Dispatcher (WRD)

NOTE
The following procedure is not required if the default web environment is used.

To configure the web environment:

1. Configure the web server and servlet engine to run Uniface servlets. For more information,
see Configuring a Web Server for Uniface Applications [p. 50].
2. Configure the Uniface Web Application Server. For more information, see Configuring
the Uniface Web Application Server [p. 51].
3. If you want to run the Tomcat servlet engine under Microsoft IIS, see Configuring Microsoft
IIS to Use Tomcat [p. 54].

Uniface Installation and Configuration Guide for Windows 49

Chapter 5 ∙ Configuring the Web Environment

Configuring a Web Server for Uniface Applications

Uniface automatically installs the Apache Tomcat HTTP Server and servlet engine, which can
be used to test and deploy Uniface web applications and web services. However, you can use
any Web server capable of connecting to a servlet engine that is compliant with the 2.3 or 3.0
Java servlet specification.
You need to configure your web server to run the Java servlets provided by Uniface. Most J2EE
web servers have an administrator console or other tools for configuring the servlet engine and
deploying applications. Servlet definitions and parameters may be specified in an ASCII file or
through a GUI, depending on the servlet engine. For details, refer to the documentation of your
Web server and servlet engine. The following instructions are general guidelines.

TIP
Get the values you need to define the servlets in your environment from the web.xml file in
UnifaceInstallDir/uniface/webapps/uniface/WEB-INF.

To configure a servlet engine to use the Uniface servlets:

1. Using the web server tools, provide the location of the servlet jar file wrd.jar. This is
located in UnifaceInstallDir/common/tomcat/common/lib.
The Java Virtual Machine must know where the servlet .jar file is located. This information
is normally provided in the CLASSPATH environment variable, but some servlet engines
provide their own way to specify the location.
2. Define the servlets in an ASCII file or through a GUI, depending on the servlet engine.
The servlet engine must know that the servlet exists.
3. Edit the servlet parameters for each servlet.
The default values are available in web.xml but you can set others. For more information,
see Configuration Settings: Uniface Servlet [p. 78].
a. Ensure that the MIDDLEWARE parameter of each servlet is set, providing the server
name, and the name and password used to run the Uniface Server process. For example:
<init-param>
<param-name>MIDDLEWARE</param-name>
<param-value>UV8:firefly.nl.myorg.com|userver|userver|wasv</param-value>
</init-param>

b. Optionally, set the TESTABLE servlet parameter to true. For example:

<init-param>
<param-name>TESTABLE</param-name>
<param-value>true</param-value>
</init-param>

This setting makes it possible to display a test page to confirm that the servlet is running.

NOTE
This should only be set to true during configuration and testing. In a production
environment, it should be removed or set to false.

4. Stop and restart the web server to have the new servlets and settings take effect.

50 Uniface Installation and Configuration Guide for Windows

 Chapter 5 ∙ Configuring the Web Environment

5. Test that the web server can connect to Uniface.

For example, if the TESTABLE servlet parameter is true, you can enter the URL of the
Uniface test page (Uniface Test Middleware Response):
• If the servlet setting USERUNPREFIX is false (default):
http://ServerHost/uniface/wrd/WRD_Version
• If the servlet setting USERUNPREFIX is true:
http://ServerHost/uniface/wrd/run/WRD_Version

For example: http://firefly.nl.myorg.com/uniface/wrd/WRD_Version

The test page should be displayed, providing the WRD version number, the minimum Java
Servlet API required, the Uniface build name and date.

Figure 2. Uniface Test Middleware Response Page

If this page is not displayed, there is likely to be a problem with the configuration. For
troubleshooting assistance, see the Uniface WRD Configuration Errors for your platform
(Windows or Unix).
If this page is displayed correctly, remove the TESTABLE servlet setting from the web.xml
file, then stop and restart the web server.

Configuring the Uniface Web Application Server

The Uniface Web Application Server (WASV) is automatically configured to work with the
default Apache Tomcat web server, so you only need to perform this task if you are creating
your own web deployment environment, or customizing the existing configuration.

Before You Begin

If you are not using the default Apache Tomcat web server installed with Uniface, you must
configure a web server to run the Uniface Java servlets. For more information, see Configuring
a Web Server for Uniface Applications [p. 50].

The Uniface Web Application Server consists of a Uniface Server (by default, it is wasv), the
Uniface Router, and Uniface Java servlets running in a servlet engine. The WRD servlet handles

Uniface Installation and Configuration Guide for Windows 51

Chapter 5 ∙ Configuring the Web Environment

server page requests in web applications, and the SRD servlet handles SOAP and WSDL requests
for web services.
Configuring the WASV is thus largely a matter of configuring these individual components.
For example:
• If you want to use a Uniface Server other than wasv, you will need to specify the new server
in the urouter.asn file, create an assignment file for it, and edit the MIDDLEWARE servlet
settings to call the new server.
• If you want to fine-tune servlet behavior, you can set optional servlet parameters, not just
those defined in the default configuration.
• If you change the machine hosting your web server, you need to update the MIDDLEWARE
servlet parameter.

The following instructions assume the default Tomcat web server. If you are using another web
server and servlet engine, refer to the documentation for your preferred web server for details
on defining and setting servlet parameters. This may be done in an ASCII file or through a GUI.
You can get the values you need to define the servlets in your environment from the web.xml
file in UnifaceInstallDir/uniface/webapps/uniface/WEB-INF.

1. If you are using a Uniface Server other than wasv, specify the Uniface Server Type (UST)
for the Uniface Server in your urouter.asn file (in the Uniface/common/adm directory).
The UST must be the same as the UST defined in the servlet MIDDLEWARE parameter. By
default, the installed urouter.asn file specifies the UST wasv, which matches the UST
as specified in the servlet MIDDLEWARE parameter.
For example:
; urouter.asn
[SERVERS]
wasv = "D:\Uniface\Uniface 9.6.05\common\bin\userver.exe" /dir="D:\Uniface\Uniface
9.6.05\common\project" /adm="D:\Uniface\Uniface 9.6.05\uniface\adm" /asn=wasv.asn

2. Update the assignment file wasv.asn (in the Uniface/uniface/adm, which corresponds
to the the UST wasv, with settings for your specific environment.
By default, this assignment file uses your development environment settings. For testing,
the following settings are usually used, but they are normally changed for deployment:
; wasv.asn
[SETTINGS]
;$WEB_CODEBASE ../common
;$TEST_MODE_COMPONENTS
$SEARCH_DESCRIPTOR DBMS_FIRST
$SEARCH_OBJECT DBMS_FIRST

If the setting $CHECK_SIGNATURE_ID is present in your [SETTINGS] section, remove it.

NOTE
When you make changes to assignment files that are used by the Uniface Router or Uniface
Server, stop and restart the Uniface Router for those changes to take effect.

3. Modify the servlet parameters for each servlet.

In Tomcat, edit the web.xml file.

52 Uniface Installation and Configuration Guide for Windows

 Chapter 5 ∙ Configuring the Web Environment

For each parameter, define the <param-name> and <param-value> tags within a
<init-param> tag. For more information, see Configuration Settings: Uniface Servlet
[p. 78]..
By default, the each servlet is configured to use the local Uniface Router, the local user
account userver, and the Uniface Server Type wasv, all installed and configured by the
Uniface installer.
<!-- Uniface WRD Servlet -->
<servlet>
<servlet-name>
wrd
</servlet-name>
...
<init-param>
<param-name>MIDDLEWARE</param-name>
<param-value>UV8:localhost+13001|userver|userver|wasv</param-value>
</init-param>
</servlet>

4. Specify the servlet mapping pattern for each servlet.

Servlet mappings enable any URL containing a specified pattern to be directed to a specific
servlet, without actually knowing the servlet name.
For example, the following URL is a request for the WRD servlet to return the server page
MYDSP:
http://localhost:8080/uniface/wrd/mydsp

The following URL is a request for the SRD servlet to return the WSDL of the service
MYSERVICE:
http://localhost:8080/uniface/services/myservice?wsdl

For Tomcat, servlet mappings are located near the end of the web.xml file.
<servlet-mapping>
<servlet-name>wrd</servlet-name>
<url-pattern>/wrd/*</url-pattern>
</servlet-mapping>

By default, the WRD servlet is mapped to the pattern /wrd/*, and the SRD servlet is
mapped to the pattern /services/*.
5. Stop and restart the web server.
6. Test the WRD configuration by running a server page component.
For example, enter the URL of the server page.
http://localhost:8080/uniface/wrd/mydsp

Alternatively, if the TESTABLE servlet setting is true, you can enter URL of the Uniface
Test Middleware Response page. For more information, see TESTABLE [p. 84].
7. Test the SRD configuration by running a Uniface web service.
For more information, see Constructing Service Components in the Uniface Library 9.7.03
and Deploying a Uniface Web Service in the Uniface Library 9.7.03.

Uniface Installation and Configuration Guide for Windows 53

Chapter 5 ∙ Configuring the Web Environment

Configuring Microsoft IIS to Use Tomcat

By default, a Uniface installation uses its own Apache Tomcat web server and servlet engine.
However, for deployment, it is possible to use the Microsoft Internet Information Services (IIS)
web server and Tomcat as the servlet engine.

Before You Begin

To configure IIS to use Apache Tomcat servlet engine, you need:
• IIS-Tomcat Redirector, a filter plug-in for IIS that enables it to redirect client requests to
Tomcat. It consists of the DLL isapi_redirect.dll and its associated properties file,
isapi_redirect.properties. These files are located in the
UnifaceInstallDir\common\tomcat\bin\w32 directory. For documentation on using
it, consult the Tomcat web site (tomcat.apache.org/connectors-doc).
• Uniface
• Apache Tomcat Web server (tomcat.apache.org). You can use the Apache Tomcat delivered
with Uniface or a separate Tomcat installation
• Microsoft IIS Web server
• Sun-Win32 JDK

CAUTION
The Tomcat webapp context and IIS virtual directory cannot share the same name.

When installing the Deployment Suite, you are given the option to Configure IIS for use with
Uniface. If selected, Uniface tries to configure IIS to use the Tomcat servlet engine delivered
with the Uniface APS. Configuration fails if IIS is not installed, or if it has been previously
configured to run the servlets provided with the Uniface APS products.
Perform this procedure if one of the following circumstances apply:
• You plan to use the Microsoft Internet Information Services (IIS) Web server and Tomcat
as the servlet engine, where the Tomcat installation is not the one delivered with the APS.
• You chose the option Configure IIS for use with Uniface when installing the Deployment
Suite, but received the following error:
IIS could not be configured for use with Uniface, either because IIS
is not installed, or because the jakarta filter, the jakarta or the
unifaceview virtual directory already exists within IIS.

1. If you are using a Tomcat installation other than that delivered by Uniface, copy the desired
.xml files from UnifaceInstallDir\common\tomcat\conf\Catalina\localhost to
a similar location in your Tomcat directory. For Uniface, this is uniface.xml.
2. Open the file isapi_redirect.properties in a text editor and ascertain the locations
of the following files:

54 Uniface Installation and Configuration Guide for Windows

 Chapter 5 ∙ Configuring the Web Environment

• workers.properties—this is the value for the property worker file. The

workers.properties file describes the hosts and ports used by the Tomcat worker
process. A worker is a Tomcat process that accepts work from the IIS web server.
• uriworkermap.properties—this is the value for property worker_mount_file.
The uriworkermap.properties file maps URL path patterns to Tomcat worker
processes.

NOTE
The following instructions for refer to a Tomcat worker process called uniface. You can replace
uniface with the Tomcat worker process that you plan to use for any Uniface product.

3. Edit the specified workers.properties file in a text editor.

a. For each application, define a worker. For more information, consult the The Apache
Tomcat Connector - Reference Guide: workers.properties configuration
b. Locate the worker.list line and add the parameter myworker, separated by a comma
from other parameters.
For example:
worker.list=worker.uniface,ajp13

c. Save and close the file.

4. Edit the uriworkermap.properties file to add URL path information for the ISAPI
Tomcat redirector.
a. Open the specified uriworkermap.properties file in a text editor and add the
required worker mappings at the bottom of the file. For more information, consult the
The Apache Tomcat Connector - Reference Guide: uriworkermap.properties
configuration.
For example:
# --- Worker mappings for Uniface ---
/uniface/*=$(uniface.worker)

#--- End Uniface worker mappings ---

b. Save and close the file.

5. Apply the changes by stopping and restarting the World Wide Web Publishing Windows
service and Tomcat.

Configuring the Tomcat SecurityManager

By default, the Apache Tomcat web server delivered with Uniface is installed with the
SecurityManager enabled, which protects the web server from untrusted applets running in the
browser.
When using the Tomcat web server to deploy a Uniface application, the SecurityManager should
be correctly configured and enabled. For more information, see the Apache Tomcat
documentation (Security Manager HOW-TO).
However, if you are running Tomcat only in a local environment for testing Uniface applications,
you may choose to run it without the SecurityManager.

Uniface Installation and Configuration Guide for Windows 55

Chapter 5 ∙ Configuring the Web Environment

1. To configure the SecurityManager:

a. Edit the file catalina.policy located in
UnifaceInstallDir/common/tomcat/conf/ directory.
For more information, see the Apache Tomcat web site:Configuring Tomcat With A
SecurityManager
b. Stop and restart Tomcat using the shortcuts in the Web server folder of the Uniface
program group.
2. To disable the SecurityManager:
a. Edit the file UnifaceInstallDir/common/tomcat/bin/service.bat and comment
out the line with java.security.manager
b. From the command line, remove the Tomcat service:
service.bat remove
c. From the command line, reinstall the service without the security manager:
service.bat install

Configuring the SOAP Connector

To use Uniface functionality for web services call-out, you need to choose a Uniface SOAP
connector and configure it.
The Uniface SOAP U1.0 and U2.0 connectors support different binding styles. For more
information, see WSDL in the Uniface Library 9.7.03.

1. To use SOAP connector U2.0, ensure that the following setting is present in the client
assignment file:
[DRIVER_SETTINGS]
SOP U2.0

2. Alternatively, to use the SOAP connector U1.0:

a. Install the Microsoft SOAP Toolkit from the Microsoft Web site.
b. Ensure that the following setting is present in the client assignment file:
[DRIVER_SETTINGS]
SOP U1.0

3. Optionally, specify connector options and call-out component parameters:

a. In the [DRIVER_SETTINGS] section, specify connector-wide options for the SOAP
connector using the USYS$SOP_PARAMS setting.
b. In the [SERVICES_EXEC] section, specify parameters for specific components that
will be executing call-out to Web services.
Settings in the [SERVICES_EXEC] section override the corresponding connector
options specified in the [DRIVER_SETTINGS] section. The connector options in
USYS$SOP_PARAMS cannot be nullified; they can only be overridden with another value.

NOTE
If your SOAP service uses entity or occurrence parameters, it is not possible to reassign
it to another application in the [SERVICES_EXEC] section. For more information,
see [SERVICES_EXEC] in the Uniface Library 9.7.03.

56 Uniface Installation and Configuration Guide for Windows

 Chapter 5 ∙ Configuring the Web Environment

4. To call out to web services from a Uniface Server, add the /su switch in the Uniface Server's
UST in the Uniface Router's assignment file.
This prevents problems with permissions. The /su switch causes the Uniface Server to
start in the environment of the user rather than in the environment of the Uniface Router.

Uniface Installation and Configuration Guide for Windows 57

Chapter 5 ∙ Configuring the Web Environment

58 Uniface Installation and Configuration Guide for Windows

APPENDIX A
Assignment Files

A Uniface assignment file contains one or more assignment settings, which determine the
environment of a Uniface application and control aspects of its behavior. Assignment settings
can determine the location of application resources and servers, set environment variables,
define application logicals, and set Uniface system settings to influence runtime behavior.
Each application and Uniface product has its own assignment file, usually with the same name
as its startup shell or executable. When you start an application, Uniface builds an internal
assignment file from a global assignment file (usys.asn) followed by a local assignment file
(for example, myapp.asn). Settings in the local assignment file take precedence over those in
the global assignment file.
In fact, it is possible to have multiple global and local assignment files, because one assignment
file can reference another assignment file using the #FILE directive. This makes it possible
name and organize assignment files to suit your requirements.
An assignment file is an ASCII or EBCDIC text file (depending on the platform) with the
extension .asn, so you can use any ASCII file editor to create or edit assignment files.

NOTE
If you use non-ASCII characters in an assignment file, you need to save it in the Unicode
(UTF-16 or UTF-8) encoding.

Assignment File Syntax

An assignment file is divided into sections, which organize assignment settings and allow
Uniface to check the syntax of your assignments. For more information, see Assignment File
Sections [p. 60].
The assignment settings themselves typically have the format :
Setting {=} Value
For more information, see Assignment Settings [p. 25].
In addition to section headers and settings, an assignment file can include:
• Comment lines—denoted by a semicolon (;). The semicolon can be preceded by spaces
and tab characters, but not by other characters.

Uniface Installation and Configuration Guide for Windows 59

Appendix A ∙ Assignment Files

NOTE
Comments must be defined on separate lines. They cannot be defined on the same line as
an assignment setting.

• #FILE directives—used to include the contents of another assignment file. For more
information, see Including Assignment Files in the Uniface Library 9.7.03.
• Blank lines—to enhance readability by separating groups of related assignments.

Sample Assignment File

;sample assignment file
#file D:\Uniface 9.6.05\common\adm\dbms.asn

[SETTINGS]
$putmess_logfile = D:\Uniface 96 Data\log\mylog.log

[FILES]
my*.frm D:\myapp\components\my*.frm

Assignment File Sections

All assignments that follow a section header belong to that section, until another section header
is found, or until the end of the file.

Table 11. Assignment File Sections

Section Description

[SETTINGS] Settings that control your Uniface application, such as application

appearance, I/O behavior, application environment settings, testing,
compatibility settings, and so forth.

[DRIVER_SETTINGS] Connector-specific settings, such as the connector version and

connector-specific parameters. The parameters available depend on which
connector is in use.

[SERVERS] Server names (USTs) of Uniface servers; used only in the Uniface Router
assignment file (urouter.asn).

[PRE_START] USTs of Uniface servers that the Uniface Router should automatically
start when the Router starts; used only in the Uniface Router assignment
file (urouter.asn).

[PATHS] Paths to DBMS, network, or GUI drivers. Path assignments can include
path-to-connector assignments and path-to-path assignments.

[RESOURCES] Paths to the locations where Uniface must look for Uniface objects. These
are usually .uar files but can also be directory paths. Uniface applications
use this section to locate all the objects they need.

[FILES] Paths to non-DBMS files.

[ENTITIES] Paths to individual entities, giving the target database table a different
name than the name of the entity, or specifying the physical file name for
database tables for record-level databases.

60 Uniface Installation and Configuration Guide for Windows

 Appendix A ∙ Assignment Files

Table 11. Assignment File Sections (continued)

Section Description

[LOGICALS] Logical value definitions that you can access in your application using the
$logical Proc function.

[SERVICES_EXEC] Direct the execution of service components to a network path, COM

connector, or SOAP connector.

[REPORTS_EXEC] Direct the execution of report components to a network path specified in

the [PATHS] section. The report component is then executed by the
Uniface server identified by the UST in the path definition.

[WIDGETS] Logical to physical widget mappings in character mode

[PROXY_SETTINGS] Proxy settings used by the UHTTP component

[USER_3GL] Uniface 3GL extensions to be made available to the application

[XLOGIN] Network paths requiring extended logon

[META_CHARSET] Defining your own mappings between Unicode and the character set
specified in LANGUAGE.

urouter.asn
Assignment file for the Uniface Router. You can use the urouter.asn file to specify settings,
paths to connectors, and Uniface Server environment definitions, such as USTs.

Default location: UnifaceInstallDir\common\adm

File Sections
The assignment file typically contains the following file sections:
• [SETTINGS] [p. 63]
• [SERVERS] [p. 63]
• [PRE_START] [p. 64]

Assignment Settings
The [SETTINGS] section can include the following assignment settings:
• $DEFAULT_NET [p. 66]
• $DEFAULT_TCP_HOST [p. 67]
• $DNP [p. 68]
• $MAX_CLIENTS [p. 68]
• $MAX_MONS [p. 69]
• $MAX_SERVERS [p. 69]
• $NET_TIMEOUT [p. 69]

Uniface Installation and Configuration Guide for Windows 61

Appendix A ∙ Assignment Files

Command Line Switches

UST definitions in the [SERVERS] section can include (but are not limited to) the following
command line switches:
• /asn
• /dir
• /ex
• /gates
• /hostrc
• /max
• /maxreq
• /maxidle
• /pri
• /shr
• /su (not supported on iSeries)

This example shows a typical urouter.asn file. The [SETTINGS] and [SERVERS] sections
demonstrate the following:
• USTs (server names) of several Uniface servers, including the default server default, to
be used if none is specified by the client.
• The /ex switch used with the /gates switch. The UST PAYROLL example specifies that,
for an exclusive connection requested by the client to the Uniface Server, the port selected
for the connection should be in the range 3800 to 3999 (/gates)
• Working directories (/dir)
• Assignment files (/asn)
• Maximum Uniface Application Server instances allowed ($MAXSERVERS and /max)
• Maximum Uniface Router Monitor instances allowed ($MAXMONS)
• Maximum requests that can be executed (/maxreq). In a development environment only,
maxreq should be set to 1. If this is not done, you will always see the old HTS file.
• Maximum idle time (/maxidle)

Windows
[SETTINGS]
$putmess_log_file = urouter.log
$MAXSERVERS = 500
; number of Uniface Application Servers allowed
$MAXMONS = 3
; number of Uniface Router Monitors allowed

[SERVERS]
DEFAULT = userver.exe /maxidle=2h /dir=..\home\guest
SALES = userver.exe /max=10 /asn=..\usr\local\sales\asv.asn /dir=..\home\kees
HR = userver.exe /max=50 /maxreq=100 /asn=..\usr\local\hr\asv.asn
PAYROLL = userver.exe /ex /gates=3800-3999 /asn=..\usr\secure\payrollasv.asn

62 Uniface Installation and Configuration Guide for Windows

 Appendix A ∙ Assignment Files

[SETTINGS]
The [SETTINGS] section contains settings that control your Uniface application, such as
application appearance, I/O behavior, application environment settings, testing, compatibility
settings, and so forth.
Setting {{=} Value}

Arguments
• Setting— name of the setting.
• Value—value of the setting. If not specified, the default value is used. See the individual
assignment settings for their default values.

Description
Descriptions of specific settings are provided in the Uniface Reference section. For more
information, see Configuration Settings: Assignment in the Uniface Library 9.7.03..

[SETTINGS]
The following example assignment file specifies a number of settings:
[SETTINGS]
$CENTURY_BREAK = 05
$SEARCH_DESCRIPTOR = DBMS_FIRST
$SEARCH_OBJECT = DBMS_FIRST
$PUTMESS_LOG_FILE = idf.log

[SERVERS]
The [SERVERS] section specifies the server names (USTs) of Uniface Servers, and is used
only in the Uniface Router assignment file (urouter.asn).
UST {=} Executable {/CommandLineSwitch1 /CommandLineSwitchn} {ApplicationShell}

Arguments
• UST—name of the server. The name of the default or fallback UST is DEFAULT.
• Executable—Uniface Server executable, (for example, userver). including the path.
• CommandLineSwitch—command line switch and its value, for configuring the Uniface
Server (UServer).
• ApplicationShell—name of the startup shell (by default, userver.aps).

Switches
The standard command line switches include (but are not limited to):
• /asn—For more information, see /asn [p. 89].
• /dir—For more information, see /dir [p. 91].
• /dnp—For more information, see /dnp [p. 90].
• /ex—For more information, see /ex [p. 93].

Uniface Installation and Configuration Guide for Windows 63

Appendix A ∙ Assignment Files

• /gates—For more information, see /gates [p. 94].

• /pri—For more information, see /pri [p. 98].
• /shr—For more information, see /shr [p. 100].
• /su—For more information, see /su in the Uniface Library 9.7.03.

The following switches are only applicable for shared Uniface Servers:
• /max—For more information, see /max [p. 95].
• /maxreq—For more information, see /maxreq [p. 97].
• /maxidle—For more information, see /maxidle [p. 96].

NOTE
Although you are allowed to use the /ex switch in the Uniface Router’s assignment file, it is
recommended that you use the /ex switch only in the client’s assignment file.

Description
Each UST defined in the Uniface Router assignment file serves as a command line string to
start a userver process. This may result in a command line that exceeds the allowable command
line length for your operating system, especially if the /dir and /dnp switches are used. You
should therefore ensure that the length of the UST command line conforms to the limits for
your platform.

The following example assignment file shows a [SERVERS] section on Microsoft Windows:
[SERVERS]
DEFAULT = c:\uniface\bin\userver.exe /maxidle=2h /dir=..\project
SALES = c:\uniface\bin\userver.exe /asn=asv.asn /dir=..\home\kees /max=10 myaps.aps
HR = c:\uniface\bin\userver.exe /asn=asv.asn /max=50 /maxreq=100
PAYROLL = c:\uniface\bin\userver.exe /asn=usysadm:payrollasv.asn

[PRE_START]
The [PRE_START] section specifies the server names (USTs) of Uniface servers that the Uniface
Router should automatically start.
NetworkMnemonic:{HostID}|UserName|Password|UST {/ex | /shr} {/su | -nosu}

Arguments
• NetworkMnemonic—three-letter Uniface mnemonic for a network connector, for example
TCP.
• HostID—network node name for the host; optional.
The HostID field is not actually used, because the Uniface Router determines this
information from its own administration. You may leave HostID empty, but the pipe symbol
is required, for example: tcp:|user1|pass1|ust1.
• UserName—logon name and additional operating system-specific information to log on to
HostID. On Microsoft Windows, additional optional information may include a domain
name to validate UserName, for example: Mydomain\Me.

64 Uniface Installation and Configuration Guide for Windows

 Appendix A ∙ Assignment Files

• Password—password of UserName to log on to HostID.

• UST—Uniface Server Type; specifies the name of a specific Uniface server to pre-start. It
must be declared in the [SERVERS] section.

Switches
• /ex—For more information, see /ex [p. 93].
• /shr—For more information, see /shr [p. 100].
• /su—For more information, see /su in the Uniface Library 9.7.03.

Description
The [PRE_START] section is used only in the Uniface Router assignment file (urouter.asn)

In the following example, the Uniface Router starts three servers, one for each of the three
unique lines in the [PRE_START] section. Two of these are started using the [SERVERS]
section ust1 definition for user1 and user2, and the third server using the ust2 definition for
user2.
[PRE_START]
tcp:host|user1|pass1|ust1
tcp:host|user2|pass2|ust1
tcp:host|user2|pass2|ust2

[SERVERS]
ust1 = userver /asn=asn1.asn /dir=d:\dir1
ust2 = userver /asn=asn2.asn /dir=d:\dir2

usys.asn
Every Uniface application looks for global assignments in a file called usys.asn in the USYSADM:
(\adm) subdirectory of the Uniface installation directory.

Default location: UnifaceInstallDir\common\adm

Description
Uniface uses the assignments from the usys.asn file, along with any local assignments that it
can locate, to create its internal assignments file. The global assignments should be designed
to serve all applications as a fall-back for objects that are not assigned locally.
The usys.asn file is not automatically read by all applications in the Uniface installation. It
must be included in the application assignment file using #file. For example:
#file C:\Progam Files\Uniface\Uniface97\common\adm\usys.asn

wasv.asn
The wasv.asn file is a basic assignment file for the Web Application Server.

Default location: UnifaceInstallDir\uniface\adm

Uniface Installation and Configuration Guide for Windows 65

Appendix A ∙ Assignment Files

Description
The wasv.asn file is created during installation of Uniface. As defined in the default
urouter.asn file, the Web Application Server uses this assignment file to answer
remote-browser requests for USPs.
The wasv.asn file contains only WASV-specific settings such as codebase and log file
definitions. It includes a database assignment file for path-to-database redirections, which, by
default, point to the SQLite development database.
You can modify the file to suit your own environment.

Common Assignment Settings

$DEFAULT_NET
Set the default network path for clients, Uniface servers, or Uniface Routers.
$DEFAULT_NET = Protocol:HostID+PortNumber{|UserName|Password}

Arguments
• Protocol—network protocol. Uniface supports TCP.
• HostID—identifier of the host machine on which the Uniface Router is running. If omitted,
the default is localhost. The format of HostID determines the TCP protocol version to
be used. For more information, see Host Identification for TCP/IP in the Uniface Library
9.7.03..
• PortNumber—port number port number on HostID on which the Uniface Router process
is listening. If omitted, the default value is 13001.
• UserName—logon name and additional (operating system-specific) information to log on
to HostID. Additional information might be, for example, a domain name used by HostID
to validate UserName.
• Password—password of UserName to log on to HostID

NOTE
UserName and Password are ignored when using $DEFAULT_NET in the urouter,asn file. The
Uniface Router uses the setting to determine which port it should listen on.

Defaults

Assignment file: assignment files of clients, Uniface servers, and Uniface

Routers

Section: [SETTINGS]

Default value: None

66 Uniface Installation and Configuration Guide for Windows

 Appendix A ∙ Assignment Files

Description
The $DEFAULT_NET assignment file setting can be used to specify the default network path of
the local host.
Uniface programs search for the port number in the following order:
1. Path assignment setting in the [PATHS] section
2. $DEFAULT_NET assignment setting in the [SETTINGS] section
3. Default port (13001)

$DEFAULT_NET
For example, for a client it is useful to specify the default host name, port number, user name,
and password to remove redundancy from the assignment file, for example:
[SETTINGS]
$DEFAULT_NET = TCP:myhost+13005|guest|?

[PATHS]
$FILES = TCP:||| + FIL:|||
$SRU = TCP:||| + SRU:|||

$DEFAULT_TCP_HOST
Specify the default host identifier for the local host.
$DEFAULT_TCP_HOST = localhost | HostID

Arguments
HostID—identifier of the host machine on which the Router is running. If omitted, the default
is localhost. The format of HostID determines the TCP protocol version to be used. For more
information, see Host Identification for TCP/IP in the Uniface Library 9.7.03..

Defaults

Assignment file: assignment files of Uniface Servers and the Uniface Router

Section: [SETTINGS]

Default value: localhost

Description
Use the $DEFAULT_TCP_HOST assignment file setting in the [SETTINGS] section of the
assignment files of Uniface Servers and the Uniface Router to specify the default host identifier
for the local host.
To determine which protocol version should be used to create a listening port, the TCP connector
attempts to discover the IP addresses for the local machine. Because the protocol version is
derived from the format of the host identifier, either as a literal IP address or as a name that
resolves to an IP address, the $DEFAULT_TCP_HOST setting provides some flexibility as to which
protocol version is used for this listening port.

Uniface Installation and Configuration Guide for Windows 67

Appendix A ∙ Assignment Files

This setting is especially useful in an exclusive server assignment file, because it unambiguously
specifies the identifier for the local host.

$DNP
Specify the Uniface Router default network path.
$DNP {=} Protocol:{HostID}{+PortNumber}{|||ClientID}

Arguments
• Protocol—network protocol.
• HostID—identifier of the host machine on which the Router is running. If omitted, the
default is localhost. The format of HostID determines the TCP protocol version to be
used. For more information, see Host Identification for TCP/IP in the Uniface Library
9.7.03..
• PortNumber—port number for the specified host. If omitted, the default value is 13001.
• ClientID—logical ID of the Uniface client; used when registering a Uniface client with
the Router. Alternatively, you can use the /ust command line switch to supply the logical
client ID.

Defaults

Assignment file: client and server assignment files

Section: [PATHS]

Default value: none

Description
Specify the Uniface Router default network path, also known as the Default Network for
Postmessage (DNP). This setting is useful when registering both clients and servers with the
Uniface Router.
If ClientID is omitted from the $DNP setting, it must be supplied either using /dnp or /ust,
or using the ‘open ... |||ClientID’ Proc statement.

$DNP
The following example defines the default protocol as TCP, connecting to the mammal server
on port 13002, with client ID tiger. The user is prompted to enter a username and password
at run time.
$DNP = TCP:mammal+13002|||tiger

$MAX_CLIENTS
Specify the maximum number of clients that the Uniface Router can accept for a shared Uniface
Server.
$MAX_CLIENTS {=} NumberOfClients

68 Uniface Installation and Configuration Guide for Windows

 Appendix A ∙ Assignment Files

Assignment file: urouter.asn

Section: [SETTINGS]

Default value: None

$MAX_SERVERS
Specify the maximum number of shared Uniface Servers that the Uniface Router can start. This
setting is not applicable to exclusive servers.
$MAX_SERVERS = NumberOfServers

Assignment file: urouter.asn

Section: [SETTINGS]

Default value: None

$MAX_MONS
Specify the maximum number of Uniface Router Monitors that the Uniface Router can accept.
$MAX_MONS {=} NumberOfMonitors

Arguments
NumberOfMonitors—maximum number of Uniface Router Monitors that the Uniface Router
can accept.

Defaults

Assignment file: urouter.asn

Section: [SETTINGS]

Default value: None

Description
By default, the Uniface Router can accept an unlimited number of Uniface Router Monitors.

$NET_TIMEOUT
Specify the maximum length of time that one or more specified network activities can continue.
Activities that can be timed out include establishing a connection to the Uniface Router. or an
idle process.
N
$NET_TIMEOUT {=} {Option=Duration{TimeUnit} }{,Option=Duration {TimeUnit}}

Arguments
• Option—setting that determines the activity for which a timeout is set. One of:

cct=ClientConnectionTimeout

Uniface Installation and Configuration Guide for Windows 69

Appendix A ∙ Assignment Files

sct=ServerConnectionTimeout
idl= IdleTimeout
pmi=PostmessageTimeout
uec= UnifaceExistCheckTimeout | off
vfy=VerifyConnectionTimeout | off

See Table 12. $NET_TIMEOUT options [p. 70].

• Timeout—maximum length of time that the network activity continues, expressed in
seconds (the default unit), or TimeUnit.

NOTE
The actual times can vary by a number of seconds from those specified, because the timeout
is checked with a 15 second interval.

• TimeUnit—optional; one of the following:

s—for seconds (the default, if TimeUnit is omitted)

m—for minutes
h—for hours
d—for days
w—for weeks

NOTE
You cannot combine time units, such as $NET_TIMEOUT idl=4w2d.

Defaults

Assignment file: urouter.asn

Section: [SETTINGS]

Default value: None

Description
Use the $NET_TIMEOUT assignment setting to control how long the Uniface Router waits before
a client or server connects to the Router, how long the Router or Uniface Server is idle, and so
on.
If an option is set in an inappropriate assignment file, it is ignored.

Table 12. $NET_TIMEOUT options

Option Use In Description

cct urouter.asn Client connection timeout. Specifies the time for a client to establish
Client ASN file a connection with the Uniface Router, or to reconnect if the connection
is lost. The default is 180 seconds. The setting does not include the
time for a server to start and respond.

70 Uniface Installation and Configuration Guide for Windows

 Appendix A ∙ Assignment Files

Table 12. $NET_TIMEOUT options (continued)

Option Use In Description

If you use the /gates command line switch, unless you are working
in a WiFi environment or an environment with an unreliable network,
it suggested that you set $NET_TIMEOUT cct= to a low value, such as
10.

sct urouter.asn Server connect timeout. Specifies the maximum time that the Uniface
Router will wait for a server to register with the Uniface Router after
the server starts. The default is 60 seconds.
Use only in a Uniface Router assignment file. It has no effect in a client
or server assignment file.

idl urouter.asn Idle timeout. Specifies the maximum time that the Uniface Router or
userver.asn Uniface Server is allowed to be idle. If not specified, the default is -1
(unlimited time period). If specified, IdleTimeout must be a whole
number.
If present in the Uniface Router’s assignment file, the Uniface Router
closes the socket and ends the thread to the client and the server after
being idle for the specified time. After the socket is closed, the server
stops processing.
If present in the server’s assignment file, for either a shared or exclusive
server, the server will stop processing after being idle for the specified
time.

pmi urouter.asn Postmessage timeout. Specifies the maximum length of time a special
queue that has been created to handle postmessages can be inactive
before it is released.
Applicable only when $USE_PMQ is used to create a queue in memory
for each postmessage target application. For more information, see
$USE_PMQ in the Uniface Library 9.7.03.

uec urouter.asn Uniface existence check timeout. Specifies the maximum length of
time that no communication is received from a client before the Uniface
Router checks whether the client is still active.
Use only if error -23 (Duplicate UST) is returned in a repeating loop.
See Use of uec and vfy [p. 71].

vfy urouter.asn Verify connection timeout. Specifies the maximum length of time that
a client connection thread blocks receive requests before it checks
whether a connection is still required.
Use only if error -23 (Duplicate UST) is returned in a repeating loop.
See Use of uec and vfy [p. 71].

Use of uec and vfy

Use the vfy or uec options only if error -23 (Duplicate UST) repeatedly occurs when trying
to reestablish a connection with the Uniface Router. This can happen when the Uniface Router
does not know about a network connection failure on a channel that it thinks is open. In this
case, a client will automatically try to re-register its $DNP path with the Uniface Router. Because

Uniface Installation and Configuration Guide for Windows 71

Appendix A ∙ Assignment Files

the Uniface Router already considers the $DNP path to be in use, it repeatedly returnd error
-23, until it is informed that the connection has been lost.
To prevent such a reconnect loop from happening, you can set the uecor vfy timeout settings.
Both of these settings affect the performance of the Uniface Router, so they should not be set
unless you encounter the looping reconnect problem.
• Setting $NET_TIMEOUT uec=xxx pro-actively asks the client to confirm that the connection
is still required. If the client is no longer active, the connection is closed. If it is still active,
the check ensures that the connection remains open. This ensures that a broken connection
is detected before the client attempts to re-register the UST and the -23 error will not be
issued.
This is useful if your firewall automatically closes TCP channels that have been inactive
for a specified period. By setting the uec timeout to a value that is shorter than the firewall
timeout, you can ensure that the connection is not closed.
• Setting $NET_TIMEOUT vfy=xxx timeout is more reactive. It forces an open connection
thread to stop blocking receive requests and check whether the connection must be verified.
Verification is required only if a registration has been requested for an existing UST. If a
broken connection is found, the registration is cleaned up so that the next reconnect request
can succeed.

Both options can affect the performance of the Uniface Router, so you must find a balance
between the Uniface Router performance and the response time of the client after a client-side
network failure. In general, you can set the uec setting to a longer interval than the vfy option.
When setting the vfy time, be aware that it takes at most twice the value of
VerifyConnectionTimeout to re-register the $DNP path. Setting a long timeout causes less
impact on Uniface Router performance, but will increase the response time of the client after
this type of network failure. Determine a maximum acceptable client response time and use half
of that value as your verify timeout.
When set in the Uniface Router's assignment file, the uec and vfy timeout options are applied
to all clients connected with the Uniface Router. If the looping reconnect problem occurs on
specific clients only, you can set the /uec or /vfy flags on the network path specified in the
client's assignment file. To disable these flags in the client paths, you can set the $NET_TIMEOUT
settings to off.

$NET_TIMEOUT
To specify a timeout of 100 seconds for both the cct and sct options in the Uniface Router’s
assignment file, use the following assignment:
[SETTINGS]
$NET_TIMEOUT = cct=100, sct=100

$PUTMESS_LOG_FILE
Copy the message frame contents to one or more files.
$PUTMESS_LOG_FILE | $PUTMESS_LOGFILE {=} Filename | {/append}
$PUTMESS_LOG_FILE | $PUTMESS_LOGFILE {=} Filename {, totalsize=n} {, count=p}
$PUTMESS_LOG_FILE | $PUTMESS_LOGFILE {=} NONE

72 Uniface Installation and Configuration Guide for Windows

 Appendix A ∙ Assignment Files

Arguments
Argument Meaning

Filename Full path name to the output log file; can have a maximum length of 64 characters.
The name can include one or more of the following identifiers, in any order, to
differentiate individual log files.
• %p—process ID of the started application. If specified, /append is ignored.

• %t—time stamp. Using this adds an extra performance penalty, because the
file names must also be saved.
• %h—host name

• %u—user name

totalsize=n Total disk space in kilobytes that can be used for all rotating log files together. This
size will not be exceeded. If not specified, the default value is 10000 (10 MB).

count=p Number of files used in rotating log files. See Rotating Log Files [p. 74].
The minimum value of count is 2. There is no maximum. However, there is a lower
limit to the log file size of 3 KB. If the combination of totalsize and count
produce a file size that is less than that, the count will be reduced to achieve the
minimum file size.

NOTE
Rotating through a large number of files imposes a large overhead and performance
penalty.

/append Append any message frame information to the specified Filename. See Using
/append [p. 74]

NONE Do not create log files for Uniface Router or Uniface Server processes. If specified,
use uppercase.

Defaults

Assignment file: Any application assignment file

Section: [SETTINGS]

Default value: None

Description

NOTE
It is recommended that you use $PUTMESS_LOG_FILE only during development and testing.
Using it in a production environment can result in many large log files that use up valuable disk
resources.

$PUTMESS_LOG_FILE directs a copy of the message frame information for the application to a
log file Filename. The file contains a complete record of all output to the message frame, that

Uniface Installation and Configuration Guide for Windows 73

Appendix A ∙ Assignment Files

is, the file is not cleared when the message frame is cleared. This means the log file can become
very large if a large application is run. To control this, consider using rotating log files.
When a new file is created, a file banner is written to the file with information about the
application. For rotating log files each banner line starts with the [logsegmentN]. For
non-rotating files, the banner starts with [startup].
If the Filename already exists when the application starts using $PUTMESS_LOG_FILE, the file's
contents are cleared, unless /append is used, in which case the logging information is added
to the file.

Rotating Log Files

Adding the optional totalsize=n and count=p parameters enables you to use rotating log
files. The first and most recent file always has the name specified in the assignment setting.
When the file size reaches the maximum size, as determined by the totalsize divided by the
count, the file is renamed, appending _1, and logging continues in a newly created file with
the name specified in the assignment. When this file reaches the specified maximum size, the
_1 file is renamed to _2, and the new file has _1 appended, and logging continues in a newly
created file. This process is repeated until the number of log files matches the value of count,
and then the oldest is deleted as new log files are created. As files are renamed, any existing
file with that name is deleted.
As the log proceeds through the rotation, the oldest part of the log is deleted. Make sure you
have defined a totalsize large enough to maintain a reasonable history, otherwise error
messages written earlier may be lost.
If an error occurs during the rotation and it is no longer possible to guarantee that the total file
size is below the totalsize argument, logging will stop. The error will be written to a
uniface_app_type_%p.log in the working directory of the application, not in the directory
specified for the $PUTMESS_LOG_FILE.

Using /append
You can use /append for rotating files to continue the rotation. If files exist with the same name
and sequence numbers they will continue to be used.

NOTE
Never share rotating log files over multiple concurrent sessions. The size calculations will not
be accurate.

For non-rotating log files, /append can be useful when two sessions are started, either
simultaneously or sequentially. The file will contain the logging information from both sessions.
If /append is not defined, the file will contain only the logging information of the last session.

Log Files for Multiple Server Processes

For the Uniface Router or Uniface Server, there can be multiple server processes running
concurrently, so the default behavior is always to create a unique log file for each Router and
each Server instance, even if you do not specify $PUTMESS_LOG_FILE.

74 Uniface Installation and Configuration Guide for Windows

 Appendix A ∙ Assignment Files

If you do not want log files to be created, either for the Uniface Router or for the servers, use
the NONE option of $PUTMESS_LOG_FILE in the appropriate assignment files to suppress their
creation.

In this example, if 214 were the process ID of the running application, the log file name would
be named myapp214.log.
$PUTMESS_LOG_FILE=myapp%p.log

Uniface Installation and Configuration Guide for Windows 75

Appendix A ∙ Assignment Files

76 Uniface Installation and Configuration Guide for Windows

APPENDIX B
Web Configuration Files and Settings

web.xml
Configuration file of the web application.

Default location: UnifaceInstallDir\uniface\webapps\uniface\WEB-INF.

Description
The web.xml file contains the web application deployment descriptors used by Java-based web
servers. The Uniface servlets run in the environment of the web application; settings for the
Uniface servlets, WRD and SRD, are stored in the web.xml file.

Settings
The settings for the servlets are grouped in servlet configuration sections, one for each servlet.
The web.xml file uses the following format to configure servlet settings:
<web-app>

<servlet>
<servlet-name>ServletName</servlet-name>
<servlet-class>ServletClass</servlet-class>
<init-param>
<param-name>ParamName<param-name>
<param-value>ParamValue<param-value>
</init-param>
...
</servlet>
</web-app>

where
• ServletName—name of the servlet (for example, the Uniface servlet wrd)
• ServletClass—Java class inplementing the servlet
• ParamName—name of the servlet configuration setting
• ParamValue—value of the setting

Uniface Installation and Configuration Guide for Windows 77

Appendix B ∙ Web Configuration Files and Settings

Table 13. Servlet Settings

Setting Description

ASVTIMEOUT [p. 80] Specifies the period of time, in seconds, that the servlet waits for
a reply or acknowledgement from the Uniface Server.

AUTHORIZATION [p. 80] Instructs the servlet that user authorization is required.

DEFAULTENCODING [p. 81] Specifies the default encoding used for converting inbound and
outbound HTML.

ERRORDIR [p. 82] Specifies the path to the parent directory of the Web error message
pages.

MAXFILEUPLOADSIZE [p. 83] Specifies the maximum size, in kilobytes, of files that can be
uploaded from the client to the server.

MAXFILEUPLOADS [p. 83] Specifies the maximum number of files that can be uploaded
during any one client session.

MIDDLEWARE [p. 83] Specifies the middleware module to use and the path to a Uniface
Server host.

RESOURCEDIR [p. 83] Specifies the directory that temporarily holds the downloadable
resources.

RESOURCETIMEOUT [p. 84] Specifies the maximum time, in seconds, that downloadable
resources are cached by the servlet before they are deleted from
the server.

SESSIONCOOKIE [p. 84] Specifies whether cookies can be set on the client. Default value
is TRUE. If set to dynamic, the servlet determines if the browser
can accept cookies.

TESTABLE [p. 84] Boolean value to specify whether a test USP is displayed with
the information page. Default value is TRUE.

UseRunPrefix [p. 85] Specifies whether the WRD should handle references to
documents on relative paths.

WEBAPPURL [p. 86] Specifies the absolute URL path of the Web application directory
for the servlet.

File Sections
• SRD Servlet Section [p. 79]
• WRD Servlet Section [p. 79]

Configuration Settings: Uniface Servlet

Uniface servlets run in the environment of the web application. Settings for the Uniface servlets,
the WRDand SRD, are stored in the web.xml file, which is the configuration file of the web
application.

78 Uniface Installation and Configuration Guide for Windows

 Appendix B ∙ Web Configuration Files and Settings

The settings for the Uniface servlets are grouped in servlet configuration sections, one for each
Uniface servlet. The web.xml file uses the following format to configure servlet settings:
<web-app>

<servlet>
<servlet-name>ServletName</servlet-name>
<servlet-class>ServletClass</servlet-class>
<init-param>
<param-name>ServletSetting<param-name>
<param-value>ServletSettingValue<param-value>
</init-param>
...
</servlet>
</web-app>

where:
• ServletName—name of the servlet (for example the Uniface servlet wrd or srd)
• ServletClass—Java class inplementing the servlet
• ServletSetting—name of the servlet setting
• ServletSettingValue—value of the servlet setting

SRD Servlet Section

Section of the web.xml file containing the definition and settings for the SOAP Request
Dispatcher (SRD).

Description
Uniface servlets run in the environment of the Web Application; the the SOAP Request
Dispatcher (SRD) definition and settings are stored in the SRD servlet configuration section in
the web.xml file, which is the configuration file of the Web Application (not to be confused
with the Uniface WebApplication Server).
The SRD servlet configuration section uses the following format:
<web-app>
<!-- Uniface S(oap) R(equest) D(ispatcher) Servlet -->
<servlet>
<servlet-name>srd</servlet-name>
<servlet-class>com.compuware.uniface.urd.SRDServlet</servlet-class>
<init-param>
<param-name>ParamName</param-name>
<param-value>ParamValue</param-value>
</init-param>
<!-- More servlet settings... -->
</servlet>
<!-- More servlet definitions -->
</web-app>

where
• ParamName—name of the SRD servlet setting, for example MIDDLEWARE.
• ParamValue—value of the SRD servlet setting.

WRD Servlet Section

Section of the web.xml file containing the definition and settings for the Web Request Dispatcher
(WRD)

Uniface Installation and Configuration Guide for Windows 79

Appendix B ∙ Web Configuration Files and Settings

Description
Uniface servlets run in the environment of the Web Application; the Web Request Dispatcher
(WRD) definition and settings are stored in the WRD servlet configuration section in the web.xml
file, which is the configuration file of the Web Application (not to be confused with the Uniface
WebApplication Server).
The WRD servlet configuration section uses the following format:
<web-app>
<!-- Uniface W(eb) R(equest) D(ispatcher) Servlet -->
<servlet>
<servlet-name>wrd</servlet-name>
<servlet-class>com.compuware.uniface.urd.WRDServlet</servlet-class>
<init-param>
<param-name>ParamName</param-name>
<param-value>ParamValue</param-value>
</init-param>
<!-- More servlet settings... -->
</servlet>
<!-- More servlet definitions -->
</web-app>

where:
• ParamName—name of the WRD servlet setting, for example MIDDLEWARE.
• ParamValue—value of the WRD servlet setting.

ASVTIMEOUT
Specifies the period of time, in seconds, that the servlet waits for a reply or acknowledgment
from the Uniface Server.

Description
Default if omitted: 120 seconds

NOTE
Some Web browsers and Web servers use their own connection time-outs. For more information,
see your Web server documentation.

AUTHORIZATION
Instructs the WRD that user authorization is required.

Description
Possible parameter values:
• REMOTE_USER
Specifies that the Web server should perform the authentication (anonymous is not accepted).
The Web server identifies the remote user and makes the user name known to the WRD to
pass to the Uniface Application Server. For more information, see Using Web Server
Authentication in the Uniface Library 9.7.03..
• Realm

80 Uniface Installation and Configuration Guide for Windows

 Appendix B ∙ Web Configuration Files and Settings

The name of the Realm in which the user is allowed to request Web pages. BASIC
authentication is performed by the Web server. The first time a user makes a request, the
servlet instructs the browser to ask for a user id and password, which are passed to the
Uniface Application Server. This combination can be verified by the Server, after which
the user can request pages in this realm. For more information, see Using Uniface
Authentication in the Uniface Library 9.7.03..

Default if omitted: None—The Web server determines whether, and what kind of, user
authorization is performed.

DEFAULTENCODING
Specifies the default encoding used for converting inbound and outbound HTML.

Description
The value of this parameter is used to specify the encoding used by the WebApplication Server
for converting inbound and outbound TEXT, HTML, and XML, if no encoding is specified in
the request. This setting influences the conversion to the Web browser.
Default if omitted: UTF-8
For the value of the parameter, use one of the codes in the following table:

Table 14. Encoding for converting inbound and outbound HTML

Encoding code Description

UTF-8 Unicode

ISO-8859-1 Western Europe

ISO-8859-2 Czech; Eastern Europe

ISO-8859-5 Russian; Cyrillic

ISO-8859-6 Arabic

ISO-8859-7 Greek

ISO-8859-8 Hebrew

ISO-8859-8-I Hebrew

ISO-8859-15 Euro sign

windows-1250 Czech; Eastern Europe

windows-1251 Russian; Cyrillic

windows-1252 English and Western Europe (default)

windows-1253 Greek

windows-1255 Hebrew

windows-1256 Arabic

LATIN1 Western Europe

Uniface Installation and Configuration Guide for Windows 81

Appendix B ∙ Web Configuration Files and Settings

Table 14. Encoding for converting inbound and outbound HTML (continued)

Encoding code Description

LATIN2 Czech; Eastern Europe

LATIN5 Russian; Cyrillic

LATIN6 Arabic

LATIN7 Greek

LATIN8 Hebrew

LATIN9 Euro sign

Shift_JIS Japanese; Kanji; Hankaku

EUC-JP Japanese; Kanji; Hankaku

ISO-2022-JP Japanese; Kanji; Hankaku

GB_2312-80 Chinese Simplified

KSC_5601 Korean; Hangul; Hanja

DEFAULTENCODING
The operating system is Microsoft Windows, the web browser is Internet Explorer, and the web
server is Tomcat. A Uniface application uses Cyrillic character sets.
In the directory UnifaceInstallationDirectory\uniface\webapps\uniface\WEB-INF,
modify the file web.xml by inserting the following lines into the WRD servlet’s specification:

<init-param>
<param-name>DEFAULTENCODING</param-name>
<param-value>windows-1251</param-value>
</init-param>

The results are:

• The web browser’s encoding is automatically set to Cyrillic (Windows).
• Uniface communicates with the web browser using characters in the Cyrillic character set.

ERRORDIR
Specifies the path to the parent directory for one or more directories (one for each language)
that contain web error message pages. The WRD servlet requires read access to these directories.

Description
Usually, the error_en (English) and other error_Lang directories are located in the web
application directory, which is located in the document tree of the web server. If this setting is
omitted, the default used it the language directory within the web application, for example
WEB-INF

82 Uniface Installation and Configuration Guide for Windows

 Appendix B ∙ Web Configuration Files and Settings

NOTE
Do not specify this parameter in a self-contained web application.

MAXFILEUPLOADS
Specifies the maximum number of files that can be uploaded during any one client session. If
the number of uploads exceeds this number, the excess is ignored by the WRD.

Description
Default value if omitted: 10

MAXFILEUPLOADSIZE
Specifies the maximum size, in kilobytes, of files that can be uploaded from the client to the
server. This can be used to protect the Web server and the WRD against large uploads which
would slow down the overall performance of a business-critical application.

Description
Default if omitted: 64 KB

MIDDLEWARE
Specifies the middleware module to use and the path to a Uniface Server host.
Module:Host|{Domain\}User|Password|UST

Arguments
• UV8:—Uniface TCP/IP middleware module
• Host—machine where the Uniface Server is installed; can be specified as a host name or
as an IP address
• Domain—Windows only, an optional domain name on the host machine
• User—user name to start the Uniface Server process
• Password—password required to start the Uniface Server process
• UST—UST of the Uniface Server you want to start; default for Uniface Web Application
Server is wasv

Description
The MIDDLEWARE parameter must be set for each Uniface servlet; there is no default.
UV8:113.105.399.22|webuser|webpass|wasv

RESOURCEDIR
Specifies the directory that temporarily holds the downloadable resources.

Uniface Installation and Configuration Guide for Windows 83

Appendix B ∙ Web Configuration Files and Settings

Description
For example: c:\temp
Default if omitted: The Servlet Attribute "javax.servlet.context.tempdir" is used. You
can set this attribute in the Servlet Container.

NOTE
Do not specify this parameter in a self-contained Web application.

RESOURCETIMEOUT
Specifies the maximum time, in minutes, that downloadable resources are cached by the WRD
before they are deleted from the server.

Description
Default value if omitted: 5 minutes

SESSIONCOOKIE
Specifies whether cookies can be accepted by the client browser.

Description
Possible values:
• TRUE—enable Cookie-based state management
• FALSE—enable URL-based state management
• DYNAMIC—enable dynamic state management, where the WRD determines per request to
use cookie-based or URL-based state management

Default if omitted: TRUE

TESTABLE
Specifies whether the test page (Uniface Test Middleware Response ) can be displayed.

Values
• TRUE—generates the test page containing version information about the current WRD.
• FALSE—displays an error page. An activate error -50 is returned, as for any other request
for a nonexistent server page. This is the default.

Description
You can use this setting when configuring the web server (or servlet engine) to run the WRD,
to confirm that the web server is able to connect to Uniface.
Once the WRD is confirmed to be running, you can set TESTABLE to FALSE or remove it
completely, so that the version information is not accessible.

84 Uniface Installation and Configuration Guide for Windows

 Appendix B ∙ Web Configuration Files and Settings

Using TESTABLE
Set TESTABLE to true.
<init-param>
<param-name>TESTABLE</param-name>
<param-value>true</param-value>
</init-param>

After restarting the web server (to pick up the new value of the setting), enter the URL for the
test page:
• If the servlet setting USERUNPREFIX is false (default):
http://ServerHost/uniface/wrd/WRD_Version
• If the servlet setting USERUNPREFIX is true:
http://ServerHost/uniface/wrd/run/WRD_Version

Figure 3. Uniface Test Middleware Response Page

UseRunPrefix
Specifies whether the WRD should handle references to documents on relative paths (such as
../css/applic.css).

Value Description

True The WRD Java servlet redirects a request, for example css/applic.css, to the
root of the WRD servlet, or to the value of the WEBAPPURL setting.

False
• Relative paths starting with ../ will not be processed by the WRD, because
the URL-pattern does not match. Therefore, the presence of relative paths,
such as ../css/applic.css, will not cause errors.
• The value of the WEBAPPURL setting is not used
• If an existing URL contains the /run prefix, it is redirected a URL without
the prefix.
For example,
http://urltowebserver/uniface/wrd/run/logonusp.start is
redirected to http://urltowebserver/uniface/wrd/logonusp.start

Uniface Installation and Configuration Guide for Windows 85

Appendix B ∙ Web Configuration Files and Settings

Description
If UseRunPrefix is omitted, the default value is True.

WEBAPPURL
Specifies the absolute URL path of the Web application directory for the WRD Java servlet.

Description
This setting is used to translate the relative paths used in the HTML skeleton files (for example
../css/applic.css) into absolute paths that the browser can use to access the required file.
For example, when a client tries to access the css/applic.css file, the Web server sends a
redirect message to the Web browser, which instructs it to obtain the object from
WebApp/css/applic.css.
The syntax for the WEBAPPURL parameter is:
WebApp, where WebApp is the name of your Web application, for example /unifaceweb.
Default if omitted: It will be reconstructed from the request, when possible.

NOTE
This parameter has no effect in a self-contained Web application.

86 Uniface Installation and Configuration Guide for Windows

APPENDIX C
Executables and Command Line Switches

Uniface applications and servers can be started with optional parameters. Some of the most
commonly used executables and command line switches are described here. More are described
in the Uniface Library.

Server Executables
urouter
Executable file for the Uniface Router.
urouter { /inst= ServiceName...} {/stop|/shut= ServiceName...} {/rem=
ServiceName...} {/show= ServiceName...} {/asn=AssignmentFile}

Switches
• /asn—path and name of the assignment file. If not specified, the default is
InstallationDirectory\adm\urouter.asn. For more information, see /asn [p. 89].
• /stop—For more information, see /stop (and /shut) in the Uniface Library 9.7.03.

The following switches work only on Windows platforms:

• /inst—For more information, see /inst in the Uniface Library 9.7.03.
• /rem—For more information, see /rem in the Uniface Library 9.7.03.
• /show—For more information, see /show in the Uniface Library 9.7.03.

Description
Use this executable to start and stop the Uniface Router, or install or remove the Uniface Router
as a service. By default, it is located in the bin subdirectory.
On Microsoft Windows operating systems that support services, you can use the /inst switch
to install multiple Uniface Routers as separate services, each one registered with a unique service
name. For more information, see Installing the Uniface Router as a Service in the Uniface
Library 9.7.03.

Uniface Installation and Configuration Guide for Windows 87

Appendix C ∙ Executables and Command Line Switches

userver
Executable for the Uniface Server, located in the USYSBIN: (\bin) subdirectory.
userver {/ust=...} {/dnp=...} {/drv=...} {/dir=...}

Switches
• /ust [p. 101]
• /dnp [p. 90]
• /drv [p. 92]
• /dir [p. 91]

Description
Specify this executable and its command line switches when defining USTs in the urouter.asn
file or when manually starting a Uniface Server.
If the Uniface Router listens to a port other than 13001, specify the port using the /dnp command
line switch. Alternatively, define $DNP or $DEFAULT_NET in usys.asn or in the Server
assignment file.

Command Line Switches

When you start a Uniface application or server, you can optionally supply parameters using
command line switches. Command line switches can be used to specify configuration files, run
utilities, supply parameters, apply operating constraints, and otherwise qualify the session. They
remain in effect for the duration of that application session.
You can enter command line switches either directly on the command line, in the command
line dialog box, in UST definitions, and scripts.
Some switches can take one or more additional sub-switches. Sub-switches have no meaning
if they are entered without the accompanying switch.
• When you combine command line switches and sub-switches, these must appear on the
command line (in any order) before any parameters.
• Wherever a DateTime parameter appears, it should have the following format:
dd-mm-yyyy:hh:nn:ss
All the separators are optional; all the digits must be present.

NOTE
Some command line switches recognize a limited set of wildcards in parameters. Also, some
information provided with parameters can be misunderstood by your operating system. For
more information, see Wildcards in Parameters in the Uniface Library 9.7.03.

Command line switches can have an alternate name but both names have the same effect.

88 Uniface Installation and Configuration Guide for Windows

 Appendix C ∙ Executables and Command Line Switches

Windows
For example, on Windows, the following command starts the Uniface Development Environment
using the settings specified in the usys.ini and idf.asn configuration files, and starts the
command line dialog box:
"C:\Uniface\Uniface 9\bin\idf.exe" /ini=usys.ini /asn=usysadm:idf.asn ?

The default shortcut for the Uniface Development Environment makes use of command line
switches to present a dialog box in which you can enter command line switches. For example:

You can perform actions without starting the user interface. For example, you can compile all
components by entering the following at in the Microsoft Windows Run dialog box:
D:\Uniface\Uniface 9\bin\idf.exe /all

/adm
Specify the directory where the application's configuration files are located
/adm=AdmDirectory

Use
All Uniface applications.

Description
The Uniface installation has an adm directory in both the \common and \uniface subdirectories.
To ensure that the correct configuration files are used, each Uniface application, such as the
Development Environment, must be started with the /adm switch to set the correct context.
/adm should be specified before /asn or /ini

/asn
Specify the assignment file used by the application.
/asn={Path}FileName

Use With
All Uniface applications, including:
• idf—Uniface Development Environment
• urouter—Uniface Router
• userver—Uniface Server
• udebug—Debugger

Uniface Installation and Configuration Guide for Windows 89

Appendix C ∙ Executables and Command Line Switches

• udeploy—deployment utility
• User applications

Description
Run the application using assignments from FileName.
The file specified with the /asn switch overrides both the assignment file entry for the startup
shell and the default assignment file, named Application.asn.
If Path is omitted, the /asn switch should be preceded by the /adm switch to specify the location
of the assignment file.
Uniface begins by searching for a file named FileName, exactly as entered on the command
line, then in lowercase characters and, finally, in uppercase. If no file is found and FileName
does not contain an extension, the extension .asn is added and the search is repeated.
If you use the /asn switch to specify an assignment file with the same name as the startup shell
(that is, Shell.asn), you should be sure to include the extension .asn. Otherwise, Uniface
will find the startup shell Shell and try to use that as an assignment file.

In the following example, assignments are located in a file named another.asn in the current
directory:
/asn=another

/delacc
Delete a Uniface Router or Uniface Server account on Windows platforms.
/delacc AccountName

Parameters
AccountName—name of the account to be deleted.

Description
Use /delacc to delete an account. This is required if you want to change the password of an
existing account; for example, if you want to change the password of the default urouter or
userver accounts.
In this case, use /delacc to remove the account, and then recreate it with /newacc and /passwd.

/dnp
Register a client application or Uniface Server under a symbolic name with a Uniface Router.
/dnp=NetworkMnemonic: {HostID {+PortNumber} } { |||SymbolicName}

Parameters
• NetworkMnemonic— three-letter connector code; default is TCP but it is not always possible
to omit this value

90 Uniface Installation and Configuration Guide for Windows

 Appendix C ∙ Executables and Command Line Switches

• HostId—host name or IP address where the Uniface Router is running. If omitted, the
default is localhost ( the current machine). The format of HostID determines the TCP
protocol version to be used. For more information, see Host Identification for TCP/IP in
the Uniface Library 9.7.03.
• PortNumber—port number on which the Uniface Router is listening. If omitted, the default
value is 13001.
• SymbolicName—a logical client ID for the Uniface client, or a UST for the Uniface Server.
In combination with the user name, it uniquely identifies the application process. If omitted,
use the /ust command line switch to supply the symbolic name.

NOTE
The assignment file setting $DEFAULT_NET can be used to specify the default value for all the
parameters except the SymbolicName. If $DEFAULT_NET is not specified, the parameter default
(if there is one) is used.

Description
For a Uniface client application, the only reason to register with the Uniface Router is to be
able to receive postmessages. The combination of user name and symbolic name must be unique;
otherwise, the registration will fail.
For an automatically started Uniface Server, the Uniface Router appends this qualifier to the
userver command line when it starts the server. The Uniface Server registers with the Uniface
Router to let the router know that the startup was successful, that it is available to handle client
requests, and that it can receive postmessages.
Once an application or Uniface Server is registered under a client ID or UST, it cannot change
its registration.
If a Uniface Server is started manually, /dnp and/or /ust must be supplied on the command
line. For more information, see Starting Uniface Servers in the Uniface Library 9.7.03.
It can also be used to register a started server with another remote Uniface Router.

/dir
Specify the working directory for a Uniface application.
/dir=WorkingDirectory

Use With
All applications

Description
Run the application using the working directory specified. You can specify the full path name
to the directory. If the path contains spaces, enclose the full path name in double quotes. When
a file name is encountered in Proc that is not fully qualified, this directory is used as the current
directory.

Uniface Installation and Configuration Guide for Windows 91

Appendix C ∙ Executables and Command Line Switches

Using with Uniface Router

In Microsoft Windows, the Uniface Router can be started with the /dir switch on the command
line, or started as a service ( Control Panel ➤ Services) with /dir in the Startup Parameters
field. In the Startup Parameters field, backslashes are removed, so you can either use two
backward slashes or use one forward slash to separate directory specifications in the path. For
example, for the path c:\uniface\project, you need to specify one of the following /dir
switches:
/dir=c:\\uniface\\project or /dir=c:/uniface/project
The /dir switch can also be used in the [SERVERS] section of the Uniface Router assignment
file (urouter.asn) to specify the working directory for a particular Uniface server name (UST).
If the server working directory cannot be determined from urouter.asn, the default will be
the same as for the Router.

Using with Uniface Deployment Utility

Using the /dir command line switch sets the current working directory for the deployment
utility.
The /dir command line switch requires the presence of the /uar command line switch.

/drv
Specify the role of the Uniface Server.
/drv=ServerCode

Argument
ServerCode representing the server role.

Table 15. Uniface Server Roles

Code Server Role Description

ANY (or blank) ANY server Performs all Uniface Server functions. User name
and password are not required, but you can have
multiple database paths or logins.

Database connector code Database Server Connects to the database connector.

(such as SOL, DB2, ORA)

FIL File Server Locates Uniface resources files

SRU Application Server Executes the remote components of a Uniface

application, such as services and reports.

S3C Component Server Calls non-Uniface components that the Uniface

application needs

Description
The /drv command line switch is used only with the userver.exe executable to set the role
of the Uniface server instance.

92 Uniface Installation and Configuration Guide for Windows

 Appendix C ∙ Executables and Command Line Switches

/ex
Instruct the Uniface Router to create an exclusive connection from the client to the Uniface
Server.
/ex

Description
Use the /ex switch in the client’s assignment file to specify that the Uniface Router should
create an exclusive connection from the client to the Uniface Server. By default, the Uniface
Router starts shared servers.
On Windows, Unix, ans OpenVMS, when /su is not used, the exclusive server inherits the
connection to the client from the Uniface Router and uses the same port number as the Uniface
Router. If this is undesirable, use the /gates switch with the /ex switch to enable a direct
connection with the Uniface Server. For example, on a mobile device that periodically goes out
of range of the server, you should use /ex with /gates to ensure that it can re-establish the
connection when an exclusive connection is required.
The client then disconnects from the Uniface Router and reconnects to the started server directly
on the port. The Uniface Router no longer routes requests from the client.
Use the /ex switch in either of the following places:
• In the path declaration of the client’s assignment file (Recommended)
• In the path declaration for a UST in the [SERVERS] section of the Uniface Router’s
assignment file urouter.asn

NOTE
Although you are allowed to use the /ex switch in the Uniface Router’s assignment file,
it is recommended that you use the /ex switch only in the client’s assignment file.

Table 16. Effect of /ex and /shr in Client and Uniface Router Assignment Files
The /ex switch for a particular UST on the client side works only if there is no corresponding /shr
switch for that UST in the Uniface Router’s assignment file. If the switch specified in the client's
assignment file is different from the switch specified in the Uniface Router assignment file, the client's
switch is ignored and a warning message is generated.

urouter.asn

no switch /ex /shr

Client.asn no switch shared (default) exclusive shared

/ex exclusive exclusive shared + Warning

message

/shr shared Error message shared

Firewalls
Note that the use of the /ex switch has an effect on the use of a firewall.

Uniface Installation and Configuration Guide for Windows 93

Appendix C ∙ Executables and Command Line Switches

• On Unix, with the inheritance mentioned above, only the port number used by the Uniface
Router needs to be available through the firewall.
• On other platforms, you should use the /gates switch to specify the range of ports that
should be used for the exclusive connection, and hence to be made available through the
firewall.
• When a NAT (Network Address Translation) firewall is used between the client and the
server, use the /hostrc switch with the UST declaration in the URouter’s assignment file
to specify that the host name, rather than the IP address, should be used for reconnecting
to the client.

Failure Recovery
If an exclusive Uniface Server is killed or crashes, the recovery behavior depends on whether
the /gates switch was used, because the use of /gates effectively turns off connection
inheritance:
• Without /gates—executing a subsequent operation returns and error; executing it again
starts a new exclusive userver.
• With /gates—the client attempts to reconnect until the timeout time has expired. Therefore,
unless you are working in a WiFi environment or an environment with an unreliable network,
it suggested that you set the assignment setting $NET_TIMEOUT cct= to a low value, such
as 10.

/gates
Specify a range of ports to be searched for starting an exclusive server over TCP.
/gates=PortFrom-PortTo

Description
Use the /gates switch in a UST declaration to specify a range of ports to be searched by the
Uniface Router when it attempts to start an exclusive server using /ex. For example, on a mobile
device that periodically goes out of range of the server, you should use /gates to ensure that
it can re-establish the connection when an exclusive connection is required.
PortFrom and PortTo are decimal port numbers, and PortFrom must be less than PortTo, but
no other checks are performed. If specification errors occur, they are reported in the Uniface
Router’s log file, and no connection is made. If a port cannot be found in the specified range,
an error is reported to the client.
The /gates switch can only be used:
• For an exclusive connection to a server (started using the /ex command line switch). In
effect, /gates turns of connection inheritance.
• Over TCP
• In the [SERVERS] section of the Uniface Router’s assignment file
• With a UST declaration

94 Uniface Installation and Configuration Guide for Windows

 Appendix C ∙ Executables and Command Line Switches

For example:
[SERVERS]
; optional default server
default = userver /dir=/home/xxx
sales = userver /ex /gates=3800-4010 /hostrc
local = userver /maxidle=600

NOTE
For important information about firewall usage, see /ex [p. 93].

/hostrc
Specify that the host name should be used for reconnecting to an exclusive Uniface Server.
/hostrc

Used With
/ex [p. 93]

Description
Use the /hostrc switch with a UST declaration in the Uniface Router’s assignment file to
specify that the host name, rather than the IP address, should be used by the client to reconnect
to an exclusive server over TCP.
This switch is for use with a NAT (Network Address Translation) firewall where the untranslated
IP address of the Uniface Server is of no use to the client, so the host name must be used.
The /hostrc switch can be used:
• Only for an exclusive connection to a server (see the /ex command line switch)
• Only over TCP
• Only in the [SERVERS] section of the Uniface Router’s assignment file
• Only with a UST declaration

For example:
[SERVERS]
sales = userver.exe /ex /hostrc

/max
Specify the maximum number of instances of a shared Uniface Server that the Uniface Router
can start.
/max=MaxServers

Description
Use the /max switch in the [SERVERS] section of the Uniface Router assignment file
urouter.asn to specify the maximum number of shared Uniface Server instances that the
Uniface Router is allowed to start for each server name (UST), per user. The /max switch has
meaning only for shared servers.

Uniface Installation and Configuration Guide for Windows 95

Appendix C ∙ Executables and Command Line Switches

The Uniface Router counts the number of servers by comparing the complete specification,
meaning the UST, the OS account, the server role, and the logon specification. If the maximum
number of server instances is reached, a client request for another Uniface Server is blocked
until a Uniface Server instance is available.
If omitted, the default value is -1, meaning an unlimited number of Uniface Servers. If you
specify /max=0, the server will never be started and an error will be sent to the client. This can
be used to disable certain servers for maintenance.
For example:
[SERVERS]
DEFAULT = userver.exe /maxidle=2h /dir=..\home\guest
SALES = userver.exe /max=10 /asn=..\usr\local\sales\asv.asn /dir=..\home\kees
HR = userver.exe /max=50 /maxreq=100 /asn=..\usr\local\hr\asv.asn
PAYROLL = userver.exe /ex /gates=3800-3999 /asn=..\usr\secure\payrollasv.asn

/maxidle
Specify the maximum idle period for a shared Uniface Server.
/maxidle=MaxIdleTime{TimeUnit}

Parameters

Description
The /maxidle switch is used only in the [SERVERS] section of the Uniface Router’s assignment
file urouter.asn to specify the maximum time a shared server, identified by its server name
(UST), is allowed to be idle (not handling any requests).
If omitted, the default value for MaxIdleTime is -1, meaning an unlimited time period. If
specified, MaxIdleTime must be a whole number.
The optional TimeUnit is one of the following:
• s—for seconds (the default, if TimeUnit is omitted)
• m—for minutes
• h—for hours
• d—for days
• w—for weeks
You cannot combine time units, such as /maxidle=4w2d.

The server will be stopped only if the following conditions, corresponding to the server’s role,
are true:
• No open files
• No open database transactions
• No open component instances

For an example, see urouter.asn.

96 Uniface Installation and Configuration Guide for Windows

 Appendix C ∙ Executables and Command Line Switches

/maxreq
Specify the maximum number of requests a shared Uniface server can execute.
/maxreq=MaxRequests

Description
Use the /maxreq switch in the [SERVERS] section of the Uniface Router assignment file
urouter.asn to specify the maximum number of requests that a shared server, identified by
its server name (UST), is allowed to execute. The /maxreq switch has meaning only for a shared
server.
The server will be stopped only if the following conditions, corresponding to the server’s role,
are true:
• No open files
• No open database transactions
• No open component instances

If omitted, the default value is -1, meaning an unlimited number. If you specify /maxreq=0,
the server will never be started and an error will be sent to the client. This can be used to disable
certain servers for maintenance.
Note that in urouter.asn the /maxreq should be set to 1 in a development environment. If
this is not done, you will always see the old HTS file.

/newacc
Create a new account on Windows platforms for the Uniface Router or Uniface Server.
/newacc AccountName {GroupName} {/passwd Password}

Subswitches
/passwd

Parameters
• AccountName—name of the account to create.
• GroupName—name of the group to which this account belongs. If the group does not exist,
it is created with the required privileges to run userver. If omitted, it is added to the group
UNIFACE Server Users, which is automatically created during installation.

Description
When you install Uniface on Windows, the installer normally creates two user accounts named
URouter and UServer, with their passwords set to the account name. However, if your Windows
system has a password policy that does not allow passwords to be the same as the account name,
or that requires the password to follow certain rules, creation of these accounts fails.
You can create these accounts manually by starting the Uniface Router from the command line
using the /newacc switch.

Uniface Installation and Configuration Guide for Windows 97

Appendix C ∙ Executables and Command Line Switches

NOTE
You may also have to modify the userver password in some of the assignment files, and in
web.xml.

The following illustration shows how you can create new Uniface Server accounts.

Figure 4. Creating a New Server Account

/passwd
Creates a password for the newly created Uniface Server or Uniface Router account.
/passwd Password

Use With
/newacc

Parameters
Password—a password of at least 4 characters

Description
You cannot use /passwd to change the password of an existing account. However, you can use
/delacc to remove it, and then recreate it with /newacc and /passwd.

/pri
Specify the types of messages sent to the message frame or log file.
/pri=Value

Parameters
Value—number that equals the total of the desired message codes from the following table:

98 Uniface Installation and Configuration Guide for Windows

 Appendix C ∙ Executables and Command Line Switches

Table 17. Message Codes for Uniface I/O

Code Description

1 Store sequence messages. For more information, see Message Level 1: Store Sequence
Messages in the Uniface Library 9.7.03.

2 Connector requests. For more information, see Message Level 2: DBMS Connector
Requests in the Uniface Library 9.7.03.

4 Return values from Fetch and Select connector requests. For more information, see
Message Level 4: Return Values from Fetch and Select Connector Requests in the Uniface
Library 9.7.03.

8 Description from Open connector request. For more information, see Message Level 8:
Description Block from Open Connector Request in the Uniface Library 9.7.03.

16 Descriptions from where and order by clauses. For more information, see Message
Level 16: Descriptions From where and order by Clauses in the Uniface Library 9.7.03.

32 Generated SQL (if available). For more information, see Message Level 32: Generated
SQL in the Uniface Library 9.7.03.

64 All system calls Uniface sends to operating system. For more information, see Message
Level 64: All System Calls Uniface Sends to Operating System in the Uniface Library
9.7.03.

128 All calls to global objects and descriptors. For more information, see Message Level 128:
All Calls to Global Objects and Descriptors in the Uniface Library 9.7.03.

1024 Network messages

2048 Image loader information

Table 18. Message Codes for the Uniface Router

Output appears only in the Uniface Router’s log file

Message Description
Level

0 Error messages only

1 Router Monitor requests (only if $MAXMONS > 0)

4 New clients and servers

32 Client and server state changes

128 Non-Router Monitor messages

256 Router Monitor messages

Description
This switch specifies the types of messages sent to the message frame or log file. For example:
• Use 0 to suppress I/O messages from Uniface; in this case, the message frame is never
cleared.

Uniface Installation and Configuration Guide for Windows 99

Appendix C ∙ Executables and Command Line Switches

• Use 111 (=1+2+4+8+16+32+64) to request all messages except calls to global objects and
descriptors.

The given Value overrides the entry in the startup shell definition.
The ability to select the messages appearing in the message frame can be very useful during the
development process. However, generating this information reduces the performance of the
application, so it is recommended that you disable the messages in a production environment.
Use messages only when you are experiencing particular difficulties.

/pri
The following example requests that all Store sequence messages (code=1), connector function
calls (code=2), Fetch and Select return values (code=4) and Open description blocks (code=8)
be shown in the message frame. The sum of the desired codes (1+2+4+8) is used for the requested
Value.
/pri=15

/shr
Specify that the Uniface Router manages the connection between the client and the Uniface
Server.
/shr

Description
Use the /shr switch for a particular UST in the assignment file to specify that the Uniface
Router should take the lead in managing the connection between the client and the Uniface
Server. This is the default behavior for the Uniface Router.
/shr has the opposite effect of the /ex switch. Use the /shr switch for a particular UST in the
Uniface Router’s assignment file to override an exclusive connection request (/ex) from the
client side.
Although the /shr switch can be used in the client’s assignment file, it has no effect.

Table 19. Effect of /ex and /shr in Client and Uniface Router Assignment Files
The /ex switch for a particular UST on the client side works only if there is no corresponding /shr
switch for that UST in the Uniface Router’s assignment file. If the switch specified in the client's
assignment file is different from the switch specified in the Uniface Router assignment file, the client's
switch is ignored and a warning message is generated.

urouter.asn

no switch /ex /shr

Client.asn no switch shared (default) exclusive shared

/ex exclusive exclusive shared + Warning

message

/shr shared Error message shared

100 Uniface Installation and Configuration Guide for Windows

 Appendix C ∙ Executables and Command Line Switches

/ust
Register a client application or Uniface Server under a symbolic name with a Uniface Router.
/ust = SymbolicName

Parameters
• SymbolicName—a logical client ID for the Uniface client, or UST for the Uniface Server.
In combination with the user name, it uniquely identifies the application process. If omitted,
use the /ust command line switch to supply the symbolic name.
The value is a string that can consist of alphanumeric characters, dashes, and underscores.
Colons, slashes, dots, brackets, and so on, are not allowed.

Description
For a Uniface client application, the only reason to register with the Uniface Router is to be
able to receive postmessages. The combination of user name and symbolic name must be unique;
otherwise, the registration will fail.
For an automatically started Uniface Server, the Uniface Router appends this qualifier to the
userver command line when it starts the server. The Uniface Server registers with the Uniface
Router to let the router know that the startup was successful, that it is available to handle client
requests, and that it can receive postmessages.
Once an application or Uniface Server is registered under a client ID or UST, it cannot change
its registration.
If a Uniface Server is started manually, /dnp and/or /ust must be supplied on the command
line. For more information, see Starting Uniface Servers in the Uniface Library 9.7.03.
It can also be used to register a started server with another remote Uniface Router.

Server Registration
Use the /ust switch on the command line of a manually-started Uniface Server to register it
with the Uniface Router. This enables the Uniface Router to route client requests to this Uniface
Server and start additional instances of this server.
If it is omitted, and the UST is not defined in the [SERVERS] section of the Uniface Router
assignment file, the Uniface Router uses the default UST definition. If this is not specified,
the server will be started with all the normal default settings.

Server Registration
The following example demonstrates starting a Uniface server manually and registering it with
the Uniface Router. The /ust command line switch specifies the server name HOME, for which
several switches are specified in the Router’s assignment file urouter.asn.

Example 1. Windows
On the command line:
userver.exe /ust=HOME

Uniface Installation and Configuration Guide for Windows 101

Appendix C ∙ Executables and Command Line Switches

In urouter.asn:
[SERVERS]
default = c:\usys82\userver.exe /max=10 /maxidle=2h
HOME = c:\usys82\userver.exe /asn=home\home.asn /dir=c:\usys82\project

Client Registration
Use the /ust switch on the command line of a Uniface client application to register the client
with the Uniface Router. The Uniface Router requires this information to route messages to
client applications.

NOTE
The client ID in the /ust switch overrides the client ID provided in $DNP, if any.

Client Registration
The following example starts a Uniface application using the /ust command line switch, which
registers the Uniface client with the Uniface Router.
Windows : uniface.exe /ust=unikees appl.aps

102 Uniface Installation and Configuration Guide for Windows