UCM Manual

UCM Unitec Home Page

Unitec Communication Manager

Release 2.0

Welcome to the UCM reference manual. It contains the following chapters:

1. Introduction
2. Installation
3. Utility Descriptions
4. Function Descriptions
5. Active-X Introduction
6. Property Descriptions
7. Event Descriptions
8. Method Descriptions
9. Programming
10. Configuration
11. Unitec Coding Standards

Copyright © by Unitec Informatik, CH-8625 Gossau, Switzerland. All rights reserved.

Back to top


Introduction

Chapter 1 - Introduction

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:

Chapter | Name | Contents
1 | Introduction | Short overview of the functionality of UCM, the organization of this manual and the changes implemented in the current version.
2 | Installation | Description of the installation procedure.
3 | Utility Descriptions | Description of all UCM utility programs.
4 | Function Descriptions | Description of the UCM Unix library libucm.a and the Win32 library ucm.lib.
5 | Active-X Introduction | Conceptual overview of the Windows UCM data sink Active-X control Ucm.ocx.
6 | Property Descriptions | Description of all properties of the Windows UCM data sink Active-X control Ucm.ocx.
7 | Event Descriptions | Description of all events of the Windows UCM data sink Active-X control Ucm.ocx.
8 | Method Descriptions | Description of all methods of the Windows UCM data sink Active-X control Ucm.ocx.
9 | Programming | Description of the UCM Unix sample Cobol interface library.
10 | Configuration | Description of UCM configuration tables and system requirements.
11 | Unitec Coding Standards | Description of the Unitec standards for symbol naming, comments and indentation.
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.

Symbol | Meaning
| | Separates alternative entries.
[] | Encloses optional items.
... | Follows bracketed syntax that may be repeated.
{} | Encloses a group of options that are separated by '|'. one of the options must be selected.
< > | Encloses a key-name. For example, the Control key is represented by <Ctrl>.

Typefaces

Typeface | Meaning
Bold | A reserved word, a function-, command- or argument-name.
Italic | Names of variables to which values must be assigned, such as filenames and command-options.
Underlined | Default options.
Monospaced | Example programs and data.

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:

ID | Reference
(I) | Chapter 2 / Installation
(U) | Chapter 3 / Utility Descriptions
(F) | Chapter 4 / Function Descriptions
(P) | Chapter 6 / Property Descriptions
(E) | Chapter 7 / Event Descriptions
(M) | Chapter 8 / Method Descriptions
(L) | Chapter 9 / Programming (Cobol Interface Library)
(C) | Chapter 10 / Configuration
(1) | UNIX Standard-Commands
(2) | UNIX System-Calls
(3) | UNIX Library Subroutines
(4) | UNIX Special Files
(5) | UNIX File Formats
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.

Source | Description
$HOME/.progrc | The users home directory may contain a file named .progrc (dot - prog - remote-control for program prog). If such a file exists, all the options it contains will be considered as if they had been entered on the command line. The file may contain several lines and lines starting with the number symbol '#' are treated as comment.
PROGOPT | If the shell environment has an exported variable with the name PROGOPT (options for the program prog), its content will be included in the command line.
prog command line | see above
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.


Copyright

Copyright / Trademarks

Copyright © 1996-2000 by Unitec Informatik. All rights reserved.

Information in this document is subject to change without notice and does not represent a commitment on the part of Unitec Informatik. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license or nondisclosure agreement.

Unitec Informatik
Thomas Madörin
Leerüti 797

CH-8625 Gossau

Switzerland

Unix is a registered trademark of AT&T Bell Labs Incorporated.
Unitec is a registered trademark of Unitec Informatik, Switzerland.
Windows, Visual Basic, Excel, Word, Project and Power Point are registered trademarks of Microsoft Incorporated.


License

Unitec License Agreement

Important Notice:

Please read this license agreement carefully before installing the enclosed UCM software! By using this software you indicate your acceptance of the Unitec license agreement.

This is a legal agreement between the user of the product Unitec Communication Manager UCM thereafter referred to as User, and

Unitec Informatik
Thomas Madörin
Leerüti 797

CH-8625 Gossau

referred to as Unitec and covers all parts of the software and its documentation.

By installing and/or using the enclosed software, you are agreeing to be bound by the terms of this agreement. It includes all component parts of the UCM Software such as libraries, executables, user interfaces, source components and all associated documentation, jointly referred to as Products.

Unitec Informatik (Unitec) grants you (User) the limited right to use one (1) copy of the enclosed Product in object code on a single terminal connected to a single computer. Multi terminal licenses are available from Unitec. This agreement supersedes all prior agreements, proposals, and representations between you and Unitec regarding: 1) the Unitec Software contained in this package; 2) earlier releases of this Software and; 3) all accompanying written materials, including any prior written agreement or any agreement in the manuals.

  1. You may use the Products to develop computer programs in compiled, linked, executable form (your Application Programs), provided none of the programs constitute either a spooler system or a communication management product which could be used to commercially compete with any Unitec product currently available. You may not delete Unitec copyright notices from your Application Programs. You may use the Products only with the type of operating system specified on the media labels. Other licenses must be obtained form Unitec for development in other environments.

  2. If the Product label specifies a multi-user operating system, the Product may be used by the same number of users and/or programmers as the number granted by your serial number and activation key combination, provided they all use the same, single Central Processing Unit (CPU). For single user operating systems, you must obtain a license for each CPU (effectively each user, programmer or workstation on a network) on which the Product is used, whether in source code or object code.

  3. You may modify and compile the Product source code, if supplied, provided you do not delete copyright notices. All modified versions are part of the licensed Products subject to this agreement and the property of Unitec. All modifications of, partial replacements of, and extensions of Unitec source code must be delivered to Unitec upon written request. If you compile the source code for use with an operating system other than specified on the media labels, you must license another copy of the Products, specifying that operating system, or obtain a special license from Unitec for that operating system, even if you intend to use both versions on only a single CPU.

  4. You agree to indemnify, hold harmless, and defend Unitec form and against any claims or lawsuits, including attorneys’ fees, that arise or result from the use or distribution of programs distributed under this license, including any claim that Application Programs which you created under this license infringe any rights of any third parties.

  5. The Products contain proprietary and confidential information. You must keep the Products in strict confidence and ensure that anyone with access to the Products refrains from unauthorized reproduction or disclosure. All copies of the Products, including written materials, are protected by national copyright laws and international treaty provisions and are owned by Unitec or its suppliers. You may not use, reproduce, modify, distribute, disclose, or transfer the Products, except as allowed by this license. You may make a reasonable number of copies solely for working, backup, or archival purpose, provided you use only one working copy at a time for each licensed CPU. You may not copy the written materials accompanying the Products. You may not sell, sublicense, rent, lease, assign, give, or transfer any Unitec end user license or Product. Your obligations under this agreement survive any substitution and/or termination of the licenses granted by this agreement.

  6. The license granted herein may be terminated by returning or destroying all copies of the Products materials within your control and so notifying Unitec in writing. The above licenses, including your right to use the Products, will terminate automatically if you infringe Unitec copyrights or breach this agreement. Unitec may suspend or terminate the above licenses, with 30 days prior notice and opportunity to cure, if you fail to pay any amount due Unitec or any Unitec distributor, dealer, or subsidiary. Termination of the above licenses neither impairs third party rights in programs lawfully distributed prior thereto, nor does such termination affect other obligations under this agreement.

  7. Unitec warrants that the Products have been accurately recorded on the media and that the media contain no defects. If you return any medium which does not meet this warranty to the place where you obtained it within 30 days from the date of shipment, Unitec or its reseller will repair or replace the medium without charge. Unitec disclaims all other warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, and all other remedies for breach of the above warranty. You assume all risks with respect to the accuracy, adequacy, quality, reliability, and performance of the products. All implied warranties which may not be disclaimed are limited to 30 days.

  8. In no event shall Unitec, its resellers, or suppliers be liable for any damages whatever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use this product, whether in an action based on contract or tort, including negligence or strict liability, even if Unitec has been advised of the possibility of such damages. Any liability of Unitec is limited in the aggregate to amounts paid to Unitec for this Software and license.

  9. Whenever possible, each provision of this agreement shall be interpreted in such manner as to be valid and effective under applicable law. If any provision is invalid, the remaining provisions remain enforceable.

  10. The laws of the Kanton Zürich, Switzerland, control this agreement. It is enforceable by Unitec and/or its distributors and dealers. Disputes will be finally resolved by arbitration pursuant to uncitral rules of arbitration and conducted in Zürich, Switzerland. The arbitration will be conducted, at Unitec’s option, either in English or German by one arbitrator. The prevailing party in any action related to an alleged infringement of Unitec proprietary rights is entitled to recover its costs and expenses, including reasonable attorneys’ fees.


Installation

Chapter 2 - Installation

2.1. Overview
2.2. Unix Installation
2.3. Windows Installation
2.4. Unix Compilation
2.5. Installation Programs

2.1. Overview

This chapter provides the information necessary to get started using UCM. Information about the installation and basic configuration is presented in a cookbook manner. For detailed configuration information, please refer to chapter 9, Configuration.

Note!

All Unitec products require the license manager ULM to run properly.
The setup(I) program for the Unix UCM software will install all components in the proper locations.

2.2. Unix Installation

As a first step, an empty directory has to be created on the hard disk of the target system to install all the UCM files. Throughout the following sections we use the directory /usr/ucm as the base for the installation. If you prefer to choose another directory, you should substitute the default name with the your selection.

login as root
mkdir /usr/ucm

Next, the data on the distribution media must be stored in the /usr/ucm directory on your hard disk. Normally Unix UCM is shipped on 3½" MS-DOS DD or HD diskettes. Special formats are available upon request:

3½" DD or HD diskette, Unix tar(1) format
5¼" MS-DOS format, 720KB or 1.2MB
5¼" 96 Tpi, 720KB or 1.2MB, Unix tar(1) format
QIC 24 tape cartridge, Unix tar(1) format

MS-DOS Format

MS-DOS diskettes contain one file ucm.tar or ucm.tzr. This file has to be transferred to the Unix file system. Several methods are possible. If you are using PC/TCP, Pathworks or PC-NFS the standard DOS copy command can be used to copy the software to any mounted Unix device. If you are using ftp, you must use binary transfer mode. Some Unix implementations provide a command to read DOS diskettes (e.g. SCO doscp -r).

Important!

Some copy utilities distinguish between text and binary files. The UCM files have to be transferred in binary mode in order to prevent any cr/lf conversions. As an example, the SCO doscp command must be used with the r-option and ftp must be set to binary mode.

Once you have copied the UCM software to your /usr/ucm directory, login as root and change to it (cd(1) command). If the suffix of the filename is .tzr, use the following shell commands:

mv ucm.tzr ucm.tar.Z
uncompress ucm.tar

To extract all files use:

tar xvf ucm.tar

If the tar(1) command reports a Directory checksum error, try:

dd if=ucm.tar conv=swab | tar xvf –

You are now ready to run the setup program:

./setup

Unix Format

If your distribution media is in Unix format, use the tar(1) command to extract the UCM files:

tar xvf /dev/x

where /dev/x is the device name of the drive required (e.g. /dev/tape, /dev/ct0, /dev/fd, /dev/fd0135ds18). If you are unsure about the device name, pleas consult your Unix manual. Some systems define a default device for the tar(1) command, so just tar xv may do the job.

If the tar(1) command reports a Directory checksum error, try:

dd if=/dev/x conv=swab | tar xvf –

If just one file named ucm.tar.Z is extracted use:

uncompress ucm.tar
tar xvf ucm.tar

and then

./setup

Setup

After calling the UCM setup(I) utility, just follow the on screen instructions. For a detailed description of this program, please refer to the program documentation later in this chapter.

Note!

Since this library product does not require special file distribution actions, it is shipped with the Unitec License Manager setup program. You will therefor be prompted for ULM (and not UCM) environment parameters.

The contents of the various directories after successful installation is listed below:

Name | Contents
/etc | Configuration file ulm.default, ulm(I) program.
/usr/lib/ulm | Default ULM base directory as defined by ulm_base_dir. Will hold the ULM database ulm.dat, a copy of setup(I) for potential uninstallation and internal information.
support | Subdirectory of ulm_base_dir: read.me and other support files.
cwd | UCM files, sample programs and functions.

After the download of the software, you may find additional information on UCM in a READ.ME file.

If you plan extended use of the UCM library, you may want to copy some general purpose files to standard Unix locations:

cp ucm.h /usr/include
cp libucm.a /usr/lib

This concludes the basic installation and configuration. Many parameters may be set to change the behavior of the UCM software. The description of the configuration files can be found in the remainder of this manual.

Note!

In order to run programs using UCM services, you will have to configure your TCP/IP network. Please consult the appropriate sections in Chapter 9, Configuration.

2.3. Windows Installation
  • Start MS-Windows and insert the UCM Setup diskette into drive A:
  • In the Program Manager choose File - Run
  • Enter a:\setup and hit <Return>

Configuration information can be found in Chapter 9, Configuration.

2.4. Unix Compilation

To compile the configurable library modules or the sample programs, a makefile is provided. The most parameters are set, to run correctly under generic Unix. In any case, the makefile needs some small modifications. The table below lists the configurable make(1) macros.

Macro | Description | Default Setting
cflags | Compiler flags. Please refer to the cc(1) manual page. | -O
ldflags | Loader flags. Please refer to the cc(1) and ld(1) manual pages. | -n
libtype | Library type: portar portable archive ranlib ranlib(1) type library | portar

After the makefile preparations, just run make(1).

cd /usr/ucm
make

2.5. Installation Programs

This section contains descriptions of the UCM installation programs in alphabetical order. The page headers for the descriptions contain the name and a brief description of the utility.

The Synopsis section contains the command line syntax, showing all possible options and arguments.

The Description section explains the purpose of the utility and any command line arguments.

The Options section explains each of the possible command line options.

Where applicable, program configuration details are listed in the Configuration section.

Program | Title
setup | Product Installation.
ulm | Unitec License Manager.


Setup

UCM Installation

setup(I)
Synopsis Description Options Notes Files See also

Synopsis

setup [-t] [-v]

Description

Setup installs or uninstalls the UCM/ULM software on the target Unix system. Prior execution, the software distribution files have to be copied into a working directory such as /tmp. For details, please consult the appropriate sections earlier in this chapter.

When invoked, the setup installation program will startup in interactive mode.

Main menu (first invocation):

ULM 1.00 Setup Program

Commands:
1 - Install ULM
q - Quit

Enter Command:

Main menu (subsequent invocations):

ULM 1.00 Setup Program

Commands:
1 - Reinstall/Update ULM
2 - Uninstall ULM
q - Quit

Enter Command:

Choosing items will open a submenu or a request to enter installation parameters. On each menu level, entering 'q' or just hitting <Return> will get you back one level or terminate the program respectively.

Selection 1 installs or updates the ULM software. Setup will check for the presence of all files of the distribution media in the current working directory. If files are missing, setup will terminate with an error message. Please follow on screen instructions.

Selection 2 uninstalls the ULM software from the system. Some files will be reported to be left unchanged. To completely remove ULM, use the rm(1) command to manually delete the reported files. If a later reinstallation is likely, the conserved files will ease the future setup process.

All the actions performed by setup are logged in the file setup.log.

Options

-t | Test option. Using this option logs all actions in setup.log, but does not perform them.
-v | Show software version information.

Notes

Since UCM for Unix is a library product that does not require special file distribution actions, it is shipped with the ULM Unitec License Manager setup program. You will therefore be prompted for ULM (and not UCM) environment parameters.

Files

setup.log

Program action log.

See also

ulm, ULM.DEFAULT(C)


Ulm

Unitec License Manager

ulm(I)
Synopsis Description Options Files See also

Synopsis

ulm [-a key -c name [-d date] -p prod -r rel -s serno] [-v]

Description

The ulm program is the main control-unit in the ULM license management system. Its action is driven by the command line options or, if no options are specified, by user input in interactive mode. Batch serializing can be performed by specifying all of the a-, c-, p-, r- and s-options.

