1.1. Welcome
1.2. About UCM
1.3. Changes in this Release
1.4. Migration from Release 1.x to Release 2.0
1.5. Conventions Used in this Manual
1.6. Syntax of Command Lines
1.7. Support, Feedback

1.1. Welcome

This manual is the reference for the Unitec Communication Manager software UCM. It provides complete description of all UCM utilities, functions and configuration tables. The information provided explains in detail, what the system capabilities are, but it does not explain the technical implementation. The software has been developed by using the Unitec C-Library CLib. The reference manuals of this package constitutes an integral part of the UCM documentation.

The manual is organized as follows:

1.2. About UCM

The Unitec Communication Manager UCM is a sophisticated inter-process communication system. In a client-server environment, it allows easy data transfer between Unix or Windows NT and Windows processes. For server developers, UCM provides a communication library with a standard ANSI C interface. The Windows UCM software has been implemented by using state of the art OLE 2.0 technology in order to achieve unmatched speed.

The major components of UCM are:

• libucm.a Unix ANSI C and ucm.lib Win32 communication library. Comes with several example programs and a Cobol interface library in C source.
• Ucm.exe The Windows Unitec Communication Manager handles the communication with services located on remote systems. It administers all necessary TCP/IP connections by the use of Windows Sockets (wsock32.dll located in your Windows system directory).
• Ucm.ocx The UCM Active-X control provides the client application interface to UCM. It fires events whenever new data is available and lets the programmer send messages to other UCM controls or to remote server processes. Any number of Ucm.ocx controls may be placed on a form. An application typically has one control on each form with the same Service(P) property value but different message ID settings. This allows a server process to satisfy different requests by sending the result messages to the proper form. For a complete description of the dispatching algorithm, see Chapter 5, Active-X Introduction and Service(P).
  Active-X controls can be used with many development systems such as C++, PowerBuilder, Delphi, Visual Basic, VBA (Access, Excel, Word, PowerPoint) and so on.
• UcmConf This program can be used to configure UCM on any PC.

UCM provides a set of powerful functions, such as:

• Send messages to and receive messages from other UCM controls located on any form of the same or a different process.
• Send messages to and receive messages from services provided by one or more processes located on any remote system in the net. Once UCM is configured, communication is transparently handled by the communication manager Ucm.exe.
• Design sophisticated, event driven applications by using the automatic program launch feature on the arrival of predefined message types (see ucmconf(U)).
• Extremely easy to use Windows communication. Sending data to a server process on a remote system is done by a simple assignment statement to the OutputMsg property of an UCM control. If incoming data has to be processed, events will be fired and the message can be accessed in the InputMsg property. Everything else is completely handled by UCM!
• Asynchronous communication supports multiple, well behaving concurrent Windows UCM tasks.
• Support for automatic heart beat probe packets, to prevent zombie server processes.
• UCM uses message data compression to reduce net traffic.

The Exciting Presence

Use UCM today in multiple development platforms. The sample Cobol interface library in Chapter 9, Programming, gives you a quick start for the transition of host based applications to the state of the art Unix-Windows client-server model. Integrate and use the features of most major Windows applications through OLE Automation or DDE links. Save time and money by including widely available third party development components such as Active-X Controls (OCX) for graphics, spread sheets, tool bars, Fax integration and so on.

1.3. Changes in this Release

This release of UCM incorporates all enhancements already described in the READ.ME file of release 1.x and the manual has been extended accordingly. All other changes are shown in the following list:

• Support utilities and programming libraries for Win32 (Windows 95 and NT) have been added.
  
• C and Cobol functions for client processing have been added.
  
• The C interface has been redesigned and grouped under the UCM function family.
  
• The Cobol interface has been redesigned and grouped under the UCI function family (former UDM). A compatibility layer for the Rel. 1.x is provided.
  
• To bypass the UCM service definitions and to directly specify host IP addresses and port numbers (TCP/IP services), utility arguments and function prototypes have been extended and new Active-X properties have been added. The additional new addressing methods relax the need to administer the hosts and services control files throughout the net.
  
• Heart beat functionality has been added to prevent zombie server processes on ungraceful client termination.
  
• As with each new release, many "minor" changes, corrections and improvements have been implemented.

1.4. Migration from Release 1.x to Release 2.0