When invoked without options, the ULM license administration program will startup in interactive mode.

Main menu:

Unitec License Manager

Select Product:
1 - CSS Commercial Spooling System
2 - WinCss / CSS Windows Interface
3 - UCM Unitec Communication Manager
q - Quit

Enter Selection:

Choosing items will open a submenu or a request to enter serializing parameters. On each menu level, entering 'q' or just hitting <Return> will get you back one level or terminate the program respectively.

After product selection, the next menu is visible:

Unitec License Manager

Commands:
1 - Serialize <Product>
2 - Set <Product> License Unit Assignment
q - Quit

Enter Command:

where <Product> shows the name of the product selected in the main menu.

Selection 1 enters the product serialization process (also called product branding). In order to successfully complete this section, please have your Activation Key ready. The following data has to be entered:

Prompt | Entry
Activation Key | This eight character key is used to verify all data entered. It consists of characters and/or digits and is not case sensitive, i.e. it may be entered in upper or lower case.
Serial Number | The product serial number consists of three parts, delimited by hyphens ‘–’. The first part represents the unique product number assigned to the customer, the second part identifies the license type and the third part shows the number of license units (i.e. the number of users allowed to work with the software). Missing parts use predefined defaults.
Company Name | The customer name. To prevent terminal compatibility problems, umlauts may be entered as ae, oe and ue.
Street Address | A missing street address must be entered as hyphen ‘–’.
ZIP / City | ZIP code and city name.
Release Number | Product release number.
Date Period | Used for time limited demo versions. This entry does not show for unlimited license types. The date must be entered in the format yyyymmdd–yyyymmdd

After all parts have been entered, individual modification is possible. To conclude the serialization process just hit the <Return> key.

Selection 2 allows the system administrator to predefine the users allowed to run the software. Each user identification consist of either the numeric client IP address (for Client-Server products such as WinCss and UCM) or the name of the invoking tty (for plain Unix products such as CSS and CssLib).

Manual assignments are however not required. On startup, each Unitec program locates its product entry in the license database and searches for the current user identification in all available license unit slots. If no such slot can be found, an automatic assignment to the first vacant slot is performed. When all slots have been used, execution of the software is not possible for unassigned user ids.

In rare circumstances, if the network layout or an IP address have changed, you can clear or modify the data stored in a license unit in this menu section.

Options

-a key | Activation key for batch branding.
-c name | Customer information. Three parts enclosed in quotes must be given 'Name:Street:City'. If the street address is missing, it must be entered as empty string 'Name::City'.
-d date | Optional date period yyyymmdd-yyyymmdd.
-p prod | Product name CSS, WinCss or UCM. Not case sensitive.
-r rel | Product release number.
-s serno | Serial number.
-v | Show software version information.

Files

ulm.dat

License database, located in the ULM_BASE_DIR.

See also

ULM.DEFAULT(C)


Utilities

Chapter 3 - Utility Descriptions

3.1. Overview

This chapter contains descriptions of the UCM utility programs in alphabetical order. The page headers for the descriptions contain the name and a brief description of the utility.

The Synopsis section contains the command line syntax, showing all possible options and arguments.

The Description section explains the purpose of the utility and any command line arguments.

The Options section explains each of the possible command line options.

Where applicable, program configuration details are listed in the Configuration section.

The following utility overview is grouped by category:

• Unix / Windows NT utilities

Program | Title
UcmServer | Generic Server.

• Windows utilities

Program | Title
Ucm | Communication Manager.
UcmConf | Configuration Utility.


Ucm

Communication Manager

ucm(U)
Synopsis Environment Description Files See also

Synopsis

windows\System\Ucm.exe

Environment

Windows

Description

The Unitec Communication Manager Ucm.exe handles all UCM communication task in the Windows client environment. Incoming data is locally distributed in UCM message format. Outgoing messages are received and are transmitted through the winsock.dll standard communication interface. For maximum speed, local data transfer between Ucm and the application programs is accomplished by the use of OLE/COM technology. Benchmark tests have shown, that UCM is capable to distribute thousands of messages per second. The only limitation arises form network throughput.

Ucm is automatically started upon the first inter-system message transfer. To reduce application load time, you may however start Ucm at Windows startup time. Ucm is located in your Windows System directory.

Ucm shows a status icon in the system tray, normally located on the right side of the taskbar:

SyssTray.gif (954 bytes) The green triangle indicates the communication output status, the red triangle indicates the input status.
Color | Status
grey | idle
red | communication start
green | communication end

The Ucm Monitor window can be opened by double clicking on the status icon:

UcmMonSt.gif (7885 bytes)

Selecting the Connections tab will show the current connection status:

UcmMonCon.gif (6505 bytes)

The information shown is:

Node | Description
UcmMonID.gif (931 bytes) | Each ID node represents a UCM communication space. The number shown represents the setting of the CommID(P) property in the contained UCM controls.
UcmMonIP.gif (925 bytes) | Each IP node represents a TCP/IP socket connection to the Host(P) and Port(P) indicated. All contained controls use the same connection. The special wildcard entry '*' contains the controls that have not (yet) set their IP properties.
UcmMonAx.gif (928 bytes) | Each Ax node represents one instance of an Active-X control Ucm.ocx.
UcmMonI.gif (899 bytes) | The I node shows the current input message ID settings in the InputID(P) property of the parent control. It contains input message and character statistic leafs.
UcmMonO.gif (916 bytes) | The O node shows the current output message ID setting in the OutputID(P) property of the parent control. It contains output message and character statistic leafs.
UcmMonM.gif (926 bytes) | Shows the number of messages sent or received.
UcmMonC.gif (914 bytes) | Shows the number of characters sent or received.

Selecting the Show Log button will open the message log window:

UcmMonLog.gif (6029 bytes)

Each message log entry has the following syntax:

TF[ID] Message data

where:

T | Message type: I for input, O for output, E for error
F Status flag, meaningful for input messages only:
blank | message has been forwarded to one UCM Acive-X control
2..9 | message has been forwarded to the number of controls indicated
* | message has been forwarded to more than 9 controls
- | message could not be forwarded, no control was ready to accept this message ID
ID | Message ID as defined by the InputID(P) or OutputID(P) properties. Error message expose the number of the error occurred. For a list of all UCM errors, refer to the Error(E) event description.
Warning:

Pressing the Unload button when active UCM connections exist, may cause your programs or the operating system to hang. Whenever it is unsafe to unload Ucm.exe you will be prompted with a warning dialog.

Files

Windows Registry

UCM configuration at HKEY_LOCAL_MACHINE\SOFTWARE\Unitec\Ucm

See also

UcmConf, Chapter 5 Active-X Introduction


UcmConf

Configuration Utility

UcmConf(U)
Synopsis Environment Description Remarks Files See also

Synopsis

UcmConf

Environment

Windows

Description

UcmConf is a user friendly interface for modifications of the UCM registry configuration data. It provides two sections, Services and Autostart.

1. Services

This section defines the remote services that may be used in the Service(P) property of the UCM Active-X Control. These definitions are required for remote communication with the AdrMode(P) property set to ucmService only. With the ucmTCP addressing mode and for local interprocess message transfer, no services need to be defined. Each entry in this section consists of three fields:

Entry | Description
UCM Service | The UCM service ID that can be used as Service(P) property in the Ucm.ocx control.
TCP/IP Port The TCP/IP port number or name that will provide the services identified by UCM Service. When using a symbolic name, it must also be defined in the TCP/IP services file of the local and the remote system referenced by the Host IP Address entry. Each line in the services file holds the server name, a port number and a port type (type should always be ‘tcp’). To avoid conflicts with standard TCP/IP ports, these numbers should have values > 5000 assigned by convention. Unitec software uses port numbers in the rage 6800 to 6999, e.g. for a future version of the license manager the port 6800 has been reserved and the CSS spooler uses port 6801. To avoid conflicts with standard TCP/IP and Unitec ports, you should use numbers in the range 5001 to 6799 or >= 7000. The server names and port numbers must match on both systems. Example:

aServer 5001/tcp

The TCP/IP Port entry defaults to the value stored in UCM Service. It is possible to have several different UCM Service’s using the same TCP/IP Port. This will result in multiple TCP/IP socket connections, one for each UCM Service in use.

Host IP Address | The host IP address or name as defined in the TCP/IP hosts file.

2. Autostart

This section defines the programs that shall provide automatic, event driven message processing service. Each entry in this section consists of two fields:

Entry | Description
MsgID | Whenever UCM has to deliver a message of the defined MsgID and does not find a process waiting for such a message (no UCM Active-X Control with the InputID(P) property set to this message ID), the program defined in the Program column will be started.
Program | The full path of the executable that will process the UCM message. It is important, that such programs do have an Ucm.ocx control with the InputID(P) set to the value of MsgID.
Hint:

Use UcmConf to properly configure one client system in a new network environment. Once you have verified correct operation, run the Windows regedit and navigate to the location

HKEY_LOCAL_MACHINE\SOFTWARE\Unitec\Ucm\Services

Choose the export option to write the selected branch to e.g. services.reg. Copy this file to the other client systems and double click on it from the Windows Explorer. This will import the same settings into the new clients registry.

The same procedure can be applied to the AutoStart definitions at

HKEY_LOCAL_MACHINE\SOFTWARE\Unitec\Ucm\AutoStart

Remarks

To make new settings available to a running system, please close all UCM applications and unload the communication manager Ucm.exe (double click on the system tray icon and choose Unload). The next application performing UCM IO will cause the manager to reload automatically.

Files

Windows Registry

UCM configuration at HKEY_LOCAL_MACHINE\SOFTWARE\Unitec\Ucm

See also

Chapter 5 Active-X Introduction


UcmServer

Generic UCM Server

UcmServer(U)
Synopsis Environment Description Options Diagnostics Notes Examples See also

Synopsis

UcmServer -e prog -s service [-u user] [-d] [-f] [-l]

Environment

Unix, Windows NT

Description

The UcmServer program is a generic server daemon, that can be used to simplify dedicated server development. It approximates the functionality of the Internet Superserver inetd(1) for a single service. Multiple UcmServer’s may be started in order to provide daemons for different services.

Typically UcmServer is invoked at boot time from the /etc/rc startup file or from /etc/inittab (System V only).

Options

-e prog | Executable prog, to be started upon a connection request to service. If the full pathname of prog is not specified, it must be available through the PATH environment variable. The first command line argument argv[1] of prog contains the socket number to be used in the call to UcmInit(F) function. The ASCII socket number may be converted to a t_socket type by the atio(3) function.
-s service | Identifies the service that UcmServer has to listen for. The service argument may be given as symbolic TCP/IP service name or as numeric port number. When using the symbolic service name, the same service must be defined in /etc/services or the Windows services file with type ftp. This option is required.
-u user | This option will cause prog to be executed under the user ID user. The argument user may be given as symbolic user name or as numeric user ID. This option is available on Unix UCM only.
-d | Run the server programs prog invisible in the background (detached) This option is available on Win32 UCM only.
-f | Run the UcmServer program visible in the foreground. This option is available on Win32 UCM only.
-l | Show connection log messages in the UcmServer console window. This option implies the f-option and is available on Win32 UCM only.

Diagnostics

UcmServer will fail and exit with status 1, if one or more of the following is true:

  • Not both of the e- and s-options are specified.
  • The user specified in the u-option could not be fount in /etc/passwd.
  • The program is unable to change to user. In order to change to another user ID (setuid(2)) the UcmServer program must have been invoked by root.

Notes

UcmServer can be stopped by the command kill -15 pid.

Unless started by the init(1) program, UcmServer will detach automatically from the calling process.

Examples

The following line could be included in the file /etc/rc(4):
/usr/ucm/UcmServer -s cssws -e /usr/lib/css/cssws 2>/tmp/cssws.log 1>&2

Unix System V only

The same service can be established on System V by inserting the following line /etc/inittab(4):

cssws:1:respawn:/usr/ucm/UcmServer -s cssws -e /usr/lib/css/cssws 2>/tmp/cssws.log 1>&2

See also

inetd(1), inetd.conf(4), init(1), initab(4), services(4)


Functions

Chapter 4 - Function Descriptions

4.1. Overview

This chapter contains descriptions of the application program interface of all UCM runtime library functions. The page headers for each description contain the function name and title.

The Synopsis section gives a summary of the actual function declaration.

The Description explains all of the function's operational details.

In the Diagnostics section, common status and error codes are listed, often with possible explanation for their occurrences.

Related functions are identified in the See Also section.

An Example section is provided for each function. The example is intended to illustrate how the function is called, not necessarily how to use the function. In some cases, the example is very brief. In all cases, it should be sufficient to show how the call is made.

The following functions are in alphabetical order:

Function | Title
UcmClientVersion | Get software version of UCM Client.
UcmClose | Close an UCM Connection.
UcmCntl | UCM control operations.
UcmConnect | Connect to an UCM Server.
UcmInit | Initialize UCM Communication.
UcmOpen | Open UCM Server Connection.
UcmRecv | Receive Message.
UcmSend | Send Message.
UcmSendf | Send Formatted Message.
UcmServer | Generic UCM Server Function.
UcmTerm | Terminate UCM Communication.
UcmVersion | Get UCM library software version.

Return- and error codes of all UCM functions are described in ucmErrno.


UcmClose

Close an UCM Connection

UcmClose(F)
Synopsis Environment Description Diagnostics See also Examples

Synopsis

#include "ucm.h"

int UcmClose(sock);
T_SOCKET sock;

Environment

Unix, Win32

Description

The UcmClose function closes the socket sock, that has been initialized by UcmConnect or UcmOpen. In order to allow correct socket housekeeping, this call is mandatory.

UcmClose will fail if one or more of the following is true:

UE_NOTINIT | The UCM software has not been initialize (see UcmInit)
UE_BADSOCK | The value of sock is not a valid socket descriptor or the socket is not open.

Diagnostics

Upon successful completion UcmClose returns UCM_SUCCESS. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the error.

See also

UcmConnect, UcmInit, UcmOpen

Examples

See UcmOpen.


UcmCntl

UCM Control Operations

UcmCntl(F)
Synopsis Environment Description Diagnostics Notes See also Examples

Synopsis

#include "ucm.h"

int UcmCntl(sock, cmd,
    [arg...]);
T_SOCKET sock;
int cmd;

Environment

Unix, Win32

Description

UcmCntl allows to get or change control variables of an open socket sock. Data type and value of argument arg are dependent on the command cmd. The symbolic names for all possible commands are defined in the header ucm.h.

The following values for cmd and the operations they specify are available:

UC_IFLUSH Discard all messages currently available through socket sock (input flush). The argument arg has no significance and may be omitted.
UC_TIMEOUT Sets the timeout for subsequent UcmRecv calls with the UF_TIMEOUT flag on the given sock to (int) arg1 seconds and (int) arg2 milliseconds. Both arguments must be specified.
The default timeout values value after UcmConnect are zero.
The return value of this command is the timeout value setting in seconds for the socket before the call.
UC_KEEPALIVE Causes the process to send heart beat messages to clients. This command should only be used in server processes. A server typically spends most of its time in the UcmRecv function, waiting for client requests. If the client crashes or a network error occurs the server has no way of knowing this. In several TCP/IP implementations even a send operation will not return a bad status in such situations. Since Unitec has found the standard SO_KEEPALIVE socket option not to work correctly on many systems, the UC_KEEPALIVE command has been implemented in the UCM transport layer of Release 2.0. After (int) arg1 seconds without receiving any client requests, the internal logic of UcmRecv will post a transparent probe packet. Event driven clients (i.e. clients built with the UCM Active-X control) will automatically respond to such messages. After (int) arg2 unsuccessful retries, the server considers the client to have crashed and returns an UE_CONNECT error to the caller of the receive function. Non event driven clients need to call their own UcmRecv function in order to catch probe packets. Since such programs typically spend most of their time waiting for user input, we discourage the use of UC_KEEPALIVE, to prevent the server process to wrongly assume that the connection has broken. You may want to set the standard SO_KEEPALIVE socket option in these environments:
T_SOCKET sock;
int one = 1;
...
UcmOpen(sock);
setsockopt(sock, SOL_SOCKET, SO_KEEPALIVE, (char *) &one, sizeof(one));
...

Normally a server process reading from a broken communication link does not impact system performance. The UC_KEEPALIVE settings should therefore be chosen conservatively, e.g. 120 seconds, 15 retries.

UcmCntl will fail if one or more of the following is true:

UE_NOTINIT | The UCM software has not been initialize (see UcmInit)
UE_INVALID | Invalid argument.
UE_BADSOCK | The value sock does not identify an open socket.

Diagnostics

Upon successful completion UcmCntl returns UCM_SUCCESS. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the error (see exception below).
UC_TIMEOUT previous timeout value (seconds)

Notes

The UC_KEEPALIVE feature should only used with UCM client software of release 2.0 or higher. The UcmClientVersion function may be used to obtain client version information.

See also

UcmInitComm

Examples

#include "ucm.h"

T_SOCKET sock;
...
UcmInit();
UcmOpen(sock);
UcmCntl(sock, UC_KEEPALIVE, 120, 10);
...
UcmCntl(sock, UC_IFLUSH);
UcmClose(sock);
UcmTerm();


UcmConnect

Connect to an UCM Server

UcmConnect(F)
Synopsis Environment Description Diagnostics Globals Notes See also Examples

Synopsis

#include "ucm.h"

T_SOCKET
      UcmConnect(host, service);
char *host;
char *service;

Environment

Unix, Win32

Description

UcmConnect opens and initializes a BSD stream type socket to the server identified by service on the node host. There is no need for a client process to call UcmOpen, since UcmConnect implies all necessary initializations. Before terminating a process that has successfully called this function, UcmClose should be called to properly release the socket. The host argument represents the TCP/IP address or host name on which the server process providing the service is located. When using the symbolic host name, it must be defined in /etc/hosts or the Windows hosts file. The second argument identifies the service that the socket will be assigned to. Service may be given as symbolic TCP/IP service name or as numeric port number. When using the symbolic service name, it must be defined in /etc/services or the Windows services file with type ftp.

UcmConnect will fail if one or more of the following is true:

UE_NOTINIT | The UCM software has not been initialize (see UcmInit)
UE_INVALID | Invalid argument.
UE_HOST | The value host does not identify a known host.
UE_SERVICE | The value service does not identify a known service.
UE_BADSOCK | The operating system returned a bad status while creating a new socket.
UE_CONNECT | The given host does not provide the requested service.
UE_NOMEM | The new socket could not be entered into the internal database, due to low memory.
UE_NOMSG | The initialization handshaking with the server failed.
UE_ULMREG | The product UCM is not registered in the license database. Enter your activation key in the ulm(I) utility.
UE_ULMEXP | The UCM license has expired. This error may occur in demo versions only.
UE_ULMBUSY | Too many users. The UCM license does not allow additional users at this time. Please consult Unitec for details on how to increase your license.

Diagnostics

Upon successful completion UcmConnect returns a valid socket number. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the error.

Globals

char *ucmProgName; /* reference */

Notes

UcmConnect sets the linger options of socket to:

l_onoff = TRUE;
l_linger = 30;

For a detailed description of these options see setsockopt(2), so_linger. If your application needs different settings, these should be made after the call to UcmConnect.

The global pointer char *ucmProgName, which is defined in ucm.h and allocated in libucm.a, may optionally be set to the program name of the calling task. This string will be used to identify possible messages on stderr. If ucmProgName is not set, the default string ‘UCM Library’ will be used.

See also

UcmInit, UcmClose, UcmTerm, hosts(4), services(4)

Examples

#include "ucm.h"

T_SOCKET sock;
...
UcmInit();
sock = UcmConnect("128.41.01.01", "6001");
...
UcmClose(sock);
UcmTerm();


UcmErrno

UCM Error Number

ucmErrno(F)
Synopsis Environment Description

Synopsis

#include "ucm.h"

extern int ucmErrno;

Environment

Unix, Win32

Description

The global variable ucmErrno is defined in ucm.h and is available to all programs using the UCM function family. The symbol names of all possible error codes are defined in the header ucm.h:
Name | Value | Description
UE_SUCCESS | 0 | Successful function call
UE_NOTINIT | 1 | Not initialized
UE_INVALID | 2 | Invalid argument
UE_BADSOCK | 3 | Invalid socket descriptor
UE_BADMSG | 4 | Invalid message
UE_NOMSG | 5 | No message received
UE_HOST | 6 | Invalid host
UE_SERVICE | 7 | Invalid service
UE_CONNECT | 8 | Connection error
UE_INTR | 9 | Interrupted function call
UE_ULMREG | 20 | Product not registered
UE_ULMEXP | 21 | Product expired
UE_ULMBUSY | 22 | Too many users
UE_ULMVERSION | 23 | Version conflict
UE_NOMEM | 99 | Allocation error

In addition, the following return codes are defined:

Name | Value | Description
UCM_SUCCESS | 0 | Successful function call
UCM_ERROR | -1 | An error occurred, detailed description in ucmError


UcmInit

Initialize UCM Communication

UcmInit(F)
Synopsis Environment Description Diagnostics Globals Notes See also Examples

Synopsis

#include "ucm.h"

int UcmInit(void);

Environment

Unix, Win32

Description

UcmInit registers the calling process to the license manager ULM and initializes UCM message processing. In order to properly release all resources used by UCM, UcmTerm should be called upon program exit.

Diagnostics

UcmInit always returns UCM_SUCCESS.

Globals

char *ucmProgName; /* reference */

Notes

The global pointer char *ucmProgName, which is defined in ucm.h and allocated in libucm.a, may optionally be set to the program name of the calling task. This string will be used to identify possible messages on stderr. If ucmProgName is not set, the default string ‘UCM Library’ will be used.

See also

UcmTerm

Examples

#include "ucm.h"

main(argc, argv)

int argc;
char *argv[];
{
    T_SOCKET sock;          /* socket from argv[1] */

    ucmProgName = argv[0];  /* for UCM error msgs */
    sock = atoi(argv[1]);
    UcmInit();
    if (UcmOpen(sock))
        Error("UcmOpen failed, error=%d", ucmErrno);
    UcmSendf(sock, "MsgId", "Hello world");
    UcmClose(sock);
    UcmTerm();
    return 0;               /* terminate program */
}


UcmOpen

Open UCM Server Connection

UcmOpen(F)
Synopsis Environment Description Diagnostics Globals Notes See also Examples

Synopsis

#include "ucm.h"

int UcmOpen(sock);
T_SOCKET sock;

Environment

Unix, Win32

Description

UcmOpen establishes an UCM server side communication for the socket sock, that has been received by the UcmServer(U) program or as a function argument from the UcmServer callback function DoService. If the generic UCM server process UcmServer(U) is used, the socket number is available as the first (and only) command line argument and should be converted to a T_SOCKET type through atoi(3). This BSD stream type socket is a prerequisite for the use of all of the UCM library functions. Before terminating a process that has successfully called this function, UcmClose and UcmTerm should be called to properly release the socket.

UcmOpen will fail if one or more of the following is true:

UE_NOTINIT | The UCM software has not been initialize (see UcmInit)
UE_NOMEM | The new socket could not be entered into the internal database, due to low memory.
UE_ULMREG | The product UCM is not registered in the license database. Enter your activation key in the ulm(I) utility.
UE_ULMEXP | The UCM license has expired. This error may occur in demo versions only.
UE_ULMBUSY | Too many users. The UCM license does not allow additional users at this time. Please consult Unitec for details on how to increase your license.

To provide error feedback to the client user, UcmOpen sends a message through socket on all of the above license error conditions. Feedback messages all use the reserved message ID ‘_ucm_’:

Error | Message ID | Message | Description
UE_ULMPROD | _ucm_ | E1 | UCM not registered
UE_ULMEXP | _ucm_ | E2 | License expired
UE_ULMBUSY | _ucm_ | E3 | Too many users
UE_ULMVERSION | _ucm_ | E4 | Version conflict

The VB utility UcmInfo(U), which has been registered as auto start program in the UCM registry section by the Windows setup program, is the default sink for these messages and will inform the user about the error in a message box. This utility is available in VB source and may be modified (i.e. translated to the local language) by the software integrator. As an alternative, you may place an Ucm.ocx on your client applications main form, set the InputID(P) property to ‘_ucm_’ and leave the Servic(P) property unset. This will prevent an automatic start of UcmInfo(U) and enables the application to take appropriate actions by itself. For configuration details, please consult Chapter 10, Configuration and UcmConf(U).

Diagnostics

Upon successful completion UcmOpen returns UCM_SUCCESS. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the error.

Globals

char *ucmProgName; /* reference */

Notes

UcmOpen sets the linger options of socket to:

l_onoff = TRUE;
l_linger = 30;

For a detailed description of these options see setsockopt(2), so_linger. If your application needs different settings, these should be made after the call to UcmOpen.

The global pointer char *ucmProgName, which is defined in ucm.h and allocated in libucm.a, may optionally be set to the program name of the calling task. This string will be used to identify possible messages on stderr. If ucmProgName is not set, the default string ‘UCM Library’ will be used.

See also

UcmClose, UcmServer, UcmServer(U), UcmTerm

Examples

#include "ucm.h"

main(argc, argv)

int argc;
char *argv[];
{
    T_SOCKET sock;          /* socket from argv[1] */

    ucmProgName = argv[0];  /* for UCM error msgs */
    sock = atoi(argv[1]);
    UcmInit();
    if (UcmOpen(sock))
        Error("UcmOpen failed, error=%d", ucmErrno);
    UcmSendf(sock, "MsgId", "Hello world");
    UcmClose(sock);
    UcmTerm();
    return 0;               /* terminate program */
}


UcmRecv

Receive Message

UcmRecv(F)
Synopsis Environment Description Diagnostics Globals Notes See also Examples

Synopsis

#include "ucm.h"

int
      UcmRecv(sock, msgId, msg, msgLen, flag);
T_SOCKET sock;
char *msgId, *msg;
int msgLen, flag;

Environment

Unix, Win32

Description

UcmRecv reads the next available message through the BSD stream type socket sock and places it into the buffer pointed to by msg. The received message is truncated to msgLen bytes if it is larger than msgLen. The truncated part of the message is lost and no indication of the truncation is given to the calling process. By specifying msgLen as -1, the entire message up to the UCM defined limit of UCM_MAX_MSG bytes (see ucm.h) may be received.

One or more (bitwise inclusive OR-operation) of the following modes may be selected in the parameter flag:

UF_NOFLAGS | No special processing / normal case.
UF_NOWAIT | Normally UcmRecv will suspend execution until the next message comes available or the timeout span specified through UcmCntl has expired. Setting the UF_NOWAITt flag causes UcmRecv to return immediately with a return value of -1 and errno set to ENOMSG if no pending messages exist.
UF_TIMEOUT | This flag causes UcmRecv to return with the UE_NOMSG error when the time span set with the UC_TIMEOUT UcmCntl command has elapsed without receiving any message.

UcmRecv will fail and no message will be received if one or more of the following is true:

UE_NOTINIT | The UCM software has not been initialize (see UcmInit)
UE_BADSOCK | The value of sock is not a valid socket descriptor or the socket is not open.
UE_INTR | The read process has been interrupted by a signal.
UE_NOMSG | No message is available and UF_NOWAIT is set or UF_TIMEOUT is set and the timeout span specified via UcmCntl has expired.
UE_CONNECT | The socket has been closed.

Diagnostics

Upon successful completion UcmRecv returns a value equal to the number of bytes actually placed into msg. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the error.

Notes

The header ucm.h defines constants and types, that may be used to allocate msgId and msg buffers:
Name | Description
UCM_MAX_MSG | Constant, maximum message size in the current implementation (see also Chapter 9, Configuration Limits)
UCM_MAX_MSGID | Constant, maximum message ID size
T_UCM_MSG | Type, message buffer, large enough to hold any UCM message
T_UCM_MSGID | Type, message ID buffer, large enough to hold any UCM message ID

Globals

char *ucmProgName; /* reference */

See also

UcmCntl, UcmConnect, UcmOpen

Examples

#include "ucm.h"

T_SOCKET socket;
T_UCM_MSG msg; /* buffer to hold message */
T_UCM_MSGID msgId; /* buffer to hold message ID */
int len; /* size of message received */
...
len = UcmRecv(sock, msgId, msg, -1, UF_NOFLAGS);
printf("UcmRecv returned %d\n", len);


UcmSend

Send Message

UcmSend(F)
Synopsis Environment Description Diagnostics See also Examples

Synopsis

#include "ucm.h"

int
      UcmSend(sock, msgId, msg, msgLen, flag);
T_SOCKET sock;
char *msgId, *msg;
int msgLen, flag;

Environment

Unix, Win32

Description

UcmSend sends msgLen bytes of the data in the buffer pointed to by msg through the socket sock. If zero-terminated strings have to be sent, msgLen may be specified as -1. This causes UcmSend to transfer strlen(msg) + 1 bytes (by including the string terminator, the receiving program may safely use sscanf to extract fields from the message).

One or more (bitwise inclusive OR-operation) of the following modes may be selected in the parameter flag:

UF_NOFLAGS No special processing / normal case.

Note: At this time, no other flags are available. This parameter is reserved for future use.

UcmSend will fail if one or more of the following is true:

UE_NOTINIT | The UCM software has not been initialize (see UcmInit)
UE_BADSOCK | The value of sock is not a valid socket descriptor or the socket is not open.
UE_INTR | The send process has been interrupted by a signal.
UE_CONNECT | The socket has been closed.

Diagnostics

Upon successful completion UcmSend returns UCM_SUCCESS. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the error.

See also

UcmInit, UcmRecv, UcmSendf

Examples

#include "ucm.h"

T_SOCKET socket;
T_UCM_MSG msg; /* message buffer */
T_UCM_MSGID msgId; /* message ID buffer */
...
rc = UcmSend(socket, msgId, msg, -1, UF_NOFLAGS);
printf("UcmSend returned %d\n", rc);


UcmSendf

Send Formatted Message

UcmSendf(F)
Synopsis Environment Description Diagnostics See also Examples

Synopsis

#include "ucm.h"

int UcmSendf(sock,
    msgId, format [, arg]...);
T_SOCKET sock;
char *msgId, *format;

Environment

Unix, Win32

Description

UcmSendf sends a printf(3) formatted message trough the socket specified by sock.

UcmSendf will fail if one or more of the following is true:

UE_NOTINIT | The UCM software has not been initialize (see UcmInit)
UE_BADSOCK | The value of sock is not a valid socket descriptor or the socket is not open.
UE_INTR | The send process has been interrupted by a signal.
UE_CONNECT | The socket has been closed.

Diagnostics

Upon successful completion UcmSendf returns UCM_SUCCESS. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the error.

See also

UcmInit, UcmSend, printf(3)

Examples

#include "ucm.h"

int rc;       /* return-code */
...
rc = UcmSendf(sock, "TestID", "One more time: %s", "Hello world");
printf("UcmSendf returned %d\n", rc);


UcmServer

Generic UCM Server Function

UcmServer(F)
Synopsis Environment Description Diagnostics Notes See also Examples

Synopsis

#include "ucm.h"

int UcmServer(service,
    DoService);
char *service;
int (*DoService)(T_SOCKET sock);

Environment

Unix, Win32

Description

The UcmServer function provides the same services as the UcmServer(U) utility. In contrast to the utility implementation, UcmServer allows you to develop self-contained servers. This server type features faster connect times, since it does not have to use the exec(2) system call. It results however in larger executables for the daemon, since it includes the full server logic. The call of this function will detach the program from the parent process, unless the parent has the PID 1, i.e. is the init(1) process.

The first argument identifies the service that the socket will be assigned to. Service may be given as symbolic TCP/IP service name or as numeric port number. When using the symbolic service name, it must be defined in /etc/services or the Windows services file with type ftp.