This section is of importance to users only who are currently using UCM Release 1.x. The notes are intended help you to avoid incompatibilities, they do however not cover new features that may be used without affecting current installations. This latest release of UCM has undergone a major redesign. The technology changes since the old Visual Basic Control (VBX) times to today's OLE/COM methods are so huge, that it would not have been reasonable to try to achieve backward compatibility. Where applicable we do provide compatibility layers. Most of the transition work will have to be done in adapting the Active-X interface to the new version. Not taking the burden of keeping the old design, will force users of pre-versions to invest some time in conversion effort. An estimated 10 minutes per control is well worth the advantage achieved by using state of the art technology. Due to reserved word conflicts in some development environments, the naming of a number of interface objects had to been changed.

• The following properties and events have changes their name and/or prototype:
  

  old:	Input	(Property)
  new:	InputMsg
  old:	Output	(Property)
  new:	OutputMsg
  old:	Input(EnumFields as Integer)	(Event)
  new:	DataInput()
  old:	Service / name> wildcard method	(Property)
  new:	Service, CommID	(Properties)

   

• The following properties and events have been removed:
  

  old:	Field, FieldIndex, FromField, ToField                   example: for i = 1 to Ucm.NoOfFields     Ucm.FieldIndex = i     ' do something with Ucm.Field Next i	(Properties)
  new:	Field(index as Long) example: for i = 1 to Ucm.NoOfFields     ' do something with Ucm.Field(i) Next i	(Collection)
  old:	FistInput(EnumFields as Integer)	(Event)
  new:	FirstInput()
  old:	BeginInput, FieldInput, EndInput	(Events)
  new:	- no replacement -
  old:	Action	(Property, pseudo method)
  new:	Send, SendMsg	(Methods)

1.5. Conventions Used in this Manual

This section describes how the various symbols and typefaces are used in this manual.

Symbols

If you have worked with C before, you may already be familiar with many of this manual's symbols.

Typefaces

References

In order to minimize distraction by references to additional information of specific topics, the following conventions apply:

A reference to a section in the same chapter is represented by the section name in bold type.

A reference to a section in a different chapter or in the standard Unix-Manual is represented by the section name in bold type followed by a chapter identification enclosed in parenthesis ().

The reference id's used throughout this manual are:

1.6. Syntax of Command Lines

The general format of UCM command lines is:

command [option...] [file...]

• command

Name of the command

• option

We distinguish between options with and options without arguments (switches).

Options without argument

Switches have to be entered as -s, this is a hyphen '-' immediately followed by a letter. The entry is case sensitive. To override preset switches (e.g. from an environment variable) the form -+s can be used. Multiple switches may be grouped together after one hyphen (e.g. -af).

Options with argument(s)

If the command syntax requites an option argument it has to be supplied. Spaces between the option letter and the option argument are optional. If the argument string contains embedded spaces, it has to be enclosed in single or double quotes (e.g. -t 'Customers 1998'). If the option allows multiple arguments, they have to be separated by commas or colons without intermediate spaces. The first delimiter encountered becomes effective for all of the remaining arguments (example -r arg1:arg2). Some of the UCM utilities may use multi letter option names. Such options require at least one space between the name and the argument value (e.g. -e20 arg).

Special options

To terminate an option list, the user may enter two hyphens '--'. This allows to include files whose name start with a hyphen.
Some programs may have numeric options. In such a situation the option name and the option argument can be viewed as the same entity. These options may occasionally also allow a plus sign as the delimiter character (e.g. prog +7).
All of the UCM programs include an option -help which will display a short summary of the command syntax and the possible options.

• file

File arguments are optional. All utilities that expect file name arguments will substitute standard input if no such name has been entered. A single hyphen '-' will be interpreted as standard input or standard output depending on context. As an example, the command line pr f2 | prog f1 - f3 will cause prog to process the file f1 followed by the file f2 which has been preprocessed by pr(1) and finally the file f3.

If specified in the manual, UCM programs may allow options to be specified remotely. The later an option is processed, the higher is its priority. This means that from multiple definitions of the same option, the most recent will be effective.

1.7. Support, Feedback

Most of the problems that might arise with the use of UCM may be solved by careful reading of this manual. The chapter Utility Descriptions contains all the information needed for normal operation. The chapters Installation and Configuration are the primary source of information to set up the UCM environment and the chapter Programming serves the software developer as a reference on how to integrate UCM features into their applications. Additional information will be supplied through Release Notes, Technical Notes or may be found in a READ.ME file.

If however you cannot solve your problem with the documentation supplied, you should consult the support department of your software dealer.

It was our desire to make this document as complete, accurate and useful as possible. However, it is inevitable that errors will exist and improvements can be made. We can only serve you better if you take the time to notify us, preferably in writing, of any errors, suggested improvements, or areas of confusion. Please contact us at the address given in the Unitec license agreement.