After each successful connect request, UcmServer forks (fork(2)) and calls the function at address DoService with the socket number sock as first and only argument. On Win32 platforms each DoService invocation is executed in its own thread. The DoService function should use UcmOpen for the new socket and return a non negative (int) return code after UcmClose.

UcmServer will fail if one or more of the following is true:

UE_NOTINIT | The UCM software has not been initialize (see UcmInit)
UE_INVALID | An invalid parameter has been passed.
UE_SERVICE | The value service does not identify a known service (i.e. is not defined in /etc/services).
UE_CONNECT | The bind(2) or accept(2) system call has failed.
UE_INTR | The accept(2) system call has been interrupted by a signal.

Diagnostics

Upon successful completion UcmServer returns (int) >= 0. Otherwise, a value of UCM_ERROR is returned and ucmErrno is set to indicate the error.

Notes

Typically programs using the UcmServer function, are invoked at boot time from the /etc/rc startup file or from /etc/inittab (System V only).

See also

init(1), initab(4), services(4), UcmOpen, UcmServer(U), UcmTerm

Examples

#include "ucm.h"

#if defined(__STDC__)
static int DoService(T_SOCKET sock);
#else
static int DoService();
#endif

main()
{
    ucmProgName = argv[0]; /* for UCM error messages */
    UcmInit();
    UcmServer("7001", DoService);
    UcmTerm();
    return 0;
}

static int DoService(sock)

T_SOCKET sock;
{
    T_UCM_MSG msg;     /* buffer to hold message */
    T_UCM_MSGID msgId; /* buffer to hold message ID */

    if (UcmOpen(sock))
        Error("UcmOpen failed");
    while (UcmRecv(sock, msgId, msg, -1, UF_NOFLAGS) > 0)
    {
        /* this server just echoes back its input */
        UcmSendf(sock, "Got ‘%s:%s’", msgId, msg);
    }
    UcmClose(sock);
    return 0;
}


UcmTerm

Terminate UCM Communication

UcmTermComm(F)
Synopsis Environment Description Diagnostics See also Examples

Synopsis

#include "ucm.h"

int UcmTerm(void);

Environment

Unix, Win32

Description

UcmTerm concludes the UCM message processing for the calling process. All open sockets are closed and the memory used for status information is released.

UcmTerm will fail if one or more of the following is true:

UE_NOTINIT The UCM software has not been initialize (see UcmInit)

Diagnostics

Upon successful completion UcmTerm returns UCM_SUCCESS. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the error.

See also

UcmInit

Examples

See UcmInit.


UcmVersion

Get UCM Version

UcmVersion(F)
Synopsis Environment Description Diagnostics Notes See also Examples

Synopsis

#include "ucm.h"

int UcmVersion();

int UcmClientVersion(sock, timeOut);
T_SOCKET sock;
unsigned int timeOut;

Environment

Unix, Win32

Description

UcmVersion returns the current version number of the UCM library used to link the program. The version integer contains the sum of the major release number multiplied by 100 and the minor release number, i.e. release 2.03 will be returned as 203.

UcmClientVersion returns the current version number of the UCM Active-X control or the UcmConnect library function used to establish the socket sock with the caller. Starting with release 2.03 the client logic of UCM sends an internal version information message immediately after establishing a socket connection and before transmission of any application data. If this internal message is not received within timeOut milliseconds or any application data is received without prior internal version information, a value of 0 (zero) will be returned, indicating an unknown version. It is usually safe to use a large value (e.g. 20'000) as timeOut argument.

It is best to assume UCM 1.0 (formerly named UDM) if the UcmClientVersion function returns zero.

Both version functions may be used prior a call to UcmInit.

UcmClientVersion will fail and no version information will be returned if one or more of the following is true:

UE_BADSOCK | The value of sock is not a valid socket descriptor or the socket is not open.
UE_INTR | The read process of the internal version message has been interrupted by a signal.
UE_CONNECT | The socket has been closed.

Diagnostics

Upon successful completion UcmVersion and UcmClientVersion both return a version integer value as described above. Otherwise, UCM_ERROR is returned and ucmErrno is set to indicate the error.

Notes

The version functions have been introduced in release 2.03. The use of the UcmClientVersion function with socket arguments created by older UCM clients will return a version value of 0 (zero), indicating an unknown version.

See also

UcmConnect

Examples

#include "ucm.h"

main(argc, argv)

int argc;
char *argv[];
{
    int version;            /* client version */
    T_SOCKET sock;          /* socket from argv[1] */

    ucmProgName = argv[0];  /* for UCM error msgs */
    sock = atoi(argv[1]);
    version= UcmClientVersion(sock, 10000);
    UcmInit();
    if (UcmOpen(sock))
        Error("UcmOpen failed, error=%d", ucmErrno);
    if (version >= 200)
        UcmCntl(sock, UC_KEEPALIVE, 120, 10);
    while ((len = UcmRecv(sock, msgId, msg,
                                -1, UF_NOFLAGS)) > 0)
    {
        /* process incoming message */
        if (strcmp(msg, "Exit") == 0)
            break;
        UcmSendf(sock, msgId, "Got: %s", msg);
    }
    UcmClose(sock);
    UcmTerm();
    return 0;               /* terminate program */
}


ActiveX

Chapter 5 - Active-X Introduction

5.1. Overview
5.2. UCM Messages
5.3. Addressing Methods

5.3.1. Message ID
5.3.2. TCP/IP Address
5.3.3. Communication Space
5.3.4. Global Communication Space
5.3.5. Terms

5.4. AutoStart Processes
5.5. Closing an UCM Connection
5.6. UCM Error Handling

5.1. Overview

This chapter contains an introduction to the features of the UCM Active-X control Ucm.ocx. To make full use of the control, it is important to understand the underlying concepts. Please read the following section carefully. All examples used in this chapter assume a VB program with a form named Form1 containing an UCM control named Ucm1.

5.2. UCM Messages

An UCM message consists of a message ID and the message body. The message ID serves as the lowest level addressing component in the data transport. Sending a message requires the OutputID(P) property to be set. To receive UCM messages a control must set the InputID(P) property to the message type it is ready to accept. Except when specifying the wildcard ID "*", which means 'any', only one message type can be received by a control at a given time.

Message ID Message Data

Input message data may optionally be subdivided into fields by setting the Delimiter(P) property. Fields can be accessed by the Field(M) method:

Message ID Field : Field :

Field

5.3. Addressing Methods

5.3.1. Message ID

UCM supports several addressing methods. As stated above, the message ID constitutes the lowest level in the addressing scheme. It controls data distribution of messages sent from the local or a remote system. The control in the following example will receive all local and remote messages with ID someID:

Sub Form1_Load()
    Ucm1.InputID = "someID"
End Sub

Sub Ucm1_DataInput()
    Debug.Print "Input event, got message:"; Ucm1.InputMsg
End Sub

If several controls are waiting for the same message ID, UCM will duplicate the message and broadcast to each of them. To perform a local data transfer, another program could be used:

Sub Form1_Load()
    Ucm1.OutputID = "someID"
    Ucm1.OutputMsg = "Hello World"
End Sub

Even a second Active-X control contained in the same program could be the sender of such a message. Of course, a control will never receive a message that has been sent by itself. If no Ucm.ocx is ready to receive a local message posted, an Error(E) event is raised in the sending control and the message is discarded (see the AutoStart feature below for an exception of this rule).

The special wildcard InputID "*" matches any message ID value.

5.3.2. TCP/IP Address

The next higher addressing level consists of the TCP/IP address of the server thread or process.

To establish a TCP/IP Client-Server connection, the client must know the IP address of the system providing the server functionality. In addition, each connection type is identified through a unique port number. The TCP/IP hosts and services control files define symbolic names for the standard IP addresses (hosts) and for most of the ports (services) used in a network environment. Using these symbolic names requires the hosts and services file to be present on each network node, i.e. on the host and on all client systems. On Unix systems, the files are located in the /etc directory. On Windows systems the location varies depending on OS type and version. Each line in the hosts file contains the standard four number IP address and one or more symbolic alias names. Each line in the services file holds the service name, a port number and a port type (for UCM communication the type should always be tcp). To avoid conflicts with standard TCP/IP ports, these numbers should have values > 5000 assigned by convention. Unitec products use port numbers in the range from 6800 to 6999.

Important note:

In TCP/IP programming a communication link between a server and a client is established by the use of an entity called socket, introduced by UCB University of California at Berkley, also referred to as BSD sockets. A socket is defined by the IP address of the two participating systems and a so called port number. Port numbers often have a symbolic service name assigned in a control file named services, but internally the number is used as is. Many well known port numbers (reserved services) are defined in the range between 1 and 1023, but room should be left for extensions. By convention, user port numbers should have values > 5000 assigned. Unitec software uses port numbers in the rage 6800 to 6999, e.g. for a future version of the license manager the port 6800 has been reserved and the CSS spooler uses port 6801. To avoid conflicts with standard TCP/IP and Unitec ports, you should use numbers in the range 5001 to 6799 or >= 7000.

To initialize an UCM control for non local communication, the Host(P) and Port(P) properties must be set. Both values may be given in either symbolic or standard numeric notation. To reduce administration overhead, it is recommended to use the numeric addressing method. This removes the need to maintain similar copies of the hosts and services file across the network:

Sub Form1_Load()
    Ucm1.AdrMode = ucmTCP
    Ucm1.Host = "128.41.1.3"
    Ucm1.Port = "7201"
    Ucm1.InputID = "form1"
    Ucm1.OutputID = "form1"
    Ucm1.Delimiter = ":"
    Ucm1.OutputMsg = "Request address of customer 8712"
End Sub

Sub Ucm1_DataInput()
    Dim name as String
    Dim street as String
    Dim city as String

    ' Ucm1.InputMsg might contain:
    ' "Unitec:Leerueti 797:Gossau"
    name = Ucm1.Field(1)
    street = Ucm1.Field(2)
    city = Ucm1.Field(3)
    ...
End Sub

The scope of possible input messages of the Ucm1 control in the above example is now reduced to the socket identified by the Host and Port properties and which is automatically established by the communication manager upon the first output operation. Even if a message with the same "form1" ID enters the system and has to be distributed, Ucm1 will only receive the message if it origins from the socket it is attached to. The deeper the addressing level is defined, the closer the data sink object can be determined. Now consider another form in the same program, with its own UCM control needing to communicate with the same server process. This second form Form2 would have to initialize its control exactly the same way, except that it should set its InputID and OuptutID to a different value, e.g. "form2". Failing to do so, would cause both forms to receive any response message, regardless of the sender of the request. In fact it is common practice for a program to have one UCM control per form, each addressing the same server process, but with distinct message IDs. The server program normally analyzes a request message and sends one or several response messages with the same message ID that was used in the request. The first form of the client program that sends a message by assignment to its OutputMsg(P) property causes UCM to establish a connection to the server by creating a socket. All other controls that refer to the same address are attached to the already existing connection.

There remains one problem: what if two invocations of the same program are running? Since they both use the same message IDs on say Form1, and the same TCP address, will not each program also get response messages to requests that origin from the other copy of the program? The answer is yes, they both share the same socket (i.e. communicate with the same copy of the server thread or process) and the broadcast feature of UCM will duplicate input messages for each control listening for the same message ID. This might be what we require, but normally it is exactly the behavior we do not want.

Before introducing the highest addressing level, the communication space, we have to take one more close look at the example above. The AdrMode(P) property is used as:

    Ucm1.AdrMode = ucmTCP

An alternative to the ucmTCP mode is ucmService. It uses the Service(P) property to specify the server address instead of the Host and Port properties. By using the UcmConf(U) utility, a symbolic service name can be defined for a host and port address pair. This UCM service name can then be assigned to the Service property. When installing software in many different environments, the advantages of symbolic names that can be configured externally over hard coded addresses are obvious.

Hint:

Use UcmConf(U) to properly configure one client system in a new network environment. Once you have verified correct operation, run the Windows regedit and navigate to the location

HKEY_LOCAL_MACHINE\SOFTWARE\Unitec\Ucm\Services

Choose the export option to write the selected branch to e.g. services.reg. Copy this file to the other client systems and double click on it from the Windows Explorer. This will import the same settings into the new clients registry.

UCM controls have their TCP/IP address set if either AdrMode(P) is ucmTCP and Host(P) as well as Port(P) are not empty, or AdrMode(P) is ucmService and Service(P) is not empty. Such controls are said to be bound, all other controls are unbound.

5.3.3. Communication Space

Remember the problem of two or more concurrent invocations of the same program described above? In such a situation, we normally do not want to share the same socket connection between different processes. Starting with UCM Release 2.0 an additional addressing level, the so called communication space, has been introduced. It is identified by a long integer and can be set using the CommID(P) property. Each control belongs to a communication space, by default to ID 0 (zero). Also each socket created by the client side communication manager Ucm.exe, belongs to a communication space, namely to the space of the control, that caused the socket to be established. With one exception (explained below), input messages are not distributed across communication space boundaries. Since only one connection to a given address may exist in each space, all controls referring the same TCP address and CommID share one single connection. In local communication, the CommID of the sending control identifies the target space. It is important to note, that communication spaces are system local entities. The server does not need to know to which space the other end of the socket belongs to. The CommID property should be set prior to the first output operation. A perfect value is the ID of the main thread of a process, since it is guaranteed to be unique:

Sub Form1_Load()
    Ucm1.CommID = App.ThreadID
    Ucm1.AdrMode = ucmService
    Ucm1.Service = "payroll"
    Ucm1.InputID = "form1"
    Ucm1.OutputID = "form1"
    Ucm1.Delimiter = ":"
End Sub

Although making little sense, it is possible to change the CommID of a control at runtime. If in the new space no socket with the same address already exists, the space membership of the existing socket is changed to the new ID. If such a socket already exists, the control is attached to it and the connection left in the old space is closed.

Important note:

If two controls in the same process refer to the same TCP address but have distinct CommID settings, each of the controls communicate with a separate server tread or process. Since this is not what normally is wanted, all CommIDs in a single program should be set to the same value.

5.3.4. Global Communication Space

The default value of the CommID(P) property is 0 (zero), which identifies the global communication space. Unbound UCM controls in the global space will receive messages from all communication spaces if their InputID(P) property value matches the ID of the message that has to be forwarded by the communication manager Ucm.exe. Upon message arrival, the sender address information can be retrieved in the InputCommID(P), InputHost(P), InputPort(P) and InputService(P) properties. When using the wildcard InputID(P) value "*", the message ID is available in the InputMsgID(P) property.

The global communication space mimics the UCM pre 2.0 release behavior.

5.3.5. Terms

This was a lot of new information. Before proceeding to the Active-X reference sections, the definition of some terms will help to understand the concept of UCM communication and its addressing methods. These terms will be used throughout the Property, Event and Method manual pages.

Term | Description
message ID | Each UCM message is identified by an ID with data type string. Sending a message requires the OputputID(P) property to be set, whose value will become the message ID. To enable a control to receive UCM messages, the InputID(P) property must be set. Only messages that match this value will be received (i.e. will cause an DataInput(E) event to be fired). The special wildcard value "*" matches any ID.
message data | To launch a message transfer, the contents data must be assigned to the OutputMsg(P) property. If the AutoSend(P) property is set to True, transfer is immediate, otherwise the Send(M) method must be used to initiate the send operation. The value of an incoming message is available in the InputMsg(P) property whenever a DatInput(E) event occurs.
message field | UCM messages are optionally subdivided into fields. The field delimiter can be set in the Delimiter(P) property. Individual field values may be accessed with the Field(M) method and the number of fields contained in an input message is available in the NoOfFields(P) property.
bound control An UCM control is said to be bound if one of the following is true:
  • the AdrMode(P) property is set to ucmTCP
    the Host(P) as well as the Port(P) properties are not empty

  • the AdrMode(P) property is set to ucmService
    the Service(P) property is not empty
unbound control | An Ucm control is said to be unbound, if it is not bound (see above). Output operations of unbound controls are local only.
communication space | Each control operates within the context of a communication space, which is identified by the CommID(P) property. Also each socket established by the communication manager is attached to a communication space, namely the space the control belongs to, that caused the socket to be created. Message forward occurs only within the given space. This enables multiple copies of the same client program to each communicate with its own server process or thread.
global space | The global communication space is identified by ID 0 (zero). Unbound controls will receive input messages from any space when their InputID(P) matches the ID of the message to be distributed.
5.4. AutoStart Processes

With the help of the configuration utility UcmConf(U) automatic program startup on message arrival can be defined. Each entry in the AutoStart table defines a message type (InputID) and the full path to the executable that will handle that message. Whenever a message (local or remote) has to be delivered, and no active UCM control is currently ready to receive that message type (i.e. has its InputID property set to the type in question), the communication manager scans the AutoStart table for a matching entry. If an entry is found, the program specified is started automatically. One of the first actions an AutoStart program must perform, is to initialize an UCM control with the required InputID. Failing to do so may lead to multiple invocations of the same program and to undeliverable messages that will be silently discarded.

5.5. Closing an UCM Connection

UCM connections are dropped automatically when the last Active-X control object using the socket exits, i.e. when the container of the control terminates.

5.6. UCM Error Handling

When an error occurs, UCM controls fire the Error(E) event. Why does UCM not use the Err object and the error trapping methods built into the VB language? Communication errors are not immediate, an application program just initiates operations that are handled asynchronously by UCM. Waiting for each communication request to terminate would lead to unacceptable slow programs. All error events will thus happen unsolicited.

Communication errors must normally be considered as severe. The situation can be compared to memory allocation failures, where in almost all cases, there exists no reasonable way to continue execution of a program. The same holds true for UCM errors.

Since multiple UCM controls may be using the same communication link, all of them might receive the same Error(E) event, e.g. when a connection is dropped by the remote process. Error handling in such situations is a little bit tricky, since you must prevent multiple user notifications for the same error. The code involved might look like this:

Option Explicit

Public g_ucmError as Boolean

Public Sub UcmError(ByVal ErrNumber As UcmOcx.ucmErrors, _
                    ByVal ErrText As String)
    If (g_ucmError) Then
        Exit Sub
    End If
    g_ucmError = True
    If (ErrNumber = ucmErrHost _
    Or  ErrNumber = ucmErrServiceUnknown) Then
        Call MsgBox("No connection could be established." & vbCr & _
                    "Please verify your host or port configuration.", _
                    vbInformation, "UCM Error")
        Call TermApp    ' terminate application
        Exit Sub
    End If
    If (ErrNumber = ucmErrMngrShutdown) Then
        Call MsgBox("The UCM manager has been stopped!" & vbCr & _
                    "Please restart your program.", _
                    vbInformation, "UCM Error")
        Call TermApp    ' terminate application
        Exit Sub
    End If
    Call MsgBox("A communication error has occurred!" & vbCr & _
                "Please close your program and restart.", _
                vbInformation, "UCM Error")
    Call TermApp    ' terminate application
End Sub

Once the public g_ucmError flag is set, UCM output should be avoided. This is best done by wrapping output operations like this:

    If (Not g_ucmError) Then
        Ucm1.OutputMsg = "some output"
    End If

As a final step, implement error event handling for each control:

Private Sub Ucm1_Error(ByVal ErrNumber As UcmOcx.ucmErrors, _
                       ByVal ErrText As String)
    Call UcmError(ErrNumber, ErrText)
End Sub


Properties

Chapter 6 - Property Descriptions

6.1. Overview

Properties are a set of variables available in each instance of an Active-X Control (OCX). The majority of these variables allow the programmer to set or access their value, some of them are read only. Each assignment as well as each reference of property variables are controlled by underlying program code within the OCX. Most of the properties are available at design time. This allows the OCX user to set or change initial values without having to write code. Another advantage is, that the OCX logic ensures, that the values read form properties are always valid.

To learn more about the concepts of UCM communication and its addressing methods, please refer to the Active-X section in this manual.

This chapter contains descriptions of all properties of the UCM Active-X control Ucm.ocx. The page headers for each description contain the property name and title.

The Usage section gives a summary of the actual assignment or reference declaration.

The Description explains all of the property’s operational details.

The Data Type section, defines the storage type of the property variable.

Related properties, events and methods are identified in the See Also section.

These properties are also described in the Windows help file ucm.hlp and are available context sensitive within the property window at design time.

The following properties are in alphabetical order:

Property | Title
(About) | Activate About Dialog.
AdrMode | Addressing Mode.
AutoConnect | Automatic Server Connect.
AutoSend | Automatic Message Send.
CommID | Communication Space ID.
Delimiter | Message Field Delimiter.
FieldBase | Base Index of Field Collection.
Host | Host IP Address.
InputCommID | UCM CommID of Last (Current) Input Message.
InputMsg | Input Message Value.
InputMsgID | Message ID of Last (Current) Input Message.
InputHost | Host IP Address of Last (Current) Input Message.
InputID | Input Message ID.
InputPort | Port Number of Last (Current) Input Message.
InputService | UCM Service of Last (Current) Input Message.
MessageID | Input/Output Message ID.
NoOfFields | Number of Fields in Input Message.
OutputMsg | Output Message Value.
OutputID | Output Message ID Value
Port | TCP/IP Port Number.
Service | UCM Service Name.


About

Activate About Dialog

About(P)

 | Name Environment Usage Description Remarks
Name | Action
Environment | Windows
Usage | Click on the ellipses ('...') button next to the property text to activate the about dialog box.
Description | Displays version information about the control.
Remarks | Available at design time only.


AdrMode

TCP/IP Addressing Mode

AdrMode(P)

Name Environment Usage Description Data Type Remarks See also

Name

AdrMode

Environment

Windows

Usage

[Form.]Ucm.AdrMode = value

Description

The AdrMode property controls the method used to address a server process.
Value | Description
ucmService | The ucmService setting causes the communication manager to convert the value in the Service property into a valid TCP/IP host and port address. By using the UcmConf(U) utility, a symbolic service name can be defined for a host and port address combination. This UCM service name can then be assigned to the Service property. When installing software in many different environments, the advantages of symbolic names that can be configured externally over hard coded addresses are obvious.
ucmTCP | This setting uses direct TCP addressing through the values assigned to the Host and Port properties.

Data Type

ucmAdrMode Enumeration

Remarks

The default setting of AdrMode is ucmService.

See also

CommID, Host, Port, Service


AutoConnect

Automatic Server Connect

AutoConnect(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | AutoConnect
Environment | Windows
Usage | [Form.]Ucm.AutoConnect = boolean
Description | When the AutoConnect property is set to True, the first message of a remote sender that matches the given InputID will automatically attach the control to the originating socket connection and set the Host and Port properties to the TCP/IP address of the sending server process. In addition, the AdrMode property is set to ucmTCP and the CommID property to the ID of the communication space in which the underlying socket is a member of. As with every DataInput(E) event, the address information is also available in the InputCommID, InputHost, InputPort and the InputService properties.
Data Type | Boolean
Remarks | The default setting of AutoConnect is True.
See also | AdrMode, CommID, DataInput(E), Host, InputID, Port


AutoSend

Automatic Message Send

AutoSend(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | AutoSend
Environment | Windows
Usage | [Form.]Ucm.AutoSend = boolean
Description | When the AutoSend property is set to True, an assignment to the OutputMsg property will automatically trigger a send action. If set to False, send actions may be performed by the Send(M) method.
Data Type | Boolean
Remarks | The default setting of AutoSend is True.
See also | OutputMsg, Send(M)


CommID

UCM Communication Space

CommID(P)

Name Environment Usage Description Data Type Remarks See also

Name

CommID

Environment

Windows

Usage

[Form.]Ucm.CommID = value&

Description

The CommID property identifies the communication space the control and the underlying TCP/IP socket is a member of. All message IO is done within the defined space, i.e. communication data can not cross space boundaries. The main purpose of the CommID property is to allow multiple instances of a client program, each communicating to its own server thread or process.

This additional addressing level has been introduced starting with UCM Release 2.0. It is identified by a long integer. Each control belongs to a communication space, by default to ID 0 (zero). Also each socket created by the client side communication manager Ucm.exe(U), belongs to a communication space, namely to the space of the control, that caused the socket to be established. Again, input messages are never distributed across communication space boundaries. Since only one connection to a given address may exist in each space, all controls referring the same TCP address and CommID share one single connection. In local communication, the CommID of the sending control identifies the target space. It is important to note, that communication spaces are system local entities. The server does not need to know to which space the other end of the socket belongs to. The CommID property should be set prior to the first output operation. A perfect value is the ID of the main thread of a process (i.e. App.ThreadID), since it is guaranteed to be unique.

The global communication space is identified by ID 0 (zero). Unbound controls will receive input messages from any space when their InputID matches the ID of the message to be distributed.

Data Type

Long

Remarks

The default setting of CommID is 0 (zero).

Although making little sense it is possible to change the CommID of a control at runtime. If in the new space no socket with the same address already exists, the space membership of the existing socket is changed to the new ID. If such a socket already exists, the control is attached to it and the connection in the old space is dropped.

Important note:

If two controls in the same process refer to the same TCP address but have distinct CommID settings, each of the controls communicate with a separate server tread or process. Since this is not what is normally wanted, all CommIDs in a single program should be set to the same value.

See also

Host, Port, Service, Chapter 5 Active-X Introduction


InputMsg

Message Field Delimiter

Delimiter(P)

Name Environment Usage Description Data Type Remarks See also

Name

Delimiter

Environment

Windows

Usage

[Form.]Ucm.Delimiter = value$

Description

This property allows you to set the delimiter of the fields within a message. Whenever an input message is received, the NoOfFields property holds the number of fields based on the current setting of Delimiter. The default value for Delimiter is the colon ':'.

Data Type

String (1 Character)

Remarks

The default setting of Delimiter is the colon ":".

Each message consists of an message ID, a colon separator and the message value optionally subdivided into fields separated by the Delimiter property value. Upon receipt of a message, the ID field is accessible in the InputID property and the message value in the InputMsg property. The sub field values may be retrieved with the Field(M) method. If the Delimiter property is set to an empty string, Field(1) is identical to InputMsg. Server processed will receive UCM messages in the format shown below.

ID

:

Field

D
e
l
i
m
i
t
e
r

Field

D
e
l
i
m
i
t
e
r

Field

Setting a Delimiter value at runtime will cause the control to actualize the NoOfFields property for the current InputMsg value with regard to the new delimiter.

See also

DataInput(E), Field(M), FieldBase, InputMsg, NoOfFields


FieldBase

Field Index Base

FieldBase(P)

Name Environment Usage Description Data Type Remarks See also

Name

FieldBase

Environment

Windows

Usage

[Form.]Ucm.FieldBase = value

Description

The FieldBase property sets the base index of the message Field collection.
Value | Description
ucmBase0 | The index to access the first message field through the Field(M) method is 0 (zero). This setting is best used with the C programming language.
ucmBase1 | The index to access the first message field through the Field(M) method is 1. This is the preferred setting for VB.

Data Type

ucmBase Enumeration

Remarks

The default setting of FieldBase is ucmBase1.

See also

Field(M)


Host

TCP/IP Host Name

Host(P)

Name Environment Usage Description Data Type Remarks See also

Name

Host

Environment

Windows

Usage

[Form.]Ucm.Host = value$

Description

The Host property identifies the IP address of the system providing the server functionality. The value can be set in the standard four number notation (e.g. "128.41.1.3") or as symbolic alias name as defined in the TCP/IP hosts file. On Unix systems, this file is located in the /etc directory. On Windows systems the location varies depending on OS type and version. Each line in the hosts file contains the numeric IP address and one or more symbolic alias names.

Once both set, the Host and Port properties reduces the I/O scope to messages from that service in the communication space CommID (and - as always - to messages with the same ID as defined by the InputID property). If Host is not set, messages from any source that match InputID will be received and output is forwarded to all UCM controls on the local system that have their Service, Host and Port properties cleared too.

The Host property is meaningful only with AdrMode set to ucmTCP.

Data Type

String

Remarks

In addition to the IP address, the ucmTCP addressing mode requires the setting of a valid port number or service alias name in the Port property. For local communication neither the Host nor the Port property should be set.

A connection is established upon the first send operation of the control. If a socket with identical Host, Port and CommID already exists, the control uses this existing communication link. Note, that this may also occur indirectly when the line was established using a synonym Service property with addressing mode ucmService.

See also

AdrMode, CommID, Port, Service


InputCommID

UCM CommID of Input Message

InputCommID(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | InputCommID
Environment | Windows
Usage | value& = [Form.]Ucm.InputCommID
Description | The InputCommID property contains the communication space ID of the latest message received. The information available will divert from the value of the CommID property for unbound controls only.
Data Type | Long
Remarks | This property is read only and is not available at design time.
See also | AutoConnect, CommID, DataInput(E), InputHost, InputMsgID, InputPort, InputService


InputHost

UCM Host of Input Message

InputHost(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | InputHost
Environment | Windows
Usage | value$ = [Form.]Ucm.InputHost
Description | The InputHost property contains the IP address or the symbolic host name of the (remote) sender of the latest message received.
Data Type | String
Remarks | This property is read only and is not available at design time.
See also | AutoConnect, DataInput(E), InputCommID, InputPort, InputService


InputID

Input Message ID

InputID(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | InputID
Environment | Windows
Usage | [Form.]Ucm.InputID = value$
Description | Setting the InputID property enables the control to receive messages with the given ID from other UCM controls or - if the Host, Port properties are set - from a server process. When cleared, InputID defaults to MessageID, if both are cleared, message input is disabled. The special wildcard setting "*" allows the control to receive messages with any ID value.
Data Type | String
Remarks | The InputID must contain letters, digits, ‘_’ (underscore) and ‘.’ (period) characters only. Embedded spaces are not allowed. To avoid conflicts, please do not use InputID’s starting with an underscore '_' as these names are reserved for internal use by Unitec.
See also | DataInput(E), InputMsg, MessageID


InputMsg

Input Message Value

InputMsg(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | InputMsg
Environment | Windows
Usage | value$ = [Form.]Ucm.InputMsg
Description | The InputMsg property contains the value portion of the last message received by the control.
Data Type | String
Remarks | This property is read only and is not available at design time.
See also | DataInput(E), Field(M) , InputHost, InputID, InputPort, InputService


InputMsgID

Message ID of Input Message

InputMsgID(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | InputMsgID
Environment | Windows
Usage | value$ = [Form.]Ucm.InputMsgID
Description | The InputMsgID property contains the message ID of the latest message received. The information available will divert from the value of the InputID property for wildcard ID settings only.
Data Type | String
Remarks | This property is read only and is not available at design time.
See also | DataInput(E), InputID


InputPort

UCM Port of Input Message

InputPort(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | InputPort
Environment | Windows
Usage | value$ = [Form.]Ucm.InputPort
Description | The InputPort property contains the TCP/IP port number or symbolic name of the (remote) service process of the latest message received.
Data Type | String
Remarks | This property is read only and is not available at design time.
See also | AutoConnect, DataInput(E), InputCommID, InputHost, InputService


InputService

UCM Service of Input Message

InputService(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | InputService
Environment | Windows
Usage | value$ = [Form.]Ucm.InputService
Description | If applicable, the InputService property contains the service name of the (remote) sender of the latest message received.
Data Type | String
Remarks | This property is read only and is not available at design time.
See also | AutoConnect, DataInput(E), InputCommID, InputHost, InputPort


MessageID

Input/Output Message ID

MessageID(P)

 | Name Environment Usage Description Data Type See also
Name | MessageID
Environment | Windows
Usage | [Form.]Ucm.MessageID = value$
Description | The MessageID property acts as a default for both the InputID and OutputID values. Since it is very common to use the same settings for the InputID and the OutputID properties, you can leave both properties unset and assign the ID string to MessageID instead.
Data Type | String
See also | InputID, OutputID


NoOfFields

Number of Fields in Input Message

NoOfFields(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | NoOfFields
Environment | Windows
Usage | value& = [Form.]Ucm.NoOfFields
Description | The NoOfFields property is set to the number of message sub fields with regard to the current Delimiter whenever a new input message is received. If Delimiter is unset, NoOfFields will contain 1.
Data Type | Long
Remarks | Setting a Delimiter value at runtime will cause the control to actualize the NoOfFields property for the current InputMsg value with regard to the new delimiter. This property is read only and is not available at design time.
See also | Delimiter, Field(M), InputMsg


OutputID

Output Message ID

OutputID(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | OutputID
Environment | Windows
Usage | [Form.]Ucm.OutputID = value$
Description | The value of the OutputID property is used to assemble UCM messages as described in the Delimiter description. Setting this value is mandatory for send operations. When cleared, OutputID defaults to the value of the MessageID property.
Data Type | String
Remarks | The OutputID must contain letters, digits, ‘_’ (underscore) and ‘.’ (period) characters only. Embedded spaces are not allowed. To avoid conflicts, please do not use OutputID’s starting with an underscore '_' as these names are reserved for internal use by Unitec.
See also | MessageID, OutputMsg


OutputMsg

Output Message Value

OutputMsg(P)

 | Name Environment Usage Description Data Type Remarks See also
Name | OutputMsg
Environment | Windows
Usage | [Form.]Ucm.OutputMsg = value$
Description | Assignments to the OutputMsg property will cause the control to build a message with the current OutputID and to transmit this message to the server identified by either the Host and Port properties or the Service property. If all of these address properties are unset, the message will be broadcasted to all other UCM controls on the local system that have themselves their address properties unset and are waiting for such messages (see InputID). If the AutoSend property is set to False, the Send(M) method must be called to initiate the data transfer.
Data Type | String
Remarks | Setting an OutputMsg, OutputID and optionally the address properties Host and Port or Service values at design time will cause the control to transmit the message at load time. For timing information please consult the Microsoft Visual Basic Reference Manual.
See also | AutoSend, OutputID, Send(M)


Port

TCP/IP Port

Port(P)

Name Environment Usage Description Data Type Remarks See also

Name

Port

Environment

Windows

Usage

[Form.]Ucm.Port = value$

Description

The Port property identifies the TCP/IP port number the server process is operating on. The value can be set as numeric value (e.g. "7001") or as symbolic alias name as defined in the TCP/IP services file. On Unix systems, this file is located in the /etc directory. On Windows systems the location varies depending on OS type and version. Each line in the services file holds the service name, a port number and a port type (for UCM communication the type should always be tcp). To avoid conflicts with standard TCP/IP ports, these numbers should have values > 5000 assigned by convention. Unitec products use port numbers in the range from 6800 to 6999.

Once both set, the Host and Port properties reduces the I/O scope to messages from that service in the communication space CommID (and - as always - to messages with the same ID as defined by the InputID property). If Port is not set, messages from any source that match InputID will be received and output is forwarded to all UCM controls on the local system that have their Service, Host and Port properties cleared too.

The Port property is meaningful only with AdrMode set to ucmTCP.

Data Type

String

Remarks

In addition to port number the IP address, the ucmTCP addressing mode requires the setting of a valid IP address or host alias name in the Host property. For local communication neither the Host nor the Port property should be set.

A connection is established upon the first send operation of the control. If a socket with identical Host, Port and CommID already exists, the control uses this existing communication link. Note, that this may also occur indirectly when the line was established using a synonym Service property with addressing mode ucmService.

Important note:

In TCP/IP programming a communication link between a server and a client is established by the use of a entity called socket, introduced by UCB University of California at Berkley, also referred to by BSD sockets. A socket is defined by the IP address of the two participating systems and a so called port number. Port numbers often have a symbolic service name assigned in a control file named services, but internally the number is used as is. Many well known port numbers (reserved services) are defined in the rage between 1 and 1023, but room should be left for extensions. By convention, user port numbers should have values > 5000 assigned. Unitec software uses port numbers in the rage 6800 to 6999, e.g. for a future version of the license manager the port 6800 has been reserved and the CSS spooler uses port 6801. To avoid conflicts with standard TCP/IP and Unitec ports, you should use numbers in the range 5001 to 6799 or >= 7000.

See also

AdrMode, CommID, Host, Service


Service

UCM Service Name

Service(P)

Name Environment Usage Description Data Type Remarks See also

Name

Service

Environment

Windows

Usage

[Form.]Ucm.Service = value$

Description

The Service property is used to connect the control to a server process on a remote system. The value specified will be looked up in the UCM configuration section of the registry, which may be modified with the UcmConf(U) utility. Each service ID entry in the configuration file points to a host IP address and port number pair that identifies a TCP/IP connection. Once set, the Service property reduces the I/O scope to messages from the named service in the communication space CommID (and - as always - to messages with the same ID as defined by the InputID property). If Service is not set, messages from any source that match InputID will be received and output is forwarded to all UCM controls on the local system that have their Service, Host and Port properties cleared too.

The Service property is meaningful only with AdrMode set to ucmService.

Data Type

String

Remarks

The user of the UCM control does not have to call any TCP/IP functions. All communication tasks are handled by the Unitec Communication Manager Ucm.exe. For local communication the Service property should not be set.

The ‘>‘ character is interpreted as a special wildcard string terminator and causes UCM to automatically provide an unused Service from a Service group. Consider the situation where you want to allow the user to start multiple occurrences of a given program, each using the same remote server (Service). The Service table in the UCM configuration program should list a Service group, e.g.

Service | Server | IP Address
myserv1 | aServer | 128.41.2.1
myserv2 | aServer | 128.41.2.1
myserv3 | aServer | 128.41.2.1

In the Load event of the form containing the UCM control, you should then feed the Service property as follows:

On Error GoTo ErrorHandler

   Ucm1.Service = "myserv>"
   Exit Sub

ErrorHandler:
    MsgBox("You have already used all available communication lines.", _
           16, "AppName")
End

If no error occurs, an unused Service of myserv1, myserv2 or myserv3 has been reserved and assigned to the Service property.

Please note, that the wildcard service feature has become obsolete by the introduction of communication spaces in Release 2.0. It is maintained for compatibility and may be dropped in a future release.

As outlined in Chapter 1, Section 1.2 About UCM, any number of Ucm.ocx controls may be placed on a form. An application server typically handles requests of multiple controls on different forms, each of which has the same Service property value but different MessageID settings. The message dispatching algorithm is as follows:

A message sent by an UCM control through OutputMsg is forwarded to

  • the server identified by the Service value. (If no such connection exists, the communication manager UCM will create the socket and thus start the remote server).
  • any local UCM control with the proper InputID setting, when both the sending and the receiving control have their Service property not set. This may result in a broadcast type message, if more than one control have the same InputID value. If no such control exists on the local system and the AutoStart section created with UcmConf(U) defines a process for the given message ID, the named process is spawned, else the message is silently ignored.

A message sent by a remote server process is forwarded to any control that has the Service property set to the value that caused UCM to initialize the socket connection, and the InputID property set to the ID of the message. Again, this may result in a broadcast type message, if more than one control meet this condition. If no such control exists on the local system and the AutoStart section created with UcmConf(U) defines a process for the given message ID, the named process is spawned, else the message is silently ignored.

See also

AdrMode, CommID, DataInput(E), Host, InputMsg, InputID, OutputMsg, OutputID, Port


Events

Chapter 7 - Event Descriptions

7.1. Overview

Events are connections between occurrences determined by an Active-X Control (OCX), such as input message arrival, and code written by the OCX user (event handlers). In essence, an event is a hook for the programmer to specify what code to execute when a particular occurrence happens. Events are not available at design time.

To learn more about the concepts of UCM communication and its addressing methods, please refer to the Active-X section in this manual.

This chapter contains descriptions of all events of the UCM Active-X control Ucm.ocx. The page headers for each description contain the property name and title.

The Synopsis section gives a summary of the actual event function declaration.

The Description explains all of the event’s operational details.

The Parameter section, describes the event handler parameters and their data type.

Related events, properties and methods are identified in the See Also section.

These events are also described in the Windows help file ucm.hlp.

The following events are in alphabetical order:

Event | Title
DataInput | Process Input Message.
Error | An Error Occurred.
FirstInput | First Input Message Event.


DataInput

Process Input Message

DataInput(E)

 | Name Environment Synopsis Description Parameters See also
Name | DataInput
Environment | Windows
Synopsis | Sub Ucm_DataInput()
Description | The DataInput event fires whenever a message matching the expected InptuID(P) has become available. Sender address information is available in the InputCommID(P), InputHost(P), InputPort(P) and the InputService(P) properties. When the event occurs due to a wildcard InputID(P), the InputMsgID(P) property may be used to determine the message ID.
Parameters | None
See also | Delimiter(P), Field(M), FirstInput, NoOfFields(P)


Error

UCM Error

Error(E)

Name Environment Synopsis Description Parameters Notes See also

Name

Error

Environment

Windows

Synopsis

Sub Ucm_Error(ErrNumber As ucmErrors, ErrText As String)

Description

The Error event is raised when the communication manager Ucm.exe(U) detects an error. All flagged errors should cause the underlying application program to terminate without further communication requests.
Error | Code | Term | Text
ucmErrInternal | 1 | X | Internal error (specific text).
ucmErrNoMem | 2 | X | Out of memory.
ucmErrCanceled | 3 |  | The operation was canceled.
ucmErrBlocking | 4 | X | The socket operation will block.
ucmErrAddress | 5 | X | General addressing error.
ucmErrBusy | 6 |  | A socket operation in progress.
ucmErrSize | 7 |  | The message is too large to fit into the buffer and is discarded.
ucmErrPort | 8 |  | The specified port is not supported.
ucmErrInUse | 9 |  | Address in use.
ucmErrUnavailable | 10 |  | Address not available from the local machine.
ucmErrNet | 11 | X | Network subsystem failed.
ucmErrNetDown | 12 | X | The network cannot be reached from this host at this time.
ucmErrNetReset | 13 | X | Connection has has been reset.
ucmErrTimeout | 14 | X | Connection is aborted due to timeout or other failure.
ucmErrConnReset | 15 | X | The connection is reset by remote side.
ucmErrNoBuf | 16 | X | No buffer space is available.
ucmConnExists | 17 | X | Socket is already connected (should not occur).
ucmNotConn | 18 | X | Socket is not connected (should not occur).
ucmErrSockDown | 19 | X | Socket has been shut down.
ucmErrReject | 20 | X | Connection is forcefully rejected.
ucmErrNotInit | 21 | X | The Windows socket layer is not initialized (should not occur).
ucmErrHost | 22 |  | Host not found.
ucmErrNoData | 23 |  | No data record.
ucmErrUnknown | 99 | X | Unknown error.
ucmErrServiceUnknown | 101 |  | Service (TCP/IP port) unknown.
ucmErrMngrShutdown | 102 | X | UCM manager shutting down.

Parameters

ErrNumber (ucmError enumeration), ErrText (String)

Notes

When multiple controls are attached to the same communication link, most of the errors will be sent to each of them. The suggested handling is to define a global error flag which is set upon the first fatal Error event. When the global error flag is set, subsequent events should then be ignored and termination routines should avoid to send further messages through the control.

See also

Active-X Introduction, Ucm.exe(U)


FirstInput

First Input Message Event

FirstInput(E)

 | Name Environment Synopsis Description Parameters See also
Name | FirstInput
Environment | Windows
Synopsis | Sub Ucm_FirstInput()
Description | The FirstInput event fires upon the first input that occurs for the UCM control. Since a control is initialized with each form load, this initial state may occur several times in the lifetime of a program.
Parameters | None
See also | DataInput


Methods

Chapter 8 - Method Descriptions

8.1. Overview

Methods are function entry points provided by an Active-X control. They typically act on the data contained in the control object. Methods may take parameters and may also return a value. Methods are not available at design time.

To learn more about the concepts of UCM communication and its addressing methods, please refer to the Active-X section in this manual.

This chapter contains descriptions of all methods of the UCM Active-X control Ucm.ocx. The page headers for each description contain the property name and title.

The Synopsis section gives a summary of the actual event function declaration.

The Description explains all of the methods operational details.

The Parameter section, describes the function parameters and their data type.

Related methods, events and properties are identified in the See Also section.

These methods are also described in the Windows help file ucm.hlp.

The following methods are in alphabetical order:

Method | Title
Field | Retrieve Message Field Value.
Send | Send Output Message.


Field

Get Message Field Data

Field(M)

 | Name Environment Synopsis Description Data Type Parameters See also
Name | Field
Environment | Windows
Synopsis | value$ = [Form.]Ucm.Field(FieldIndex as Long)
Description | The Field method returns the value of the message field indexed by the FieldIndex parameter. The base of FieldIndex depends on the setting of the FieldBase(P) property.
Data Type | String
Parameters | FieldIndex (Long)
See also | Delimiter(P), FieldBase(P), InputMsg(P)


Send

Send Message

Send(M)

 | Name Environment Synopsis Description Data Type Parameters See also
Name | Send
Environment | Windows
Synopsis | [Form.]Ucm.Send()
Description | If the AutoSend(P) property is set to False, the Send method serves to initiate output data transfer.
Data Type | Void
Parameters | None
See also | AutoSend(P), OutputID(P), OutputMsg(P)


Programming

Chapter 9 - Programming

9.1. Overview
9.2. C-Language Interface
9.3. Cobol Interface Parameters
9.4. Cobol Interface Functions

9.1. Overview

This chapter serves as reference to the software developer wanting to utilize the communication services of UCM.

Section 9.2 shows some examples on how to use the C-Language Interface.

9.2. C-Language Interface

In this section three different server models are shown:

  • Standard Server
  • Self-Contained Server
  • Inetd Server

All of these servers do the same processing, they just write back the messages received. The purpose of this section is to show how to implement and configure UCM servers, but not application dependent message processing.

To test all of these examples, a simple C or Visual Basic program can be made:

C Client

/* UCM Client / ucmtest.c */

#include "ucm.h"

main(argc, argv)

int argc;
char *argv[];
{
    int len;
    T_SOCKET sock;
    T_UCM_MSGID msgId;
    T_UCM_MSG msg;

    ucmProgName = "UcmTest";         /* for UCM error messages */
    UcmInit();
    sock = UcmConnect("128.41.1.1", "7999");
    if (sock < 0)
    {
        fprintf(stderr, "UcmConnect failed, ucmErrno=%d\n", ucmErrno);
        return 1;
    }
    UcmSendf(sock, "Test", "Hello World!");
    if ((len = UcmRecv(sock, msgId, msg, -1, UF_NOFLAGS)) > 0)
        printf("From server: ‘%s’\n", msg);
    UcmClose(sock);
    UcmTerm();
    return 0;
}

Visual Basic Client

Create a project and use the Project | Components... dialog to add the UCM Active-X Control, Ucm.ocx, located in your Windows system directory, to the new project.

On Form1 (the main form) place two label controls, two text controls, two button controls, and an UCM control. Your form should now lock like this:

UcmVbFrm1.gif (3194 bytes)

Set the properties of the new controls as follows:

Property | Value
Form1.Caption | UCM Test
Label1.Caption | Output:
Label2.Caption | Input:
Text1.Text | <blank>
Text2.Text | <blank>
Command1.Caption | &Send
Command2.Caption | E&xit
Ucm1.AdrMode | ucmTCP
Ucm1.Host | 128.41.1.1 / use correct IP address of your UCM server system
Ucm1.Port | 7999
Ucm1.InputID | Test
Ucm1.OutputID | Test

Now your form locks like:

UcmVbFrm2.gif (3076 bytes)

To finish the test program, you have to add event logic:

Command1_Click()

Ucm1.OutputMsg = Text1

Command2_Click()

Unload Me

Form1_Unload(Cancel as Integer)

Ucm1.OutputMsg = "Exit"

Ucm1_DataInput()

Text2 = Ucm1.InputMsg

As a final step, use File | Make EXE File... to create the ucmtest.exe program. You have just created an UCM client application in less than five minutes!

Configuration is easy as well. Throughout this section we use TCP/IP service ID 7999. If this number is already in use, select any number greater than 5000. It is however important, that the same ID is used on both, the server and the client systems.

Important note:

In TCP/IP programming a communication link between a server and a client is established by the use of a entity called socket, introduced by UCB University of California at Berkley, also referred to by BSD sockets. A socket is defined by the IP address of the two participating systems and a so called port number. Port numbers often have a symbolic service name assigned in a control file named services, but internally the number is used as is. Many well known port numbers (reserved services) are defined in the rage from 1 to 1023, but room should be kept for extension. By convention, user port numbers should have values > 5000 assigned. Unitec software uses port numbers in the rage 6800 to 6999, e.g. for a future version of the license manager the port 6800 has been reserved and the CSS spooler uses port 6801. To avoid conflicts with standard TCP/IP and Unitec ports, you should use numbers in the range 5001 to 6799 or >= 7000.

Your new UCM client application is now ready to run. But wait, before the test run starts, the server program has to be developed on the host.

A) Standard Server

/* Standard UCM Server */

#include "ucm.h"

static T_SOCKET sock;
static T_UCM_MSGID msgId;
static T_UCM_MSG   msg;

main(argc, argv)

int argc;
char *argv[];
{
    int len;

    if (argc < 2 || (sock = atoi(argv[1]) < 1))
    {
        fprintf(stderr, "illegal socket argument\n");
        return 1;
    }
    ucmProgName = argv[0];    /* for UCM error messages */
    UcmInit();
    if (UcmOpen(sock))
    {
        fprintf(stderr, "UcmOpen failed, ucmErrno=%d\n", ucmErrno);
        return 1;
    }
    while ((len = UcmRecv(sock, msgId, msg, -1, UF_NOFLAGS)) > 0)
    {
        /* process incoming message */
        if (strcmp(msg, "Exit") == 0)
            break;
        UcmSendf(sock, msgId, "Got: %s", msg);
    }
    UcmClose(sock);
    UcmTerm();
    return 0;
}

Compile with: cc -o test1 test1.c libucm.a

Start the new server manually with:

UcmServer -s 7999 -e test1

Now you can switch to Windows and run ucmtest.exe. Enter ‘Hello World!’ in the Input box and push the Send button. You should now see ‘Got: Hello World’ in the Output box. To stop the program, push the Exit button.

Back to Unix, use the ps(1) command and locate the UcmServer process. Use the numeric process ID (PID) to stop the server with kill(1)

kill <PID>

B) Self-Contained Server

/* Self-Contained UCM Server */

#include "ucm.h"

#if defined(__STDC__)
static int DoService(T_SOCKET sock);
#else
static int DoService();
#endif

main(argc, argv)

int argc;
char *argv[];
{
    ucmProgName = "test2";    /* for UCM error messages */
    UcmInit();
    UcmServer("7999", DoService);
    UcmTerm();
}

static int DoService(sock)

T_SOCKET sock;
{
    int len;
    T_UCM_MSGID msgId;
    T_UCM_MSG   msg;

    if (UcmOpen(sock))
    {
        fprintf(stderr, "UcmOpen failed, ucmErrno=%d\n", ucmErrno);
        return 1;
    }
    while ((len = UcmRecv(sock, msgId, msg, -1, UF_NOFLAGS)) > 0)
    {
        /* process incoming message */
        if (strcmp(msg, "Exit") == 0)
            break;
        UcmSendf(sock, msgId, "Got: %s", msg);
    }
    UcmClose(sock);
    return 0;
}

Compile with: cc -o test2 test2.c libucm.a

Start the new server manually with:

test2

Again, you can use this server with the Windows ucmtest.exe client.

To stop the server, use the ps(1) command and locate the test2 process. Use the numeric process ID (PID) to stop the server with kill(1).

C) Inetd Server

/* Inetd UCM Server */

#include "ucm.h"

static T_SOCKET sock;
static T_UCM_MSGID msgId;
static T_UCM_MSG   msg;

main(argc, argv)

int argc;
char *argv[];
{
    int len;

    sock = 0;                 /* stdin, stdout and stderr all point to the
                              ** socket descriptor we may use.
                              */
    ucmProgName = argv[0];    /* for UCM error messages */
    UcmInit();
    if (UcmOpen(sock))
        return 1;
    while ((len = UcmRecv(sock, msgId, msg, -1, UF_NOFLAGS)) > 0)
    {
        /* process incoming message */
        if (strcmp(msg, "Exit") == 0)
            break;
        UcmSendf(sock, msgId, "Got: %s", msg);
    }
    UcmClose(sock);
    UcmTerm();
    return 0;
}

Compile with: cc -o test3 test3.c libucm.a

The Internet Superserver inetd(1) requires to use symbolic service names as defined in the services file.

Edit your /etc/services file and add the same lines as on the client system:

# UCM Services
ucmtest 7999/tcp

Now edit your /etc/inetd.conf file and add the lines:

# UCM Services
ucmtest stream tcp nowait root /usr/ucm/test3

The inetd(1) process reads configuration file /etc/inetd.conf at startup to initialize itself. This will also make our ucmtest service available for connections through ucmtest.exe on the Windows client.

As shown in this section, writing UCM server- as well as client applications is very easy and provides fast development cycles.

9.3. Cobol Interface Parameters

The Unix distribution media of UCM contains a Cobol copy book and an interface library in source. These files enable programmers to implement Cobol UCM servers. Since many different Cobol flavors exist, some adaptations may be necessary. The functions have been tested to work with MF Cobol. Other environments will likely need some changes in the area of parameter passing to functions (see Calling Conventions in your Cobol documentation).

The copy book is named uci.cpy:

*-----------------------------------------------------
* Unitec Communication Manager Copy-Book
* **************************************
*
* Parameter:
*
* UCI-PAR:
* - UCI-SOCKET:   Socket-No. from 'ucmserver'
* - UCI-ERRNO:    Error-No. if return code <> 0
*
* UCI-ADDR:
* - UCI-HOST:     Host IP address or host name
* - UCI-SERVICE:  TCP/IP service name or port no.
*
* UCI-MSG:
* - UCI-IDSIZE:   Length of the message ID buffer
* - UCI-MSGSIZE:  Length of the message buffer
* - UCI-MSGLEN:   Length of the current input message
* - UCI-IDBUF:    Message-ID value
* - UCI-MSGBUF:   Message value
*
* UCI-RELEASE:
* - UCI-TIMEOUT:  UciClientVersion timeout in ms
* - UCI-VERSION:  Version number
*
*-----------------------------------------------------

 01      UCI-PAR.
     05  UCI-SOCKET     PIC 9(5) VALUE 0.
     05  UCI-ERRNO      PIC 99.
*
 01      UCI-ADDR.
     05  UCI-HOST       PIC X(32).
     05  UCI-SERVICE    PIC X(32).
*
 01      UCI-MSG.
     05  UCI-IDSIZE     PIC 9(2) VALUE 32.
     05  UCI-MSGSIZE    PIC 9(4) VALUE 2000.
     05  UCI-MSGLEN     PIC 9(4).
     05  UCI-IDBUF      PIC X(32).
     05  UCI-MSGBUF     PIC X(2000).
*
 01      UCI-RELEASE.
     05  UCI-TIMEOUT    PIC 9(5) VALUE 10000.
     05  UCI-VERSION    PIC 9(4).
*
* End 'uci.cpy'

The values of UCI-IDSIZE and UCI-MSGSIZE must correspond to the size of UCI-IDBUF and UCI-MSGBUF respectively. The maximum values are described under Configuration Limits, Chapter 10.

9.4. Cobol Interface Functions

This section contains descriptions of the UCM Cobol Interface function family UCI. Users of UCM Rel 1.x may also use the compatibility layer grouped in the UDM function family. For a description of the UDM functions, please refer to the Rel. 1.x manual. The page headers for each description contain the function name and title.

The Synopsis section gives a summary of the actual function declaration.

The Description explains all of the function's operational details.

In the Diagnostics section, common status and error codes are listed, often with possible explanation for their occurrences.

Related functions are identified in the See Also section.

An Example section is provided for each function. The example is intended to illustrate how the function is called, not necessarily how to use the function. In some cases, the example is very brief. In all cases, it should be sufficient to show how the call is made.

The following functions are in alphabetical order:

Function | Title
UciClientVersion | Get software version of UCM client.
UciClose | Close UCM Connection.
UciConnect | Open UCM connection (Client).
UciInit | Initialize Communication.
UciOpen | Open UCM connection (Server).
UciRead | Receive Client Message.
UciTerm | Terminate Communication.
UciVersion | Get UCM library software version.
UciWrite | Send Message to Client.

Return- and error codes of all UCI functions are described in ucmErrno.

Although most of the UCM clients make use of the Active-X control Ucm.ocx, the following table shows the control flow of a typical Cobol only client-server session:

Server | Client
Start server through UcmServer(U) |
 | Call UciInit Call UciConnect
Call UciInit Accept socket from command line Call UciOpen |
 | Call UciWrite [1]
Call UciRead, receive message [1] Call UciWrite [2] |
 | Call UcmiRead, receive message [2]
Repeat read/write as needed | Repeate write/read as needed
Call UciClose Call UciTerm | Call UciClose Call UciTerm


UciClose

Close UCM Connection

UciClose(L)

Name Environment Synopsis Description Examples

Name

UciClose

Environment

Unix, Win32 Cobol

Synopsis

CALL "UciClose" USING UCI-PAR.

Description

The UciClose function closes the socket UCI-SOCKET of the UCI-PAR structure, that has been initialized by UciConnect

Examples

COPY "UCI.CPY".

CALL "UciInit".
ACCEPT UCI-SOCKET FROM COMMAND-LINE.
CALL "UciOpen" USING UCI-PAR.
...
CALL "UciClose" USING UCI-PAR.
CALL "UciTerm".


UciConnect

Open UCM Connection (Client)

UciConnect(L)

Name Environment Synopsis Description Diagnostics Notes See also Examples

Name

UciConnect

Environment

Unix, Win32 Cobol

Synopsis

COPY "UCI.CPY".

CALL "UciConnect" USING UCI-PAR
UCI-ADDR.

Description

UciConnect creates a socket connection to the server process identified by the UCI-SERVICE and UCI-HOST fields of the UCI-ADDR parameter structure. The UCI-HOST argument represents the TCP/IP address or host name on which the server process providing the UCI-SERVICE is located. When using the symbolic host name, it must be defined in /etc/hosts or the Windows hosts file. The UCI-SERVICE field identifies the service that the socket will be assigned to. It may be given as symbolic TCP/IP service name or as numeric port number. When using the symbolic service name, it must be defined in /etc/services or the Windows services file with type ftp. Normally, the next UCI function used after UciConnect is UciWrite. There is no need to call UciOpen on the new socket, since UciConnect performs all nescessary initialization tasks. Upon successful execution, UciConnect stores the resulting socket number in the UCI-SOCKET field of the UCI-PAR structure. The same UCI-PAR structure should be used in all subsequent function calls that address the new socket.

The UciClose function closes the socket that has been opened by UciConnect. In order to allow correct socket housekeeping, this call is mandatory.

UciConnect will fail if one or more of the following is true:

UE_NOTINIT | The UCI interface has not been initialize by a call to UciInit (UCI-ERRNO 1).
UE_INVALID | Invalid argument (2).
UE_HOST | The value UCI-HOST does not identify a known host (6).
UE_SERVICE | The value UCI-SERVICE does not identify a known service (7).
UE_BADSOCK | The operating system returned a bad status while creating a new socket (3).
UE_CONNECT | The given UCI-HOST does not provide the requested UCI-SERVICE (8).
UE_NOMEM | The new socket could not be entered into the internal database, due to low memory (99).
UE_NOMSG | The initialization handshaking with the server failed (5).
UE_ULMEXP | The UCM license has expired. This error may occur in demo versions only (21).
UE_ULMBUSY | Too many users. The UCM license does not allow additional users at this time. Please consult Unitec for details on how to increase your license (22).

Diagnostics

Upon successful completion UciConnect returns ZERO. Otherwise, the value of the global ucmErrno is returned and the field UCI-ERRNO in the UCI-PAR structure is set to indicate the error. In most Cobol implementations the return code of C functions may be accessed through a predefined variable named RETURN-CODE.

Notes

As described under UciOpen, a program may use the system(3) function (CreateProcess on Win32 platforms) to spawn another task that itself uses the same socket number. Each of these tasks should use their own UciInit, UciOpen, UciClose and UciTerm sequence.

It is possible for a client process, to maintain connections to several different servers at any time. Each of these connections shoult then be identified by an unique UCI-PAR structure, which must be passed to the send, receive and close functions of the socket in question.

See also

UciInit, UciOpen, UciTerm

Examples

COPY "UCI.CPY".

CALL "UciInit".
MOVE "unitec.ch" TO UCI-HOST.
MOVE "6000" TO UCI-SERVICE.
CALL "UciConnect" USING UCI-PAR
                         UCI-ADDR.
...
CALL "UciClose" USING UCI-PAR.
CALL "UciTerm".


UciInit

Initialize UCM Communication

UciInit(L)

Name Environment Synopsis Description Diagnostics See also Examples

Name

UciInit

Environment

Unix, Win32 Cobol

Synopsis

COPY "UCI.CPY".

CALL "UciInit".

Description

UciInit initializes the client-server processing and should be called before any other function of the UCI family.

Diagnostics

UciInit always returns ZERO.

See also

UciTerm

Examples

COPY "UCI.CPY".

CALL "UciInit".
ACCEPT UCI-SOCKET FROM COMMAND-LINE.
CALL "UciOpen" USING UCI-PAR.
CALL "UciRead" USING UCI-PAR
                     UCI-MSG.
...
CALL "UciClose" USING UCI-PAR.
CALL "UciTerm".


UciOpen

Open UCM Connection (Server)

UciOpen(L)

Name Environment Synopsis Description Diagnostics Notes See also Examples

Name

UciOpen

Environment

Unix, Win32 Cobol

Synopsis

COPY "UCI.CPY".

ACCEPT UCI-SOCKET FROM COMMAND-LINE.
CALL "UciOpen" USING UCI-PAR.

Description

UciOpen initializes the socket identified by the number stored in the UCI-SOCKET field of the UCI-PAR structure. By using the generic server utility UcmServer(U), this number is available as command argument and may be received from COMMAND-LINE. The next UCI function call after UciOpen should be UciRead.

UciOpen will fail if one or more of the following is true:

UE_NOTINIT | The UCI interface has not been initialize by a call to UciInit (UCI-ERRNO 1).
UE_INVALID | The value of UCI-SOCKET is not a valid socket descriptor (2).
UE_NOMEM | The new socket could not be entered into the internal database, due to low memory (99).
UE_ULMREG | The product UCM is not registered in the license database. Enter your activation key in the ulm(I) utility (20).
UE_ULMEXP | The UCM license has expired. This error may occur in demo versions only (21).
UE_ULMBUSY | Too many users. The UCM license does not allow additional users at this time. Please consult Unitec for details on how to increase your license (22).

Diagnostics

Upon successful completion UciOpen returns ZERO. Otherwise, the value of the global ucmErrno is returned and the field UCI-ERRNO in the UCI-PAR structure is set to indicate the error. In most Cobol implementations the return code of C functions may be accessed through a predefined variable named RETURN-CODE.

Notes

The socket number to be passed to UciOpen is received on the command line from the UcmServer(U) utility. This number may be passed to other Cobol programs using the same mechanism through the system(3) library function (CreateProcess on Win32 platforms). To maintain correct socket housekeeping, it is important, that each of these task do their own UciInit, UciOpen, UciClose and UciTerm call sequence.

See also

UciInit, UciClose, UciTerm

Examples

COPY "UCI.CPY".

ACCEPT UCI-SOCKET FROM COMMAND-LINE.
CALL "UciInit".
CALL "UciOpen" USING UCI-PAR.
CALL "UciRead" USING UCI-PAR
                     UCI-MSG.
...
CALL "UciClose" USING UCI-PAR.
CALL "UciTerm".


UciRead

Receive Client Data

UciRead(L)

Name Environment Synopsis Description Diagnostics See also Examples

Name

UciRead

Environment

Unix, Win32 Cobol

Synopsis

COPY "UCI.CPY".

CALL "UciRead" USING UCI-PAR
UCI-MSG.

Description

The UciRead function reads the next client message from the socket UCI-SOCKET in UCI-PAR, initialized through UciConnect . The maximum size of the message ID and the message data are stored in the fields UCI-IDSIZE and UCI-MSGSIZE respectively. If the buffers provided are too small to hold the full ID or message data, the values received will be truncated. The truncated parts of the message are lost and no indication of the truncation is given to the calling process.

UciRead will fail if one or more of the following is true:

UE_NOTINIT | The UCI interface has not been initialize by a call to UciInit (UCI-ERRNO 1).
UE_INVALID | The value of UCI-IDSIZE or/and UCI-MSGSIZE is invalid (2).
UE_BADSOCK | The socket has not been initialized by a call to UciConnect or UciOpen (3).
UE_CONNECT | The socket identifier UCI-SOCKET has been removed, i.e. the connection has been terminated by the client (8).
UE_NOMSG | No message was available when the read was cancelled, e.g. by a signal (5).

Diagnostics

Upon successful completion UciRead returns ZERO. Otherwise, the value of the global ucmErrno is returned and the field UCI-ERRNO in the UCI-PAR structure is set to indicate the error. In most Cobol implementations the return code of C functions may be accessed through a predefined variable named RETURN-CODE.

See also

UciConnect, UciOpen

Examples

COPY "UCI.CPY".

ACCEPT UCI-SOCKET FROM COMMAND-LINE.
CALL "UciInit".
CALL "UciOpen" USING UCI-PAR.
CALL "UciRead" USING UCI-PAR
                     UCI-MSG.
...


UciTerm

Terminate UCM Communication

UciTerm(L)

Name Environment Synopsis Description Diagnostics See also Examples

Name

UciTerm

Environment

Unix, Win32 Cobol

Synopsis

CALL "UciTerm".

Description

The UciTerm function terminates UCM processing.

UciTerm will fail if one or more of the following is true:

UE_NOTINIT The UCI interface has not been initialize by a call to UciInit (UCI-ERRNO 1).

Diagnostics

Upon successful completion UciTerm returns ZERO. Otherwise, the value of the global ucmErrno is returned and the field UCI-ERRNO in the UCI-PAR structure is set to indicate the error. In most Cobol implementations the return code of C functions may be accessed through a predefined variable named RETURN-CODE.

See also

UciClose, UciInit

Examples

COPY "UCI.CPY".

CALL "UciInit".
ACCEPT UCI-SOCKET FROM COMMAND-LINE.
CALL "UciOpen" USING UCI-PAR.
...
CALL "UciClose" USING UCI-PAR.
CALL "UciTerm".


UciVersion

Get UCM Version

UciVersion(L)

Name Environment Synopsis Description Diagnostics Notes See also Examples

Name

UciClientVersion, UciVersion

Environment

Unix, Win32 Cobol

Synopsis

COPY "UCI.CPY".

CALL "UciVersion" USING UCI-PAR
UCI-RELEASE.

CALL "UciClientVersion" USING UCI-PAR
UCI-RELEASE.

Description

UciVersion retrieves the current version number of the UCM library used to link the program into the UCI-VERSION field of the UCI-RELEASE structure. The value contains the sum of the major release number multiplied by 100 and the minor release number, i.e. release 2.03 will be returned as 203.

UciClientVersion retrieves the current version number of the UCM Active-X control or the UciConnect library function used to establish the socket UCI-SOCKET in UCI-PAR with the caller. Starting with release 2.03 the client logic of UCM sends an internal version information message immediately after establishing a socket connection and before transmission of any application data. If this internal message is not received within UCI-TIMEOUT milliseconds or any application data is received without prior internal version information, a value of 0 (zero) will be returned in the UCI-VERSION field of the UCI-RELEASE structure, indicating an unknown version. It is usually safe to use a large value (e.g. 20'000) as UCI-TIMEOUT argument.

It is best to assume UCM 1.0 (formerly named UDM) if the UciClientVersion function returns zero in UCI-VERSION.

Both version functions may be used prior a call to UciInit.

UciClientVersion will fail and no version information will be returned if one or more of the following is true:

UE_CONNECT The socket identifier UCI-SOCKET has been removed, i.e. the connection has been terminated by the client (UCI-ERRNO 8).

Diagnostics

Upon successful completion UciVersion and UciClientVersion both return ZERO. Otherwise, the value of the global ucmErrno is returned and the field UCI-ERRNO in the UCI-PAR structure is set to indicate the error. In most Cobol implementations the return code of C functions may be accessed through a predefined variable named RETURN-CODE.

Notes

The version functions have been introduced in release 2.03. The use of the UciClientVersion function with socket arguments created by older UCM clients will return a version value of zero, indicating an unknown version.

See also

UciConnect

Examples

COPY "UCI.CPY".

ACCEPT UCI-SOCKET FROM COMMAND-LINE.
CALL "UciClientVersion" USING UCI-PAR
                              UCI-RELEASE.
IF UCI-VERSION < 200
    PERFORM UDM-COMPATIBLE-COMM
ELSE
    PERFORM UCI-COMM.
...


UciWrite

Send Message to Client

UciWrite(L)

Name Environment Synopsis Description Diagnostics See also Examples

Name

UciWrite

Environment

Unix, Win32 Cobol

Synopsis

COPY "UCI.CPY".

CALL "UciWrite" USING UCI-PAR
UCI-MSG.

Description

UciWrite sends the content of the UCI-MSG message structure to the client process identified by UCI-SOCKET in UCI-PAR. The fields UCI-MSGBUF and UCI-MSGLEN of the UCI-MSG structure should hold the data and the length of the message to send. Typically each client request received through UciRead causes the server to send one or more response messages.

UciWrite will fail if one or more of the following is true:

UE_NOTINIT | The UCI interface has not been initialize by a call to UciInit (UCI-ERRNO 1).
UE_BADSOCK | The socket has not been initialized by a call to UciConnect or UciOpen or the socket is not open (UCM-ERRNO 3).
UE_INTR | The send process has been interrupted by a signal (9).
UE_CONNECT | The socket has been closed (8).

Diagnostics

Upon successful completion UciWrite returns ZERO. Otherwise, the value of the global ucmErrno is returned and the field UCI-ERRNO in the UCI-PAR structure is set to indicate the error. In most Cobol implementations the return code of C functions may be accessed through a predefined variable named RETURN-CODE.

See also

UciInit, UciRead

Examples

COPY "UCI.CPY".

ACCEPT UCI-SOCKET FROM COMMAND-LINE.
CALL "UciInit".
CALL "UciOpen" USING UCI-PAR.
CALL "UciRead" USING UCI-PAR
                     UCI-MSG.
MOVE "Answer 1" TO UCI-MSGBUF.
MOVE 8 TO UCI-MSGLEN.
CALL "UciWrite" USING UCI-PAR
                      UCI-MSG.
MOVE "Answer 2" TO UCI-MSGBUF.
CALL "UciWrite" USING UCI-PAR
                      UCI-MSG.
...
MOVE "Alarm" TO UCI-MSGID.
MOVE "You have new mail" TO UCI-MSGBUF.
MOVE 13 TO UCI-MSGLEN.
CALL "UciWrite" USING UCI-PAR
                      UCI-MSG.
...


Configuration

Chapter 10 - Configuration

10.1. Overview
10.2. System Requirements
10.3. Configuration Limits

10.1. Overview

This chapter describes the configuration of the UCM and ULM operational environment:

  • Windows system wide parameters are set in the file \windows\ucm.ini.
  • License manager parameters are set in the file /etc/ulm.default.
  • License information is stored in the file ulm.dat located in the ULM base directory ULM_BASE_DIR.
10.2. System Requirements

a) Unix

  • BSD (Berkeley) Sockets.

b) Windows

  • Windows 95 or higher.
  • Windows NT 3.51 or higher.
  • winsock.dll 1.1 or higher (normally included in TCP/IP software products).
10.3. Configuration Limits

Configuration Limits

  • Maximum message id: 64 characters.
  • Maximum message: 4096 characters.


ulm.default

ULM Environment

ulm.default(C)
Name Description Notes See also

Name

/etc/ulm.default

Description

Ulm.default contains the definitions of system-wide ULM license manager parameters. Each command searches for this file whenever it is invoked. The file contains one or more entries that define the default information. Each entry has the form:

NAME=Value

where keyword identifies the type of information available and value defines its value. Both keyword and value must consist of letters, digits and punctuation. The exact spelling of a keyword and the appropriate value are described in the following table. In contrast to parameter values, parameter names (keywords) are case insensitive.

Any line beginning with a number sign (#) is considered a comment and is ignored.

Keyword | Description | Default
ULM_VERSION | Installed license manager version. This entry is generated by the setup(I) process and should never be changed. |
ULM_BASE_DIR | Base directory that holds ULM programs, configuration tables and data. | /usr/lib/ulm

Notes

If /etc/ulm.default is missing, ULM will run with the default configuration.
Important!

If the directory entriy ULM_BASE_DIR does not correspond to the current configuration, ULM will not be able to run correctly.

See also

setup(I), ulm(I)


Standards

Chapter 11 - Unitec Coding Standards

11.1. Overview
11.2. Symbol Naming
11.3. Comments
11.4. Indentation

11.1. Overview

This chapter describes the Unitec standards for all code written for internal, as well as external distribution. The purpose of these standards is to improve the readability, organization and maintenance of source code and header files.

Standards do not develop in one day. Ideas evolve and many years of experience (and some failures) lead to the inspirations of how things can be done best. As in every society, each group working on the same project has to follow some rules. These rules are not intended to impose one person's style to the universe nor to confine creativity. Their sole purpose is to set a common base for understanding and communication. Creativity is not achieved through personal indentation styles, but by finding the best solutions and most efficient algorithms for the problems to solve. Good programming cannot be taught by preaching generalities, the way to improve programming style is by the application of few principles of good practice and a little common sense. Shortcomings show only that we are all human, and that under the pressure of a large, intellectually demanding task like writing a program, it is much too easy to do some things imperfectly. In the following sections you will find our bashful attempt to achieve perfect programming.

11.2. Symbol Naming

Many major companies (including Microsoft - they can't be wrong) use a naming convention called the 'Hungarian Prefix Notation' (e.g. szName is a zero terminated string containing a name). This standard is especially aimed at reducing type conflicts. Since modern compilers do a good job in detecting such conflicts the method has lost its strongest argument. The major drawback is the promotion of two or three character abbreviations for meaningful things. The terminology is most often known only to the small group of developers involved in the project. The possible problems for the maintenance teams are obvious. For these reasons, Unitec has chosen a more descriptive method.

Functions

Functions should be self explanatory and should be in name-case format (i.e., first letter per word upper-case lettering, all remaining characters in lower-case lettering) with no underscores used to separate words. In addition, the function name should describe the operation that is performed by the function.

Some example function names are shown below:

int LogOpen(char *fileName);
extern void ProgTerm(int rc);
extern int AddFunction(void (*func)());

Since the C language does not provide a method of hiding global symbols that are of importance in a restricted set of functions only (i.e. functions used by different modules of a library, but hidden from the application program using the library), the following convention is used:

- Global symbols of tools and libraries have an underscore added to their name, as in LogCntl_.

- Application programs avoid the use of the underscore in symbol names.

Variables

Variable names should be self-explanatory and should be in lower-case lettering for the first word, then name-case for each word thereafter:

int pageCount;
char *cmdLine;
static int firstTime = 1;

For restricted global symbols, the same conventions are used as described under the Functions section.

Constants, pseudo functions, types, tags

Constants (defines), pseudo functions (preprocessor macros), types (typedef) and tags (structure and union tag-names) should be self-explanatory and should be in upper-case lettering, with an underscore separating the words. To avoid side-effects, arguments to pseudo functions should not include assignment, increment and decrement expressions.

Some example constant names are shown below:

#define MAX_BUF    1024
#define MIN(a, b)  (((a) < (b)) ? (a) : (b))
typedef char BOOL;
struct ADDRESS
{
    char street[30];
    char town[30];
};

11.3. Comments

Judicious use of comments and consistent indentation can ease the task of reading and understanding a program. Comments can however be misused in ways that seriously affect the readability of program code. The compilers do not understand the contents of comments, so there is no way of ensuring that a comment is meaningful, describes the program accurately and is up to date. Many programs contain comments that are incomprehensible, ambiguous or just plain wrong. Bad comments can be worse than no comments. If something can be stated in the language itself, it should be, and not just mentioned in a comment. This statement is aimed at comments such as

"count" must be initialized
"flag" may not be used outside of function "Init()"
call function "Init()" first
function "Func()" takes two arguments

The most accurate information of what has to be done, is the statement itself. Once something has been stated clearly in the language, it should not be mentioned a second time in a comment:

sum = a + b;   /* sum becomes a + b */
count++;       /* increment the counter */

Such comments are worse than simply redundant, they increase the amount of text the reader has to look at and often obscure the structure of the program. A well chosen and well-written set of comments is an essential part of a good program.

Source files

Each source file (.c or .h) should contain a comment-header that contains the library or program name, the name of the file and copyright information. The copyright year should include the original year when the product was created and all subsequent years when major revisions were made.

/* Help.c:    CLib / Print help message and exit
**
** Syntax:    void Help(helpText);
**            char *helpText[];
**
** Author:    Unitec Informatik
**            Thomas Madörin
**            Leerüti 797
**            CH-8625 Gossau, Switzerland
**
** Copyright (c) 1998 by Unitec Informatik
*/

Functions

Each routine may be preceded by a short description giving the routine's purpose and any related algorithms. If the routine name intuitively describes the routine, no comment is needed.

Variables

Function arguments and local variables should only have descriptive comments if their names are not descriptive. These comments should be lined up on a right region.

Blocks

Block comments are used to describe a group of related code. Most block comments should be one line, if possible, and reside immediately above the block being commented. If more than a one line comment is needed, the extra lines should each begin with the double asterisk '**'. Block comments should be indented to match the indentation level of the line of code following it. A single blank line should precede the comment and the block of code should follow immediately after. Small blocks of code that do a specific job should be commented but not individual lines (unless the line is complex or not intuitive).

11.4. Indentation

There are several different consistent styles of indentation used. No fundamental reasons exist, to prefer one over another. Unitec has chosen the so called 'Allman' style because we think it best emphasizes the structure of the underlying code. The indention unit used is 4 characters.

Unions and structures

Unions and structures should have all members listed on individual lines and should be indented on unit from the left margin.

typedef union
{
    int logLevel;
    long fileSize;
    LOG_HDR *logHdr;
}   LOG_CNTL;

Functions

The main body of routines should have braces below the function declaration. All function code should be indented one unit.

void Help(helpText)

char *helpText[];
{
    ...
}

Function calls

Parameters in a function call should be listed with each argument followed by a comma and one space. If a routine call cannot fit on one line on the screen, it should be broken with the next half of the call and indented one ore more unites farther over. It should be split after a comma or logic symbol if possible.

Case statements

The reserved word case should be indented one unit from the switch statement, and all code information should be indented an additional unit. The colon should immediately follow each case and the statement(s) should start on a new line. The break should also be on a separate line. If the switch statement appears in a deep indentation level the word case and the statements may be indented by half a unit each. Additional levels of logic should be indented one unit.

switch (opt)
{
    case 'a':
        aOpt = TRUE;
        break;

    case 'b':
        bOpt = TRUE;
        break:

    default:
        Error("illegal option %c", opt);
}

If, for and while statements

Statements following an if, for or while should be indented one unit, and simple conditionals should use the inline ? operator.

if (aOpt == TRUE)
{
    printf("a-option set\n");
    return 1;
}

The braces enclosing the block should be aligned with the if, for or while keywords. If no statements exist for the for or while loop, the semicolon should be placed on the next line.

while (*dest++ = *src++)
    ;