Binder10 03

Instruction FAST/TOOLS FAST/TOOLS
Manual Installation Manual Linux

and Unix
IM50C03C01-01EN/R10.03
YOKOGAWA YOKOGAWA ELECTRIC CORPORATION

9-32 Nakacho 2-chome,
Musashino-shi, Tokyo 180-8750, Japan
IM50C03C01-01EN/R10.03
©Copyright July 2017
Tel: +81-422-52-5616
Email:GSC_Sales@ml.jp.yokogawa.com
© Yokogawa Electric Corporation
YOKOGAWA
The information in this document is subject to change without notice and should not
be construed as a commitment by Yokogawa.
Yokogawa assumes no responsibility for any errors that may appear in this
document.
The software described in this document is furnished under license and may only be
used or copied in accordance with the terms of such license.
ii
Table of Contents
Table of Contents
1 Preface ...................................................................................1-1
1.1 Introduction ...............................................................1-1
1.2 Prerequisites ...............................................................1-1
1.3 Supported Unix/Linux platforms ...............................1-1
1.4 Structure of this document .........................................1-1
1.5 Conventions and abbreviations ..................................1-2
2 FAST/TOOLS basic concepts ..............................................2-1
2.1 Introduction ...............................................................2-1
2.2 FAST/TOOLS configurations ...................................2-1
2.3 The FAST/TOOLS package ......................................2-2
2.4 FAST/TOOLS for Linux and Unix ...........................2-3
2.4.1 Supported configurations .......................................... 2-3
2.4.2 Supported Unix versions ........................................... 2-4
2.5 Required Disk Space .................................................2-4
2.5.1 Item definition file .................................................... 2-4
2.5.2 Item history files ....................................................... 2-4
2.5.3 Alarms history ........................................................... 2-5
2.5.4 Classes and object ..................................................... 2-5
2.5.5 Reports ...................................................................... 2-6
2.6 Required System Memory .........................................2-6
2.7 The installation procedure .........................................2-6
2.7.1 Read the Release Notes document ............................ 2-6
2.7.2 FAST/TOOLS installation ........................................ 2-6
2.7.3 Requesting a FAST/TOOLS licence ......................... 2-7
2.7.4 Validating FAST/TOOLS ......................................... 2-7
2.7.5 Setting up you HMI connection ................................ 2-7
2.8 Where to get your FAST/TOOLS licence .................2-7
3 FAST/TOOLS installation ...................................................3-1
3.1 Introduction ...............................................................3-1
3.2 Preparing your system ...............................................3-1
3.2.1 Create a FAST/TOOLS directory (optional) ............ 3-1
3.2.2 Create a FAST/TOOLS user and group (optional) ... 3-1
3.3 Installing FAST/TOOLS ...........................................3-2
3.4 Requesting a licence ..................................................3-4
3.5 Validating FAST/TOOLS ..........................................3-4
4 Setting up a HMI connection ...............................................4-1
4.1 Prerequisites ...............................................................4-1
4.1.1 Firewall configuration ............................................... 4-1
4.2 Server configuration ..................................................4-4
FAST/TOOLS Installation Manual Linux and Unix iii

Table of Contents
4.3 HMI configuration .................................................... 4-4

5 Using FAST/TOOLS ........................................................... 5-1
5.1 Introduction ............................................................... 5-1
5.2 Starting and stopping FAST/TOOLS ........................ 5-1
5.3 Manually starting and stopping ................................. 5-1
5.4 Running FAST/TOOLS as a service ......................... 5-1
5.4.1 RedHat Enterprise Linux .......................................... 5-2
5.4.2 Sun Solaris ................................................................ 5-4
5.4.3 IBM AIX ................................................................... 5-4
5.5 Clearing FAST/TOOLS Runtime Data ..................... 5-4
5.6 Removing FAST/TOOLS ......................................... 5-5
5.6.1 RedHat Enterprise Linux .......................................... 5-5
5.6.2 Sun Solaris ................................................................ 5-6
5.6.3 IBM AIX ................................................................... 5-6
Appendix A:Distributed systems .................................................. A-1
A.1 Introduction .............................................................. A-1
A.2 HMI, Host, Front-end components .......................... A-1
A.3 Interconnecting components .................................... A-2
A.4 Distribution of data sets ........................................... A-3
A.5 Item copy processes ................................................. A-4
A.6 Distributed ALARM/FAST ..................................... A-4
A.7 Distributed Item Interface (GIN DII) ....................... A-5
A.8 Stepwise configuration actions ................................ A-5
iv FAST/TOOLS Installation Manual Linux and Unix

Introduction Preface
1 Preface
1.1 Introduction
This manual describes the procedure for installing FAST/TOOLS on
any of the supported Unix and Linux platforms. It will provide
step-by-step instructions on how to setup, install and licence your
FAST/TOOLS system.
1.2 Prerequisites
It is assumed that you have some basic Unix/Linux system
administration knowledge. You should have a basic understanding of
Unix/Linux file ownership, user accounts, and user groups.
If you are installing FAST/TOOLS on Linux it is assumed that you are
using Redhat Enterprise Linux 6, which is the officially supported Linux
distribution for the current FAST/TOOLS release. If you are using
another Linux distribution, you might need a more detailed knowledge
on how to configure your system.
1.3 Supported Unix/Linux platforms

In FAST/TOOLS release R10.03 the following Unix/Linux platforms
are supported:
• Redhat Enterprise Linux 7(RHEL 7)
1.4 Structure of this document

The FAST/TOOLS Installation Manual can be divided into a number of
chapters/appendices.
• Chapter 1, Preface, Introduction and Conventions.
• Chapter 2, FAST/TOOLS basic concepts, explains the basic
concepts behind the available FAST/TOOLS configurations and
licensing options. This will help you to choose the right
configuration and license for your situation.
• Chapter 3, FAST/TOOLS installation, a step by step guide on how
to install and license FAST/TOOLS.
FAST/TOOLS Installation Manual Linux and Unix 1-1

Preface Conventions and abbreviations
• Chapter 4, Setting up a HMI connection, explains how to setup a

HMI (Human Machine Interface) between your Unix/Linux system
and a FAST/TOOLS HMI station running on Microsoft Windows.
• Chapter 5, Using FAST/TOOLS, very brief introduction on how to
start FAST/TOOLS and how FAST/TOOLS can be setup to run as
a service.
• In Appendix A, a description is given of the configuration of a
distributed FAST/TOOLS system.
1.5 Conventions and abbreviations

The following conventions may be used in this manual:
CONVENTION MEANING
[] Indicates that the enclosed item is the default.
UPPERCASE Indicate reserved words and predefined names,
letters e.g. NULL, TRUE, DUR_NOWAIT.
(I) Indicates that the specified parameter is input.
(O) Indicates that the specified parameter is output.
"" Used in format descriptions. Double quotes indi-
cate that the character is to be taken literally.
<name> Used in format descriptions. <name> indicates a
variable.
file_name This type-setting is used to indicate file names.
output This type-setting is used to indicate output on a
terminal.
input This type-setting is used to indicate input from
the user.
n.u. not used.
1-2 FAST/TOOLS Installation Manual Linux and Unix

Introduction FAST/TOOLS basic concepts
2 FAST/TOOLS basic concepts
2.1 Introduction
This chapter introduces some basic FAST/TOOLS concepts you need to
be aware of when setting up your FAST/TOOLS system.
2.2 FAST/TOOLS configurations

A FAST/TOOLS configuration can consist of one single FAST/TOOLS
system or of a number of FAST/TOOLS systems connected to a central
server. A configuration with one FAST/TOOLS system is called a
stand-alone system. A configuration with more than one FAST/TOOLS
systems is called a distributed system.
The individual FAST/TOOLS systems in a distributed configuration are
called the nodes of that system. Each FAST/TOOLS node is given a
unique node-name and node-number when FAST/TOOLS is licensed.
The nodes in a distributed FAST/TOOLS configuration can be assigned
different tasks. There are three types of FAST/TOOLS nodes, they are
called Server, Front-end and HMI.
- Server
The server is the central system within a distributed
configuration. It contains the configuration and historical
databases.
- Front-end node
A Front-end node takes care of data gathering from attached
equipment (PLC, RTU). In addition some local control is
possible.
- HMI node
A HMI node (Human Machine Interface) is used for system
configuration and he process visualization.
Note: The HMI-node in a FAST/TOOLS configuration is only

available on the Microsoft Windows version of FAST/TOOLS. This
means that a stand-alone Unix configuration consists of a Unix server
and one Microsoft Windows HMI node for system configuration and
process visualization.

FAST/TOOLS basic concepts The FAST/TOOLS package
In a distributed configuration all the HMI nodes must be Microsoft

Windows systems. The Server and Front-end nodes can be Unix/Linux
based.
2.3 The FAST/TOOLS package

The FAST/TOOLS software package is divided in a number of
functional components called TOOLS. Each tool provides a part of the
total FAST/TOOLS functionality.
The following table gives a short overview of the different tools and
their function within the FAST/TOOLS package.
Table 1: The FAST/TOOLS collection
Tool name Description
BUS/FAST Basic support and communications

DATABASE/ FAST ISAM based file support
Distributed data set services
HISTORY/FAST History scheduler
AUDIT/FAST Audit trailing
ITEM/FAST Real time item data handling
EQUIPMENT/ FAST Equipment drivers
ALARM/FAST Alarm handling
PROCESS/ FAST Sequences, processing and calculations
REPORT/FAST Reporting
ACCESS/FAST Open DataBase Connectivity (ODBC) interface
USER/FAST FAST/TOOLS User Interface (only available on the
Microsoft Windows) version of FAST/TOOLS
INTEGRATION Miscellaneous FAST/TOOLS functionality and
placeholder for user applications.
The difference between the three FAST/TOOLS node types (server,

Front-end and HMI) lies in the combination of tools that are installed on
each of these node types.

FAST/TOOLS for Linux and Unix FAST/TOOLS basic concepts
The following table lists the tools and in which component they are
found:
Table 2: Tools in relation to the node type
Node type
Tool name
Server Front-end HMI SDK
BUS/FAST * * * *
DATABASE/FAST * * * *
HISTORY/FAST * *
AUDIT/FAST * *
ITEM/FAST * * *
EQUIPMENT/FAST * * *
ALARM/FAST * * *
PROCESS/FAST * * *
REPORT/FAST * *
ACCESS/FAST * *
USER/FAST * * *
INTEGRATION * * *
The installation of FAST/TOOLS is based upon node types. For

example: When you install the server node you will get the tools as listed
in the ‘Server’ column in the previous table. Whether or not a certain
tool will be activated is depending on whether or not the tool is licensed.
2.4 FAST/TOOLS for Linux and Unix

This section gives some specific information you need when installing
FAST/TOOLS for Linux/Unix.
2.4.1 Supported configurations
As explained in section 2.2, the FAST/TOOLS HMI node type is only

available on the Microsoft Windows platform. Because FAST/TOOLS
requires the HMI for system configuration each FAST/TOOLS system
will need to include at least one Microsoft Windows as HMI node. Unix

FAST/TOOLS basic concepts Required Disk Space
based FAST/TOOLS systems can be used as Server or as Front-end

node.
2.4.2 Supported Unix versions
The supported Unix versions for FAST/TOOLS are listed in section 1.3
of this manual. It is assumed that you are using one of these Unix/Linux
versions.
If you need to install FAST/TOOLS on Linux distribution other than
Redhat Enterprise Linux, you may require some distribution specific
knowledge.
2.5 Required Disk Space

To installing the FAST/TOOLS software you will require about 200
Mbytes of disk space.
While running FAST/TOOLS, additional disk space is required to store
configuration and historical data:
2.5.1 Item definition file
The item definition requires 1800 bytes for each item defined (Server
component only).
Add 350 bytes per item for each system where the Front-end component
is installed.
2.5.2 Item history files
The size of an item history file depends on the type of storage you
choose. This paragraph gives an overview of the commonly uses storage
types. These values should be seen as a rule of thumb. All file size
aspects like key file overhead and bucket slack size are counted in the
sample size values.
Disk compression is not counted.
• Event based collection/event based storage
This storage type is used when you define a storage group of type
Event/Event in the HMI. On average you can expect each sample

Required Disk Space FAST/TOOLS basic concepts
to take 100 bytes of disk space.
• Scan based collection/Time based storage

Scan/Time in the HMI. This storage group has the optional
compression and can be configured to store the items quality code
as well as the value and status. Depending on the choices you make
the following table gives the average disk space each item sample
will take:
Table 3: Disk space required for Scan/Time sample
Use compression Store quality code Bytes used per sample
No No 14
Yes No 10
No Yes 18
Yes Yes 14
• Event based collection/Item based storage

Event/Item in the HMI. This storage type is intended to be used for
frequently changing analog values which are time stamped in the
field. Its efficiency increases with the number of samples per file
rollover. Frequently changing analogs with more than 100 events
per file rollover will use on average 30 bytes per sample. Slow
changing signals (less then 10 events per file rollover) will use on
average 100 bytes of disk space per sample.
2.5.3 Alarms history
ALARM/FAST can store events for a period of time. One event costs on
average 550 byte disk space. The number of events and the life time is
completely user-dependent and/or process-dependent.
2.5.4 Classes and object
Each class defined and compiled, typically costs 18 Kbytes of disk space
typical. Each object consumes 2 Kbytes in average.

FAST/TOOLS basic concepts Required System Memory
2.5.5 Reports
Each defined report takes about 2 Kbytes. The size of a generated report
is undefined because of the nature of a report definition.
2.6 Required System Memory

The following system memory sizes are advised:
Table 4: Advised memory sizes
Advised
Software memory size
(Mbytes)
Small stand alone system with Server or Front-end compo- 512

nent (up to 2000 items)
FAST/TOOLS Server system 2048
Large FAST/TOOLS server system (100.000 items or more) 4096
Note that additional non FAST/TOOLS applications may require

additional memory.
2.7 The installation procedure

This section gives you overview of the FAST/TOOLS installation
procedure. Later in this manual the steps are explained in detail.
2.7.1 Read the Release Notes document
Before you start the installation procedure you should read the Release
Notes document, available on the FAST/TOOLS distribution DVD. It
may contain valuable information and tips.
2.7.2 FAST/TOOLS installation
During the installation, the FAST/TOOLS software package is

transferred to your system. For this step you require the system root
password.

Where to get your FAST/TOOLS licence FAST/TOOLS basic concepts
2.7.3 Requesting a FAST/TOOLS licence
Next you need to request a FAST/TOOLS licence from Yokogawa. The

licence file you will receive is linked to the FAST/TOOLS node name
and number. Requesting a licence can be done using the Licence
Request Wizard that is part of the FAST/TOOLS distribution. You can
use the ‘jtoolslicreq’ License Request tool from Linux to request a
license, or if you are requesting multiple licenses for different machines,
use the Licence Request Wizard from a Microsoft Windows system.
You are able to run FAST/TOOLS without a licence for one hour for
evaluation purposes.
2.7.4 Validating FAST/TOOLS
Once you have received your licence file you can validate your
FAST/TOOLS system and it will be assigned its node number and node
name. Run the ‘jtoolslic’ License Validation wizard on Linux, or
ft_validate on Unix flavours to validate the license file you received.
2.7.5 Setting up you HMI connection
Next you need to setup the connection to your HMI station.

FAST/TOOLS for Unix/Linux requires at least one HMI station for
system configuration.
2.8 Where to get your FAST/TOOLS licence

FAST/TOOLS licences can be obtained by sending a licence request to
the following address:
YOKOGAWA ELECTRIC CORPORATION

9-32 Nakacho 2-chome, Musashino-shi,
Tokyo 180-8750, Japan
Telephone: +81-422-52-5616
email: GSC_Sales@ml.jp.yokogawa.com

FAST/TOOLS basic concepts Where to get your FAST/TOOLS licence

Introduction FAST/TOOLS installation
3 FAST/TOOLS installation
3.1 Introduction
This chapter gives a step by step explanation on how to install
FAST/TOOLS on your Unix/Linux system.
3.2 Preparing your system

Before you start installing FAST/TOOLS, you need to prepare your
FAST/TOOLS system.
3.2.1 Create a FAST/TOOLS directory (optional)

The FAST/TOOLS installer program suggests installing FAST/TOOLS
into the directory /opt. On Unix systems, this is the directory intended
for application software. Furthermore it is recommended to create a
separate file system for FAST/TOOLS and to mount this under /opt,
especially if the disk space available in this partition is limited. The
advantage of using a seperate filesystem is that in case it becomes full it
will not affect operation of system software or other applications.
If you want to install FAST/TOOLS anywhere else, you should create
the install directory before starting the install procedure.
The installer will create a directory called “fasttools” beneath the install
directory.
3.2.2 Create a FAST/TOOLS user and group (optional)

Before you install FAST/TOOLS you should decide who will be the
'owner' of the FAST/TOOLS package. File ownership will be given to
the user account from which FAST/TOOLS is installed. Also the files
will get the group id of the installers account.
It is a good idea to create a new user account for FAST/TOOLS.
Traditionally the user name "tools" and group name "tools" were used
for this but you are free to choose any user and group name.
Add the paths “/tls/com” and “/tls/exe” to the PATH environment
variable for the FAST/TOOLS user in the user’s profile so that the user
has access to the runtime environment of FAST/TOOLS.

FAST/TOOLS installation Installing FAST/TOOLS
3.3 Installing FAST/TOOLS

Finally we are ready to install FAST/TOOLS. For this we have to be
logged in as the FAST/TOOLS user. In this manual we will assume that
you have created a user call "tools" and a group "tools" for this purpose.
The first thing to do is to copy the install pack from the FAST/TOOLS
distribution DVD to a temporary directory in the home directory of the
user "tools"
$ mkdir tmp_install
Copy the install pack, the name of you cd-rom device on your system
may be different.
On RedHat Enterprise Linux:
$ cp -r /media/cdrom/fasttools* ~/tmp_install
$ cd ~/tmp_install
On Sun Solaris:
$ cp -r /cdrom/fasttools* $HOME/tmp_install
$ cd $HOME/tmp_install
On IBM AIX:
$ cp -r /cdrom/fasttools* ~/tmp_install
$ cd ~/tmp_install
The temporary install directory will now contain a tar file called
fasttools_<rel_nr>.tar where <rel_nr> is the number of the
FAST/TOOLS release you are installing. You now have to unpack the
tar file:
$ tar -xvf fasttools_<rel_nr>.tar
The tar file is unpacked into a directory called fasttools<rel_nr>. Enter

the directory and start the installation script:
$ cd fasttools_<rel_nr>
$ ./ft_install
The first question the install script will ask is if you have read the licence
terms and whether you agree with them:

Installing FAST/TOOLS FAST/TOOLS installation
Have you read the FAST/TOOLS licence terms and do you agree with
these terms?
Please enter Yes if you agree or No to exit installation [Yes]
If you do not agree you should answer “No” and the installation will
stop. Otherwise you can press enter to select the default answer “Yes”.
Next you are asked to enter the root password:
The FAST/TOOLS installation procedure requires root privileges.

Please enter the root password to continue.
Password:
After you entered the password the install script will ask for the
FAST/TOOLS install directory. The default is /opt/fasttools.
Please enter the FAST/TOOLS install directory or press enter

to accept default.
Install directory: [/opt/fasttools]
FAST/TOOLS is installed on your system. Next you are asked if you

want FAST/TOOLS to be started automatically when you startup your
system.
FAST/TOOLS can be configured to start automatically

when your system is started.
Do you want FAST/TOOLS to start with your system? .
* Please enter Yes or No [Yes]
When the install script is finished FAST/TOOLS is installed on your

system. The next step is to request a licence file.
Note: By default the /tls/com and /tls/exe paths

are added to /etc/profile. For AIX systems
these paths should added manually to
/etc/environment.
Note: Selecting the “start automatically” will add
an entry to /etc/rc.o/init.o/fasttools.

FAST/TOOLS installation Requesting a licence
3.4 Requesting a licence

On Linux the ‘jtoolslicreq’ License Request wizard can be started from
the command line. Follow the steps of the wizard to request a licence for
the system.
For other operating systems requesting a FAST/TOOLS licence can be
done using the Licence Request Wizard that is found on the
FAST/TOOLS distribution DVD. Install the wizard on a Microsoft
Windows System. After installing the wizard is activated from the FAST
TOOLS start menu. Follow the steps of the wizard to request a licence
for the system.
3.5 Validating FAST/TOOLS

Once you have received your FAST/TOOLS licence file form
Yokogawa you are ready to validate FAST/TOOLS. Validating means
applying your licence.
Validating is done by passing the licence file as parameter to the
ft_validate script in the install directory of the Unix/Linus system:
$ cd ~/tmp_install/fasttools_<rel_nr>
$ ./ft_validate NODE_1.lic
--------------------------------------------------------------
F A S T / T O O L S L i c e n s e I n f o r m a t i o n
--------------------------------------------------------------
License Customer Name : Acme Scada Corporation.

License Node Name : NODE_1
License Node Number : 1
License System Number : C3311158839
Your FAST/TOOLS system was successfuly validated !.
You have now installed FAST/TOOLS on your Unix system

For Linux, a graphical version of the License Validation Wizard can be
launched using the ‘jtoolslic’ command from the command line.

Prerequisites Setting up a HMI connection
4 Setting up a HMI connection

Because the FAST/TOOLS visualization and system managers interface
is only available on the Microsoft Windows platform every Unix based
FAST/TOOLS configuration requires a Microsoft Windows based HMI
station.
This section describes how to setup a HMI connection.
4.1 Prerequisites
Before you can connect you Unix system to a Microsoft Windows HMI
you should have the following information available:
Unix/Linux Server:
- Host name or IP address
- FAST/TOOLS node number
Microsoft Windows HMI Station:

- Host name or IP address
- FAST/TOOLS node number
4.1.1 Firewall configuration

You should also allow the FAST/TOOLS communication through any
firewall. FAST/TOOLS nodes communicate with each other using the
an UPD connection on port 17001.
By default the Redhat Enterprise Linux firewall will not allow any UDP
connections.
To open this port we can use the Firewall Configuration. Start this
application from the System menu:

Setting up a HMI connection Prerequisites
After starting the Firewall Configuration you must enter the super user
(root) password to continue:

Prerequisites Setting up a HMI connection
Then select Other Ports and add the 17001 UDP port:
Apply the new settings:

Setting up a HMI connection Server configuration
Finally effectuate the settings:
If you later need to open more ports for example for equipment
managers you, can add more UPD or TCP ports.
4.2 Server configuration

On the Unix/Linux server, we need to edit the file durm_1_udp.sup
setup file in the directory /tls/sup.
At the end of this file the addresses of the other machines to which this
system should be connected are specified by the ‘remote’ parameter.
Create a new ‘remote_set’ entry and set it to the value of the IP addresses
or Host names of the HMI node(s) you want to connect. For example:
remote_set = "HMI-1"
That’s it for the Unix server.
4.3 HMI configuration

On the HMI node, modify the file dur.sup in the .../tls/sup directory of
your FAST/TOOLS installation. Change the "host_node" parameter to
the BUS/FAST node number of the server system.

HMI configuration Setting up a HMI connection
Next copy the file durm_start from the .../tls/tpl directory to

../tls/com.
Finally edit the file durm_1_udp.sup setup file in the directory .../tls/sup.
At the end of this file the addresses of the other machines to which this
system should be connected are specified by the ‘remote_set’ parameter.
Create a new ‘remote’ entry and set it to the value of the IP addresses or
Host names of the server node. For example:
remote_set = "SERVER-1"
Now restart FAST/TOOLS on both Server and HMI-node and the
connection will be established.

Setting up a HMI connection HMI configuration

Introduction Using FAST/TOOLS
5 Using FAST/TOOLS
5.1 Introduction
This sections contains a basic introduction to managing your
FAST/TOOLS system.
5.2 Starting and stopping FAST/TOOLS

A FAST/TOOLS system can be started manually by a user or
automatically when the system is booted. FAST/TOOLS will then run
as a Service.
If you start an unlicensed FAST/TOOLS system it will run for one hour.
This is done for evaluation/demo purposes.
5.3 Manually starting and stopping

Starting and stopping FAST/TOOLS manualy is done by running the
fast_start and fast_stop script that can be found in /tls/com. To start
FAST/TOOLS type:
$ fast_start
This command will start FAST/TOOLS by calling the start scripts of all
the individual tools in the right order. To stop FAST/TOOLS type:
$ fast_stop
This will stop FAST/TOOLS by calling the stop scripts of all the
individual tools in the right order.
5.4 Running FAST/TOOLS as a service

FAST/TOOLS can be configured to be started when your system is
started. This will ensure FAST/TOOLS is running after a booting your
system.

Using FAST/TOOLS Running FAST/TOOLS as a service
During installation you were asked if you wanted to start FAST/TOOLS

at startup of your system. If you answered ‘yes’, the installer will use the
command (on RedHat Enterprise Linux):
$ /sbin/chkconfig --add fasttools
to register the file fasttools.rc as a service, or another appropriate

command for AIX or Solaris. This file can be found in the installer
directory in .../fasttools_<rel_nr>/bin.
Unfortunately, different Unix versions and Linux distributions use
slightly different ways to register services. If you are using another
Linux distribution, you can use the fasttools.rc file as a starting
point and register it in the way required by your Linux distribution.
5.4.1 RedHat Enterprise Linux

On RedHat Enterprise Linux, if you have FAST/TOOLS registered as a
service you can start and stop the from the service dialog in the Gnome
desktop.
Start the Service Configuration from the System menu:

Running FAST/TOOLS as a service Using FAST/TOOLS
Scroll to the fasttools services en click the Enable button. If enabled

FAST/TOOLS will start as soon as the Linux system is started:
Finally you have to grant the changes by entering the password of the
super user (root):

Using FAST/TOOLS Clearing FAST/TOOLS Runtime Data
5.4.2 Sun Solaris

On Sun Solaris, it is possible to enable and disable the script by
renaming the symbolic link found in /etc/rc3.d/ according to the
SystemV init style. For example, to disable FAST/TOOLS startup
service:
# cd /etc/rc3.d
# mv S99fasttools K10fasttools
And to enable FAST/TOOLS startup service again:

# cd /etc/rc3.d
# mv K10fasttools S99fasttools
5.4.3 IBM AIX

On IBM AIX, FAST/TOOLS must be enabled and disabled from within
the /etc/inittab file by commenting or uncommenting the line
which starts the service. To disable, the FAST/TOOLS line should read
(note the beginning colon character)
:
:fasttools:234:once:/etc/rc.fasttools start
And to enable the service, remove the commenting character, as follows:

fasttools:234:once:/etc/rc.fasttools start
5.5 Clearing FAST/TOOLS Runtime Data

To clear FAST/TOOLS runtime data, the fast_clear script should
be run with the appropriate parameter. In order to use this script,
FAST/TOOLS should first be stopped if it is running using the
fast_stop script.
To clear gathered history units and generated reports:
fast_clear -u
To clear all runtime and historical data:

Removing FAST/TOOLS Using FAST/TOOLS
fast_clear -a
In both cases, the script will ask you to confirm the action that is to be
taken. Adding -q as the second parameter to the script will suppress this
confirmation request, as follows:
fast_clear -a -q
fast_clear -u -q
5.6 Removing FAST/TOOLS

To un-install the FAST/TOOLS software you need to take the following
steps depending on your platform:
5.6.1 RedHat Enterprise Linux

• Stop FAST/TOOLS.
• Remove the FAST/TOOLS service.
Start the Service Configuration from the System menu:

Using FAST/TOOLS Removing FAST/TOOLS
Select the fasttools services and click Disable:
• Remove the fasttool directory. If you selected the default location

during installation this directory can be found within the /opt
directory.
5.6.2 Sun Solaris

• Stop FAST/TOOLS
• Enter the following commands as root:
# rm /etc/rc3.d/*fasttools
# rm /etc/init.d/fasttools

directory.
5.6.3 IBM AIX

• Stop FAST/TOOLS
• Enter the following commands as root:
# rm /etc/rc.fasttools
In addition, on IBM AIX, the following line should be removed

from the /etc/inittab file:
fasttools:234:once:/etc/rc.fasttools start

directory.

Introduction
Appendix A: Distributed systems
A.1 Introduction
This appendix is intended to describe the starting points on a distributed
FAST/TOOLS configuration. Furthermore it describes what kind of
actions must be taken to configure a distributed FAST/TOOLS system.
The structure of this chapter is as follows:
• First an introduction is given on various notions/concepts that are

directly related to the configuration of a distributed FAST/TOOLS
system. Since these notions/concepts are already covered in much
more detail in other parts of the FAST/TOOLS product
documentation, the notions are just introduced globally. Each of the
paragraphs globally describing a specific concept, contains a
reference to the product document in which the concept is
elaborated further.
The intention of this global introduction to these concepts is, to
make sure that you understand what kind of actions are needed to
configure a distributed FAST/TOOLS system.
• Secondly, the configuration actions are described in more detail and
in a stepwise fashion.
A.2 HMI, Host, Front-end components

The FAST/TOOLS product can be used both in stand-alone- and
distributed configurations.
In a standalone configuration the FAST/TOOLS product is installed on
one physical computer system. In a distributed configuration, the FAST/
TOOLS product is installed on multiple physical computer systems
where each of the computer systems is given a specific role. From here
on the notions "computer system" and "node", are used interchangeably.
In a FAST/TOOLS system, the following roles are distinguished with

respect to the configuration:
• HMI component:
The component that acts as user interface to the FAST/TOOLS
product. One or more of these HMI components exist in a
FAST/TOOLS Installation Manual Linux and Unix A-1

Interconnecting components
distributed configuration.
• Host component:
The component that primarily acts as central data concentrator.
In many situations one such Host component exists in a FAST/
TOOLS system. From an "availability" point of view however, it is
possible to have redundant/dual Host components. This latter
situation however, is beyond the scope of this discussion.
• Front-end component:
The component that primarily acts as a local data concentrator. In
that role this component gathers/controls a subset of the total
amount of process signals.
In a stand-alone configuration, the roles of HMI, Host and Front-end are

actually combined in one physical computer system. In a distributed
configuration the roles of HMI, Host and Front-end are often mapped
one to one on separate physical computer systems. However, it is also
possible to combine these roles in one and the same physical computer
system (for example a physical computer system that acts as Host and
HMI component).
A.3 Interconnecting components

Although various combinations are possible, in the context of this
discussion and as a reference implementation of a distributed FAST/
TOOLS system, it is assumed that each HMI, Host and Front-end
component, is mapped upon a separate physical computer system. Each
of these physical systems is connected to a network. Furthermore it is
assumed that:
• One Host component exists in such a configuration.
• Each HMI component is connected via a DURM connection to the
Host component and each of the Front-end components.
• The Host component is connected via a DURM connections to each
of the Front-end components.
By logically connecting the various FAST/TOOLS components to each

other in the above described way, there is some form of inherent fallback
scenario configured.
Suppose for example that a HMI component fails. Since the other HMI
component is also connected to the Host- and Front-end components,
there is still access to the Host- and Front-end components via this other
HMI component.
A-2 FAST/TOOLS Installation Manual Linux and Unix

Distribution of data sets
Suppose for example that the Host component fails. Without a

redundant/dual Host in place, undoubtedly some FAST/TOOLS
functionality will not be available. However by having a DURM
connection between the HMI- and Front-end components, it is still
possible to monitor and control vital functions in the process being
supervised.
Remark:
Although possible, it is normally not the case that an HMI component is
connected (via DURM) to other HMI components and/or a Front-end
component is connected to other Front-end components.
Detailed information about DURM and configuring DURM can be

found in the BUS/FAST System Integrator’s Manual.
A.4 Distribution of data sets

Via the FAST/TOOLS data set model, configuration- and process data
is, exhibited to and controlled/manipulated by, among others, the HMI
components under strict conditions. The FAST/TOOLS functionality
that implements this data set model is called Data Set Services (DSS).
Thanks to DSS, the configuration- and process data can be redundantly
stored in more than one physical computer system. Such a dataset is said
to be "distributed". The advantage of this is obvious: should a physical
computer system fail, there is still the possibility to read the required
data elsewhere. This is entirely transparent to the DSS clients, among
which the HMI components.
Updating data that is redundantly stored in more than one physical
computer system, works slightly different. With one exception (the
dataset containing item-values), updating a distributed data set, requires
the availability of all physical computer systems on which the data is
stored. If one of the computer systems on which the data should be
stored cannot be "reached", the data in the dataset cannot be updated.
The definition of where the data is stored, is done via the so called data
set definitions.
Detailed information about DSS and data set definitions can be found in
• DATABASE/FAST System Integrator’s Manual
• DSS Language Manual

Item copy processes
A.5 Item copy processes

In a distributed FAST/TOOLS system, the System Manager makes
specific choices regarding the so called "distribution group" and
"distribution type" attributes of an item. Together the "value" of these
attributes for a FAST/TOOLS item, determine:
• Whether an item is distributed (image available at Host and Front-
end) or not.
At most, a FAST/TOOLS item is replicated on 2 nodes.
• Where the master image of the item resides (in the Host- or Front-
end component).
• In case the item image is solely stored in the Front-end component
(not distributed) or in case of a distributed item, which Front-end
component (which node) is involved.
For distributed items the so called item copy processes in the FAST/
TOOLS system, are responsible for updating the "slave" image of an
item. The item copy processes play no role for non-distributed items
(non distributed items, only have their image in the Host component).
Note:
It is intentional that the plural form is used here: item copy processes.
These processes always act as a pair on a given computer system;
The Master Item copy process on a given computer system is
responsible for passing updates from a master item on its node, to the
slave image. It does so by communicating with the Slave Item copy
process on the node where the "slave" image of the item resides.
Briefly then; in a distributed FAST/TOOLS system a pair of item copy
processs (a master and a slave) must be active on each of the nodes
acting as Host and Front-end.
Detailed information about distributed items and the item copy

processes can be found in the ITEM/FAST System Integrator’s Manual.
A.6 Distributed ALARM/FAST

In a distributed FAST/TOOLS system it is possible to use the ALARM/
FAST functionality without the link between Host and Front-end being
active. In such a configuration, the systems on which the Host- and
Front-end components are installed, offer independent ALARM/FAST

Distributed Item Interface (GIN DII)
functionality although they can not communicate with each other.

Whether or not the distributed ALARM/FAST functionality must be
available, can be configured via the alm.sup file.
Deatiled information about distributed ALARM/FAST functionality can

be found in ALARM/FAST System Integrator’s Manual.
A.7 Distributed Item Interface (GIN DII)

The purpose of the Distributed Item Interface is to make item
manipulation transparent across nodes in a distributed FAST/TOOLS
system. When one of the nodes in a distributed environment goes off-
line, the distributed FAST/TOOLS system must continue to operate in
the best possible way. The Distributed Item Interface represents this
functionality transparently to its clients:
• Obtains item attributes from the correct node.
• Sets item attributes on the correct node.
• Redirect item event requests when the node currently servicing the
event request, fails.
The Distributed Item Interface uses a (default) node approach/access

scheme to perform these tasks. Important to note here is that this default
scheme can be configured via a setup file.
Detailed information about the Distributed Item Interface and the

modification of the node default access scheme, can be found in the GIN
Programmer’s Manual.
A.8 Stepwise configuration actions

1 Make sure that all nodes involved, "know" which one of them acts
as Host component.
This can simply be configured in the "dur.sup" setup file on each
node by specifying the Host node number in this setup file.
2 Configure the DURM connections.

Make sure a durm_start (Unix)/durm_start.cmd (Microsoft
Windows) file is present on the FAST/TOOLS command directory

Stepwise configuration actions
(../tls/com for Microsoft Windows, ../tls/com_node for Unix). This

durm_start(.cmd) file is used by the FAST/TOOLS startup-
procedure to start the (various) DURM connection(s).
Make sure a setup file is configured for each of the DURM
processes to be started on a given node. One of the most important
aspects to configure in these setup files is/are the Host-name(s) or
IP-address(es) of the counterpart computer systems (the node(s)
with which we want to establish a DURM connection).
3 Configure the distribution of datasets

Configure the distribution of datasets in such a way that all datasets
are present on all Host- and Front-end- nodes. This can be done by
editing the file "dss_global.dss" on the FAST/TOOLS source
directory (../tls/src) on the node containing the Host component.
Look in this file for the macro definition for "mcStorageNodes" and
add "node-labels" to this macro for each of the additional nodes in
the FAST/TOOLS system. Since this macro is used by almost all of
the dataset definitions, all datasets will use this "storage node"
definition automatically. Once the data set definitions are compiled
(during first startup of FAST/TOOLS on the node containing the
Host component), DSS knows where the various FAST/TOOLS
data sets can be found.
Note: When the contents of a DSS file is changed, run the DSS
compiler on the directory where the DSS files are stored (usually ../
tls/src). Then stop and restart the FAST/TOOLS.
4 Configure the startup of item copy processes.

Since the item copy processes are not started by default, the file
item_start (Unix)/item_start.cmd (Microsoft Windows) must be
changed manually.
Look in this file for the startup commands for the ITMCPM and
ITMCPS executables and uncomment these startup commands.
5 Configure PROCESS/FAST node connection scheme.

Next we must tell PROCESS/FAST running on the host node that
it must connect to all the Front-end. This is done by modifying the
setup file opc.sup. In this file remove the line:
NODE_IGNORE = -1
This must only be done on the HOST node.
6 If distributed ALARM/FAST functionality is required activate this

in the "alm.sup" on each node where distributed ALARM/FAST

functionality must be available.
7 Activate the option “Check all MDUR nodes” in the gin.sup setup
file and if required, re-configure the default access scheme.
Note: If adding a Front-end to an existing

configuration as the result of system
expansion for example, run the following
commands on the FAST/TOOLS server once
the Front-end has been connected:
dsschk -r
dsschk -e r


Index
Index
A PROCESS/FAST 2-2
abbreviations 1-2
ACCESS/FAST 2-2
R
ALARM/FAST 2-2 REPORT/FAST 2-2
AUDIT/FAST 2-2
S
B Server 2-1
BUS/FAST 2-2
C
conventions 1-2
D
DATABASE/FAST 2-2
E
EQUIPMENT/FAST 2-2
F
fasttools.rc 5-2
Firewal 4-1
Front-end node 2-1
H
HISTORY/ FAST 2-2
HMI node 2-1
I
INTEGRATION 2-2
ITEM/FAST 2-2
L
Licensing 2-7
O
objectives 1-1
ODBC 2-2
P
Prerequisites 4-1
FAST/TOOLS Installation Manual Linux and Unix 1

Index
2 FAST/TOOLS Installation Manual Linux and Unix

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
GSC_Sales@ml.jp.yokogawa.com
Reader’s Comment
Manual name: ......................................................................................Version: .........................
Did you find this manual understandable, usable, well organized? Please make suggestions for
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Did you find any errors in this manual? If so, please specify the error and page number.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Note: Yokogawa will use comments submitted on this form at its own discretion.
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Manual Installation Manual
Windows
IM50C03C00-01EN/R10.03

IM50C03C00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
0.2 Intended audience ......................................................0-1
0.4 Associated document .................................................0-1
1 General ..................................................................................1-1
1.1 Introduction ...............................................................1-1
1.2 Requirements .............................................................1-3
1.2.1 Required Software .................................................... 1-3
1.2.2 Required Disk Space ................................................. 1-4
1.2.3 Required Memory Space .......................................... 1-6
1.3 The phases of installation ..........................................1-6
1.3.1 Read the Release Notes document ............................ 1-6
1.3.2 FAST/TOOLS installation ........................................ 1-6
1.3.3 Re-installing .............................................................. 1-7
1.3.4 Directory structure .................................................... 1-7
1.4 How to obtain your licence numbers .........................1-8
3 SimbaServer ..........................................................................2-1
3.1 Installing the SimbaServer .........................................2-1
4 SimbaClient ...........................................................................3-1
4.1 Installing SimbaClient ...............................................3-1
4.2 Supported ODBC enabled applications .....................3-2
5 FAST/TOOLS Components ................................................4-1
5.1 Installing FAST/TOOLS components .......................4-1
5.2 Licensing FAST/TOOLS ...........................................4-1
5.3 Starting and stopping FAST/TOOLS ........................4-2
5.4 Starting and stopping the HMI ..................................4-3
5.4.1 Manually ................................................................... 4-3
5.4.2 Automatically ............................................................ 4-4
5.4.3 Stopping .................................................................... 4-4
5.5 Time synchronisation ................................................4-4
5.6 Using the Default User account .................................4-4
5.7 Available Procedures .................................................4-5
5.8 Uninstallation of FAST/TOOLS ...............................4-6
5.9 Changing FAST/TOOLS service startup-time ..........4-6
FAST/TOOLS Installation Manual Windows iii

Table of Contents
Appendix A:Distributed systems .................................................. A-1

A.1 Introduction .............................................................. A-1
A.2 HMI, host, front-end components ............................ A-1
A.3 Interconnecting components .................................... A-2
A.4 Distribution of data sets ........................................... A-3
A.5 Item copy processes ................................................. A-4
A.6 Distributed ALARM/FAST ..................................... A-4
A.7 Distributed Item Interface (GIN DII) ....................... A-5
A.8 Stepwise configuration actions ................................ A-6
iv FAST/TOOLS Installation Manual Windows

Objectives Preface
0 Preface
0.1 Objectives
This manual has the following objective:
• To provide all information needed to install the FAST/TOOLS
package on the Windows platform.
This includes information about the installation of third party
packages used by the FAST/TOOLS product.
• To provide information about concepts and step-by-step
instructions related to the configuration of a distributed
FAST/TOOLS system.
0.2 Intended audience

This manual is intended for anyone wanting to install one or more of the
tools of the FAST/TOOLS package.
The reader is assumed to be familiar with the Windows platform and the
Windows operating system and is assumed to have some knowledge of
the FAST/TOOLS philosophy.

The FAST/TOOLS Installation Manual is divided into a number of
chapters / appendices
• Chapter 1 describes the general procedure that should be followed
when installing any configuration of FAST/TOOLS.
• Subsequent chapters describe how to install the FAST/TOOLS
software and related third-party packages.
• In Appendix A, a description is given of the configuration of a
distributed FAST/TOOLS system.
0.4 Associated document

Windows platform dependent documentation set.
FAST/TOOLS Installation Manual Windows 0-1


The following conventions may be used in this manual:
CONVENTION MEANING
[] Indicates that the enclosed item is the default.
UPPERCASE Indicates reserved words and predefined names,
"" Used in format descriptions. Double quotes indi-
cate that the character is to be taken literally.
variable.
file_name This type-setting is used to indicate file names.
output This type-setting is used to indicate output on a
terminal.
input This type-setting is used to indicate input from
the user.
n.u. not used.
0-2 FAST/TOOLS Installation Manual Windows

Introduction General
1 General
1.1 Introduction
This manual describes the procedure for installing FAST/TOOLS on a
Windows system based upon the Intel x86 or x64 PC architecture.
This chapter describes the philosophy behind the procedures as well as
the Windows specific information.
FAST/TOOLS consists of a number of functional tools:
Table 1: The FAST/TOOLS collection
Tool name Description
BUS/FAST Basic support and communications

DATABASE/FAST ISAM based file support
Distributed data set services
HISTORY/FAST History scheduler
AUDIT/FAST Audit trailing
ITEM/FAST Real time item data handling
EQUIPMENT/FAST Equipment drivers
ALARM/FAST Alarm handling
PROCESS/FAST Sequences, processing and calculations
REPORT/FAST Reporting
ACCESS/FAST Open DataBase Connectivity (ODBC) interface
OPC server and client functionality
USER/FAST FAST/TOOLS User Interface
INTEGRATION Various pieces of FAST/TOOLS functionality (e.g.
quick load, int-server).
This FAST/TOOLS functionality may be contained by one system

(stand-alone configuration) or distributed over more than one system
(distributed configuration).

General Introduction
A system in a distributed configuration has a certain function

(component). The following components are defined:
Table 2: The components within a distributed configuration
Function Description
Server The server is the central system within a distributed configura-

tion.
Front-end A front-end takes care of gathering data from the attached equip-
ment. In addition some local control is possible.
HMI A Human Machine Interface enables the Operator to monitor and
control the process.
Setup File The FAST/TOOLS Setup File Editor provides a graphical user
Editor interface to ease the process of editing setup files.
FAST/Start FAST/Start setup installs additional files to get started quickly. It
supplies a user interface that hides features that are less com-
monly used.
Remark: This component is technically equal to the “Server”
component plus the additional files meant to get started quickly.
In addition a system may contain mixed components. For example a

system may contain the Server, Front-end and HMI components. This
may be a stand-alone system.
The following table lists the tools and in which component they are
found:
Table 3: Tools in relation to the components
Component
Tool name
Server Front-end HMI
BUS/FAST * * *
DATABASE/FAST * * *
HISTORY/FAST *
AUDIT/FAST *
ITEM/FAST * *
EQUIPMENT/FAST * *
ALARM/FAST * *
PROCESS/FAST * *
REPORT/FAST *

Requirements General
Table 3: Tools in relation to the components
Component
Tool name
Server Front-end HMI
ACCESS/FAST * *
(OPC only)
USER/FAST * *
INTEGRATION * *
The tables above describe which functions are used where in a

FAST/TOOLS system. Whether or not a certain tool will be activated
depends on whether or not the tool is licensed.
1.2 Requirements
To install FAST/TOOLS, you must have administrator privileges on
your system. Therefore you must be logged in as an Administrator or as
a user with administrator privileges.
Make sure that no other applications are active during installation of
FAST/TOOLS.
1.2.1 Required Software
Before you install FAST/TOOLS, other software must be installed. For

the version number of the various software packages, please consult the
Release Notes document.
• Windows
Windows 2016 Server, Windows 10 Enterprise LTSB,
Windows 7 Professional 64-bit SP1.
• Visual Studio 2015
This is required when you intend to write application programs that
link to FAST/TOOLS libraries.
• SimbaServer
When you want to enable PC applications to access FAST/TOOLS
datasets via the ODBC interface, the SimbaServer is required. This
server must be installed on the system where the FAST/TOOLS
Server component is to be installed. The SimbaServer can be found
on your FAST/TOOLS CD. However, it is installed separately from
FAST/TOOLS. See Chapter 3 for installing SimbaServer.

General Requirements
• SimbaClient
When you want to enable an application running on a Windows
system to access FAST/TOOLS data located on a FAST/TOOLS
system via an ODBC interface, then you have to install
SimbaClient on the client system.
SimbaClient can be found on your FAST/TOOLS CD. See Chapter
4 for installing SimbaClient.
• When you want to use the FAST/TOOLS archiving functionality in

combinations with CD’s, you must install a CD creation software
package that has the possibility to format CD’s in Universal Disk
Format (UDF).
1.2.2 Required Disk Space
To install the FAST/TOOLS software you will require about 400

Mbytes of disk space.
Whilst running FAST/TOOLS, additional disk space is required to store
configuration and historical data:
Item definition file

The item definition requires 1,800 bytes for each item defined (Server
component only).
Add 350 bytes per item for each system where the front-end component
is installed.
Item history files

The size of an item history file depends on the type of storage you
choose. This paragraph gives an overview of the commonly used storage
types. These values should be seen as a rule of thumb. All file size
aspects such as key file overhead and bucket slack size are counted in
the sample size values.
Disk compression is not counted.
• Event based collection/event based storage
Event/Event in the HMI. On average you can expect each sample
to take 100 bytes of disk space.
• Scan based collection/Time based storage

Requirements General
Scan/Time in the HMI. This storage group has optional
compression and can be configured to store the quality code of the
item as well as the value and status. The following table gives the
average disk space each item sample will take, depending on the
choices you make:
Table 4: Disk space required for Scan/Time sample
Use compression Store quality code Bytes used per sample
No No 14
Yes No 10
No Yes 18
Yes Yes 14
• Event based collection/Item based storage

Event/Item in the HMI. This storage type is intended to be used for
frequently changing analog values that are time stamped in the
field. Its efficiency increases with the number of samples per file
rollover. Frequently changing analogs with more than 100 events
per file rollover will use, on average, 30 bytes per sample. Slow
changing signals (less then 10 events per file rollover) will use on
average 100 bytes of disk space per sample.
Alarms history
ALARM/FAST can store events for a period of time. One event costs,
on average, 550 byte disk space. The number of events and the life time
is completely user-dependent and / or process-dependent.
Classes and objects

Each class defined and compiled typically costs 18 Kbytes of disk space.
Each object consumes 2 Kbytes in average.
Reports
Each defined report takes about 2 Kbytes. The size of a generated report
is undefined due to the nature of a report definition.
Displays and symbols

On average a display or symbol takes 30 Kbytes of disk space.

General The phases of installation
1.2.3 Required Memory Space
The following system memory sizes are advised:

Table 5: Advised memory sizes
Advised
Software memory size
(Mbytes)
Small stand alone system with Server, Front-end and HMI 2048
component installed (up to 2000 items)
FAST/TOOLS Server system 2048
Large FAST/TOOLS Server system (100.000 items or more) 4096
HMI component only 2048
Front-end component only 1024
SDK component 512
Note that additional non FAST/TOOLS applications may require

additional memory.
1.3 The phases of installation
1.3.1 Read the Release Notes document
Before you start the installation of software, read the Release Notes
document. Among other things, it contains information about the
versions of third party software packages, required Service Packs, etc.
1.3.2 FAST/TOOLS installation
The installation of FAST/TOOLS is divided into a number of phases:

1 Installation of third party software components.
2 The components of the FAST/TOOLS package are installed.
3 After installation of the FAST/TOOLS package, the functional
tools should be licensed by running the License and Authorize
options from the Licence Wizard. When you omit this phase, you
still can explore the functionality of FAST/TOOLS for one hour
each time you start FAST/TOOLS.

The phases of installation General
Make sure that these phases are performed under a user account with
administrator privileges.
After installation, the tools can be started using the commands in the
FAST/TOOLS entry in the Start menu.
1.3.3 Re-installing
Whenever the hardware and/or software configuration is changed in

some way, it may be necessary to reinstall some of the FAST/TOOLS
components as appropriate. Make sure that FAST/TOOLS is not
running when components are added or re-installed.
1.3.4 Directory structure
During installation of FAST/TOOLS, the following directory structure

is created (note that not all subdirectories may be there, depending on the
components installed):
• %TLS_ROOT_PATH%
The directory where FAST/TOOLS program files are installed.
• %TLS_ALLUSERS_PATH%
The directory where application run-time and configuration files
are stored.
• %TLS_ROOT_PATH%\tls
Directory which contains the FAST/TOOLS components.
• %TLS_ALLUSERS_PATH%\tls\dat
Directory for data files that are indispensable for programs to
function correctly (not to be confused with
%TLS_ALLUSERS_PATH%\tls\sav).
• %TLS_ALLUSERS_PATH%\tls\lst
Directory for list and output files created by programs.
• %TLS_ALLUSERS_PATH%\tls\sav
Directory to store files that can be re-generated if they should be
lost, e.g. code files for PROCESS/ FAST and warm-start files for
ITEM/FAST.
• %TLS_ROOT_PATH%\tls\sup
Directory for setup files that contain setup parameters which can be
changed in a run-time environment.
• %TLS_ROOT_PATH%\tls\com
Directory for command files, procedures and scripts.
• %TLS_ROOT_PATH%\tls\exe

General How to obtain your licence numbers
Directory for executables (binaries).

• %TLS_ROOT_PATH%\tls\hlp
Directory that contains help files.
• %TLS_ROOT_PATH%\tls\inc
Directory for FAST/TOOLS include files. Typically *.h files are
stored here, but *.inc files containing programming fragments are
also present.
• %TLS_ROOT_PATH%\tls\lib
Directory for object libraries.
• %TLS_ROOT_PATH%\tls\src
Directory for source files.
• %TLS_ROOT_PATH%\tls\tpl
Directory for template files, typically used when installing tools or
specifying parameters.
• %TLS_ROOT_PATH%\tls\upg
Directory for upgrade utilities.
• TLS_ALLUSERS_PATH\tls\his
Directory for historical data files.
• %TLS_ALLUSERS_PATH%\tls\wap
Directory for web application files
• %TLS_ROOT_PATH%\tls\jre
Java runtime environment directory
1.4 How to obtain your licence numbers

To obtain the licence numbers for the any tools of the FAST/TOOLS
collection, start the FAST/TOOLS Licence Wizard from the
FAST/TOOLS program group in the start menu and follow the
instructions given.
Contact Yokogawa to obtain licence numbers at the following address:
Global SCADA Center

Yokogawa Electric Corporation
Musashino-shi,
Telephone: +81-422-52-5616
email: GSC_LICENSE@ml.jp.yokogawa.com

Installing the SimbaServer SimbaServer
3 SimbaServer
3.1 Installing the SimbaServer

Note: When you are going to install SimbaServer
on a Windows system that has Terminal
Services installed, always install
SimbaServer via “Add/Remove Programs”
control panel found in the
“Start/Settings/Control Panel” folder.
Then follow the instructions given.
• Go to the SimbaServer directory on the FAST/TOOLS CD.
• Activate the setup application.
• Follow the instructions on your screen.

SimbaServer Installing the SimbaServer

Installing SimbaClient SimbaClient
4 SimbaClient
4.1 Installing SimbaClient

Note: When you are going to install SimbaClient
on a Windows system that has Terminal
Services installed, always install
SimbaClient via “Add/Remove Programs”
control panel found in the
• Go to the SimbaClient directory on the FAST/TOOLS CD.
The setup application can activate an Explorer window. You can ignore
and close this window.
After installing SimbaClient then the ODBC data sources need to be
updated with the FAST/TOOLS ODBC driver. To do this run the
SimbaClient Configuration Utility “simutl32.exe” located in the
SimbaClient installation directory (default installation is “c:\Program
Files\Simba Technologies\SimbaClient”) using the local
administrator account .

SimbaClient Supported ODBC enabled applications
• Make sure FAST/TOOLS is running on the server machine.
• Select “Apply above to system data sources” from the dialog.
• Click the “Advanced” button and enter the IP address of the

FAST/TOOLS server machine or use the loopback address
“127.0.0.1” when configuring the client on the same machine as the
server.
• Click the “Update” button to add FAST/TOOLS to the list of data

sources.
4.2 Supported ODBC enabled applications

SimbaClient installed supports only 32 bit ODBC enabled applications.

Installing FAST/TOOLS components FAST/TOOLS Components
5 FAST/TOOLS Components
5.1 Installing FAST/TOOLS components

Note: When you are going to install
FAST/TOOLS on a Windows system that
has Terminal Services installed, always
install FAST/TOOLS via “Add/Remove
Programs” control panel found in the
• Go to the FAST/TOOLS directory on the FAST/TOOLS CD.
• Go to one of the following sub directories:
- eng
For the English version of FAST/TOOLS.
- fre
For the French version of FAST/TOOLS.
- ger
For the German version of FAST/TOOLS.
• Select a directory where the FAST/TOOLS files should be placed.
This directory can include long directory names. The default
directory is “C:\Program Files\Yokogawa\FAST TOOLS”
• Select the FAST/TOOLS components you want to install. Select
“Custom” when you want to compose a configuration not listed
here.
• Select the Program menu folder where the menu items of
FAST/TOOLS are placed in. The default is “FAST TOOLS”
• When setup has copied the files from the CD to the system and
setup has determined that the system should be restarted, it shows
the “Setup Complete” form.
5.2 Licensing FAST/TOOLS

You may run FAST/TOOLS without licensing it. The full functionality
is then available to you. However, FAST/TOOLS will shutdown
automatically after one hour. You can then start FAST/TOOLS again for
one hour to explore its functionality.

FAST/TOOLS Components Starting and stopping FAST/TOOLS
To license FAST/TOOLS, you must start the Licence Wizard from the
“FAST TOOLS” program group in the Start menu and follow the
instructions given by the wizard.
Note: when you install FAST/TOOLS and intend to license it, it is better
not to start FAST/TOOLS before licensing it. When you have run
FAST/TOOLS before licensing it, all data that you entered whilst
running FAST/TOOLS will be lost at the moment you license it.
5.3 Starting and stopping FAST/TOOLS

A licensed FAST/TOOLS system can be started manually or
automatically. Both ways of starting FAST/TOOLS does not include
starting the HMI (see the next Section 5.4).
An unlicensed FAST/TOOLS system can only be started manually via
the “FAST TOOLS" program group in the Start menu. In this case, the
HMI is automatically started. FAST/TOOLS will shutdown
automatically after one hour.
The following information is valid only for a licensed FAST/TOOLS
system:
FAST/TOOLS is started via a service installed during installation of
FAST/TOOLS. This service can be configured to be started
automatically or manually. The result of the start procedure is output in
a log file called “fast_start.log” located in the
“%TLS_ROOT_PATH%\tls” directory. Previous log files are preserved
and named “fast_start-<n>.log” where <n> = 1 for the log file of the
previous start and so on.
To configure the FAST/TOOLS service, the following steps must be
taken:
• Login as administrator.
• Define an account for running FAST/TOOLS.
The account defined for running FAST/TOOLS and the account
under which you login to the the computer can be different
accounts. However, make sure that both accounts have at least read,
write and execute permissions on the folders and sub-folders where
FAST/TOOLS is installed.
• In the Control Panel, select Administrative Tools and then Services.
Set the Startup Type for the “StartFASTTOOLS” service to
“Automatic”.
• If you do not want FAST/TOOLS to be started automatically, set
the Startup Type for the StartFASTTOOLS service to either

Starting and stopping the HMI FAST/TOOLS Components
“Manual” if you still want to start FAST/TOOLS manually later or

“Disable” if you want to prevent someone from starting
FAST/TOOLS altogether.
• Set the account for starting the FAST/TOOLS service to the
FAST/TOOLS specific account (the account defined for running
FAST/TOOLS).
Note: Do not leave the service account to System
Account.
When the service is configured to “Manual” start, a user can start
FAST/TOOLS via the “Start FAST TOOLS” entry of the FAST/TOOLS
menu.
FAST/TOOLS will stop in a controlled way when the system is stopped,
or a user can stop FAST/TOOLS via the “Stop FAST TOOLS” entry of
the FAST/TOOLS menu.
The “FAST-Start” and “FAST-Stop” are shortcuts to the “faststarter”
utility. The “faststarter” utility can be used in your own command scripts
too and accepts the following arguments:
• faststarter -s
Start FAST/TOOLS.
• faststarter -e
Stops FAST/TOOLS when the user clicks on “YES” in a
confirmation window.
• faststarter -f
Stops FAST/TOOLS unconditionally.
• faststarter
Shows a help window.
5.4 Starting and stopping the HMI

The FAST/TOOLS HMI can be started in either of two ways; manually
or automatically.
5.4.1 Manually
When a user has logged into the Windows system, he or she may select
the “HMI” option from the FAST/TOOLS menu in the Start menu. This
is the default way after FAST/TOOLS is installed.

FAST/TOOLS Components Time synchronisation
5.4.2 Automatically
As soon as the user logs in, the FAST/TOOLS HMI is started. For this
method, copy the “HMI” menu item to the “Startup” folder of the user.
5.4.3 Stopping
The HMI is stopped when you log off from the HMI.
5.5 Time synchronisation

If, in a distributed FAST/TOOLS configuration, the time of the systems
is synchronised using the durutl utility, then the user who starts
FAST/TOOLS must have the “Change system time” privilege. This also
applies if an external time synchronisation device is attached using the
durecs utility or the equipment manager process eqp.
5.6 Using the Default User account

Section 5.3 describes how to create a user account for FAST/TOOLS.
This user account should have all resources assigned to it that are
required by the FAST/TOOLS configuration, such as printer queues and
mapped drives.
It may be useful to have the same resources used by FAST/TOOLS also
available to other user accounts. Examples are printer queues and
mapped network drives. In order to make the same resources available
to everyone that logs in on a machine without having to define it
separately for each user, the Default User account should be modified.
The following steps describe how to change the Default User account.
1 Log on as the local administrator for the machine.
2 Make sure the “Show hidden files and folders” option is enabled in
folder viewing options of Windows Explorer. This is necessary to
be able to copy all of the required folders to the Default User
profile.
3 Make a backup copy of the existing Default User profile. The
profile is located in folder Default User under folder Documents
and Settings.
4 Create a new, local user account. This will be used to define the new
characteristics of the Default User.
5 Log off again and log in under the newly created local user account.

Available Procedures FAST/TOOLS Components
6 Customise the local account by defining the required printer queues

and mapping the necessary network drives. Set one of the defined
printer queues to the desired default printer.
7 Log off and log back on as administrator.
8 Replace the current Default User profile with the customised
account as follows:
- Activate the Control Panel via the Windows Start menu.
- Double-click System.
- On the User Profiles tab, select the new user account and
click Copy To.
- In the Copy To dialog box, under Copy profile to, click
Browse, click the \Documents and Settings\Default User
folder and then OK.
- Under Permitted to use, click Change, click Everyone and
then OK.
5.7 Available Procedures

A number of command procedures are available. Most of them are
activated when an option is selected from the FAST/TOOLS menu in the
Start menu. The command procedures are available in the
%TLS_ROOT_PATH%\tls\com directory. The procedures may also be
started from a Command Prompt. In this case go to the
%TLS_ROOT_PATH%\tls\com directory and issue the commands from
there.
• fast_start.cmd
Procedure that is called by the FAST/TOOLS services to start
FAST/TOOLS.
• fast_stop.cmd
Procedure that is called by the FAST/TOOLS services to stop
FAST/TOOS.
• setenv.cmd
Procedure to setup the FAST/TOOLS environment within the
Command Prompt. It is mostly included by the other procedures.
• fast_clear.cmd
Procedure to cleanup the FAST/TOOLS environment. It resets the
FAST/TOOLS environment to its initial state as being freshly
installed. It can also be used to remove all gathered history and
generated reports only. To remove the history only, enter:
fast_clear -u
To remove all runtime data enter:
fast_clear -a

FAST/TOOLS Components Uninstallation of FAST/TOOLS
You will be prompted to continue unless you specified the -q

(quiet) switch in addition to the -u or -a switch.
Note: Be extremely careful when using fast_clear.
It removes all your definitions and history
gathered by the system.
Not all procedures may be available. This depends on the FAST/TOOLS
components you have installed.
5.8 Uninstallation of FAST/TOOLS

To un-install the FAST/TOOLS software, perform the following
actions:
• Stop FAST/TOOLS.
• Remove the FAST/TOOLS service by issuing the following
command in a Command Prompt window:
instsrv StartFASTTOOLS remove
• Via the Add/Remove Programs Control Panel, remove the
FAST/TOOLS software from your system.
Since the FAST/TOOLS software creates several data files as soon
as it is started, not all FAST/TOOLS files will be removed
automatically. Therefore you should also perform the last step.
• Remove the entire %TLS_ROOT_PATH% directory from your
system.
5.9 Changing FAST/TOOLS service

startup-time
If a large FAST/TOOLS configuration is started or stopped from the
Windows Start menu, it sometimes takes longer than the default timeout
for windows services. If stopping a service takes too long, Windows
will show an error message such as "Failed to stop in a timely fashion".
This timeout is a system wide setting that is used for all Windows
services. You can override de default by adding a entry called
ServicesPipeTimeout to the windows registry.
Warning: If you use Registry Editor incorrectly, you may cause serious
problems that may require you to reinstall your operating system.
Always make a backup of your registry before applying any changes

Changing FAST/TOOLS service startup-time FAST/TOOLS Components
To resolve this issue, increase the time-out value for service startup
process. When you increase this value, FAST/TOOLS has more time to
start and stop. To increase the service startup time, create the following
registry entry:
Subkey HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSe
t\Control
Name ServicesPipeTimeout
Type REG_DWORD
Data The number of milliseconds that you want to give the
services to start or stop. This value depends on the size of
you FAST/TOOLS configuration. For example, to use a
time-out value of 60 seconds, assign a data value of 60,000
to the ServicesPipeTimeout registry entry. A larger data
value does not decrease your computer's performance.
To create this registry entry, follow these steps:

• Click Start, click Run, type regedit, and then click OK.
• Locate and then click the following registry subkey:
"HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\
Control”
• Right-click Control, point to New, and then click DWORD
Value.
• In the New Value #1 box, type ServicesPipeTimeout, and then
press ENTER.
• Right-click ServicesPipeTimeout, and then click Modify.
• Click Decimal, type the number of milliseconds that you want
to wait until the service times out, and then click OK. For
example, to wait 60 seconds before the service times out, type
60000.
• Quit Registry Editor, and then restart the computer.

FAST/TOOLS Components Changing FAST/TOOLS service startup-time

Introduction
Appendix A: Distributed systems
A.1 Introduction
This appendix describes how to set up a distributed FAST/TOOLS
configuration. Furthermore, it describes what kind of actions must be
taken to configure a distributed FAST/TOOLS system.
The structure of this chapter is as follows:
• First, an introduction is given on various notions/concepts that are

directly related to the configuration of a distributed FAST/TOOLS
system. Since these notions/concepts are already covered in much
more detail in other parts of the FAST/TOOLS product
documentation, the notions are just introduced globally. Each of the
paragraphs globally describing a specific concept, contains a
reference to the product document in which the concept is
elaborated further.
The intention of this global introduction to these concepts is, to
make sure that you understand what kind of actions are needed to
configure a distributed FAST/TOOLS system.
• Secondly, the configuration actions are described in more detail and
in a stepwise fashion.
A.2 HMI, host, front-end components

The FAST/TOOLS product can be used both in stand-alone- and
distributed configurations.
In a standalone configuration, the FAST/TOOLS product is installed on
one physical computer system. In a distributed configuration, the FAST/
TOOLS product is installed on multiple physical computer systems
where each of the computer systems is given a specific role. From here
on, the notions "computer system" and "node", are used
interchangeably.
In a FAST/TOOLS system, the following roles are distinguished with

respect to the configuration:
• HMI component:
The component that acts as user interface to the FAST/TOOLS
FAST/TOOLS Installation Manual Windows A-1

Interconnecting components
product. One or more of these HMI components exist in a

distributed configuration.
• Host component:
The component that primarily acts as central data concentrator.
In many situations one such host component exists in a FAST/
TOOLS system. From an "availability" point of view however, it is
possible to have redundant/dual host components. This latter
situation however, is beyond the scope of this discussion.
• Front-end component:
The component that primarily acts as a local data concentrator. In
that role this component gathers/controls a subset of the total
amount of process signals.
In a stand-alone configuration, the roles of HMI, host and front-end are

actually combined in one physical computer system. In a distributed
configuration, the roles of HMI, host and front-end are often mapped
one to one on separate physical computer systems. However, it is also
possible to combine these roles in one and the same physical computer
system (for example a physical computer system that acts as both host
and HMI components).
A.3 Interconnecting components

Although various combinations are possible, in the context of this
discussion and as a reference implementation of a distributed FAST/
TOOLS system, it is assumed that each HMI, host and front-end
component, is mapped upon a separate physical computer system. Each
of these physical systems is connected to a network. Furthermore it is
assumed that:
• One host component exists in such a configuration.
• Each HMI component is connected via a DURM connection to the
host component and each of the front-end components.
• The host component is connected via a DURM connections to each
of the front-end components.
By logically connecting the various FAST/TOOLS components to each

other in the way described above, there is some form of inherent fallback
scenario configured.
Suppose for example that a HMI component fails. Since the other HMI
component is also connected to the host- and front-end components,
there is still access to the host- and front-end components via this other
A-2 FAST/TOOLS Installation Manual Windows

Distribution of data sets
HMI component.
Suppose for example that the host component fails. Without a
redundant/dual host in place, undoubtedly some FAST/TOOLS
functionality will not be available. However by having a DURM
connection between the HMI- and front-end components, it is still
possible to monitor and control vital functions in the process being
supervised.
Remark:
Although possible, it is normally not the case that an HMI component is
connected (via DURM) to other HMI components and/or a front-end
component is connected to other front-end components.
Detailed information about DURM and configuring DURM can be

found in the BUS/FAST System Integrator’s Manual.
A.4 Distribution of data sets

Via the FAST/TOOLS data set model, configuration- and process data
is exhibited to, and controlled/manipulated by, among others, the HMI
components under strict conditions. The FAST/TOOLS functionality
that implements this data set model is called Data Set Services (DSS).
Thanks to DSS, the configuration- and process data can be redundantly
stored in more than one physical computer system. Such a dataset is said
to be "distributed". The advantage of this is obvious: should a physical
computer system fail, there is still the possibility to read the required
data elsewhere. This is entirely transparent to the DSS clients, among
which are the HMI components.
Updating data that is redundantly stored in more than one physical
computer system works slightly differently. With one exception (the
dataset containing item-values), updating a distributed data set requires
the availability of all physical computer systems on which the data is
stored. If one of the computer systems on which the data should be
stored cannot be "reached", the data in the dataset cannot be updated.
The definition of where the data is stored is done via the so called data
set definitions.
Detailed information about DSS and data set definitions can be found in
• DATABASE/FAST System Integrator’s Manual
• DSS Language Manual

Item copy processes
A.5 Item copy processes

In a distributed FAST/TOOLS system, the System Manager makes
specific choices regarding the so called "distribution group" and
"distribution type" attributes of an item. Together, the "value" of these
attributes for a FAST/TOOLS item, determine:
• Whether an item is distributed (image available at host and front-
end) or not.
At most, a FAST/TOOLS item is replicated on 2 nodes.
• Where the master image of the item resides (in the host- or front-
end component).
• In case the item image is solely stored in the front-end component
(not distributed) or in case of a distributed item, which front-end
component (which node) is involved.
For distributed items, the so called item copy processes in the FAST/
TOOLS system, are responsible for updating the "slave" image of an
item. The item copy processes play no role for non-distributed items
(non distributed items only have their image in the host component).
Note:
It is intentional that the plural form is used here: item copy processes.
These processes always act as a pair on a given computer system;
The Master Item copy process on a given computer system is
responsible for passing updates from a master item on its node to the
slave image. It does so by communicating with the Slave Item copy
process on the node where the "slave" image of the item resides.
Briefly then; in a distributed FAST/TOOLS system, a pair of item copy
processs (a master and a slave) must be active on each of the nodes
acting as host and front-end.
Detailed information about distributed items and the item copy

processes can be found in the ITEM/FAST System Integrator’s Manual.
A.6 Distributed ALARM/FAST

In a distributed FAST/TOOLS system, it is possible to use the ALARM/
FAST functionality without the link between host and front-end being
active. In such a configuration, the systems on which the host- and front-
end components are installed, offer independent ALARM/FAST

Distributed Item Interface (GIN DII)
functionality, although they cannot communicate with each other.

Whether or not the distributed ALARM/FAST functionality must be
available can be configured via the alm.sup file.
Deatiled information about distributed ALARM/FAST functionality can

be found in ALARM/FAST System Integrator’s Manual.
A.7 Distributed Item Interface (GIN DII)

The purpose of the Distributed Item Interface is to make item
manipulation transparent across nodes in a distributed FAST/TOOLS
system. When one of the nodes in a distributed environment goes off-
line, the distributed FAST/TOOLS system must continue to operate in
the best possible way. The Distributed Item Interface represents this
functionality transparently to its clients:
• Obtains item attributes from the correct node.
• Sets item attributes on the correct node.
• Redirect item event requests when the node currently servicing the
event request fails.
The Distributed Item Interface uses a (default) node approach/access

scheme to perform these tasks. It is important to note that this default
scheme can be configured via a setup file.
The access scheme works by polling connected FAST/TOOLS nodes to

check for the presence of an items. However this mechanism is
deactivated by default since this generates unnecessary overhead in
system configurations that do not use front-end systems. In a distributed
environment this mechanism must be activated in the setup file of each
system by checking the “Check connected all MDUR nodes” option in
the GIN setup file.
Detailed information about the Distributed Item Interface and the

modification of the node default access scheme can be found in the GIN
Programmer’s Manual.

A.8 Stepwise configuration actions

1 Make sure that all nodes involved "know" which one of them acts
as the host component.
This can be configured in the "dur.sup" setup file on each node, by
simply specifying the host node number in this setup file.
2 Configure the DURM connections.

Make sure a durm_start (UNIX)/durm_start.cmd (Windows) file is
present on the FAST/TOOLS command directory (../tls/com). This
durm_start(.cmd) file is used by the FAST/TOOLS startup-
procedure to start the (various) DURM connection(s).
Make sure a setup file is configured for each of the DURM
processes to be started on a given node. One of the most important
aspects to configure in these setup files is/are the host-name(s) or
IP-address(es) of the counterpart computer systems (the node(s)
with which we want to establish a DURM connection).
3 Configure the distribution of datasets

Configure the distribution of datasets in such a way that all datasets
are present on all host- and front-end- nodes. This can be done by
editing the file "dss_global.dss" on the FAST/TOOLS source
directory (../tls/src) on the node containing the host component.
Look in this file for the macro definition for "mcStorageNodes" and
add "node-labels" to this macro for each of the additional nodes in
the FAST/TOOLS system. Since this macro is used by almost all of
the dataset definitions, all datasets will use this "storage node"
definition automatically. Once the data set definitions are compiled
(during first startup of FAST/TOOLS on the node containing the
host component), DSS knows where the various FAST/TOOLS
data sets can be found.
Note: When the contents of a DSS file is changed, run the DSS
compiler on the directory where the DSS files are stored (usually ../
tls/src). Then stop and restart the FAST/TOOLS.
4 Configure the startup of item copy processes.

Since the item copy processes are not started by default, the file
item_start (UNIX)/item_start.cmd (Windows) must be changed
manually.
Look in this file for the startup commands for the ITMCPM
executable and uncomment these startup commands.
5 Configure PROCESS/FAST node connection scheme.

Next we must tell PROCESS/FAST running on the host node that

it must connect to all the Front-end. This is done by modifying the
setup file opc.sup. In this file remove the line:
NODE_IGNORE = -1
This must only be done on the HOST node.
6 If distributed ALARM/FAST functionality is required, activate this

in the "alm.sup" on each node where distributed ALARM/FAST
functionality must be available.
7 Activate the option “Check all MDUR nodes” in the “gin.sup”

setup file. If required, re-configure the default access scheme.
Note: When a front-end system is
connected to an existing configuration as a
result of system expansion or upgrade then
the following commands must be run on the
server machine once the new front-end has
been connected:
dsschk -r
dsschk -e -r


Index
Index
A durutl 4-4
abbreviations 0-2
ACCESS/FAST 1-1
E
ALARM/FAST 1-1 eqp 4-4
audience 0-1 equipment manager 4-4
AUDIT/FAST 1-1 EQUIPMENT/FAST 1-1
B F
BUS/FAST 1-1 FAST/Start 1-2
fast_clear.cmd 4-5
C fast_start.cmd 4-5
fast_stop.cmd 4-5
component 1-2 front-end 1-2
front-end 1-2 functional tools 1-1
HMI 1-2
server 1-2
configuration
H
distributed 1-1 HISTORY/ FAST 1-1
stand-alone 1-1
conventions 0-2 I
installation
D philosophy 1-1
DATABASE/FAST 1-1 INTEGRATION 1-1
directory Intel PC 1-1
%TLS_ALLUSERS_PATH% 1-7 ITEM/FAST 1-1
%TLS_ROOT_PATH% 1-7
com 1-7, 4-5 L
dat 1-7 license numbers 1-8
exe 1-7
his 1-8 M
hlp 1-8 MMI 1-2
inc 1-8
lib 1-8 O
lst 1-7
objectives 0-1
sav 1-7
ODBC 1-1
src 1-8
sup 1-7
tls 1-7
P
tpl 1-8 phases of installation 1-6
upg 1-8 privileges 1-3
directory structure 1-7 PROCESS/FAST 1-1
distributed configuration 1-1
durecs 4-4
FAST/TOOLS Installation Manual Windows 1

Index
R
REPORT/FAST 1-1
S
server 1-2
setenv.cmd 4-5
Setup File Editor 1-2
SimbaClient 1-4, 3-1
SimbaServer 1-3, 2-1
stand-alone configuration 1-1
StartFASTTOOLS 4-2
U
USER/FAST 1-1
V
Visual Studio 2008 1-3
W
Windows 1-3
Windows 2000 1-1
2 FAST/TOOLS Installation Manual Windows

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction COMPUTE/FAST and FAST/TOOLS
Manual PROCESS/FAST
Language Manual
IM50N06N00-01EN/R10.03
YOKOGAWA ELECTRIC CORPORATION IM50N06N00-01EN/R10.03

YOKOGAWA 9-32 Nakacho 2-chome,
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
0 Preface ...................................................................................0-1
0.1 Manual Objectives .....................................................0-1
0.2 Intended Audience .....................................................0-1
0.3 Structure of this Document ........................................0-1
0.4 Associated Documents ..............................................0-2
0.5 Terminology ..............................................................0-2
0.6 Conventions and Abbreviations ................................0-3
1 Introduction ..........................................................................1-1
1.1 What is PROCESS/FAST? ........................................1-1
1.2 Traditional language versus Java language ...............1-1
1.3 Classes, objects and methods ....................................1-1
1.4 The PROCESS/FAST language ................................1-2
1.5 Functionality ..............................................................1-3
1.6 Using this manual ......................................................1-3
2 Language features ................................................................2-1
2.1 Introduction ...............................................................2-1
2.2 Basic features .............................................................2-2
3 Program structure ................................................................3-1
3.1 Classes and methods ..................................................3-1
3.2 Execution of methods ................................................3-2
3.3 Contents of a method .................................................3-2
4 Data Types .............................................................................4-1
4.1 Introduction ...............................................................4-1
4.2 Constants and variables .............................................4-1
4.3 Timers ........................................................................4-2
4.4 Items ..........................................................................4-2
4.5 Example declarations .................................................4-3
5 Specifying actions .................................................................5-1
5.1 Introduction ...............................................................5-1
5.2 Statements ..................................................................5-1
5.2.1 Introduction ............................................................... 5-1
5.2.2 Assignment ............................................................... 5-1
5.2.3 Addition assignment ................................................. 5-1
5.2.4 The PRINT statement ............................................... 5-2
5.2.5 The ERROR statement .............................................. 5-2
6 Guards ...................................................................................6-1
6.1 Entry-conditions ........................................................6-1
6.2 Conditional execution - the if construct ....................6-1
7 Expressions ............................................................................7-1
7.1 Introduction ...............................................................7-1
PROCESS/FAST Language Manual iii

Table of Contents
7.2 Operators ................................................................... 7-1

7.2.1 Introduction ............................................................... 7-1
7.2.2 Monadic .................................................................... 7-1
7.2.3 Arithmetic ................................................................. 7-1
7.2.4 Relational .................................................................. 7-2
7.2.5 Transitional ............................................................... 7-2
7.2.6 Bitwise ...................................................................... 7-3
7.2.7 String ......................................................................... 7-3
8 Miscellaneous ....................................................................... 8-1
8.1 Introduction ............................................................... 8-1
8.2 Step-wise control ...................................................... 8-1
8.3 The FOR construct .................................................... 8-2
8.4 Built-in functions ...................................................... 8-3
8.5 Limits ........................................................................ 8-3
9 Additional features .............................................................. 9-1
9.1 Introduction ............................................................... 9-1
9.2 Classes, objects and methods .................................... 9-1
9.3 The class prolog ........................................................ 9-2
9.4 Data types .................................................................. 9-3
9.4.1 Introduction ............................................................... 9-3
9.4.2 Signals ....................................................................... 9-3
9.5 Statements ................................................................. 9-7
9.5.1 Introduction ............................................................... 9-7
9.5.2 Triggering .................................................................. 9-7
9.5.3 Usage of the ERROR statement ................................ 9-8
9.6 Enterprise classes and objects ................................... 9-8
10 User defined functions ....................................................... 10-1
10.1 Introduction ............................................................. 10-1
10.2 Layout of a function ................................................ 10-1
11 Attributes ............................................................................ 11-1
11.1 Introduction ............................................................. 11-1
11.2 What is an attribute? ............................................... 11-1
11.3 Declaring attributes ................................................. 11-2
11.4 Attributes and prompts ............................................ 11-2
11.4.1 Using prompts ......................................................... 11-2
11.5 Advice when using attributes with signals .............. 11-3
12 Class inclusion .................................................................... 12-1
12.1 Introduction ............................................................. 12-1
12.2 Inheritance ............................................................... 12-1
12.3 The CONTAINS statement ..................................... 12-2
12.4 Triggers, signals and attributes ............................... 12-2
12.5 Nesting .................................................................... 12-3
iv PROCESS/FAST Language Manual

Table of Contents
13 Triggers ...............................................................................13-1
13.1 Introduction .............................................................13-1
13.2 The TRIGGER statement ........................................13-1
13.3 Other uses ................................................................13-2
13.3.1 Triggers and classes ................................................ 13-2
13.3.2 Triggers and signals ................................................ 13-2
13.3.3 Triggers and items ................................................... 13-3
13.3.4 Triggers and timers ................................................. 13-3
13.4 The TRIGGERED BY construct .............................13-3
14 Reference .............................................................................14-1
14.1 Introduction .............................................................14-1
14.2 Program structure ....................................................14-1
14.2.1 Class ........................................................................ 14-1
14.2.2 Epilog ...................................................................... 14-3
14.2.3 Functions ................................................................. 14-4
14.2.4 Method .................................................................... 14-6
14.2.5 Prolog ...................................................................... 14-7
14.2.6 Sequence ................................................................. 14-9
14.2.7 Sub-sequence ........................................................ 14-10
14.3 Declarations ...........................................................14-10
14.3.1 Attributes ............................................................... 14-11
14.3.2 Constants ............................................................... 14-13
14.3.3 Contains ................................................................ 14-14
14.3.4 For ......................................................................... 14-15
14.3.5 Items ...................................................................... 14-16
14.3.6 Prompts ................................................................. 14-18
14.3.7 Signals ................................................................... 14-19
14.3.8 Compatibility ........................................................ 14-28
14.3.9 Timers ................................................................... 14-28
14.3.10 Variables ............................................................... 14-30
14.4 Guards ....................................................................14-30
14.4.1 Entry-conditions .................................................... 14-30
14.5 Statements ..............................................................14-31
14.5.1 If ............................................................................ 14-31
14.5.2 Assignment ........................................................... 14-32
14.5.3 Addition assignment ............................................. 14-33
14.5.4 Error ...................................................................... 14-34
14.5.5 Print ....................................................................... 14-35
14.5.6 Trigger ................................................................... 14-36
14.6 Operators ...............................................................14-37
14.6.1 Arithmetic ............................................................. 14-37
14.6.2 Bitwise .................................................................. 14-37
14.6.3 Boolean ................................................................. 14-37
14.6.4 Monadic ................................................................ 14-38
14.6.5 Relational .............................................................. 14-38
14.6.6 String ..................................................................... 14-39
14.6.7 Transitional ........................................................... 14-39
PROCESS/FAST Language Manual v

Table of Contents
14.7 Built-ins ................................................................. 14-40

14.8 Miscellaneous ....................................................... 14-46
14.8.1 Expressions and precedence .................................. 14-46
14.8.2 Comments ............................................................. 14-47
14.8.3 Current time .......................................................... 14-48
14.8.4 Format strings ....................................................... 14-49
14.8.5 Quote operator ....................................................... 14-51
14.8.6 STEP ..................................................................... 14-52
14.8.7 Useful constants .................................................... 14-53
15 Using DSS Datasets ............................................................ 15-1
15.1 Introduction ............................................................. 15-1
15.2 Just enough DSS ..................................................... 15-1
15.3 The Basic DSS interface ......................................... 15-3
15.3.1 DSS_READ_STRING ............................................ 15-3
15.3.2 DSS_READ_INTEGER ......................................... 15-4
15.3.3 DSS_READ_FLOAT .............................................. 15-6
15.3.4 DSS_UPDATE_STRING ....................................... 15-7
15.3.5 DSS_UPDATE_INTEGER .................................... 15-9
15.3.6 DSS_UPDATE_FLOAT ....................................... 15-11
15.4 The Advanced DSS Interface ................................ 15-12
15.4.1 Using the advanced routines ................................. 15-12
15.4.2 DSS_OPEN ........................................................... 15-14
15.4.3 DSS_OPEN_ALL ................................................. 15-16
15.4.4 DSS_CLOSE ......................................................... 15-17
15.4.5 DSS_READ_EQUAL ........................................... 15-18
15.4.6 DSS_READ_NEXT .............................................. 15-20
15.4.7 DSS_GET_STRING ............................................. 15-22
15.4.8 DSS_GET_FLOAT ............................................... 15-24
15.4.9 DSS_GET_INTEGER .......................................... 15-26
15.4.10 DSS_PUT_STRING ............................................. 15-28
15.4.11 DSS_PUT_FLOAT ............................................... 15-30
15.4.12 DSS_PUT_INTEGER ........................................... 15-32
15.4.13 DSS_UPDATE ...................................................... 15-34
15.4.14 DSS_DELETE ...................................................... 15-36
15.4.15 DSS_INSERT ....................................................... 15-38
15.4.16 DSS_SET_FILTER ............................................... 15-40
15.4.17 DSS_REMOVE_FILTER ..................................... 15-42
15.4.18 DSS_ERROR_LOG .............................................. 15-43
16 AGA calculations ............................................................... 16-1
16.1 Introduction ............................................................. 16-1
16.2 AGA functions ........................................................ 16-2
16.2.1 AGA_INIT() ........................................................... 16-2
16.2.2 AGA_ERROR() ...................................................... 16-3
16.2.3 AGA_CALC() ......................................................... 16-4
16.2.4 AGA_COMP() ........................................................ 16-4
16.2.5 AGA_SP() ............................................................... 16-5
16.2.6 AGA_FT() ............................................................... 16-6
vi PROCESS/FAST Language Manual

Table of Contents
16.2.7 AGA_DP() .............................................................. 16-6

16.2.8 AGA_K() ................................................................ 16-7
16.2.9 AGA_MU() ............................................................. 16-7
16.2.10 AGA_SG() .............................................................. 16-8
16.2.11 AGA_ATM_PRESS() ............................................. 16-8
16.2.12 AGA_POSITION() ................................................. 16-9
16.2.13 AGA_DEADBAND() ........................................... 16-10
16.2.14 AGA_GPA2172() ................................................. 16-10
16.2.15 AGA_3_METER() ................................................ 16-11
16.2.16 AGA_CONE() ...................................................... 16-12
16.2.17 AGA_PULSE() ..................................................... 16-13
16.2.18 AGA_8_GROSS() ................................................ 16-14
16.2.19 AGA_9_INIT() ..................................................... 16-14
16.2.20 AGA_9_CPSM() ................................................... 16-16
16.2.21 AGA_9_CTSM() .................................................. 16-16
16.2.22 AGA_9_PCORR() ................................................ 16-17
16.2.23 AGA_9_T_RAW() ............................................... 16-17
16.2.24 AGA_R_Z_BASE() .............................................. 16-18
16.2.25 AGA_R_Z_FLOW() ............................................. 16-18
16.2.26 AGA_R_MRHO_BASE() .................................... 16-18
16.2.27 AGA_R_MRHO_FLOW() ................................... 16-19
16.2.28 AGA_R_RHO_BASE() ........................................ 16-19
16.2.29 AGA_R_RHO_FLOW() ....................................... 16-20
16.2.30 AGA_R_FLOWRATE() ....................................... 16-20
16.2.31 AGA_R_ATM_PRESS() ...................................... 16-21
16.2.32 AGA_R_SG() ....................................................... 16-21
16.2.33 AGA_R_SG_REAL() ........................................... 16-21
16.2.34 AGA_R_Y1() ........................................................ 16-22
16.2.35 AGA_R_CD() ....................................................... 16-22
16.2.36 AGA_R_EV() ....................................................... 16-23
16.2.37 AGA_R_FPV() ..................................................... 16-23
16.2.38 AGA_R_RAW_FLOW() ...................................... 16-23
16.2.39 AGA_R_SOS() ..................................................... 16-24
16.2.40 AGA_R_IDEAL_HV() ......................................... 16-24
16.2.41 AGA_R_REAL_HV() .......................................... 16-25
16.3 Example calculation ..............................................16-25
Appendix A:Examples....................................................................A-1
A.1 Introduction ..............................................................A-1
A.2 Class TWIN_UNIT_CONTR ...................................A-1
A.3 Classes SENSOR and FLUID_VESSEL ..................A-3
Appendix B:Reserved Words ........................................................ B-1
PROCESS/FAST Language Manual vii

Table of Contents
viii PROCESS/FAST Language Manual

Manual Objectives Preface
0 Preface
0.1 Manual Objectives

• To provide system managers/integrators with an overview of the
functionality of the PROCESS/FAST Traditional programming
language. The PROCESS/FAST Java programming language is
described in the PROCESS/FAST Java Language Manual.
0.2 Intended Audience

This manual is intended for system managers/integrators who wish to
write their own application software within their FAST/TOOLS
environment.
The reader is assumed to have some knowledge of the FAST/TOOLS
philosophy.
0.3 Structure of this Document

This manual contains 14 chapters and 2 appendices. Chapters 1 to 8
cover the basic language definition. Chapters 9 to 13 are only applicable
to those possessing the full PROCESS/FAST licence. Chapter 14 and
the appendices provide reference information.
• Chapter 1 gives a short introduction to PROCESS/FAST.
• Chapter 2 introduces the concepts of the PROCESS/FAST
language.
• Chapter 3 describes the language structures that define the layout of
a PROCESS/FAST program.
• Chapter 4 is a description of how program data is declared and
used.
• Chapter 5 describes the statements available within the language.
• Chapter 6 provides information on controlling the flow within a
program.
• Chapter 7 explains how expressions are formed.
PROCESS/FAST Language Manual 0-1

Preface Associated Documents
• Chapter 8 covers miscellaneous topics applicable to the basic

language definition.
• Chapter 9 provides information on the additional features found in
the full language that augment the basic definition.
• Chapter 10 describes how user-defined functions can be defined.
• Chapter 11 introduces what an attribute is and how it can be used.
• Chapter 12 describes how class definitions can be included within
other classes.
• Chapter 13 describes the use of triggers.
• Chapter 14 provides a reference guide for the complete language.
• Appendix A contains two sample PROCESS/FAST programs.
• Appendix B is a list of reserved words.
0.4 Associated Documents

1 USER/FAST User Manual.
2 PROCESS/FAST Java Language Manual.
3 PROCESS/FAST Programmer’s Guide.
4 The C Programming Language, Brian W.Kernighan and Dennis M.
Ritchie, or C - A Reference Manual, Samuel P. Harbison, Guy L.
Steele Jr., both published by Prentice Hall.
0.5 Terminology
The following list contains words that have a special meaning in the
context of PROCESS/FAST.
Activation The process of getting an object to begin executing
its defined actions.
Attribute Characteristics of classes and objects that can
be seen from the outside world.
Class A generic template defining actions and
characteristics representing a particular type
of component within a plant.
Identifier A logical name used to reference data items within
a method.
Method A sequence of actions that is performed when an
object is activated.
Object An entity derived from a class that represents a
0-2 PROCESS/FAST Language Manual

Conventions and Abbreviations Preface
specific component within a plant.

Trigger A mechanism for indicating to an object that
actions need to be performed.
0.6 Conventions and Abbreviations

The following conventions are used in this manual:
CONVENTION MEANING
() Parentheses when used in routine syntax indicates

a list of arguments that have to be passed.
[] Brackets indicate that the enclosed item is optional.
<> Angle brackets when used in routine syntax

indicates a program argument.
{} Braces when used in routine syntax indicates a

program comment.
[,...] Indicates that the previous item may be repeated

one or more times
... Indicates that not all of the statements are shown.
| Indicates that either the item to the left or to the

right of the bar may be specified

"" Used in format descriptions. Double quotes

indicate that the character is to be taken literally.

variable.
<file_name>+ Used in syntax descriptions. Exactly one or more

file names may be entered.

Preface Conventions and Abbreviations
n.u. not used
output This font is used to indicate output on a terminal
input This font is used to indicate input from the user

What is PROCESS/FAST? Introduction
1 Introduction
1.1 What is PROCESS/FAST?

PROCESS/FAST is a tool that allows system managers and system
integrators to set up and maintain a FAST/TOOLS system faster and
more efficiently. Frequently within a system, there will be many
components that are almost identical with only a few specific
characteristics distinguishing them from each other. In PROCESS/
FAST each of these process components will relate to a FAST/TOOLS
‘item’. Monitoring and manipulating these items makes it possible to
control the process. With PROCESS/FAST it is not necessary to define
items separately for every component in the process. It is much more
logical to view process system in terms of its actual components rather
than through items.
1.2 Traditional language versus Java

language
The Traditional language should be used when:
• Performance is important.
• Large number of item event must be processed.
The Java language should be used when:
• Complex process algorithms must be programmed.
In general, use Java language only in those situations where the
Traditional language cannot fulfill the requirements. The Java language
includes the same functionality as can be build using the Traditional
language and more.
1.3 Classes, objects and methods

PROCESS/FAST uses a concept based on ‘classes’ and ‘objects’. A
class can be seen as a generic template. This template contains all the

Introduction The PROCESS/FAST language
information needed to represent a typical component within a system,

such as a valve for example. Some of this information is common to all
valves, but some characteristics in the template are “blank”. This is
because the data placed in these blanks differentiates one type of valve
from another. In addition a class also has ‘methods’. The methods
represent the actions that a type of component performs within the
system.
Once a class has been created, it is then possible to derive objects from
this class. An object is related to a specific physical component within a
process. It has all the characteristics of its class with the “blanks” filled
in. The characteristics are given values that are peculiar to this object.
The object will perform the actions as defined in the class methods. It is
then possible to control the component within the system by
manipulating some of the characteristics in the object.
By means of classes and objects, it is much easier and quicker to set up
a FAST/TOOLS system since the common characteristics of one type of
process component only need to be defined once. It is also more natural
to be able to control a process in terms of its components.
1.4 The PROCESS/FAST language

The PROCESS/FAST language is used to define the methods, that is the
actions that an object will perform within the system. The language
bridges the gap between the tools widely used for programming in
industrial environments such as Programmable Logic Controller (PLC)
languages and computer-oriented languages such as BASIC,
FORTRAN and C.
Its main functions are:
• To make it possible to program application software within the
FAST/TOOLS system.
• To perform calculations on items and/or item attributes.
Its major features are:
• Immediate retrieval and/or updating of input and output directly
from the item table.
• Sequential field control.
• Item access by name.

Functionality Introduction
By incorporating the simplicity of PLC languages, and by being able to

express complex control algorithms, the PROCESS/FAST language
makes it possible to control a process completely.
1.5 Functionality
The PROCESS/FAST functionality is split into two parts. Which
functionality is available depends on which licence type is in use. The
first part offers the basic set of language capabilities. However multiple
object functionality is not available. Instead the methods act as a
program for performing some specific operation.
With the full licence of PROCESS/FAST, the full class and object
functionality is available in addition to the basic language set. The
language set is also extended with some more advanced features to take
advantage of this extra functionality.
1.6 Using this manual

The manual is divided into a number of chapters explaining the concepts
and usage of the language features. The first part describes the basic
language set. After this the more advanced features of the language are
introduced. However the more advanced features are only available to
those possessing the full PROCESS/FAST licence. After the language
description is a reference guide which explains the full syntax of the
language. Finally a set of appendices are provided including a list of all
reserved words and some example methods.

Introduction Using this manual

Introduction Language features
2 Language features
2.1 Introduction
The PROCESS/FAST language is used to define the actions that are
used to control a part of the plant. To be able to understand the structure
and objectives of the PROCESS/FAST language, a boiler will be taken
as an example.
Firstly the actions required to control the boiler must be identified. In the
first place, it must be possible to turn it on and off. Secondly it must be
possible to raise or lower the temperature of the water in the boiler and
to monitor the water temperature so that action can be taken if it
becomes too high or too low. Normally the boiler would be turned on
and off by hand and the temperature regulated by providing a heat
source. By using some kind of sensor in the water itself, the temperature
can be monitored.
100 H-H Alarm

90
H
75
60 N
45
L
30
15 L-L Alarm
0
t
sensors
Figure 2-1 Boiler example
What are the disadvantages of all these manual operations? As with

everything that is done by hand, as opposed to by machine, the speed
with which the operation is carried out is relatively slow. Consider the
interval between deciding that the boiler has to be switched on and the
time that it is actually switched on.

Language features Basic features
The problem is how to regulate all the above-mentioned operations in

such a way that the process can be fully controlled as efficiently as
possible. PROCESS/FAST methods provide a means of doing this.
2.2 Basic features

The components found in the basic set of PROCESS/FAST language
are:
• Classes and methods
These define the program structure and “procedures” within it.
• Declarations
Defines the data to be used within the program.
• Statements
The actual actions to be performed.
• Guards
Used to control whether part of a program will be executed
depending on certain conditions.
• Expressions
Each of these elements will be introduced and explained in the course of
this tutorial. The majority of the examples in this document are
simplified extracts from the PROCESS/FAST language example
provided in the appendices. It is advisable to study this example first to
become familiar with the PROCESS/FAST language.
Note: A PROCESS/FAST program uses items.
Items can be created in several ways as
described in ref[1]. However, a special
feature of PROCESS/FAST is the ability to
define its own required items.
See the description of signals in SubSection
9.4.2.

Classes and methods Program structure
3 Program structure
3.1 Classes and methods

A PROCESS/FAST program is called a class and has a unique name. A
class can be equated with the program body. A class itself contains
actions, called methods, also possessing unique names. These can be
compared to tasks.
Defining the start of a class is done by supplying the word CLASS
followed by the name of the class. Similarly a class ends with the word
ENDCLASS followed by the class name. Everything else that makes up a
class is included between these keywords.
The following example defines a class called BOILERCONTROL:
CLASS BOILERCONTROL;
...
ENDCLASS BOILERCONTROL;
This class currently does not do very much. Methods need to be defined
which will contain the actions that need to be performed. A method can
be defined by supplying the word METHOD followed by the method name.
A method is ended with the word ENDMETHOD followed by the method
name.
The following program structure relates to the control system for the
boiler in the previous example and illustrates a class containing two
methods. In the first method, all relevant variables are defined (for
example boiler temperature, pressure etc.) which must be checked so
that emergency situations can be detected. In the second method the
temperature of the furnace is regulated.
CLASS BOILERCONTROL;
...
METHOD check_safety_conditions;
...{sequence of actions}
ENDMETHOD check_safety_conditions;
METHOD raise_temperature;
... {sequence of actions}
ENDMETHOD raise_temperature;
...
ENDCLASS BOILERCONTROL;

Program structure Execution of methods
Note the use of comments in the example. Comments can be placed

anywhere within a class where annotation is deemed necessary. A
comment begins with an open brace ({) and ends with a close brace (}).
Anything between the braces is ignored.
3.2 Execution of methods

The actions and status of a class are controlled by a so-called control
item. By changing the status of this item, execution of the class methods
can be controlled.
By setting the control item to BLOCKED, it is possible to suspend the
methods. The methods will remain in this halted state until they are
UNBLOCKED, when they resume running.
It also possible to switch the methods OFF-LINE by means of the
control item. In this case the methods will stop running altogether. When
the control item is set to ON-LINE, the method will start executing as
though it had been started for the first time. See Section 0.4 Ref.1 for
more information on controlling methods.
When a class is active all methods will be executed simultaneously.
Taking the example above, although the check_safety_conditions
method precedes the raise_temperature method, that does not mean
that they will be executed in that order. That is why methods are more
analogous to tasks rather than procedures.
3.3 Contents of a method

Methods may contain:
• An entry-condition
• A prolog
• A body
• An epilog
Entry-condition
The entry-condition governs whether a particular method will be
activated or not. An entry-condition is indicated by the word

Contents of a method Program structure
ENTRYCONDITION. The result of an entry-condition is said to be either

TRUE or FALSE depending on whether the condition is satisfied. Chapter
6 Guards explains entry-conditions in more detail.
Prolog
The prolog part is optional and may only appear once in any particular
method. Typically it is used to perform initialization actions when a
method is first run. It is executed when the entry-condition is TRUE and
the method is executed for the first time (or after the class has been put
on-line again). The body part will then be executed and the epilog part
will be skipped. A prolog is indicated by including the word PROLOG
after the start of a method. Anything after this word, but before the body
part, is part of the prolog.
Body
The body part contains the main work of the method and is indicated by
the word BODY. The body part will be executed as long as the entry-
condition is TRUE and class is on-line. When there is a prolog part the
body will be executed after the prolog.
Epilog
The epilog will be executed when the class has been put off-line or the
entry-condition returns FALSE. It is typically used to perform clean-up
actions after the method body has done its work. The start of an epilog
is identified by the word EPILOG.
In order to make this clearer, the following tables summarize whether or
not a method should be executed. Which parts of the method are
executed depending on the status of the control item and whether the
entry-condition is satisfied:
Table 1:
Table to indicate which parts of a method are executed depending on the
change of the control item and entry-condition (initial old state is inactive)
Entry
Old state On-line New state Prolog Body Epilog
condition
inactive FALSE TRUE inactive

inactive FALSE FALSE inactive
inactive TRUE TRUE active * *
inactive TRUE FALSE inactive
active FALSE TRUE inactive *
active FALSE FALSE inactive *

Program structure Contents of a method
Table 1:
Table to indicate which parts of a method are executed depending on the
change of the control item and entry-condition (initial old state is inactive)
Entry
Old state On-line New state Prolog Body Epilog
condition
active TRUE TRUE active *

active TRUE FALSE inactive *

Introduction Data Types
4 Data Types
4.1 Introduction
Data within classes and methods are referenced using identifiers. These
identifiers refer to an element of a particular kind and are stated using
declarations. Declarations can be either global, meaning valid across all
methods, or local which means they are limited to the method in which
it is contained. A local declaration always overrules a global declaration
in any given method. Each declaration introduces one or more
identifiers. The different kinds of declarations are:
• Constants
• Variables
• Timers
• Items
In addition data can be given a representation:
• Numeric representations
These represent numeric values and can be one of INTEGER,
FLOAT or BOOLEAN. BOOLEAN is special in that it represents
an integer that can only have one of two values: TRUE/ON or
FALSE/OFF.
• String representation
A string consists of any sequence of characters enclosed between
double quotes.
4.2 Constants and variables

A constant contains a fixed value that cannot be modified during
execution. A variable on the other hand contains a value that can be
modified during program execution. The type of a constant or variable
is determined at compilation time from the context of its use. Assigning
a value to a variable will cause the expression to be converted to fit that
of the variable. This means floats can be assigned to integers and vice
versa,

Data Types Timers
Declaring a constant or variable is performed by including the word

CONSTANT or VAR after the start of a class or method, followed by the
declaration.
4.3 Timers
Timers possess both a value and a status. The value indicates how much
time is left before it expires. The status indicates the current condition of
the timer. A timer can have one of three states: STOPPED, RUNNING
or EXPIRED. Immediately after creation they have the status
EXPIRED.
Both the status and the value of a timer can be modified. The status and
value may be modified explicitly by means of assignment statements.
The status may be modified implicitly when a value is assigned or the
timer expires. By assigning a value to a timer, its status is set to
RUNNING (irrespective of its previous status) and after the assigned
number of seconds have elapsed the status is changed to EXPIRED.
Assigning the value zero (0) to a timer forces its status to immediately
become EXPIRED.
A PROCESS/FAST program can change the status of a timer to
STOPPED or EXPIRED before the specified interval has expired. By
subsequently changing back the status of a STOPPED timer to
RUNNING, the remaining time interval will pass before the status
becomes EXPIRED. Setting a timer to EXPIRED resets its value. This
means any remaining time is set zero. It is also possible to restart the
timer by assigning a new value to the timer.
The TIMER, when referenced, always contains the remaining interval
until expiration. Globally declared timers, which may be used in entry-
conditions, must be controlled from within methods as there are no
executable statements allowed outside methods.
4.4 Items
Items are used in FAST/TOOLS systems to interface process input and
output signals. When an item is declared, the identifier must be specified
in the following way:
[<node>:]<installation>.<unit>.<tag>[.<sub>]

Example declarations Data Types
Identifiers referring to items may be qualified to access attributes other

than their value such as status or limits. By default, reference to an item
identifier is taken to mean its value. Referencing other attributes can be
done by supplying a back quote and the name of the attribute after the
identifier. For example: inst_1.unit_1.temperature’status
Array items are also supported. An array item is an item that contains a
number of values in the form of an array. Each of these values can be
accessed by specifying the appropriate index.
From R10.01<installation> maps upon sections on the first level
and <unit> maps on the sections on the second level. This means that
from R10.01 the item declaration works only for items defined in
sections on the second level. It is strongly advised not to use the item
declaration by signals instead.
4.5 Example declarations

The following example illustrates the use of declarations and identifiers:
CLASS twin_unit_control;
...
CONSTANT {global declarations}
seq_init:= 0,
init_phase := 1,
raise_temp := 2,
test_phase := 3;
VAR
emergency_switch;
...
...
CONSTANT {local declarations}
max_raise := 1800;
ITEM
inst_1.unit_1.furnace_temp,
inst_1.unit_1.left_pressure,
inst_1.unit_1.right_pressure;
TIMER
guard_raise;
...
...
ENDCLASS twin_unit_control;

Data Types Example declarations

Introduction Specifying actions
5 Specifying actions
5.1 Introduction
Now that the structure of a program and its related data has been
introduced, the actual actions to be performed can be defined. The
actions within a method are called statements. Note that statements are
only allowed in the bodies of methods.
5.2 Statements
5.2.1 Introduction
When a method is executed, it performs a series of actions and then

stops. In the PROCESS/FAST language, these actions are expressed as
statements. The following kind of statements are available:
• Assignment
• Addition assignment
• Print
• Error
5.2.2 Assignment
The assignment statement has already been seen during the declaration
of constants. An assignment statement assigns the result of an
expression to either a variable, item or timer. The following example
illustrates the use of the assignment statement:
my_signal := 12;
5.2.3 Addition assignment
The addition assignment statement adds the specified value to the

current value of an identifier and assigns the result. The following
example illustrates the use of the addition assignment statement:

Specifying actions Statements
my_signal :+ 12;
The additional statement can also be used for subtracting and assigning
a value to a signal by simply negating the value, see the following
example:
my_signal :+ -12;
5.2.4 The PRINT statement
If the status of a particular parameter that appears on the screen needs to

be confirmed on paper, a print statement will print the expression
immediately following it. The following example illustrates the use of
the print statement:
PRINT "Twin_unit temperature = ", temp_setpoint;
5.2.5 The ERROR statement
The ERROR statement is used for signalling error conditions. When an

error statement is encountered within a method it is logged via the
default BUS/FAST logger. The ERROR statement is similar in use to the
print statement and accepts a string expression as argument. The
following example illustrates the use of the ERROR statement:
ERROR "my_signal contains a zero value";
Further execution of the method is terminated when the error statement
is encountered. The method will, however, start again the next time the
class is activated.

Entry-conditions Guards
6 Guards
6.1 Entry-conditions
If a class is on-line, all methods contained in that class are
simultaneously active. However, it is possible (and often essential) to
give methods and statements a “guarded” status. This means that a
particular series of actions should not be executed unless a certain
condition has been fulfilled. In other words, the execution of a method
can be prevented or delayed simply by introducing a conditional
expression at the beginning of that method. These guards are referred to
as entry-conditions.
Imagine that the temperature of the boiler needs to be raised. Having
specified the temperature level, a constraint is introduced: the
temperature must only be allowed to rise if the emergency switch is off.
This is then the entry-condition.
...
METHOD raise_temperature;
ENTRYCONDITION emergency_switch = OFF;
...
temp_setpoint := 100.0;
PRINT "Twin_unit temperature = ", temp_setpoint,
"degree C";
...
ENDMETHOD raise_temperature;
...
6.2 Conditional execution - the if construct

Another method of influencing the execution of a method is by using an
“if” construct. The following example illustrates that the emergency
switch should be activated if the temperature reaches or exceeds 270°C
or if the pressure in the furnace exceeds the HIGH_HIGH limit.
...
...
IF temperature >= 270.0 OR
inst_1.unit_1.pressure’status = HIGH_HIGH

Guards Conditional execution - the if construct
THEN
inst_1.unit_1.emergency_switch := ON;
...
ENDIF;
...
...

Introduction Expressions
7 Expressions
7.1 Introduction
Expressions in entry-conditions, “if” constructs and assignment
statements are evaluated when they are encountered during the
execution of methods. Expressions consist of elements (referred to by
means of identifiers) and operators.
7.2 Operators
7.2.1 Introduction
Examples of operators are:
• Monadic (NOT, -, +)
• Arithmetic (+, -, *, /)
• Boolean (AND, OR, XOR)
• Relational (=, <, >, <=, >=, <>)
• Transitional (=:, <:, >:, <=:, >=:, <>:)
• Bitwise ( |, &, ^, ~ )
• String ( || and ,)
7.2.2 Monadic
Monadic operators have higher precedence than all other operators.

These operators are applied to a single argument. Note that addition and
negation are applicable only to numeric types. The result of applying
logical NOT is a boolean value.
7.2.3 Arithmetic
Arithmetic operators are applicable to numeric types and perform basic

mathematical operations. The multiplication and division operators have
the highest precedence, followed by subtraction and addition. The

Expressions Operators
implicit precedence rules may be overridden by the use of brackets

however.
7.2.4 Relational
Relational operators have lower precedence than arithmetic operators

and are applicable to all types. They are used for comparing one
argument with another. The result of a relational operation is of type
boolean.
7.2.5 Transitional
Transitional operators are used for detecting when a change occurs, that
is at the moment an argument “becomes” a certain value. The major
difference between these and relation operators is that it is only true the
first time the expression is evaluated after the relational operator has
become true. Transitional operators have the same precedence as
relational operators. Transitional operators are applicable to all types.
The result of a transitional operation is of type boolean.The following
example illustrates the use of transitional operators:
operator switch =:ON

temperature >=: setpoint
ON
OFF alarm
t1 t2 t3 t4 t5
1) IF alarm = ON THEN action; ENDIF;

2) IF alarm =: ON THEN action; ENDIF;
Figure 7-1 Transitional operators
...
ENTRYCONDITION NOT emergency_switch;
...
IF inst_1.twin_unit.furnace_temp’status =: HIGH_HIGH OR
inst_1.twin_unit.left_pressure’status =: HIGH_HIGH OR

Operators Expressions
inst_1.twin_unit.right_pressure’status =: HIGH_HIGH
THEN
inst_1.twin_unit.emergency_switch := ON;
...
ENDIF;
...
...
By using the transitional operator in the above example, the actions
within the if-construct are only executed immediately after the
expression becomes true, i.e. at the moment that either status of the
relevant items becomes HIGH_HIGH. Transitional operators may also
be used in entry-conditions.
7.2.6 Bitwise
The bitwise operators are used for testing, setting and masking option
flags. They can be applied in a number of situations where a
combination of options can be supplied to some attribute. Bitwise
operators are only applicable to numeric types.
7.2.7 String
Currently only one string operator is available, concatenation. This is

used for joining strings together. This feature is particularly useful when
creating strings from string variables.
Concatenation can be performed by using || or a comma (,). The first
form is used when concatenating two strings. The second form can be
used for this purpose but also used for concatenating strings and numeric
values. Note that the maximum length of a string is restricted to 255
characters.

Expressions Operators

Introduction Miscellaneous
8 Miscellaneous
8.1 Introduction
The previous chapters have introduced the basic concepts and
mechanisms provided in the PROCESS/FAST language. This chapter
covers a number of miscellaneous points to note when using the
language.
8.2 Step-wise control

Whether a class is on-line or off-line is determined by the status of the
control item associated with it. However the value of this item can also
be used for controlling the methods.
Imagine a class is to operate in a number of different states, each state
represented by a method. Using the value attribute of the control item it
is possible to move through these states in a “step-wise” fashion. This
can be done by checking the value of the control item in the entry-
condition of the method. Similarly by modifying the value it is possible
to step to another state within the class.
The value of the control item can be accessed by means of the word
STEP. The example below illustrates the use of STEP:
...
CONSTANT { global declarations }
seq_init := 0,
init_phase := 1,
raise_temp := 2,
test_phase := 3;
...
METHOD seq_init;
ENTRYCONDITION STEP = seq_init;
{ Note that initially the value }
{ of the control item is zero}
...
STEP := init_phase; { go to next step }
...
ENDMETHOD seq_init;
METHOD init_phase;

Miscellaneous The FOR construct
ENTRYCONDITION STEP = init_phase;

...
STEP := raise_temp; { go to next step }
...
ENDMETHOD init_phase;
...
8.3 The FOR construct

Note: From R10.01 it is strongly advised not to
use the FOR construct and item
declarations because they map upon
sections on the second level only. Use
signals instead.
When referring to item names within methods the full item name
including the installation and unit must be specified. It is possible by
means of the FOR construct to indicate which node, item installation and
unit is to be used as the default. When searching for items, the name
specified in the FOR construct is prefixed to the item name. If this search
fails then the specified item name is sought without the prefix.
All items encountered in a method will be influenced by the preceding
FOR construct. Thus it is possible to use more than one FOR within a
method, where each successive FOR will overrule the value of the
previous one.
The following example illustrates the use of the FOR construct:
FOR inst_1;
...
ITEM twin_unit.emergency_switch;
{ refers to inst_1.twin_unit.emergency_switch }
...
...
FOR node_1:inst
CONSTANT
max_raise := 1800;
ITEM
furnace.temp,
{ refers to node_1:inst.furnace.temp }
left.pressure,
right.pressure;

Built-in functions Miscellaneous
{ here furnace, left and right are }

{ unit_level names. }
TIMER
guard_raise;
...
...
ENDCLASS twin_unit_control;
8.4 Built-in functions

The PROCESS/FAST language offers a large set of built-in functions,
mainly for mathematical purposes. Usage of a built-in function is as
follows:
<built-in> (<arg1>, <arg2>...)
where <built-in> is the name of the built-in function and arg1, arg2
represent the arguments to be supplied to the function. For a complete
description of the built-in functions and required arguments see Chapter
14. A few examples of available functions are:
• Arithmetic functions
e.g ABS, TRUNC, SQRT, POWER, LOG, EXP, SIN, COS, TAN
• String manipulation functions

e.g. LENGTH, LEFT, MIDDLE, RIGHT
• Trigger detection functions

e.g. TRGSIG_VALUE, TRGSIG_OLD_VALUE,
TRGSIG_STATUS, TRGSIG_QUALITY
• Signal manipulation functions

e.g. SIG_UPDATE, SIG_OFFLINE,
SIG_FORCE_ALARM_STATE
8.5 Limits
The following list indicates the restrictions that exist in relation to the
length of identifiers and other names:
• Identifier names are limited to 50 characters;

Miscellaneous Limits
• The node name part of the process variable is limited to 24

characters;
• Other parts of process variable names are restricted to 15 characters
in length.

Introduction Additional features
9 Additional features
9.1 Introduction
The previous chapters have introduced the features and facilities
available within the basic language set of PROCESS/FAST. With this
language it is possible to create methods for controlling a specific
process situation.
With the full functionality of PROCESS/FAST, these methods form
only a part of a larger concept. In the first part of this manual the reader
was introduced to the concept of classes and objects. The PROCESS/
FAST language provides a means of describing the actions that these
objects within the system will perform. The full language offers extra
facilities to take advantage of these concepts. These facilities will be
described in successive chapters of this document.
This chapter introduces extensions to the basic language set described in
the previous chapters. The features described in this chapter and
successive chapters are only available to those users possessing the full
PROCESS/FAST licence.
9.2 Classes, objects and methods

Frequently in a process there are many components of the same type.
These components perform similar functions. However, certain
characteristics makes each component unique from others of the same
type. The full language set offers facilities that make the job of defining
these components easier.
In the full language set, classes define a generic template that represents
a particular type of component within a system. The class definition
contains methods which define the actions that the derived objects will
perform. Objects are then derived from the classes which represent the
actual specific components within the system. An object has
characteristics that are peculiar to it and some that are shared with all
objects belonging to the class.

Additional features The class prolog
In the basic set, the class methods could be seen to correspond with the
actions performed by one object. With the full set, the class is a template
from which many objects can be defined.
9.3 The class prolog

One result of the concept of classes and objects is the use of the word
PROLOG. In the basic functionality the PROLOG was found at the start of
a method and defined a set of actions to be performed when a method
first became on-line. In terms of classes and objects, the PROLOG has an
additional function, this is; indicating the actions to be performed when
an object is created from the class.
The class prolog appears directly after the CLASS name. It is not
mandatory, but if used the word BODY must be included after the prolog
to indicate where the class prolog ends and the methods begin.
The basic program structure of a class can be seen as follows:
CLASS my_class;
PROLOG
...
BODY
...
METHOD method_1;
PROLOG
...
ENDMETHOD method_1;
...
ENDCLASS my_class;
The class prolog specifies the action to be performed on object creation.
The body and methods specify the actions to be performed when an
object is running.

Data types Additional features
9.4 Data types
9.4.1 Introduction
Constants, variables, timers and items have already been introduced in

the basic language set. The full language also offers the following
additional type:
• Signal
9.4.2 Signals
A signal is used to establish links between an object and the outside

world via process variables. The signal references a process variable by
a name that can be used elsewhere within a method. A signal is thus
similar to an item. However a signal is in fact more versatile than an
item.
In the basic language set, a method represented a particular set of actions
which controlled part of a process. This means that a method is usually
unique within a system because it will relate to a specific area. In the
concept of classes and objects this view is slightly different. The
methods are part of a class definition and objects are created from a
class. This means that the methods an object possesses will be similar to
those of another object that was created from the same class. Therefore,
an item declaration in a class, references a specific item within the
system. Thus if two objects are created from the same class, they will
both reference the same item.
However with a signal it is possible to introduce variables into the item
name. These variables can be evaluated when the object is created and
the connection is actually made. This means that the item corresponding
to a signal name within one object may be different from that within
another object. For this reason signal definitions are always located
within the class prolog so that the actual connections can be made at the
moment the object is created. A signal can reference an item that does
not yet exist at the moment of object instancing. The signal statement in
the class prolog has an option that allows item creation at the moment
of object instancing. These items are automatically removed, unless
specified otherwise, from the system when the object is deleted later on
and when no other objects address the item anymore.

Additional features Data types
In addition it is also possible to use signals to trigger methods.

Triggering is a larger issue and is discussed later in this document.
Note: When using the full language set, don’t use
the ITEM data type. Use the SIGNAL data
type instead.
A signal has the following attributes which are used to access
information from the connected item. If no attribute is specified then the
item value is assumed. Note that not all attributes can be set. Only those
attributes that can be set are marked in bold type; all other attributes are
read-only.
• VALUE
The current value of the connected item.
• OLD_VALUE
The previous value of the connected item.
• STATUS
The current status of the connected item. This can be one of
UNDERRANGED, LOW_LOW, LOW, NORMAL, HIGH, HIGH_HIGH,
OVERRANGED, UNINITIALIZED, ON, or OFF.
• CONTROL_STATUS
This can be one of ON, OFF, TRUE, or FALSE.
• OPTION_STATUS
These flags can be accessed by using the bitwise operators and can
be one of OPT_BLOCKED, OPT_UPDATED_BLOCKED,
OPT_OFF_LINE, OPT_UPDATED_OFFLINE, or
OPT_ACKNOWLEDGED.
• MERGED_STATUS
This can be one of the status options as well as being BLOCKED,
UPDATED_BLOCKED, OFFLINE or UPDATED_OFFLINE.
• ALARM_TYPE
Indicates the alarm status of the item. This can be one of NORMAL,
DIRECT or ALARM.
• ACKNOWLEDGED
Indicates whether the alarm is acknowledged and can be one of
YES/TRUE or NO/FALSE.
• HIGH_HIGH_LIMIT
The value of the item’s HIGH_HIGH limit.
• HIGH_LIMIT
The value of the item’s HIGH limit.
• LOW_LIMIT
The value of the item’s LOW limit.
• LOW_LOW_LIMIT
The value of the item’s LOW_LOW limit.

Data types Additional features
• DEADBAND
The value of the item’s deadband.
• QUALITY
The item’s quality code.
• UPDATE_TIME
The time-stamp of the item update in GMT.
• ID_NODE
The item’s node number.
• ID_GROUP
The item’s group number
• ID_NUMBER
The item’s number.
• ID_SUB
The item’s sub-number.
• INSTALLATION
The item’s installation name. E.g. the first level section. It is
strongly advised to use SECTION instead of INSTALLATION.
• UNIT
The item’s unit name. E.g. the second level section. It is strongly
advised to use SECTION instead of UNIT.
• SECTION
The item’s section path.
• TAG
The item’s tag name.
• SUB
The item’s sub name.
• APPLICATION_INFO
The item’s application specific information. It is an array of bytes.
Only one element can be accessed in a single reference by indexing
it as follows:
APPLICATION_INFO[3].
The index may be a numeric expression.
• APPLICATION_SIZE
The size of the application information in bytes.
• APPLICATION_FLAG
The item’s application flag.
• ATTACHED
Indicates whether an item is attached to the signal and can be one
of YES/TRUE or NO/FALSE.
Note: When both value and status of a signal have
to be updated in one “atomic” action then
the function sig_update must be used.

Additional features Data types
When declaring a signal, the item name supplied is a string expression.

The expression must result in a string that contains at least the a tag of
the item optionally preceded by a section path. The node and sub-names
are optional. The following example illustrates how a signal is created
and used. In this example a signal is connected to an already existing
item:
CLASS valve;
PROLOG
VAR unit_number STRING;
unit_number := "12";
SIGNAL my_signal := "plant.installation.unit" ||
unit_number || ".temp";
...
BODY
...
PRINT "Current value is", my_signal;
PRINT "Current status id", my_signal’status;
...
There are a number of constants that may be of use when declaring
signals. These constants can also be used elsewhere within methods.
• NOW
The current time represented as a FLOAT.
• NODE
The object’s node name.
• INSTALLATION
The object’s installation name. E.g. the first level section.
• UNIT
The object’s unit name. E.g. the second level section.
• SECTION
The object’s section path.
• TAG
The object’s tag name.
• CLASS
The object’s class name.
The following example illustrates the use of a signal statement in which
an item is created during object instancing:
CLASS valve;
PROLOG
SIGNAL my_signal STRING := FROM

Statements Additional features
"templates.valve.host.template_item" MAKE
"NAME" EQUAL "plant.installation.unit" ||
unit_number || ".temp"
"DEADBAND" EQUAL 3.15;
...
BODY
...
PRINT "Current value is", my_signal;
PRINT "Current status id", my_signal’status;
...
A new item is created that has the same features as the template item. In
this example only the deadband is changed, but many more item
characteristics can be specified as described in Subsection 14.3.7.
9.5 Statements
9.5.1 Introduction
The basic language set description includes a description of the available

statements including print, error, assignment and addition assignment.
These statements can be used within the full language set.
In addition the following statements are available:
• Triggering
9.5.2 Triggering
Normally an object’s methods are triggered by the object’s trigger

group. The trigger group specifies when an object is activated and
deactivated. For more information on trigger groups. See Section 0.4
Ref.1.
After a method has been initially triggered by its trigger group, when
necessary, it can be re-triggered from within the method. It is possible to
use a TRIGGER to trigger the object, independent of any trigger group
or process variable.
Triggering offers a variety of possibilities. See Chapter 13 for further
information about triggering.

Additional features Enterprise classes and objects
9.5.3 Usage of the ERROR statement
The error statement was introduced in the basic language set. The
following remarks are made in relation to the use of the error statement
within the full set:
• If the error statement is encountered within a class prolog then an
error message is returned to the client application (normally USER/
FAST) and creation of that object is aborted.
• The error statement can be used within user-defined functions,
particularly for validating arguments (see the chapter related to
user-defined functions).
9.6 Enterprise classes and objects

Using the Enterprise Engineering Module, enterprise classes and objects
are defined. The behavior of enterprise classes and objects differs from
local classes and objects defined using the Local Engineering Module.
When an object is derived from an enterprise class using the Enterprise
Engineering Module it becomes an enterprise object. This object only
exists on the Enterprise Engineering Server and its body is not executed
because the Enterprise Engineering Server only contains definitions and
is not an operational FAST/TOOLS Server. Other differences compared
to a local object (an object derived from a local class) are:
• Points created for items related to signals are not physically
connected to the field because there is no field attached to the
Enterprise Engineering Server.
• Items related to signals are not put in history groups.
To deploy the defined object on one or more enterprise servers a
deployment group is assigned to the object. On one server the object
becomes the master and on all other servers where the object is deployed
this object becomes a delegate. Only the master object will be connected
to the field. E.g. when the master object is created then points will be
created for the items related to the signals. For the delegate objects no
points will be created. Thus delegate objects will not have connections
to the field via the points. Another difference is that only the body of the
master object will be executed. The delegate objects ore purely
placeholders for the signals and related items. The runtime attributes of
the items related to the signals will be exchanged by FAST/TOOLS
between the servers where this object is deployed. It is assumed that the

Enterprise classes and objects Additional features
main information flow is in the direction from the master to the

delegates.
Using the signal statement additional functionality is available to
influence on how items related to the signals are handled. For example:
CLASS valve;
PROLOG
SIGNAL my_signal STRING := FROM
"templates.valve.host.template_item" MAKE
"CREATE_ITEM" EQUAL "MASTER_ONLY";
...
In this example the field “CREATE_ITEM” with the value
“MASTER_ONLY” tells PROCESS/FAST to create the item for the
signal on the master server only. On the delegate servers no item will be
created for this signal and thus no item will be attached to the signal.
In the Edit Module the “attached” signal attribute can be used to distinct
on whether an item is attached to the signal.
Other possible values are:
• DELEGATE_ONLY
The item is created and attached to the signal on the delegate
servers and not on the master server.
• MASTER_AND _DELEGATE
The item is created and attached on master and all delegate servers.
The field “CREATE_ITEM” is called an enterprise field. Other
enterprise fields are:
• PUT_IN_HISTORY
Depending on the value for this field and whether the signal
statement specifies that the items should be put in a history group,
the item will put in the history group on the master only, the
delegates only or all.
• ALARM_DETECTION
Depending on the value for this field and whether the signal
statement specified that the item has alarming enabled, alarming
will be enabled on the master only, on the delegates only or on all.
For more informatio see the signal statement in section 14.3.7.
If enterprise fields are used in a local class then these are ignored during
creation of the objects.

Additional features Enterprise classes and objects

Introduction User defined functions
10 User defined functions
10.1 Introduction
The PROCESS/FAST language contains a number of built-in functions.
It is also possible to create user-defined functions for use within class
methods. For users familiar with the C programming language it is
possible to write these functions in C. See Section 0.4 ref.2 for reference
documents.
Alternatively it is possible to create these functions using the
PROCESS/FAST language which is described in this chapter. These
user-defined functions are defined within a special class called
“functions”. Note that objects can not be derived from this class!
10.2 Layout of a function

The following is an example of a simple function:
CLASS functions;
...
FUNCTION INTEGER my_function;
ARG int_value INTEGER;
CONSTANT factor := 10;
VAR result INTEGER;
IF int_value = 0
THEN
ERROR "my_function expects a non-zero value!";
RETURN 0;
ENDIF;
result := factor * int_value;
RETURN result;
ENDFUNCTION my_function;
FUNCTION ...;
...
ENDCLASS functions;

User defined functions Layout of a function
From the example it is possible to break down the layout into a number
of sections:
• Start of function declaration.
This consists of the word FUNCTION followed by the representation
that it returns, followed by the name of the function. This is name
that is used to access the function within the methods. Note if no
representation is supplied, the default VOID is taken. This means
that the function does not return a value.
• Argument declarations.
This section indicates how many arguments are expected by the
function and the representation of those arguments.
• Local declarations.
Declare any constants or variables to be used within the function
here be declared. Note no other types are allowed in the local
declaration section.
• Statements.
This is where the actual work that the function performs is declared.
Any valid PROCESS/FAST statements are allowed here. The
ERROR statement is of particular use for indicating mismatched or
invalid arguments.
• Return value.
The function returns a value by means of the RETURN statement. It
can appear anywhere within the function and has the effect of
returning the specified value and ending the function. The returned
representation should be the same as that declared at the start of the
function declaration. A RETURN statement is mandatory unless it is
a void function. In this case an optional RETURN statement can be
used to end the function, no value can be returned.
• End of function.
The end of the function definition is marked by the word
ENDFUNCTION followed by the function name.
Calling a user-defined function can be done in the same way as calling
any other built-in function. Supply a function name. Follow the function
name with a list of arguments enclosed in brackets. Separate each
argument in the list with a comma. For the example given above, this
would be done as follows:
...
x := 5;
result := my_function(x);
PRINT "The result of my_function is ", result;
...
The following points should be taken into account when using functions:

Layout of a function User defined functions
• Any arguments passed to a function are passed by reference. This

means that the value of any arguments can be modified from within
the function.
• Functions can call other functions.
• When a function is called, a search is made for the name in the user-
defined functions first, before searching the built-in functions.
Therefore it is possible to override any existing built-in function by
creating a user-defined function with the same name.

User defined functions Layout of a function

Introduction Attributes
11 Attributes
11.1 Introduction
A class defines a template from which objects are defined. This template
includes methods which are the actions to be performed by the object.
This template also includes characteristics that define and reflect the
object’s behavior. They can be seen as the data which the methods can
work upon. Some of these characteristics will already be defined in the
class and are typically things that influence all objects that will be
derived from the class. Other characteristics are left blank, to be filled in
at the time an object is created. Indeed the process of creating an object
can be seen as “filling in the blanks”. Once an object is running, these
characteristics can be monitored and modified from the outside world.
11.2 What is an attribute?

An attribute is the name PROCESS/FAST gives to an object’s
characteristics. They are analogous to global variables within a program.
However the difference between a variable and an attribute is that
attributes can be seen and influenced from the outside world.
How global an attribute is depends on whether it is local or class-wide.
A local attribute is one which is private to an object. Modifying a local
attribute will affect only the object to which it belongs. So local
attributes may contain different values for each object. Class-wide
attributes have an influence over all objects derived from the class. The
value of a global attribute at any time is the same for all objects derived
from the class. So changing the value of a class-wide attribute will affect
all objects. This mechanism provides a useful means of communication
between objects derived from the class.
Attributes can be accessed from within methods just like any other
variables. They can be assigned values and given representations just
like variables. Furthermore an expression or string can be supplied as the
value of an attribute and this will be automatically converted to the
representation for that attribute. Another major difference between an
attribute and a variable is that the values of attributes are stored in non-
volatile memory so they retain their value even if the system is restarted.

Attributes Declaring attributes
11.3 Declaring attributes

The declaration of attributes is performed in the class prolog. The
following are examples of attribute declarations:
ATTRIBUTE this_is_local OBJECT INTEGER;
ATTRIBUTE this_is_class_wide CLASS STRING;
The words OBJECT and CLASS define whether an attribute is local or
class-wide. Following the type of attribute is the representation of the
attribute which are the same as those available for variables. If no type
is specified then the attribute is taken to be local. If no representation is
specified then the default, FLOAT is taken.
11.4 Attributes and prompts
11.4.1 Using prompts
When an object is being created it is useful to be able to ask the operator

for the value of an attribute - to “fill in the blanks”. The operator can only
be prompted for the values of local attributes, that is any that are private
to that object. The following example demonstrates how this can be
done:
PROMPT this_is_local QUERY "How many eggs in a dozen?";
The query text appears within the USER/FAST form when the object is
created. In addition a default value will appear when the prompt is
displayed, containing the current value of the attribute. Normally this
will be zero or an empty string depending on the representation.
However, default values can be supplied by means of the class attributes
form within USER/FAST. Once the value has been entered it is possible
to check on the value of the attribute. If necessary an ERROR statement
can be used, which indicates what is wrong. This will also have the
affect of aborting the creation of the object.
Note: PROMPT is not a statement but a declaration
and cannot be used within methods!

Advice when using attributes with signals Attributes
11.5 Advice when using attributes with signals

Attributes are writable properties that can be used to influence the
behavior of a class. However care must be taken in case the attributes are
used in the PROLOG of a PROCESS/FAST class for the construction of
SIGNAL names. Once a signal has been created after an object has been
inserted, modifying an attribute that has been used in the creation of the
signal will have no effect on the class. Furthermore, changing this value
means that the original value used at insert time will be overwritten and
lost. This can make troubleshooting and maintenance more difficult.
Therefore it is not advised to modify attribute values that are used in the
creation of signals.

Attributes Advice when using attributes with signals

Introduction Class inclusion
12 Class inclusion
12.1 Introduction
Many components within a system contain similar sub-components, for
example a valve. Furthermore there may be different types of valves
though they will all share some common features. It would be tedious to
redefine separate classes for all the different types of valve that are
available. It would also be useful if classes for frequently used sub-
components could be defined once and later used in the creation of
classes for larger components. Class inclusion provides a mechanism for
doing this.
12.2 Inheritance
Imagine that in a particular plant, a number of different types of valve
are used. All these valves have some common features. Firstly a class
could be created that represented all the common features to be found in
these valves. Specific valve classes could then be created by including
the general valve class. The new valve definition now has all the features
of the general valve. The class definition could then be completed by
defining the specific features peculiar to a particular valve type.
The specific valve definition is said to “inherit” features from the
general valve class definition. In Figure 12-1, three examples are given
of the use of inheritance. A class “valve” has been defined that contains
all features common to all valves. Two new classes “X-valve” and “Y-
valve” have also been defined. These classes inherit features from the
class valve. However “X-valve” and “Y-valve” possess additional
features that are peculiar to that type of valve.
A class “boiler” has also been defined. This class inherits some features
from the class “Y-valve”. In addition the class also takes some features
from class “sensor”, another sub-component. It is thus possible to
include features from more than one class. It is also possible to have
nested included classes.

Class inclusion The CONTAINS statement
VALVE
X_VALVE
Sensor
Y_VALVE
BOILER
Figure 12-1 Examples of class inclusion
12.3 The CONTAINS statement

PROCESS/FAST allows classes to be included by means of the
CONTAINS statement. This is always found within the class prolog.
The following example shows how the class “boiler” might be defined:
CLASS boiler;
PROLOG
CONTAINS boiler_sensor := sensor;
CONTAINS boiler_valve := y_valve;
...
12.4 Triggers, signals and attributes

Triggers, signals and attributes of included classes can be accessed from
within a class. Other information cannot be accessed.
Triggers located within an included class do not trigger that class but the
class including it. In this situation for example, a trigger that is defined

Nesting Class inclusion
in the class “Y-valve” will not trigger “Y-valve” but the class that is
including it, which in this case is “boiler”.
Attributes and signals are accessed by supplying the included class
name, followed by a period(.), followed by the signal or attribute name.
This provides a so-called inclusion path. The following example
demonstrates how this can be done:
boiler_valve.signal_1 := 5;
When a prompt is defined for an attribute in an included class, this
prompt overwrites the one for the included class. If no prompt is
specified then the prompt defined in the included class will be displayed.
It may be desirable to suppress some of the prompts from included
classes. This can be done with the word NOPROMPT as follows:
NOPROMPT valve.this_is_local;
Note that NOPROMPT must appear after any attribute declarations for the
class have been made.
Note: The ITEM data type is not allowed in a
class which is included by an other class.
12.5 Nesting
It is possible to have nested included classes. From the example, the
class “boiler” includes the class “Y-valve” which in turn includes the
class “valve”. Accessing elements from within these classes can be done
by specifying the complete inclusion path of the class. For example:
...
boiler_valve.valve.signal_1 := 10;
...

Class inclusion Nesting

Introduction Triggers
13 Triggers
13.1 Introduction
In the basic language set of PROCESS/FAST, a method within a class
was activated when its activation time was reached (provided the control
item was on-line and any entry-condition was satisfied). In the full
language set this feature is replaced by the concept of triggers. A subset
of this trigger functionality is also available in the basic language set.
A trigger is a mechanism for activating the methods in an object. When
creating an object (see Section 0.4 ref.1) it may be inserted in one or
more trigger groups. If none is provided the one supplied for the object’s
class will be used. The activation of an object’s methods can be
controlled from the trigger group. When the activation time is reached,
any objects belonging to that group will be triggered.
In addition to the trigger group facility, a statement is provided within
the PROCESS/FAST language for triggering methods independent of a
trigger group.
13.2 The TRIGGER statement

The trigger statement is used to keep triggering methods, independent of
the trigger group it belongs to. It is sometimes necessary, for example,
to keep triggering a method after a certain time period has elapsed. The
TRIGGER statement can be used as follows:
TRIGGER 60;
The TRIGGER statement takes a time period in seconds as the argument.
In this example the method will be triggered again after 60 seconds.
Multiple TRIGGER statements are allowed within a method. In this case
successive trigger statements will overwrite each other. For example if
an additional trigger of 30 seconds was added to the example above, the
method would be triggered after 30 seconds.

Triggers Other uses
13.3 Other uses
13.3.1 Triggers and classes
Triggers defined in an included class do not trigger those classes but the
class that is including them. The TRIGGER statement can be used to
trigger the methods of the included classes. This can be performed as
follows:
TRIGGER CLASS type_1_valve;
13.3.2 Triggers and signals
Signals provide a connection between methods and process variables. It

is possible to trigger a method when one of the modifiable attributes of
a signal changes. This is done by supplying one of the following
constants. A combination of options can be obtained by bitwise OR-ing
the desired options.
• VALUE
Trigger on value change.
• STATUS
Trigger on status change.
• OPTION
Trigger on change of option bits.
• UPDATE
Trigger when process variable is updated.
• FIRST
Trigger on first update.
• PIT
Trigger when value passes PIT filter.
• LIMIT
Trigger when limits (including deadband) are changed.
• QUALITY
Trigger when the quality code changes.
An example of a signal that will trigger the methods when its value or
option bits change follows:
...

The TRIGGERED BY construct Triggers
SIGNAL my_signal :=
"plant.section.unit" || unit_number || ".temp"
TRIGGER VALUE | OPTION;
...
A delay may be introduced between the triggering of the method and the
execution of the method. Meanwhile attributes of the signal which
triggered the method may be changed. A number of built-in functions
are available to determine the value of a signal attribute at the moment
of triggering. These built-in functions are described in Section 14.7.
13.3.3 Triggers and items
The functionality in the prior subsection is also available for items via
the item keyword, in order to create a better real-time behavior.
13.3.4 Triggers and timers
Timers can be used to trigger methods when the timer expires. This is
performed in the declaration of the timer as follows:
TIMER my_timer TRIGGER;
13.4 The TRIGGERED BY construct

A TRIGGER can also be used within conditional expressions by means of
the TRIGGERED BY construct. It is used to find out how an object has
been triggered. This is illustrated in the example below:
IF TRIGGERED BY <value>
THEN ...
The <value> is used to specify the source of the trigger and can be one
of:
• GROUP
The object was triggered by its trigger group.
• SIGNAL
The object was triggered by a signal.
• TIMER
The object was triggered by a timer.

Triggers The TRIGGERED BY construct
• TRIGGER
The object was triggered by a TRIGGER statement.
• ALARM
The object was triggered by an alarm acknowledgment.
• ONCE
The object was triggered by its trigger group who has a trigger
interval of ONCE.
In addition the built-in functions TRGSIG, TRGALM and TRGTIM can be
used to determine the exact signal or timer which triggered the object.
These functions return a TRUE when the specified signal or timer id did
trigger the object. For example:
IF TRGSIG(my_signal)
THEN ...
When the object is placed in a trigger group which has a trigger interval
of ONCE then the object is triggered once when activated. Activation of
the object occurs when the object is inserted, the object is reset, when its
class is reset or when PROCESS/FAST is started.
Using a trigger group with a trigger interval of ONCE is very useful for
initialization of the object when activated. The following example
shows a method to initialize the object. The object or its class must be
placed in a trigger group which has a trigger interval of ONCE.
METHOD initialize;
ENTRYCONDITION TRIGGERED BY ONCE;
..
..
ENDMETHOD initialize;

Introduction Reference
14 Reference
14.1 Introduction
This chapter provides reference material for the entire PROCESS/FAST
language. Note that some features are only applicable within the full
language set. This is indicated in the appropriate descriptions.
The conventions used within the reference section are described in
Section 0.6. Any descriptions that do not fall under these rules should be
taken literally.
14.2 Program structure
14.2.1 Class
Syntax CLASS <class_name>;

[<class_prolog>]
[BODY]
...
ENDCLASS <class_name>;
Arguments <class_name>
The name assigned to the class.
<class_prolog>
Class prolog section. See Subsection 14.2.5.
Semantics A CLASS defines the start and end of the actions to be performed by
objects derived from the class. All other PROCESS/FAST language
constructs are enclosed within a CLASS.
An optional class prolog can be included by means of the word PROLOG.
Actions to be performed at the moment an object is created can be
included here, such as the declaration and prompting of attributes.
The BODY word is only necessary when a class prolog is included. This
is necessary to identify the end of the class prolog and the beginning of
the body.

Reference Program structure
The body contains global declarations and the methods that define the
tasks the object is to perform.
The class name can be up to a maximum of 15 characters starting with a
letter followed by letters, digits or an underscore.
Notes For a description of declarations and methods, see Section 14.3 and
Subsection 14.2.4 respectively.
Example CLASS boiler;
...
PROLOG
...
BODY
...
ENDCLASS boiler;

Program structure Reference
14.2.2 Epilog
Syntax EPILOG
Arguments None.
Semantics This construct is optional and appears at the end of a method. It defines
the actions to be performed when a method is deactivated and will
typically contain “tidy-up” statements for the method. Note that epilogs
are not found at class level.
Notes For more information on prolog and body statements, see Subsection
14.2.5 and Section 14.5.
Example ...
METHOD valve_control ;
...
EPILOG
PRINT "Execution of valve_control stopped";
ENDMETHOD valve_control ;
...

14.2.3 Functions
Syntax FUNCTION [INTEGER|FLOAT|STRING|VOID] <function_name> ;

ARG <argument>
[FLOAT|INTEGER|STRING|TIMER|SIGNAL|ALARM|ATTRIBUTE
[OBJECT|CLASS][FLOAT|INTEGER|STRING]]
[,<argument>
[FLOAT|INTEGER|STRING|TIMER|SIGNAL|ALARM|ATTRIBUTE
[OBJECT|CLASS][FLOAT|INTEGER|STRING]]]... ;
<local_declarations>
<statements>
RETURN <value>;
ENDFUNCTION <function_name>;
Arguments <function_name>
The function name used to identify and call the function.
<local_declarations>
Section containing declarations local to the function. See Section 14.3
<statements>
Section defining the actions the function is to perform. See Section 14.5.
<value>
The result of the function to be passed to the caller.
Semantics This construct enables user-defined functions to be defined. When a
function is encountered, a search of the user-functions is performed first.
This means that user-defined functions with the same name as built-in
functions will take priority. Functions must be defined within a special
class called “FUNCTIONS”. Objects cannot be created from this class!
The function name can be up to a maximum of 15 characters starting
with a letter followed by letters, digits or an underscore. An argument
name can be up to a maximum of 50 characters starting with a letter
followed by letters digits or an underscore.
Only constants and variables can be declared in the local declaration
section.
A function can contain the same body statements that can be used in
classes and methods. The RETURN statement is used to return the result
of the function to the caller.
Arguments to functions are passed by reference, so their values can be
modified and passed back to the caller. The function arguments can be
any arithmetic or string expression. Note that a maximum of 10
arguments can be supplied to a function. When an identifier with
attributes is supplied to the function then those attributes can be accessed
in the same way as within a method. The attribute scope (CLASS or

OBJECT) and attribute data type (FLOAT, INTEGER or STRING)

must be specified. If omitted the attribute defaults to a local attribute
(OBJECT) of type FLOAT.
Functions are called in the following manner:
<function_name> ( [<argument>[,<argument>]...] )
Notes Functions are only supported in the full language set.
If no representation is supplied for the function then the default of VOID
is taken.
If no representation is supplied for an argument then the default of
FLOAT is assumed.
If a function is called that does not accept any arguments then the
brackets that would normally enclose them are optional.
Example FUNCTION FLOAT ADD_10;
ARG in FLOAT;
VAR out FLOAT;
out := in + 10;
RETURN out;
ENDFUNCTION ADD_10;

14.2.4 Method
Syntax METHOD <method_name>;

[<entry_condition>]
[<declarations>]
[<method_prolog>]
BODY
<body_statements>
[<epilog>]
ENDMETHOD <method_name>;
Arguments <method_name>
The name assigned to the method.
<entry_condition>
A conditional expression determining whether the method should be
executed. See SubSection 14.4.1.
<declarations>
Section containing declarations local to the method. See Section 14.3.
<body_statements>
Section defining the actions the method is to perform.See Section 14.5.
<epilog>
Section defining actions to perform when the method is de-activated.
See Subsection 14.2.2.
Semantics A method defines one of the tasks that should be performed within a
CLASS definition. All PROCESS/FAST executable statements are
enclosed within a method.The method name can be up to a maximum of
50 characters starting with a letter followed by letters, digits or an
underscore.
Notes For the description of entry-conditions, declarations, prolog, epilog and
body statements, see SubSection 14.4.1, Section 14.3, Subsection
14.2.5, Subsection 14.2.2 and Section 14.5.
Example METHOD valve_control;
...
BODY
...
ENDMETHOD valve_control;

14.2.5 Prolog
Syntax Class prolog:

PROLOG
[<local_prolog_declaration>]
[<classes_to_include>]
[<attributes>]
[<connections>]
Method prolog:
PROLOG
[<body_statements>]
Arguments <local_prolog_declarations>
Section containing declarations local to the prolog. See Section 14.3.
<classes_to_include>
Definitions of any classes which are to be contained within this class.
See Subsection 14.3.3.
<attributes>
Definitions of data that can be viewed from the outside world. See
SubSection 14.3.1.
<connections>
Definitions of connections to process variables. See Subsection 14.3.7.
<body_statements>
Actions to be performed when the prolog is executed. See Section 14.5.
Semantics This construct defines activities to be performed the first time a class or
method is run.
The class prolog defines actions to be performed upon creation of an
object. Typically this will contain prompts for attribute values and signal
definitions.
The method prolog defines actions to be performed the first time the
method is executed. This will typically contain initialization actions for
the method.
Notes Local declarations made in the class prolog only cover the scope of the
prolog. Global variables should be declared after the BODY part of the
class definition.
The class prolog is only available in the full language set. For more
information on including classes, declarations, attributes, prompts,
signals and epilog, see Subsection 14.3.3, Section 14.3, SubSection

14.3.1, Subsection 14.3.6, Subsection 14.3.7 and Subsection 14.2.2

respectively.
Example CLASS boiler ;
PROLOG
ATTRIBUTE initial_temp INTEGER;
PROMPT initial_temp QUERY “Initial temperature value”;
BODY
METHOD valve_control ;
PROLOG
start_time := NOW
BODY
...

14.2.6 Sequence
Syntax SEQUENCE <sequence_name>;

...
ENDSEQUENCE <sequence_name>;
Arguments <sequence_name>
The name assigned to the sequence.
Semantics A sequence defines the start and end of a PROCESS/FAST program in
the same way as CLASS. All other language constructions are enclosed
within a sequence. The sequence name can be up to a maximum of 15
characters, starting with a letter followed by letters, digits or an
underscore.
Notes The sequence is provided for compatibility only and is superseded in the
PROCESS/FAST language by the word CLASS.
Example SEQUENCE boiler ;
...
ENDSEQUENCE boiler;

Reference Declarations
14.2.7 Sub-sequence
Syntax SUBSEQUENCE <sub-sequence_name>;

...
ENDSUBSEQUENCE <sub-sequence_name>;
Arguments <sub-sequence_name>
The name assigned to the sub-sequence.
Semantics A sub-sequence defines the tasks that are performed within a sequence,
in the same way as a method does for a class. A sequence can consist of
many sub-sequences, each running simultaneously and performing
different functions. All statements are enclosed within a sub-sequence.
The sub-sequence name can be up to a maximum of 50 characters
starting with a letter followed by letters, digits or an underscore.
Notes This word is provided for compatibility reasons only and is superseded
in PROCESS/FAST by the METHOD construct.
Example SUBSEQUENCE valve_control;
...
ENDSUBSEQUENCE valve_control;
14.3 Declarations
Syntax ALARM <alarm_name> [TRIGGER]
[, <alarm_name> [TRIGGER]]... ;
Arguments <alarm_name>
The name assigned to the alarm.
Semantics An alarm is used to present an alarm text to an operator, together with
the originating object identification. The alarm can be acknowledged by
the operator and as a result the originating object is triggered when the
TRIGGER option was set in the alarm declaration.
Alarms have a value, status and priority associated with them. These
alarm attributes can be accessed at any time. The initial alarm value is
an empty string, the status has integer value NORMAL and the priority has
an integer value of 0. Referring to an alarm assumes a reference to its
value. Accessing its status or priority can be done by accessing the
STATUS or PRIORITY attribute of the alarm with the quote ( ’ ). The
status can be one of:

Declarations Reference
• NORMAL
• A1
• A2
• A3
When the status is set to A1, A2 or A3 in order to activate the alarm it can
be logically ORed with ACKNOWLEDGE. When the alarm is
acknowledged the alarm status is set to ACKNOWLEDGED. This is done
independently of the TRIGGER option of the alarm declaration.
The relationships between actions and status is depicted in the following
table:
Table 2: A day in the life of an alarm
Action Alarm overview New alarm status
Initially declared None NORMAL

value = "Alarm text" None NORMAL
status = A1 | "Alarm text" A1
ACKNOWLEDGE
status = NORMAL None NORMAL
status = A3 | "Alarm text" A3
ACKNOWLEDGE
alarm acknowledged by opera- "Alarm text" ACKNOWLEDGED
tor remains, but in state
"acked"
status = NORMAL None NORMAL
The priority of an alarm is only accessible within the object and can be
used to distinguish between levels of alarms. It should not be confused
with the priority of the alarm in the alarm overviews of the operators.
Notes An alarm can be associated with a TRIGGER. In this case the object (or
sequence) will be triggered immediately when the alarm is
acknowledged. A built-in function TRGALM() is available that determines
of the specified alarm triggered the object.
Example ALARM temperature_alarm TRIGGER;
14.3.1 Attributes
Syntax ATTRIBUTE <name> [CLASS|OBJECT]

INTEGER|FLOAT|STRING
[,<name> [CLASS|OBJECT] INTEGER|FLOAT|STRING]... ;

Arguments <name>
The name assigned to the attribute.
Semantics An attribute is a mechanism to enable the outside world to directly
influence an object’s methods. They can be used within methods in the
same way as variables but attributes retain their values, even after a
restart.
Attributes can be local or class-wide. A local attribute is private to a
particular object and is declared by specifying the word OBJECT in the
declaration. Changing its value will only affect that specific object. A
class-wide attribute affects all objects derived from a class and is
declared by including the word CLASS in the declaration. Modifying the
value of a class-wide attribute will modify the value for all objects in the
class.
Attribute declarations must appear within the class prolog.
An attribute name can be up to a maximum of 15 characters starting with
a letter followed by letters, digits or an underscore.
Attributes of included classes can be accessed by specifying the attribute
path in the form:
[<include_name>.]... <include_name>.<attribute>
Notes This construct is only available in the full language set.
Example ATTRIBUTE my_attribute STRING;

14.3.2 Constants
Syntax CONSTANT <name> := <expression>

[,<name := <expression>]... ;
Arguments <name>
The name assigned to the constant.
Semantics Constants are used to associate an identifier name with a value that will
not change during execution. The type of a constant is determined from
the result of the associated expression. A constant name can be up to a
maximum of 50 characters starting with a letter followed by letters,
digits or an underscore.
Notes None.
Example CONSTANT pi := 3.1415926 ;

14.3.3 Contains
Syntax CONTAINS <include_class> := <class_name>

[, <include_class> := <class_name>]... ;
Arguments <include_class>
The name used to reference the class within the methods.
<class_name>
The name of the class to be included. This is the name of the class as
defined within FAST/TOOLS User Interface.
Semantics The CONTAINS construct allows a class to include other classes. The
class will be referred to within the methods via the specified include
name. It must appear within a class prolog.
The include name can be up to a maximum of 15 characters starting with
a letter followed by a letter, digits or an underscore.
Notes This construct is only supported in the full language set.
Example CONTAINS valve_a := type_1_valve ;

14.3.4 For
Syntax FOR [<node_name>:]<installation_name>[.<unit_name>] ;

Arguments <node_name>
The node specification.
<installation_name>
The installation specification.
<unit_name>
The unit specification.
Semantics This construct is used in conjunction with ITEM to facilitate easier
definition of item names, especially when more than one tag name from
the same unit or installation is to be used. It specifies part of an item
name that will be used as a prefix to the item names specified in
successive ITEM constructs. Multiple FOR constructs can be used though
the most recent will overrule any previous FOR declarations.
Notes <installation_name> maps upon sections in the first level and
<unit_name> maps upon sections in the second level. Because all other
section levels are not handled by the FOR and ITEM declarations, it is
strongly advised not to use the FOR and ITEM declaration but use SIGNAL
instead.
Example FOR my_node:my_unit.my_installation ;
...
ITEM my_tag;
{Refers to item my_node:my_unit.my_installation.my_tag}

14.3.5 Items
Syntax ITEM <item_name> [TRIGGER <type>]

[,item_name [TRIGGER <type>]]... ;
Arguments <item_name>
The name assigned to the item to use.
<type>
A constant integer expression indicating the attribute of the item to
trigger on when TRIGGER is specified.
Semantics This construct is used to make an existing process variable accessible
from within a method. This construct can be used in association with
FOR to avoid the need for repeatedly specifying node, installation and
unit names. An item name must be of the form:
[[[<node_name>:]<installation>.]<unit>.] <tag> [.<sub>]
Array items can also be used. These are declared in the same way as an
ordinary item. Accessing the elements of the array is done by supplying
the item name immediately followed by the index number in square
brackets ([ ]).
An item has many attributes, not only its value. See Subsection 14.3.7.
Notes <installation_name> maps upon sections in the first level and
<unit_name> maps upon sections in the second level. Because all other
section levels are not handled by the FOR and ITEM declarations, it is
strongly advised not to use the FOR and ITEM declaration but use SIGNAL
instead.
For more information on FOR, see Subsection 14.3.4.
It is recommended to use only alphanumeric characters and underscores
for the item name parts. However, if item names must be used that
contain characters having a special meaning in the PROCESS/FAST
language, then the special escape character (’@’) can be used.
See the examples below.
An item can be associated with a TRIGGER. In this case the object (or
sequence) will be triggered when the item is updated and when the
trigger type matches.
The ITEM statement is not allowed in classes included by other classes.
Example ITEM installation_1.unit_1.tag_1;
ITEM index, array_1;
ITEM trg_itm TRIGGER QUALITY | STATUS;
...
array_1[index] := 10;

...
ITEM @i-1@, @tag*3@;

14.3.6 Prompts
Syntax PROMPT <attribute_name>|<attribute_path> QUERY <text>

[,<attribute_name>|<attribute_path> QUERY <text>]... ;
NOPROMPT <attribute_name>|<attribute_path>
[, <attribute_name>|<attribute_path>]... ;
Arguments <attribute_name>
The name assigned to the attribute.
<attribute_path>
The name of an attribute from an included class.
<text>
The text that the operator will see when prompted for the value.
Semantics It is used within a class prolog when requesting an initial value from the
operator for a local attribute at the moment that an object is created.
Prompt definitions that refer to attributes of included classes overrule
those of the included class.
An attribute from an included class can be referenced by specifying the
entire include path of the attribute separated by a period.
It may be necessary to suppress prompts from included classes. The
NOPROMT construct is used for this purpose and suppresses any prompt
associated with the specified attribute. NOPROMPT should appear after
any attribute declarations for the class have been made.
Example PROMPT temperature QUERY "Enter the initial temperature";
NOPROMPT boiler_1.tank.level;

14.3.7 Signals
Syntax SIGNAL
<signal_name> [<signal_type>] := <item_name>
[TRIGGER <type>]
[,<signal_name> [<signal_type>] := <item_name>
[TRIGGER <type>]]... ;
SIGNAL
<signal_name> [<signal_type>] := FROM <tpl_names>
MAKE <item_field> EQUAL <value>
[<item_field> EQUAL <value>]...
[TRIGGER <type>]
[,<signal_name> [<signal_type>] := FROM <tpl_names>
MAKE <item_field> EQUAL <value>
[<item_field> EQUAL <value>]...
[TRIGGER <type>]]... ;
Arguments <signal_name>
The name assigned to the signal.
<signal_type>
The corresponding item type. STRING, INTEGER or FLOAT, FLOAT
being default.
<item_name>
A string expression indicating the name of the item that the signal is
associated with.
<type>
A constant integer expression indicating the attribute of the item to
trigger on when TRIGGER is specified.
<tpl_names>
A string expression indicating the name of the template item where the
newly created item must be derived from and optionally the name of the
template I/O point where the newly created I/O point must be derived
from. The expression must result into the following string:
<tpl_item_name>[;<tpl_point_name>]
where <tpl_item_name> specifies the name of the template item and
<tpl_point_name> specifies the name of the template I/O point. For
example:
“AREA.PLANT.INSTALLATION.UNIT.TAG” specifies a template item,
“AREA.PLANT.INSTALLATION.UNIT.TAG.SUB” specifies a template

sub-item and
“AREA.PLANT.INSTALLATION.UNIT.TAG;STATION:POINT” specifies
a template item and a template I/O point. An I/O point name contains
always the name of the station for which the I/O point is defined and the
name for the point itself. If no template I/O point is specified then the I/
O point related to the template item will be used as template I/O point.
Note: <tpl_names> may be an empty string. In
this case there will be no item created and
the signal will not be attached to an item.
The “Attached” attribute of a signal can be
used in the Editor Module to detect
whether or not an item is attached to the
signal.
<item_field>
A string expression indicating the attribute of the new item that is
required a specific value, other than the value from the template item.
<value>
An expression indicating the value that must be assigned to the attribute
of the newly created item.
Semantics Signals are used to define connections with the outside world. Declaring
a signal is similar to declaring an item except that the referenced item
name can contain some variable part that will be completed when the
object is created. For this reason, a signal must be declared in the class
prolog section.
The first type SIGNAL statement connects a signal to an existing item,
the second type will also create the item if it does not yet exist. Note that
the template item must have been defined earlier.
A signal has the following attributes. Highlighted attributes can be
modified within methods. The rest are read-only.
• value
• old_value
• status
• control_status
• option_status
• merged_status
• alarm_type
• acknowledged
• high_high_limit
• high_limit
• low_limit

• low_low_limit
• deadband
• quality
• update_time
• id_node
• id_group
• id_number
• id_sub
• installation
• unit
• section
• tag
• sub
• application_info[<index>]
• application_size
• application_flag
• locked
• attached
Note: When both value and status of a signal have
to be updated in one “atomic” action then
the function sig_update must be used.
Note: The application_info is only available when
this feature is enabled in the FAST/TOOLS
system.
Signals can be used to trigger the object depending when a specified
signal attribute changes. The trigger type can be one of the following:
• VALUE
• STATUS
• OPTION
• UPDATE
• FIRST
• PIT
• LIMIT
• QUALITY
A signal name can be up to a maximum of 15 characters starting with a
letter followed by letters, digits or the underscore. The item name or
template item name can be any string expression that results in a
complete item name specification.
Note that the construction:

SIGNAL my_signal :=
“area.plant.installation.unit.tag_no” , 5;

is ambiguous. The ‘,’ (string concatenation, see SubSection 14.6.6)

operator was intended here. However, PROCESS/FAST interprets it as
being a list separator. Use the ‘||’ operator instead in this case.
For enterprise classes enterprise <item_field> and related <value>
can be used to have different characteristics for the item created for the
signal depending on whether the object is the master or a delegate (see
section 9.6). Possible enterprise item fields with their possible values
are:
• CREATE_ITEM
Depending on whether the object is the master or delegate the item
will be created or not.
- MASTER_ONLY
The item is created and attached to the signal for the master
object only.
- DELEGATE_ONLY
The item is created and attached to the signal for the delegate
objects only.
- MASTER_AND _DELEGATE
The item is created and attached to the signal for the master
and all delegate objects.
• PUT_IN_HISTORY
If other fields specify that the item should be put in a history group
then the value for this enterprise field specifies whether the item
will be put in the history group.
- MASTER_ONLY
The item is put in the history group for the master object only.
- DELEGATE_ONLY
The item is put in the history group for the delegate objects
only.
The item is put in the history group for the master and all
delegate objects.
If other fields do not specify that the item should be put in a history
group then this enterprise field is ignored.
• ALARM_DETECTION
If other fields specify that alarming should be enabled for the item
then the value for this enterprise field specifies whether alarming
for the item will be enabled.
- .MASTER_ONLY
Alarming is enable for the master object only.
- DELEGATE_ONLY
Alarming is enable for the delegate objects only.

Alarming is enable for the master and all delegate objects.
If other fields do not specify that alarming for the item should be
enabled then this enterprise field is ignored.
Example Examples are provided for both signal statement types. The first
connects a signal to an existing item, the second first creates a new item
and then connects the signal to that new item.
Example 1:
SIGNAL my_signal := "MY_AREA.MY_PLANT.MY_INSTALLATION.MY_UNIT" ||
unit_number || ".TEMP" TRIGGER VALUE ;
Example 2:
SIGNAL my_signal STRING :=
FROM "AREA.PLANT.INSTALLATION.UNIT.TPL_ITEM" MAKE
"NAME" EQUAL
"AREA.PLANT.INSTALLATION.UNIT.NEW_ITEM"
"DESCRIPTION" EQUAL "The level of the tank"
"LOW_LOW_LIMIT" EQUAL 230
"DEADBAND" EQUAL 12.0
"ALARMING" EQUAL OFF
"PROCESS_LIST" EQUAL "1,3,17,78"
"AOI_1" EQUAL "AOI1"
"AOI_2" EQUAL "MY_AREA"
"GROUP_NAME" EQUAL "ITEM_SCAN_GRP"
"STORE_VALUE" EQUAL TRUE
"GROUP_NAME" EQUAL "ITEM_EVENT_GRP"
"ON_VALUE_CHANGE" EQUAL TRUE
TRIGGER UPDATE ;
An item is created having the same features as the template item, but
with a number of changes:
• The low-low limit is set to 230
• The deadband is set to 12.0
• No alarms are generated when the item’s value exceeds the limits
• The process areas for the item are 1, 3, 17 and 78. Note the syntax:
the process_areas are provided as a single string expression. Each
part is separated from the other with a comma or white space
(space, tab, new-line, carriage return or form feed) or any
combination of these. A single process area must still be presented
as a string expression ("7").
• The areas of interest are provided as a string expression. Upto 16
Areas of interest can be specified

• The item is inserted in the item history group "ITEM_SCAN_GRP"

and only the values are stored. The item is also stored in in the item
history group "ITEM_EVENT_GRP", values are stored when the item
value changes.
• Any item update will trigger the object for which the item was
created.
All DSS fields of datasets ITEM_DF, SUB_ITEM_DF, ITEM_HIS_DF
and the station specific POINT_DF can be referenced in the “SIGNAL
MAKE” statement.
When specifying item history storage attributes for the item to be
created, the order of the specified fields is of importance. When the
“GROUP_NAME“ keyword is encountered, it is assumed that all storage
attributes are specified before the (optional) next “GROUP_NAME“
keyword.
Note 1: A boolean field can be ON/OFF or TRUE/FALSE.
Note 2: A new item can be inserted in upto 4 item history groups
(storage groups). Be aware that a created item is not
automatically inserted in history group(s) even if the
template item is.
It must be specified per history group what has to be stored,
the so-called storage attributes.
The value, limit, quality code, or any combination of these
may be specified.
Example: "STORE_HIGH_LIMIT" EQUAL ON
"STORE_VALUE" EQUAL ON
If the history group works on event basis (contrary to scan

basis) the storage criterion must be specified as well,
because item history must be able to determine which
events are of importance. Possibilities are: First update,
value update, status update, each item update, a changed PIT
filter, a changed option flag, an updated quality code, or
any combination of these.
Example: "ON_PASS_PIT" EQUAL TRUE
"ON_VALUE_CHANGE" EQUAL TRUE
Example 3:
FROM "AREA.PLANT.INSTALLATION.UNIT.TPL_ITEM;STATION:TPL_POINT"
MAKE
"NAME" EQUAL

"STATION" EQUAL "MY_STATION"

"POINT" EQUAL "NEW_POINT"
"IO_ADDRESS" EQUAL "RO:12"
TRIGGER UPDATE ;
An I/O point is created from the template I/O point

“STATION:TPL_POINT” with the name “MY_STATION:NEW_POINT”
and I/O address “RO:12” and an item is created having the same
features as the template item and connected with the newly created I/O
point.
Note: If the I/O point to create already exists then
an error is issued and the object is not
created.
Note: If the “POINT” field is omitted in the
previous example then PROCESS/FAST
will use the name of the item to be created
for the name of the POINT. E.g. the name
of the point will become then
“AREA.PLANT.INSTALLATION.UNIT.
NEW_ITEM”.
Example 4:
PROLOG
VAR template STRING;
ATTRIBUTE station STRING;
PROMPT station QUERY "Enter station name:";
IF station = "" THEN

template := "";
ELSE
template :=
"AREA.PLANT.INSTALLATION.UNIT.TPL_ITEM;STATION:TPL_POINT";
ENDIF;

FROM template
MAKE
"NAME" EQUAL
"STATION" EQUAL station
TRIGGER UPDATE ;
This example is the same as example 3 exexpt that the station is passed
via a prompt. If nothing was entered for the prompt then the name for the

template will be empty and there will be no item created and the signal
will not be attached to an item. In the class code you can use the
attached attribute of the signel to determine whether an item is
attached to the signal:
METHOD xxx;
IF my_signal’attached THEN
...
ENDIF;
ENDMETHOD xxx;
In the Edit Module you can use the “Attached“ attribute to detect
whether an item is attached.
Example 5:
PROLOG

FROM
"AREA.PLANT.INSTALLATION.UNIT.TPL_ITEM;STATION:TPL_POINT"
MAKE
"STATION" EQUAL station
TRIGGER UPDATE ;
This example shows that a name for the item to be created is optional. If
no name is supplied then PROCESS/FAST creates a name for the item
that will be:
<object_name>.[<containment_path>.]<signal_name>
If you create an object with the name AREA.PLANT.BOILER1 then the
name of the item for the signal my_signal will become:
AREA.PLANT.BOILER1.MY_SIGNAL
The <containment_path> is the path to the signal if the class is
included in another class. Assume that there is a valve that contains the
signal s_setpoint and it is included twice in the boiler class like:
CONTAINS water := valve;
CONTAINS gas := valve;
Then PROCESS/FAST creates the items
AREA.PLANT.BOILER1.WATER.S_SETPOINT and
AREA.PLANT.BOILER1.GAS.S_SETPOINT
While the item is created and PROCESS/FAST encounters a section that
doesn’t exists then PROCESS/FAST creates the section automatically.

If the object is deleted then PROCESS/FAST deletes these sections if

they become empty.
Note: A name for an item to be created is
optional. For sub-items you must specify
the name for the sub-item to be created and
the name field cannot be omitted.
Example 5:
PROLOG
SIGNAL my_signal :=
FROM "AREA.PLANT.TEMPLATES.INPUT_INTEGER"
MAKE
"STATION" EQUAL "STATION_12"
"IO_ADDRESS" EQUAL "RI:12"
"ALARMING" EQUAL ON
"GROUP_NAME" EQUAL "ITEM_SCAN_GRP"
"STORE_VALUE" EQUAL TRUE
"GROUP_NAME" EQUAL "ITEM_EVENT_GRP"
"CREATE_ITEM" EQUAL "MASTER_AND_DELEGATE"
"PUT_IN_HISTORY" EQUAL "MASTER_ONLY"
"ALARM_DETECTION" EQUAL "DELEGATE_ONLY";
This example shows the definition of a signal for an enterprise class.

CREATE_ITEM defines that the item will be created for the master and all
delegate objects.This is the default behavior. Thus, in this example you
can leave this out of the signal statement. However, a field value is a
string expression. Depending on the value of, for example, an attribute,
the value for CREATE_ITEM can be different for each object derived from
the class.
In the above example GROUP_NAME specifies that the item should be put
in the history groups ITEM_SCAN_GRP and ITEM_EVENT_GRP. However
the field PUT_IN_HISTORY specifies that this will only be the case for the
master object. For the delegate objects the item will not be put in those
history groups. ALARM_DETECTION works in a similar way. ALARMING
specifies that alarming should be switched on but this will only be the
case for delegate objects.
The example also shows that a point should be created for the item. This
will only be done for the master object. Points are never created for
delegate objects.

14.3.8 Compatibility
In FAST/TOOLS release R9.03 I/O points and equipment plug-ins were

introduced. For this reason the “SIGNAL MAKE” statement is not
compatible with pre-R9.03 releases. So Class source code from pre-
R9.03 releases systems has to be changed to work with FAST/TOOLS
release R9.03.
14.3.9 Timers
Syntax TIMER <timer_name> [TRIGGER]

[, <timer_name> [TRIGGER]]... ;
Arguments <timer_name>
The name assigned to the timer.
Semantics Timers are similar to variables but also have a status associated with
them. At any time, the value of a timer contains the time to go before the
timer expires, in seconds. Assigning a value to a timer sets the number
of seconds before the timer goes off.
A timer has an initial float value of 0 and an integer status of EXPIRED.
Referring to a timer assumes a reference to its value. Accessing its status
can be done by accessing the STATUS attribute of the timer with the quote
( ’ ).The status can be one of:
• STOPPED
• RUNNING
• EXPIRED
The status can be set explicitly but is also affected by the trigger’s value.
The relationships between status and value is depicted in the following
table:
Table 3: A day in the life of a timer
Action New value New status
Initially declared 0 EXPIRED

value = 5 5 RUNNING
None 4 RUNNING
None 3 RUNNING
status = STOPPED 3 STOPPED
status = RUNNING 2 RUNNING

Table 3: A day in the life of a timer
Action New value New status
value = 6 6 RUNNING
None 5 RUNNING
status = EXPIRED 0 EXPIRED
Notes A timer can be associated with a TRIGGER. In this case the object (or
sequence) will be triggered when the timer expires.
Example TIMER time_up TRIGGER;

Reference Guards
14.3.10 Variables
Syntax VAR <name> [INTEGER|FLOAT|STRING]

[,<name> [INTEGER|FLOAT|STRING] ]... ;
Arguments <name>
The name used to reference the variable.
Semantics Variables are used to associate an identifier name with a value that can
change during execution. If no representation is supplied then a default
of FLOAT is assumed.
When an expression is assigned to a variable then the result will be
automatically converted to the representation of that variable. Note
however that it is not allowed to mix strings with numerics.
A variable name can be up to a maximum of 50 characters starting with
a letter followed by letters, digits or an underscore.
Notes None.
Example VAR this_is_an_integer INTEGER;
14.4 Guards
14.4.1 Entry-conditions
Syntax ENTRYCONDITION <condition> ;

Arguments <condition>
A conditional expression.
Semantics This construct is used to determine whether a method will be executed
or not, depending on a certain condition. The entry-condition is
evaluated when the object is activated. The method is activated when the
related conditional expression evaluates to TRUE. Entry-conditions are
particularly useful in conjunction with STEP for activating different
methods of an object depending on the current state of that object.
The table 1 in Section 3.3 summarizes which parts of a method are
executed depending on the value of the previous and current results of
the entry-condition.
Notes None.
Example ENTRYCONDITION inst_1.unit_1.temp’status = HIGH_HIGH;

Statements Reference
14.5 Statements
14.5.1 If
Syntax IF <condition>
THEN <statement>...
[ELSE <statement>... ]
ENDIF ;
Arguments <condition>
A conditional expression.
Semantics This construct is used to conditionally execute blocks of statements. The
statements following the IF are executed when the conditional
expression evaluates to TRUE. An optional ELSE part is available for
executing statements when the condition is FALSE. Nested IF constructs
are allowed.
Notes None.
Example IF temp > 100
THEN
burner := OFF;
ELSE
burner := ON;
ENDIF ;

Reference Statements
14.5.2 Assignment
Syntax <identifier> := <expression> ;
Arguments <identifier>
An identifier name.
<expression>
A numeric or string expression.
Semantics This construct is used for assigning a value to some identifier. An
identifier in this case can represent one of the following things:
• Variable
• Signal, signal path or signal attributes
• Attribute or attribute path
• Timer or timer attributes
• Alarm or alarm attribute
• Function argument
The value to be assigned can be any valid numeric or string expression.
In the event that the identifier has a numeric representation then the
result will be automatically converted to that representation. Note that it
is not allowed to assign strings to numeric identifiers and numerics to
strings. The built-in functions INTEGER, FLOAT and STRING can be
used for this purpose.
Notes None
Example my_integer := 20;
my_string := "This is a string";

14.5.3 Addition assignment
Syntax <identifier> :+ <numeric_expression> ;
Arguments <identifier>
An identifier name.
<numeric_expression>
A numeric expression.
Semantics This construct is similar to the assignment statement except that instead
of assigning the result of the expression directly, it adds the result of the
expression to the current value of the identifier. The expression to be
added must evaluate to a numeric expression. See the section on the
assignment statement for the list of types that can be used in an addition
assignment construct.
Notes None
Example my_integer :+ 20 ;

14.5.4 Error
Syntax ERROR <string_expression> ;

Arguments <string_expression>
Message to be displayed.
Semantics It is used for indicating error conditions and sends the supplied error text
to the default system logger. It is especially useful within user-defined
functions, when validating arguments for example. However it can also
be included in methods.
If an ERROR construct is used within a class prolog then the error will be
displayed within USER/FAST during object creation. If it appears within
a method then the error is logged to the default BUS/FAST logger and
execution of the object is stopped. (Execution will however start again
the next time the object is triggered).
Notes None
Example ERROR "Unexpected value :", my_signal, " received";

14.5.5 Print
Syntax PRINT <string_expression> ;

Arguments <string_expression>
The text to be printed.
Semantics This construct is used for printing messages to the system printer. It is
possible to print any valid string expression and can include variables. It
is most useful for reporting status conditions or emergency messages.
Notes It may be the case that no output appears on the system printer. In this
case the PRINT statement has been disabled globally. Ask your system
integrator.
Example PRINT "Boiler temperature now ", temp," degrees";

14.5.6 Trigger
Syntax TRIGGER <interval> ;

TRIGGER CLASS <include_class> ;
IF TRIGGERED BY <value_id>
...
Arguments <interval>
A float expression indicating the time period after which the object will
be triggered.
<include_class>
Name of included class to be triggered.
<value_id>
The name of a trigger source.
Semantics This construct is used to trigger an object’s methods independently of its
related trigger group. The TRIGGER construct can be used as a statement
to trigger the object after a specified number of seconds or to trigger an
included class. A TRIGGER statement will trigger that object once.
Multiple TRIGGER statements can be used. In the event that the object
has not yet been triggered by a previous trigger then the previous one
will be overruled.
The TRIGGER construct can also be used when defining signals and
timers. See Chapter 13 for more information.
When a trigger activates an object, it is possible to identify the source of
the trigger by means of the TRIGGERED BY construct followed by a
source name which can be one of:
• GROUP
Triggered by a trigger group.
• SIGNAL
Triggered by a signal.
• TIMER
Triggered by a timer.
• TRIGGER
Triggered by a trigger statement.
• ONCE
Triggered by a trigger group which has a trigger interval of ONCE.
Notes Triggers are only supported in the full language set.
Example TRIGGER 120;
TRIGGER CLASS boiler.tank;

Operators Reference
IF TRIGGERED BY SIGNAL
THEN ...
14.6 Operators
14.6.1 Arithmetic
The arithmetic operators operate on numeric expressions. The following

operators provided:
• +
Addition.
• -
Subtraction.
• *
Multiply.
• /
Divide.
14.6.2 Bitwise
The bitwise operators provide boolean logic functions at bit level. They
are useful for masking or setting option bits. They expect an argument
of INTEGER representation. The following operators are available:
• |
Bitwise OR.
• &
Bitwise AND.
• ^
Bitwise exclusive OR.
• ~
Complement.
14.6.3 Boolean
The boolean operators provide boolean logic functions and can operate
on numeric or string expressions. They yield a boolean result of either
TRUE or FALSE. The following operators are provided:

Reference Operators
• AND
Logical AND.
• OR
Logical OR.
• XOR
Logical Exclusive OR.
Wherever boolean expressions are used, it is advisable to use these
constants:
• TRUE
• FALSE
• ON
• OFF
The constants TRUE/ON and FALSE/OFF are equivalent.
14.6.4 Monadic
The monadic operators operate on a single numeric expression. They

have a higher precedence than the other operators. The following
operators are provided:
• NOT
BOOLEAN complement.
• -
Makes the argument a negative value.
• +
Makes the supplied argument a positive value.
14.6.5 Relational
The relational operators provide comparison functions and return a

boolean value of TRUE or FALSE. The relational operators expect
numeric or string expressions. When applied to strings a lexicographical
check is performed. The following operators are provided:
• =
Equal to.
• <
Less than.
• >
Greater than.

Operators Reference
• <=
Less than or equal to.
• >=
Greater than or equal to.
• <>
Not equal to.
14.6.6 String
The following operators are available:

• ||
Concatenation. Can be applied to two string expressions.
• ,
Concatenation. Can be applied to two string expressions or a string
and a numeric expression.
14.6.7 Transitional
The transitional operators are similar to the relational operators but are
only TRUE the first time the expression is evaluated as TRUE, that is when
the comparison becomes TRUE. The transitional operators expect
numeric or string expressions. The following operators are provided:
• =:
Becomes equal.
• <:
Becomes less than.
• >:
Becomes greater than.
• <=:
Becomes less than or equal to.
• >=:
Becomes greater than or equal to.
• <>:
Becomes not equal to.

Reference Built-ins
14.7 Built-ins
The following built in functions are provided by the PROCESS/FAST
language. It is possible to define more built-ins using the FUNCTION
construct (see the section on functions for more information).
Built-in functions are called by supplying the function name, followed
by a list of arguments enclosed in brackets. Separate each argument in
the list with a comma. The function descriptions provided below are in
the form:
<result> := FUNCTION(<arg_1>, <arg_2>,...);
• <float> := ABS(<float_expr>);
Returns the absolute value of the supplied argument.
• <float> := TRUNC(<float_expr>);
Truncates the supplied argument to its whole number part.
• <float> := SQRT(<float_expr>);
Returns the square root of the supplied argument.
• <float> := POWER(<float_expr>, <float_expr>);
Raises the first argument to the power supplied as second argument.
• <float> := LOG(<float_expr>);
Returns the natural logarithm of the supplied argument.
• <float> := LOG10<float_expr>);
Returns the logarithm to base 10 of the supplied argument.
• <float> := EXP(<float_expr>);
Raises the base of the natural logarithm (e) to the power supplied as
argument.
• <float> := SIN(<float_expr>);
Returns the sine of the supplied argument.
• <float> := COS(<float_expr>);
Returns the cosine of the supplied argument.
• <float> := TAN(<float_expr>);
Returns the tangent of the supplied argument.
• <float> := ARCSIN(<float_expr>);
Return the inverse sine of the supplied argument.
• <float> := ARCCOS(<float_expr>);
Returns the inverse cosine of the supplied argument.
• <float> := ARCTAN(<float_expr>);
Returns the inverse tangent of the supplied argument.
• <float> := SINHYP(<float_expr>);
Returns the hyperbolic sine of the supplied argument.
• <float> := COSHYP (<float_expr>);
Returns the hyperbolic cosine of the supplied argument.

Built-ins Reference
• <float> : TANHYP(<float_expr>);
Returns the hyperbolic tangent of the supplied argument.
• <float> := RANDOM[()];
Returns a pseudo-random value.
• <integer> := INTEGER(<string>);
Returns the integer representation of the supplied string.
• <float> := FLOAT(<string>);
Returns the float representation of the supplied string.
• <string> := STRING(<float_expr>, <format_string>);
Converts the supplied float argument to a string using the supplied
format string. The contents of a format string are described
Subsection 14.8.4
• <integer> := LENGTH(<string>);
Returns the number of characters contained in the supplied string
argument.
• <string> := LEFT(<string>, <integer_expr>);
Returns a string containing the first n characters in the supplied
string.
• <string> := RIGHT(<string>, <integer_expr>);
Returns a string containing the last n characters of the supplied
string.
• <string> := MIDDLE(<string, <integer_expr>,
<integer_expr>);
Returns a string containing the middle n characters of the supplied
string, with the first integer value specifying the start position in the
string and the second integer value specifying the length. The first
character in a string is position 1.
• <float> := GMT(<float_expr>);
Converts the supplied time argument to Greenwich Mean Time.
• <float> := LCT(<float_expr>);
Converts the supplied time argument to Local Civil Time.
• <float> := DAYS(<float_expr>);
Returns the number of days in the month contained in the supplied
GMT time/date.
• <float> := ADDMONTH(<float_expr>, <float_expr>);
Adds the number of months supplied in the second argument to the
GMT time supplied as first argument.
• <integer> := TRGSIG(<signal_id>);
Returns TRUE when the object was triggered by the specified
signal. Returns FALSE when the object was not triggered by a
signal or the specified signal.
• <float> := TRGSIG_VALUE[()];
Returns the value of a non string type signal which triggered the

Reference Built-ins
method. The value returned is the value of the signal at the moment
of triggering.
• <float> := TRGSIG_OLD_VALUE[()];
Returns the old value of a non string type signal which triggered the
method. The value returned is the value of the signal prior the
moment of triggering.
• <string> := TRGSIG_STR_VALUE[()];
Returns the value of the string type signal which triggered the
method. The value returned is the value of the signal at the moment
of triggering.
• <float> := TRGSIG_STR_OLD_VALUE[()];
Returns the old value of the string type signal which triggered the
method. The value returned is the value of the signal prior the
• <integer> := TRGSIG_STATUS[()];
Returns the status of the signal which triggered the method. The
status returned is the status of the signal at the moment of
triggering.
• <integer> := TRGSIG_CONTROL_STATUS[()];
Returns the control status of the signal which triggered the method.
The value returned is the control status of the signal at the moment
of triggering.
• <integer> := TRGSIG_OPTION_STATUS[()];
Returns the option status of the signal which triggered the method.
The value returned is the option status of the signal at the moment
of triggering.
• <integer> := TRGSIG_MERGED_STATUS[()];
Returns the merged status of the signal which triggered the method.
The value returned is the merged status of the signal at the moment
of triggering.
• <integer> := TRGSIG_ALARM_TYPE[()];
Returns the alarm type of the signal which triggered the method.
The value returned is the alarm type of the signal at the moment of
triggering.
• <integer> := TRGSIG_ACKNOWLEDGED[()];
Returns the acknowledged flag of the signal which triggered the
method. The value returned indicates whether the alarm is
acknowledged at the moment of triggering.
• <float> := TRGSIG_HIGH_HIGH_LIMIT[()];
Returns the high high limit of the signal which triggered the
method. The value returned is the high high limit of the signal at the

Built-ins Reference
• <float> := TRGSIG_HIGH_LIMIT[()];
Returns the high limit of the signal which triggered the method. The
value returned is the high limit of the signal at the moment of
triggering.
• <float> := TRGSIG_LOW_LIMIT[()];
Returns the low limit of the signal which triggered the method. The
value returned is the low limit of the signal at the moment of
triggering.
• <integer> := TRGSIG_LOCKED[()];
Returns whether the signal is locked. The value returned is lock
status of the signal at the moment of triggering.
• <float> := TRGSIG_LOW_LOW_LIMIT[()];
Returns the low low limit of the signal which triggered the method.
The value returned is the low low limit of the signal at the moment
of triggering.
• <float> := TRGSIG_DEADBAND[()];
Returns the deadband of the signal which triggered the method. The
value returned is the deadband of the signal at the moment of
triggering.
• <integer> := TRGSIG_QUALITY[()];
Returns the quality code of the signal which triggered the method.
The value returned is the quality code of the signal at the moment
of triggering.
• <float> := TRGSIG_UPDATE_TIME[()];
Returns the update time (in seconds GMT, which may contain a
fractional part) of the signal which triggered the method. The value
returned is the time the attribute of the signal changed introducing
triggering of the method.
• <integer> := TRGTIM(<timer_id>);
Returns TRUE when the object was triggered by the specified
timer. Returns FALSE when the object was not triggered by a timer
or the specified timer.
• <integer> := TRGALM(<alarm_id>);
Returns TRUE when the object was triggered by the
acknowledgement of the specified alarm. Returns FALSE when the
object was not triggered by an alarm acknowledgement or by the
specified alarm acknowledgement.
• <float> := SIG_GETSUB(<signal_id>, <integer_expr>,
<integer_expr>)
Returns the value of a signal prior resetting it. It is normally used to
read signals which represent a so-called sub-item (integrator, pulse-
counter or minimum/maximum) and resetting it in one “atomic”
action.

Reference Built-ins
When the first <integer_expr> hold a non-zero value and the sub-
item is an integrator then the average value of the integrator is
returned which corresponds with the average value of the sub-
item’s main value since the last reset of the integrator.
When the second <integer_expr> holds a non-zero value then the
sub-item is reset in the following way:
When the result of the integer expression is one then the sub-item
is reset.
When the result of the integer expression is two and the sub-item is
a minimum/maximum then the sub-item is set to zero and the sub-
item becoms a minimum sub-item.
When the result of the integer expression is three and the sub-item
is a minimum/maximum then the sub-item is set to zero and the
sub-item becoms a maximum sub-item.
• <integer> := SIG_UPDATE(<signal_id>, <float_expr>,
<integer_expr>,<integer_expr>)
This function updates a signal with a new value and status. The
second argument contains the new value for the signal. The third
argument contains the new status for the signal. When the last
expression holds a zero then the signal is set to the specified value.
When the last expression contains a one then the specified value is
added to the current value of the signal.
The function always returns zero.
• <integer> := SIG_UPDATE_TIME(<signal_id>,
<float_expr>,<integer_expr>,<integer_expr>,
<float_expr>)
This function updates a signal with a new value and status and also
the time of the update. The second argument contains the new value
for the signal. The third argument contains the new status for the
signal. The fourth argument specifies whether the new value should
be set or added to the current value. If this value is zero then the
signal is set to the specified value and if it is one then the specified
value is added to the current value of the signal. The fifth argument
specifies the update time of the signal as a float expression. The
whole number part is seconds since 1970 (UTC) and the part after
the decimal point represents microseconds. The function always
returns zero.
Note that this function sends a message to the item handler to
provide the update time, so make sure that the message queue of
ITM is tuned so it is large enough to cope with any potential bursts.
• <integer> := SIG_OFFLINE(<signal_id>,
<integer_expr>)
Set a signal on or off-line. The signal is set off-line when the
<integer_expr> holds a non-zero value otherwise the signal is set

Built-ins Reference
on-line. When a signal is a main item all its sub-items are also set
on or off-line. The function returns always a zero.
• <integer> := SIG_FORCE_ALARM_STATE(<signal_id>,
<integer_expr>,<integer_expr>)
This function updates the force to normal and force to alarm bits of
a signal. The second argument contains the new value for the force
to normal bit (0 or 1). The third argument contains the new value
for the force to alarm bit (0 or 1). When both bits are set, the force
to alarm bit will overrule the force to normal bit.
• <integer> := SIG_LOCK(<signal_id>,<integer_expr>)
This function lockes or unlocks a signal. The second argument
contains the new value for the lock status (0 or 1) where a one locks
the signal and a zero unlocks the signal.
• <float> := SIG_GET_FLOAT<signal_id>,<integer_expr>)
This function returns the value of an attribute of a signal as a float.
The second argument contains the attribute to be returned. The
attribute is specified by its id. This function should only be used
when the attribute of the signal can not be obtained via other means.
Contact Yokogawa to obtain the id of a certain attribute.
• <integer> :=
SIG_GET_INTEGER<signal_id>,<integer_expr>)
This function returns the value of an attribute of a signal as an
integer. The second argument contains the attribute to be returned.
The attribute is specified by its id.
• <string> :=
SIG_GET_STRING<signal_id>,<integer_expr>)
This function returns the value of an attribute of a signal as a float.
The second argument contains the attribute to be returned. The
attribute is specified by its id.
• <float> := SIG_SET_FLOAT<signal_id>,<integer_expr>,
<float_exp>)
This function sets the value of an attribute of a signal as a float. The
second argument contains the attribute to be set. The attribute is
specified by its id. The third argument specifies the value to set.
The function returns the third argument.
• <integer> :=
SIG_SET_INTEGER<signal_id>,<integer_expr>,
<integer_exp>)
This function sets the value of an attribute of a signal as an integer.
The second argument contains the attribute to be set. The attribute
is specified by its id. The third argument specifies the value to set.

Reference Miscellaneous
• <string> :=
SIG_SET_STRING<signal_id>,<integer_expr>,
<string_exp>)
This function sets the value of an attribute of a signal as a string.
The second argument contains the attribute to be set. The attribute
is specified by its id. The third argument specifies the value to set.
14.8 Miscellaneous
14.8.1 Expressions and precedence
An expression consists of sub-expressions, identifiers, operators and

constants which evaluates to a single value. An expression is evaluated
at the moment it is encountered during execution.
The list of operators is given below with the highest precedence first:
• Unary + and - .
• Boolean and bitwise complement ( ~, NOT).
• Multiplication and division( /, * ).
• Addition and subtraction (+, - ).
• String concatenation (|| and , ).
• Relational and transitional equality and inequality (=, <>, =:, <>: )
• Other relational and transitional operators ( < , >, <=, >=, <:, >:,
<=:, >=: ).
• Bitwise AND ( & ).
• Bitwise XOR ( ^ ).
• Bitwise OR ( | ).
• Logical AND ( AND ).
• Logical Exclusive OR ( XOR ).
• Logical OR ( OR ).
It is possible to force higher precedence within expressions. This can be
done by surrounding expressions with brackets ( ). Any parts of an
expression within brackets will be evaluated first.

Miscellaneous Reference
14.8.2 Comments
Syntax {...<comment_text>...}
Arguments <comment text> The annotating text.
Semantics Comments can be used anywhere within methods where annotation is
necessary. It is recommended to use comment consistently within
methods in order to improve readability. Excessive or poor use of
comments however can degrade readability.
Comments can be put anywhere on a line. When the start of a comment
is encountered (an opening brace), anything after it is ignored until a
matching end of comment is encountered (a closing brace).
Comments are allowed to cross line boundaries.
Notes None.
Example VAR my_float FLOAT; { This is a float }

14.8.3 Current time
Syntax <identifier> := NOW;

Arguments None
Semantics A function is available that returns the current clock time. NOW returns a
float value that contains the current date and time in GMT.
Notes None.
Example VAR start_time;
start_time := NOW;

14.8.4 Format strings
Format strings are used within the STRING function. They specify how a
numeric value shall be converted and displayed within the returned
string.
A format string is specified just like any other string, as a sequence of
characters enclosed in quotes ("). However some of the characters
within the string are interpreted as having a special meaning. Any
characters in the string that do not have a special meaning are printed out
as part of the returned string.
If an empty format string is supplied then a default of "%g" (float) is
used. This produces output of the form [-]mmm.nnnnn or if this is not
long enough to contain it, [-]m.nnnnnnE[+|-]xx. If an attempt to
convert a float into an integer does not fit then an error is returned.
The special characters are described in the list below. They are
categorized according to use. Note that they are case sensitive
casing is significant.
Formatting numbers
• 9
Specifies field width in digits. For example "999" specifies a field
width of 3 digits.
• 0
Displays leading zeroes. For example "0999".
• +
Display the sign of the result. For example "+999".
• .
Specifies the position of the decimal point. For example "99.999".
• EEEE
Specifies exponential notation. For example "99.99EEEE".
Formatting dates
For these conversions, the value to convert is interpreted as the number
of seconds since 1970.
• D
Displays the day of the month.
• DD
The same as D except leading zeros are included if the day is less
than 10.
• DDD
The three letter day of the week.

• M
The month number.
• MM
Same as M but leading zeroes are included if the month number is
less than 10.
• MMM
The three letter month name.
• Y
Displays the last one or two digits of the year. For example 1950 is
displayed as 50, 1901 is displayed as 1. Note that 2050 is also
displayed as 50.
• YY
Displays the last two digits of the year. For example 1901 is
displayed as 01.
• YYYY
The year displayed as 4 digits.
• hh
Displays the hour number.
• mm
Displays the minute number.
• ss
Displays the number of seconds.
• p
Displays parts of a second (up to 6 decimal places). For example
ss.ppp displays the number of seconds and 1000ths of seconds.
Other characters
These characters are valid within all format strings:
• \
This is used for suppressing interpretation of a special character so
that it will be included as part of the returned string. For example
"\Day" will yield “Day” and "\% used" yields "% used".
• %
Uses the ‘C’ format conventions. Valid format characters are d, i,
u, o, x, X, f, e, E, g, G. Note l (letter ell) is not supported. Field
width can also be specified. Examples are "%5s", "%3.2f", "%3d".
See Section 0.4 - ref.3 for more information on ‘C’ format strings.

14.8.5 Quote operator
Syntax <trigger_id>|<timer_id>|<signal_id>|<item_id>|
<alarm_id>’<attribute_name>
Arguments <trigger_id>
A trigger identifier.
<timer_id>
A timer identifier.
<signal_id>
A signal identifier.
<item_id>
An item identifier.
<alarm_id>
An alarm identifier.
<attribute_name>
An attribute of the specified identifier.
Semantics Normally when referring to a TRIGGER, TIMER, SIGNAL,ITEM , or ALARM
by name, the value of that identifier is assumed. However these
identifiers possess attributes other than just their value. In order to access
those attributes, the quote (’) is used followed by the name of the
required attribute. All available attributes can be used within
expressions. However only some attributes can be assigned new values.
See the appropriate section on TRIGGER, TIMER,SIGNAL or ALARM for
information on available attributes.
Notes Triggers and signals are only supported in the full language set.
Example my_timer’status := STOPPED;

14.8.6 STEP
Syntax ENTRYCONDITION STEP <expression> ;

STEP := <state> ;
Arguments <state>
A value representing the state
Semantics This construct is used to control the state of a method. If a class
definition consists of a number of methods, each representing a given
state at a particular time then the STEP construct can be used to move
between these states.
STEP represents the value of the item controlling the object. If a control
item has not been specified then STEP operates in the normal way as
though it were a variable. However it is then not possible to modify the
state externally.
STEP can be used in expressions (usually in entry conditions) to test on
the current state and also to assign it values within methods so that the
current state can be changed. It is useful and more readable to define the
states of an object with constants rather than to use the values directly.
Notes None.
Example
ENTRYCONDITION STEP <> init_phase ;
STEP := init_phase ;

14.8.7 Useful constants
The following miscellaneous constants are provided for general use and
are only applicable within the full language set:
• NODE
The object’s node name.
• INSTALLATION
The object’s installation name. E.g. the first level section.
• UNIT
The object’s unit name. E.g. the second level section.
• SECTION
The object’s section name.
• TAG
The object’s tag name.
• CLASS
The name of the object’s class.


Introduction Using DSS Datasets
15 Using DSS Datasets
15.1 Introduction
This section desribes a number of PROCESS/FAST routines that allow
you to make use of the FAST/TOOLS Data Set Services (DSS) from
within a PROCESS/FAST class.
These routines can be divided into 'basic' and 'advanced' routines. The
basic routines are designed for ease of use; the advanced routines
provide greater flexibility and better performance but might require
more programming effort.
To make use of the PROCESS/FAST-DSS routines a basic
understanding of the FAST/TOOLS-DSS interface is required. The next
section gives you a short introduction to the concepts of DSS and tells
you every thing you need to know about DSS to effectively use the
PROCESS/FAST-DSS routines.
The sections after that will explain in detail how to use the DSS-routines.
First the basic and then the more advanced routines will be explained.
15.2 Just enough DSS

This section describes DSS at a global level. It is meant as an
introduction to DSS and tells you every thing you need to know about
DSS to use the PROCESS/FAST-DSS routines.
The DSS or Data Set Services interface was introduced to FAST/
TOOLS to offer a consistent and easy way to access FAST/TOOLS data.
Both runtime and configuration data can be read
DSS provides FAST/TOOLS data in the form of tables. These tables are
called datasets.
A dataset is a table with fixed length rows. The rows are called the
records of the dataset. The columns are called the fields of the dataset.
The table below shows an example of a dataset, in this case the
SECTION_DF dataset is shown:

Using DSS Datasets Just enough DSS
Table 4: SECTION_DF Dataset table
NAME DESCRIPTION OPC_VISIBLE BLOCKED
Section The section 0 0

Section.Plant The oil plant 1 -
Section.Plant2 The gas plant
...............
Each field in a record can be referred to by its fieldname shown in the

grey caption of the table. Each dataset record has one fieldname called
NAME that uniquely identifies the record.
The fields of a dataset can be of different data types. The NAME and
DESCRIPTION field will be of type string, others may be of a numeric
or boolean type. All available datasets and their data types can be found
in the FAST/TOOLS Engineering Module.
DSS fields can be of many different data types, but PROCESS/FAST
only supports the following data types:
• STRING
• INTEGER
• FLOAT
The PROCESS/FAST-DSS routines will convert PROCESS/FAST data
types to DSS data types as shown in the following table:
Table 5: Data type conversion
DSS data types PROCESS/FAST data type
String STRING
Multi byte string
Byte INTEGER
Unsigned byte
Short
Unsigned short
Long
Boolean
Float FLOAT
Double
Interval
Date
Unsigned long

The Basic DSS interface Using DSS Datasets
Table 5: Data type conversion
DSS data types PROCESS/FAST data type
Memo Not supported in PROCESS/FAST
15.3 The Basic DSS interface

The basic PROCESS/FAST-DSS routines can be used to read or update
individual dataset fields. The routines provided are:
Table 6: Basic DSS routines
PROCESS/FAST Routine Function
DSS_READ_STRING Read a field value as string from a dataset.

DSS_READ_INTEGER Read a field value as integer value from a data-
set.
DSS_READ_FLOAT Read a field value as floating point value from
a dataset.
DSS_UPDATE_STRING Update a string type field with a new value.
DSS_UPDATE_INTEGER Update integer type field with a new value.
DSS_UPDATE_FLOAT Update floating point type field with a new
value.
These routines will, if possible, provide data type conversion. Using for
example DSS_READ_STRING to read a DSS dataset field of type
integer will try to convert the integer value to a string.
In the next sections each of the basic DSS routines are explained in
detail.
15.3.1 DSS_READ_STRING
Description:
This routine returns the contents of a DSS dataset record field as a string
variable.
Syntax:
str_val:= DSS_READ_STRING(dataset_name, record_name,
field_name, result);

Using DSS Datasets The Basic DSS interface
• str_val
String value read from the DSS dataset record field.
• dataset_name
The dataset name to read from.
• record_name
The NAME field of the record to read from.
• field_name
The name of the dataset field to read.
• result
Integer parameter. If the routine was successful this parameter will
be set to value 1. If for some reason the routine failed the value will
be set to 0. In case of failure the result value returned by this routine
will be an empty string.
Returns:
The string value from the dataset field or an empty string in case
of failure.
Example:
{----------------------------------------------------------
| This example reads the DESCRIPTION field from the ITEM_DF
| dataset for the item called Section.Plant.Unit1.Integer01
+---------------------------------------------------------}
VAR result INTEGER;
VAR str_value STRING;
result := 0;
str_value := DSS_READ_STRING("ITEM_DF",
"Section.Plant.Unit1.Integer01",
"DESCRIPTION", result);
IF result = 0 THEN
PRINT "Error reading description from dataset.";
ENDIF;
15.3.2 DSS_READ_INTEGER
Description:

This routine returns the contents of a DSS dataset record field as an

Integer variable.
Syntax:
int_value:= DSS_READ_INTEGER(dataset_name, record_name,
• int_value
Integer value read from the DSS dataset record field.
• dataset_name
• record_name
• field_name
• result
Integer parameter. If the routine was successful this parameter will
be set to value 1. If for some reason the routine failed the value will
be set to 0. In case of failure the result value returned by this routine
will be 0.
Returns:
The integer value from the dataset field or 0 in case of failure.
Example:
{-------------------------------------------------------------
| This example reads the OPC_VISIBLE field from the
| SECTION_DF dataset for the section Section.Plant.
+------------------------------------------------------------}
VAR result INTEGER;
VAR int_value INTEGER;
result := 0;
int_value := DSS_READ_INTEGER("SECTION_DF", "Section.Plant",
"OPC_VISIBLE", result);
IF result = 0 THEN
PRINT "Error reading OPC_VISIBLE field from dataset.";
ENDIF;

15.3.3 DSS_READ_FLOAT
Description:
This routine returns the contents of a DSS dataset record field as a float
variable.
Syntax:
float_value:= DSS_READ_FLOAT(dataset_name, record_name,
• float_value
Float value read from the DSS dataset record field.
• dataset_name
• record_name
• field_name
• result
Integer parameter. If the routine as successful this parameter will be
set to value 1. If for some reason the routine failed the value will be
set to 0. In case of failure the result value returned by this routine
will be 0.
Returns:
The float value from the dataset field or 0 in case of failure.
Example:
{----------------------------------------------------------------
| This example reads the HIGH_LIMIT field from the ITEM_DF
| dataset for the item Test.Plant.Section.Integer02
+----------------------------------------------------------------}
VAR result INTEGER;
VAR float_value FLOAT;
result := 0;
float_value := DSS_READ_FLOAT("ITEM_DF",
"Test.Plant.Section.Integer02","HIGH_LIMIT", result);
IF result = 0 THEN
PRINT "Error reading HIGH_LIMIT from dataset.";
ENDIF;

15.3.4 DSS_UPDATE_STRING
Description:
This routine updates the contents of a DSS dataset record field as a string
variable.
Syntax:
result:= DSS_UPDATE_STRING(dataset_name, record_name,
field_name, str_value);
• result
Integer variable. If the routine was successful this parameter will be
set to 0.
• dataset_name
• record_name
The NAME field of the record to be updated.
• field_name
The name of the dataset field to update.
• str_value
String value to be written to the DSS dataset record field.
Returns:
The result of the routine. If successful the routine will return 1, otherwise
0.

Examples:
{-------------------------------------------------------------
| This example updates the DESCRIPTION field from the ITEM_DF
+------------------------------------------------------------}
VAR result INTEGER;
result := DSS_UPDATE_STRING("ITEM_DF",
"Test.Plant.Section.Integer02",
"DESCRIPTION",
"My item description");
IF result = 0 THEN
PRINT "Error updating item description.";
ENDIF;

15.3.5 DSS_UPDATE_INTEGER
Description:
This routine updates the contents of a DSS dataset record field as an
integer variable.
Syntax:
result := DSS_UPDATE_INTEGER(dataset_name, record_name,
field_name, int_value);
• result
set to value 1. If or some reason the routine failed the value will be
set to. 0.
• dataset_name
• record_name
• field_name
The name of the dataset field to be updated.
• int_value
Integer value to be written to the DSS dataset record field.
Returns:
The result of the routine, if successful the routine will return 1, otherwise
0.

Example:
{----------------------------------------------------------
| This example updates the OPC_VISIBLE field from the
| SECTION_DF dataset for the section Test.Plant.Section
| to 1
+--------------------------------------------------------}
VAR result INTEGER;
result:= DSS_UPDATE_INTEGER("SECTION_DF",
"Test.Plant.Section",
"OPC_VISIBLE", 1);
IF result = 0 THEN
PRINT "Error updating section DSSV_TEST";
ENDIF;

15.3.6 DSS_UPDATE_FLOAT
Description:
This routine updates the contents of a DSS dataset record field as a float
variable.
Syntax:
result := DSS_UPDATE_FLOAT(dataset_name, record_name,
field_name, float_value);
• result
set to value 1. If or some reason the routine failed the value will be
set to. 0.
• dataset_name
• record_name
• field_name
The name of the dataset field to be updated.
• float_value
Float value to be written to the DSS dataset record field.
Returns:
0.
Example:
{-------------------------------------------------------------
| This example reads the HIGH_LIMIT field from the ITEM_DF
+-----------------------------------------------------------}
VAR result INTEGER;
result := DSS_UPDATE_FLOAT("ITEM_DF",
"Test.Plant.Section.Integer02",
"HIGH_LIMIT", 100.5);
IF result = 0 THEN
PRINT "Error updating high limit.";
ENDIF;

Using DSS Datasets The Advanced DSS Interface
15.4 The Advanced DSS Interface

The advanced PROCESS/FAST-DSS routines offer greater flexibility
but require a somewhat more detailed knowledge of DSS. The routines
provided are:
Table 7: Advanced DSS routines
PROCESS/FAST Routine Function:
DSS_OPEN Open a DSS dataset with specified fields.

DSS_OPEN_ALL Open a DSS dataset including all fields.
DSS_CLOSE Close the dataset.
DSS_READ_EQUAL Read dataset record specified by name.
DSS_READ_NEXT Read dataset records sequentially.
DSS_GET_STRING Get dataset field as string.
DSS_GET_FLOAT Get dataset field as float.
DSS_GET_INTEGER Get dataset field as integer.
DSS_PUT_STRING Set dataset field as string.
DSS_PUT_FLOAT Set dataset field as float.
DSS_PUT_INTEGER Set dataset field as integer.
DSS_UPDATE Update a record in DSS.
DSS_DELETE Delete dataset record specified by name.
DSS_INSERT Insert field set contents to dataset as new record.
DSS_SET_FILTER Apply a filter to a dataset.
DSS_REMOVE_FILTER Remove filter from dataset.
DSS_ERROR_LOG Switch error logging ON/OFF.
15.4.1 Using the advanced routines
The general program flow when using the advanced routines is as

follows:
1. Open the dataset.
2. Read from the dataset / Update the dataset.
3. Close the dataset.

The Advanced DSS Interface Using DSS Datasets
When opening the dataset you can choose to include all the dataset fields
or limit the number of fields to those fields that are actually used.
Limiting the number of fields is often preferable from a performance
point of view.
The DSS_OPEN() routine allows you to provide a list of fields you want
to include when opening the dataset. The DSS_OPEN_ALL routine will
include all dataset fields. Both these routines will return a so-called
dataset id. This is an integer value that uniquely identifies the open
dataset. It will be used to refer to the open dataset in all subsequent DSS
routines.
Example:
VAR dss_id INTEGER;
VAR result INTEGER;
dss_id := DSS_OPEN("ITEM_DF", "NAME, DESCRIPTION", "ru", result);
Suppose we want to update the DESCRIPTION of a specific FAST/

TOOLS item. For that we first need to read the specific dataset record
into the field set using DSS_READ_EQUAL():
result := DSS_READ_EQUAL(dss_id, "Test.Plant.Section.Tag01");
IF result = 0 THEN
PRINT "Error in DSS_READ_EQUAL.";
ENDIF;
If the read was successful all fields included in the DSS_OPEN() routine
will be read from the record. Now we can update the DESCRIPTION
field in the fieldset:
result := DSS_PUT_STRING(dss_id, "DESCRIPTION",
"The new description");
This will update the contents of the DESCRIPTON field in the field set.
Note that the change is not yet actually written to FAST/TOOLS. The
change is only written into in the field set buffer. This makes it possible
to change more than one dataset field and then write the changed dataset
record to FAST/TOOLS in one action.
To actually write the changes to FAST/TOOLS we use the
DSS_UPDATE() routine:
result := DSS_UPDATE(dss_id);
After we are finished using the dataset it is important to close the dataset.
This will free the resources used by DSS. If the datasets are not closed it
will result in memory leaks and may eventually drain you system of
resources.
result := DSS_CLOSE(dss_id);

The following sections will explain the advanced DSS routines in detail
and give examples of how to use them.
15.4.2 DSS_OPEN
Description:
This routine opens a DSS dataset.
Syntax:
dss_id := DSS_OPEN(dataset_name, field_names, mode,
result);
• dss_id
Integer id uniquely identifying this open dataset. It will be used in
all subsequent calls to DSS routines for this dataset.
• dataset_name
String value containing the name of the dataset to open.
• field_names
The names of the dataset fields to include in the field set. This
parameter is passed as a string containing the field names in a
comma separated string.
• mode
String parameter indicating the 'mode' in which to open the dataset.
The mode can be read "r", update "u", delete "d", insert "i" or any
combination of those.
• result
Integer parameter. If the routine is successful this parameter will be
set to 0.
Returns:
0.

Example:
{------------------------------------------------------
| This example opens the ITEM_DF dataset with fields
| NAME and DESCRIPTION for read and update.
+-----------------------------------------------------}
VAR dss_id INTEGER;
VAR result INTEGER;
dss_id := DSS_OPEN("ITEM_DF", "NAME, DESCRIPTION", "ru",
result);

15.4.3 DSS_OPEN_ALL
Description:
This routine opens a DSS dataset and includes all fields in the fieldset.
Syntax:
dss_id := DSS_OPEN_ALL(dataset_name, mode, result);
• dss_id
Integer id uniquely identifying this open dataset. It will be used in
all subsequent calls to DSS routines for this dataset.
• dataset_name
String value containing the name of the dataset to open.
• mode
String parameter indicating the 'mode' in which to open the dataset.
The mode can be read "r", update "u", delete "d", insert "i" or any
combination of those.
• result
set to 0.
Returns:
0
Example:
{-------------------------------------------------
| This example opens the ITEM_DF dataset with all
| fields for read update, delete and insert
| permission.
+-------------------------------------------------}
VAR dss_id INTEGER;
VAR result INTEGER;
dss_id := DSS_OPEN_ALL("ITEM_DF", "rudi", result);

15.4.4 DSS_CLOSE
Description:
This routine closes an open dataset and frees the resources.
Syntax:
• dss_id
Integer id uniquely identifying this open dataset. Subsequent calls
to DSS routines using this dss_id will fail.
• result
set to 0.
Returns:
0.
Example:
{------------------------------------------------------
| This example closes a dataset identified by dss_id
| and frees all resources involved.
+-----------------------------------------------------}
VAR result INTEGER;

15.4.5 DSS_READ_EQUAL
Description:
This routine reads a specific record from the dataset. The record is
specified by name.
Syntax:
result := DSS_READ_EQUAL(dss_id, record_name);
• dss_id
Integer id uniquely identifying the open dataset to read from.
• record_name
String containing the value of the NAME field of the record to read.
• result
set to 0.
Returns:
0.
Example:
{------------------------------------------------------
| This example uses DSS_READ_EQUAL to read a specific
| record form a dataset.
+-----------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
result := 0;
{------------------------------------------------------
| Open dataset
+-----------------------------------------------------}
dss_id := DSS_OPEN_ALL("SECTION_DF", "r", result);
IF result = 0 THEN
PRINT "Can not open dataset SECTION_DF.";
ENDIF;
{------------------------------------------------------
| Read the section Test.Plant.Section from DSS into the
| field set.
+-----------------------------------------------------}
result := DSS_READ_EQUAL(dss_id, "Test.Plant.Section");
IF result = 0 THEN
PRINT "Can not read record Test.Plant.Section.";

ENDIF;
{------------------------------------------------------
| Get the value of the DESCRIPTION field from the
| field set.
+-----------------------------------------------------}
str_value := DSS_GET_STRING(dss_id, "DESCRIPTION",
result);
IF result = 0 THEN
PRINT "Error in DSS_GET_STRING";
ENDIF;
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.6 DSS_READ_NEXT
Description:
This routine reads a record sequentially from a dataset.
Syntax:
result := DSS_READ_NEXT(dss_id);
• dss_id
• result
set to 0.
Returns:
The result of the routine, if successful the routine will result 1, otherwise
0.

Example:
{------------------------------------------------------
| This example uses DSS_READ_NEXT to read records
| sequential form a dataset.
+-----------------------------------------------------}
VAR result INTEGER;

VAR dss_id INTEGER;
result := 0;
{------------------------------------------------------
| Open dataset
+-----------------------------------------------------}
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| Read the first record from DSS into the field set.
+-----------------------------------------------------}
IF result = 0 THEN
PRINT "Can not read record sequential,";
ENDIF;
{------------------------------------------------------
| Read the second record from DSS into the field set.
+-----------------------------------------------------}
IF result = 0 THEN
PRINT "Can not read record sequential,";
ENDIF;
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.7 DSS_GET_STRING
Description:
This routine reads the value of a field as a string.
Syntax:
field_value := DSS_GET_STRING(dss_id, field_name,
result);
• field_value
String value read from the field set. If the routine fails for some
reason field_value will contain an empty string.
• dss_id
• field_name
Name of the field to read from the field set.
• result
set to 0.
Returns:
The contents of the DSS field as a string if the routine was successful,
otherwise an empty string is returned.
Example:
{---------------------------------------------------------
| This example uses DSS_GET_STRING to read a field value
| from the field set
+--------------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
result := 0;
{------------------------------------------------------
| Open dataset
+-----------------------------------------------------}
IF result = 0 THEN
ENDIF;

{------------------------------------------------------
| field set.
+-----------------------------------------------------}
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| Get the value of the DESCRIPTION field from the
| field set.
+-----------------------------------------------------}
str_value := DSS_GET_STRING(dss_id, "DESCRIPTION",
result);
IF result = 0 THEN
PRINT "Error in DSS_GET_STRING";
ENDIF;
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.8 DSS_GET_FLOAT
Description:
This routine reads the value of a field as a float.
Syntax:
field_value := DSS_GET_FLOAT(dss_id, field_name,
result);
• field_value
Float value read from the field set. If the routine fails for some
reason field_value will be set to 0.
• dss_id
• field_name
• result
set to 0.
Returns:
The contents of the DSS field as a float if the routine was successful;
otherwise 0 is returned.
Example:
{------------------------------------------------------
| This example uses DSS_GET_FLOAT read a field value
+-----------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
VAR float_value FLOAT;
result := 0;
{------------------------------------------------------
| Open dataset
+-----------------------------------------------------}
dss_id := DSS_OPEN_ALL("ITEM_DF", "r", result);
IF result = 0 THEN
PRINT "Can not open dataset ITEM_DF.";
ENDIF;
{------------------------------------------------------
| Read the item Test.Plant.Section.Tag01 from DSS into the

| field set.
+-----------------------------------------------------}
result := DSS_READ_EQUAL(dss_id, "Test.Plant.Section.Tag01");
IF result = 0 THEN
PRINT "Can not read record Test.Plant.Section.Tag01.";
ENDIF;
{------------------------------------------------------
| Get the value of the HIGH_LIMIT field from the
| field set
+-----------------------------------------------------}
float_value := DSS_GET_FLOAT(dss_id, "HIGH_LIMIT",
result);
IF result = 0 THEN
PRINT "Error in DSS_GET_FLOAT";
ENDIF;
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.9 DSS_GET_INTEGER
Description:
This routine reads the value of a field as an integer.
Syntax:
field_value := DSS_GET_INTEGER(dss_id, field_name,
result);
• field_value
Integer value read from the field set.
• dss_id
• field_name
• result
set to 0.
Returns:
The contents of the DSS field as an integer if the routine was successful;
otherwise 0 is returned.
Example:
{-----------------------------------------------------
| This example uses DSS_GET_INTEGER read a field value
+-----------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
VAR int_value INTEGER;
result := 0;
{----------------------------------------------------
| Open dataset
+---------------------------------------------------}
IF result = 0 THEN
ENDIF;
{----------------------------------------------------
| Read the section Test.Plant.Section from DSS into
| the field set.
+---------------------------------------------------}

IF result = 0 THEN
ENDIF;
{----------------------------------------------------
| Get the value of the BLOCKED field from the
| field set
+---------------------------------------------------}
int_value := DSS_GET_INTEGER(dss_id, "BLOCKED",
result);
IF result = 0 THEN
PRINT "Error in DSS_GET_INTEGER";
ENDIF;
{---------------------------------------------------
| Close dataset
+---------------------------------------------------}

15.4.10 DSS_PUT_STRING
Description:
This routine writes the value of a field as a string.
Syntax:
result := DSS_PUT_STRING(dss_id, field_name,
field_value);
• result
Integer. If the routine is successful it will be set to value 1. If or
some reason the routine failed the value will be set to. 0.
• dss_id
Integer id uniquely identifying the open dataset to write to.
• field_name
Name of the dataset field to write.
• field_value
String value to write into the specified field.
Returns:
0.
Example:
{----------------------------------------------------
| This example uses DSS_PUT_STRING to write a field
| value.
+---------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
result := 0;
{----------------------------------------------------
| Open dataset
+---------------------------------------------------}
dss_id := DSS_OPEN_ALL("SECTION_DF", "ru", result);
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| field set.
+-----------------------------------------------------}
IF result = 0 THEN


ENDIF;
{------------------------------------------------------
| Set the value of the DESCRIPTION field in the
| field set.
+-----------------------------------------------------}
result := DSS_PUT_STRING(dss_id, "DESCRIPTION",
"My Description");
IF result = 0 THEN
PRINT "Error in DSS_PUT_STRING";
ENDIF;
{------------------------------------------------------
| Write field set to DSS
|+----------------------------------------------------}
IF result = 0 THEN
PRINT "Error updating dataset.";
ENDIF;
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.11 DSS_PUT_FLOAT
Description:
This routine writes the value of a field as a float.
Syntax:
result := DSS_PUT_FLOAT(dss_id, field_name,
field_value);
• result
set to 0.
• dss_id
• field_name
• field_value
Float value to write into the field.
Returns:
0

Example:
{-----------------------------------------------------
| This example uses DSS_PUT_FLOAT to write a field
| value.
+-----------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
result := 0;
{-----------------------------------------------------
| Open dataset
+-----------------------------------------------------}
dss_id := DSS_OPEN_ALL("ITEM_DF", "ru", result);
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| Read the item Test.Plant.Section.Tag01 from DSS into
| the field set.
+-----------------------------------------------------}
result := DSS_READ_EQUAL(dss_id,"Test.Plant.Section.Tag01");
IF result = 0 THEN
PRINT "Can not read record Test.Plant.Section.Tag01.";
ENDIF;
{------------------------------------------------------
| Set the value of the HIGH_LIMIT field in the
| field set
+-----------------------------------------------------}
result := DSS_PUT_FLOAT(dss_id, "HIGH_LIMIT", 10.5);
IF result = 0 THEN
PRINT "Error in DSS_PUT_FLOAT";
ENDIF;
{-----------------------------------------------------
|+---------------------------------------------------}
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.12 DSS_PUT_INTEGER
Description:
This routine writes the value of a field as integer.
Syntax:
result := DSS_PUT_INTEGER(dss_id, field_name,
field_value);
• result
set to 0.
• dss_id
• field_name
• field_value
Integer value to write into the field set.
Returns:
0.
Example:
{----------------------------------------------------
| This example uses DSS_PUT_INTEGER to write a field
| value into the field set
+---------------------------------------------------}
VAR result INTEGER;

VAR dss_id INTEGER;
result := 0;
{------------------------------------------------------
| Open dataset
+-----------------------------------------------------}
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| the field set.
+-----------------------------------------------------}

IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| Write a new value into the BLOCKED field of the
| field set
+-----------------------------------------------------}
result := DSS_PUT_INTEGER(dss_id, "BLOCKED", 1);
IF result = 0 THEN
PRINT "Error in DSS_PUT_INTEGER";
ENDIF;
{------------------------------------------------------
+-----------------------------------------------------}
IF result = 0 THEN
ENDIF;
{-----------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.13 DSS_UPDATE
Description:
This routine writes the updated field set to FAST/TOOLS. After a
dataset field was read from FAST/TOOLS and one or more fields were
updated it can be written back to FAST/TOOLS using the
DSS_UPDATE routine.
Syntax:
• result
set to 0.
• dss_id
Integer id uniquely identifying the open dataset to update.
Returns:
The result of the routine, if successful the routine will return 1, otherwise
0.
Example:
{-----------------------------------------------------
| This example uses DSS_UPDATE to write the contents
| of a modified dataset into FAST/TOOLS
+----------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
result := 0;
{------------------------------------------------------
| Open dataset for read and update
+-----------------------------------------------------}
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| the field set.
+-----------------------------------------------------}
IF result = 0 THEN
ENDIF;
{------------------------------------------------------

| Get the value of the BLOCKED field from the

| field set
+-----------------------------------------------------}
result := DSS_PUT_INTEGER(dss_id, "BLOCKED", 1);
IF result = 0 THEN
PRINT "Error in DSS_PUT_INTEGER";
ENDIF;
{------------------------------------------------------
+-----------------------------------------------------}
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.14 DSS_DELETE
Description:
This routine deletes a specified record from a dataset.
The NAME field of the dataset indicates the record to be deleted.
Syntax:
result := DSS_DELETE(dss_id);
• result
set to 0.
• dss_id
Integer id uniquely identifying the open dataset to delete.
Returns:
0.
Example:
{------------------------------------------------------
| This example uses DSS_DELETE to delete a record form
| a dataset.
+-----------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
result := 0;
{------------------------------------------------------
| Open dataset for delete
+-----------------------------------------------------}
dss_id := DSS_OPEN("SECTION_DF", "NAME", "d", result);
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| Write the name of the record we want to delete in
| NAME field. Here we want to delete Test.Plant.Section
+-----------------------------------------------------}
result := DSS_PUT_STRING(dss_id, "NAME", "Test.Plant.Section");
IF result = 0 THEN
PRINT "DSS_PUT_STRING error";
ENDIF;
{------------------------------------------------------
| Delete record "Test.Plant.Section"
+-----------------------------------------------------}

result := DSS_DELETE(dss_id);
IF result = 0 THEN
PRINT "Error in DSS_DELETE.";
ENDIF;
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.15 DSS_INSERT
Description:
This routine inserts a dataset record into a dataset.
Syntax:
result := DSS_INSERT(dss_id);
• result
Integer parameter. If the routine is successful this value will be set
to 1. If for some reason the routine failed the value will be set to 0.
• dss_id
Integer id uniquely identifying the open dataset to insert.
Returns:
0
Example:
{----------------------------------------------------
| This example uses dss_insert to add
| new record into DSS
+---------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
result := 0;
{----------------------------------------------------
| Open dataset for read and insert
+---------------------------------------------------}
dss_id := DSS_OPEN_ALL("SECTION_DF", "ri", result);
IF result = 0 THEN
ENDIF;
{-----------------------------------------------------
| the field set.
+----------------------------------------------------}
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| Change the NAME field in to Test.Plant.Section2.
+-----------------------------------------------------}
result := DSS_PUT_STRING(dss_id, "NAME", "Test.Plant.Section2");
IF result = 0 THEN
PRINT "Can not write record Test.Plant.Section2.";

ENDIF;
{-----------------------------------------------------
| Insert new record called Test.Plant.Section into SECTION_DF
| dataset.
+-----------------------------------------------------}
result := DSS_INSERT(dss_id);
IF result = 0 THEN
PRINT "Error in DSS_INSERT";
ENDIF;
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.16 DSS_SET_FILTER
Description:
This routine sets a filter on a dataset. Filters only apply to the
DSS_READ_NEXT() routine. Once a filter is set on a dataset only
records that conform to the filter are read by the DSS_READ_NEXT()
routine. For a detailed explanation of the DSS filter syntax please see
the DSS System Integrating manual.
In the PROCESS/FAST DSS filter expression string literals are
indicated by a single quote ', as shown in the example:
"SECTION_PATH = 'OPC_DSS'"
In case your filter is on the NAME field of a dataset record you can omit
the field name. For example:
DSS_SET_FILTER(dss_id, "NAME = 'Test.Plant.Section'");
Has the same effect as:
DSS_SET_FILTER(dss_id, "Test.Plant.Section");
Syntax:
result := DSS_SET_FILTER(dss_id, filter_expression);
• result
set to 0.
• dss_id
Integer id uniquely identifying the open dataset to place the filter
on.
• filter_expression
String containing DSS filter expression.
Returns:
0.

Example:
{------------------------------------------------------
| This example uses DSS_SET_FILTER in combination with
| the DSS_READ_NEXT routine.
+-----------------------------------------------------}
VAR result INTEGER;
VAR dss_id INTEGER;
result := 0;
{-----------------------------------------------------
| Open dataset
+-----------------------------------------------------}
IF result = 0 THEN
ENDIF;
{------------------------------------------------------
| Set filter expression. Only items from the section
| OPC_DSS are read.
+-----------------------------------------------------}
result := DSS_SET_FILTER(dss_id, "SECTION_PATH =
'Test.Plant.Section'");
IF result = 0 THEN
PRINT "Can not set filter.";
ENDIF;
{------------------------------------------------------
| Read the first record from ITEM_DF in the section
| 'Test.Plant.Section'
+-----------------------------------------------------}
IF result = 0 THEN
PRINT "Can not read record.";
ENDIF;
{------------------------------------------------------
| Remove the filter from dataset.
+-----------------------------------------------------}
result := DSS_REMOVE_FILTER(dss_id);
{------------------------------------------------------
| Close dataset
+-----------------------------------------------------}

15.4.17 DSS_REMOVE_FILTER
Description:
This routine removes a filter from a dataset.
Syntax:
result := DSS_REMOVE_FILTER(dss_id);
• result
set to 0.
• dss_id
Integer id uniquely identifying the dataset from which to remove
the filter.
Returns:
0.
Example:
Please see the example for the DSS_SET_FILTER. This includes the
DSS_REMOVE_FILTER routine.

15.4.18 DSS_ERROR_LOG
Description:
This routine is used to enable/disable error logging on the FAST/
TOOLS system log.
The error logging is a 'global' option. This means if it can only be
enabled for the whole of PROCESS/FAST. Once it is enabled in one
class, error logging for all objects is enable. To limit the amount of
logging message it is possible to surround the area of PROCESS/FAST
code you are debugging with a DSS_ERROR_LOG(1) and a
DSS_ERROR_LOG(0) statement.
If the DSS routine returns an error condition and error logging is enabled
then the error message will be logged on the FAST/TOOLS system log.
Syntax:
DSS_ERROR_LOG(logging);
• logging
Integer parameter. If set to 1 logging is turned on, if set to 0 logging
is turned off,
Returns:
None
Example:
{----------------------------------------------------
| Enable error logging
+---------------------------------------------------}
DSS_ERROR_LOG(1);
{---------------------------------------------------
| Disable error logging
+---------------------------------------------------}
DSS_ERROR_LOG(0);


Introduction AGA calculations
16 AGA calculations
16.1 Introduction
This chapter provides information about the built in AGA calculation
functions.
The AGA calculation functions are a set of functions build around an
AGA calculation engine. The AGA calculation engine contains the
following flow calculation algoritms:
• AGA3 - Orifice metering of natural gas and other related
hydrocarbon gases
• AGA7 - Measurement of gas by turbine meters
• AGA8 - Compressibility factors of natural gas and other related
hydrocarbon gases
• AGA9 - Measurement of gas by multipath ultrasonic meters
• AGA10 - Speed of sound in natural gas and other related
hydrocarbon gases
• AGA11 - Measurement of natural gas by Coriolis meter
• V-Cone
• Wafer-Cone
Further the following additional calculations are supported by the
engine:
• Calculation of gross heating value, relative density and
compressibility factor for natural gas mixtures from composition
analysis by AGA5 or GPA2172 method
• Calculation of atmospheric pressure depending on latitude and
altitude
The set of functions around the calculation engine can be divided in:
• Initialization function to allocate and initialize the parameter data
for the calculation engine.
• Input functions each filling one or more of the input parameters.
• Calculation function which will do one calculation cycle over all
given input parameters. The resulting output parameters are made
available for the output functions.
• Output functions each retrieving one output parameter.

AGA calculations AGA functions
16.2 AGA functions

The next sub sections will describe the available built in AGA functions
provided by the PROCESS/FAST language.
Many of the routines can return an integer status result <stat>. When
<stat> is zero the call was successful. A negative value indicates an error
which can be passed to the AGA_ERROR() function to translate it to a
text.
16.2.1 AGA_INIT()
Function:
This function initializes an AGA calculation. The function claims a
memory area with space for all input, output and calculation
optimization parameters for the calculation function. All parameters are
initial set to zero.
One PROCESS/FAST object can contain one AGA memory area. When
a second AGA_INIT call is done in the same object the previous claimed
area is re-used.
Syntax:
<Stat> := AGA_INIT(<Flow>, <Comp>, <Atmo>, <SG>,
<Energy>, <Unit>, <BaseT>, <BaseP>);
Where:
Parameter Description Comment
Stat Status 0 = OK
<0 = Error
Flow Select the flow calculations to 1 = AGA8 + AGA3
be done 2 = AGA8 + AGA7
3 = AGA8 + V-Cone
4 = AGA8 + Wafer-Cone
5 = AGA8 + AGA9 + AGA10
6 = AGA8
7 = AGA8 + AGA11
Comp AGA8 compression calcula- 1 = detail
tion method 2 = Gross HV/RD/CO2
3 = Gross RD/N2/CO2

AGA functions AGA calculations
Atmo Atmospheric pressure calcula- 1 = Calculate

tion method 2 = Manual
When “calculate” is selected
also the gravity is calculated else
a fixed value of 9.81 is used as
gravity. (This gravity is used in
V-Cone and Wafer-Cone calcu-
lations)
SG Specific gravity (= relative 1 = Calculate
density) calculation method 2 = Manual
Energy Energy calculation method 0 = Manual
1 = AGA5
2 = GPA2172
Unit Units to be used 1 = US units
2 = SI units
BaseT Base temperature US: degF
SI: degC
BaseP Base Pressure US: psia
SI: kPa
16.2.2 AGA_ERROR()
Function:
This function converts the AGA error code to text and optional logs the
error on UMH.
Syntax:
<Text> := AGA_ERROR(<Stat>, <Log>);
Where:
Text String containing the error text The error text

Stat Error code Error code returned by an
AGA routine
Log Log error on UMH selector 0 = Do not log
1 = Log

16.2.3 AGA_CALC()
Function:
This function will do one cycle of the AGA calculations. All previous
Syntax:
<Stat> := AGA_CALC();
Where:
Stat Status 0 = OK
<0 = Error
16.2.4 AGA_COMP()
Function:
This function stores the fraction of one component of the gas
composition in the input parameters area.
The gas composition is needed for all flow calculations.
Syntax:
<Stat> := AGA_COMP(<Comp>, <Fraction>);
Where:
Stat Status 0 = OK
<0 = Error

Comp Component number 0 = Methane, CH4

1 = Nitrogen, N2
2 = Carbon dioxide, CO2
3 = Ethane, C2H6
4 = Propane, C3H8
5 = Water, H2O
6 = Hydrogen sulphide, H2S
7 = Hydrogen, H2
8 = Carbon monoxide, CO
9 = Oxygen, O2
10 = i-Butane, IC4H10
11 = n-Butane, NC4H10
12 = i-Pentane, IC5H12
13 = n-Pentane, NC5H12
14 = n-Hexane, C6H14
15 = n-Heptane, C7H16
16 = n-Octane, C8H18
17 = n-Nonane, C9H20
18 = n-Decane, C10H22
19 = Helium, He
20 = Argon, Ar
Fraction The fraction of the selected com- Valye between 0.0 and 1.0
ponent
16.2.5 AGA_SP()
Function:
This function stores the absolute static pressure in the input parameters
area. When only a gauge static pressure is available first the atmospheric
pressure should be added to it.
The atmospheric pressure needed for this calculation can itself be
calculated, see AGA_INIT() parameter “Atmo”. However for the very
first calculation the absolute static pressure must be calculated with a
“good guess” atmospheric pressure. A good guess value is: 101.325
The absolute static pressure is needed for all calculations.
Syntax:
<Stat> := AGA_SP(<SP>);

Where:
Stat Status 0 = OK
<0 = Error
SP Absolute static pressure US: psia
SI: kPa
16.2.6 AGA_FT()
Function:
This function stores the flow temperature in the input parameters area.
The flow temperature is needed for all calculations.
Syntax:
<Stat> := AGA_FT(<FT>);
Where:
Stat Status 0 = OK
<0 = Error
FT Flow temperature US: degF
SI: degC
16.2.7 AGA_DP()
Function:
This function stores the differential pressure in the input parameters
area.
The differential pressure is needed for AGA3, V-Cone and Wafer-Cone
calculations.
Syntax:
<Stat> := AGA_DP(<DP>);

Where:
Stat Status 0 = OK
<0 = Error
DP Differential pressure US: inchH2O (60degF)
SI: kPa
16.2.8 AGA_K()
Function:
This function stores the isentropic expansion in the input parameters
area. When this function is never called a default value of 1.3 will be
used.
The isentropic expansion is used for AGA3, V-Cone and Wafer-Cone
calculations.
Syntax:
<Stat> := AGA_K(<K>);
Where:
Stat Status 0 = OK
<0 = Error
K Isentropic expansion Default 1.3
16.2.9 AGA_MU()
Function:
This function stores the viscosity in the input parameters area. When this
function is never called a default value of 0.0000068997766652 lbm/
(ft*sec) or 0.010267998472 cP will be used.
The viscosity is used for AGA3 calculations.
Syntax:
<Stat> := AGA_MU(<MU>);

Where:
Stat Status 0 = OK
<0 = Error
MU Viscosity US: lbm/(ft*sec)
SI: cP
Default:
US: 0.0000068997766652
SI: 0.010267998472
16.2.10 AGA_SG()
Function:
This function stores the manual specific gravity (= relative density) in
the input parameters area.
The manual specific gravity (= relative density) is only used when the
specific gravity calculation method “manual” is selected in
AGA_INIT().
Syntax:
<Stat> := AGA_SG(<SG>);
Where:
Stat Status 0 = OK
<0 = Error
SG Specific gravity (= relative density)
16.2.11 AGA_ATM_PRESS()
Function:
This function stores the manual atmospheric pressure in the input
parameters area.
The manual atmospheric pressure is only used when the atmospheric
pressure calculation method “manual” is selected in AGA_INIT().

The atmospheric pressure is not used in any of the AGA calculations. It

is only separately returned as an output parameter.
Syntax:
<Stat> := AGA_ATM_PRESS(<AP>);
Where:
Stat Status 0 = OK
<0 = Error
AP Manual atmospheric pressure US: psia
SI: kPa
16.2.12 AGA_POSITION()
Function:
This function stores the latitude and altitude in the input parameters area.
The latitude and altitude are used when the atmospheric pressure
calculation method “calculate” is selected in AGA_INIT().
Syntax:
<Stat> := AGA_POSITION(<Deg>,<Min>,<Sec>,<Alt>);
Where:
Stat Status 0 = OK
<0 = Error
Deg Latitude degredes 0-90
Min Latitude minutes 0-60
Sec Latitude seconds 0-60
Alt Altitude US: ft
SI: m

16.2.13 AGA_DEADBAND()
Function:
With this function a number of deadbands and a difference pressure
cutoff value can be stored in the input parameters area.
When the input variables SP, FT and DP all change less than the
deadband variable no new calculation will be done (reducing CPU time).
When the DP value is smaller than the cutoff value the calculated flow
will be zero.
Syntax:
<Stat> := AGA_DEADBAND(<SPDB>,<FTDB>,<DPDB>,<DBCutoff>);
Where:
Stat Status 0 = OK
<0 = Error
SPDB Static pressure deadband US: psia
SI: kPa
FTDB Flow temperature deadband US: degF
SI: degC
DPDB Differential pressure deadband US: inchH2O (60degF)
SI: kPa
DPCutoff Differential pressure cutoff US: inchH2O (60degF)
SI: kPa
16.2.14 AGA_GPA2172()
Function:
With this function the wet gas calculation parameters can be stored in the
input parameters area.
The AGA_INIT() function will initial set the “Do wet gas analysis”
parameter to 0 (= no wet gas).
The humidity and air fraction parameters are actually not used in the
calculations.

Syntax:
<Stat> := AGA_GPA2172(<GasAnl>, <RelHum>, <HumGas>,
<ExcAir);
Where:
Stat Status 0 = OK
<0 = Error
GasAnl Gas analysis method 0 = Dry gas
1 = Saturated gas
RelHum Relative humidity For future use
HumGas Humidity of gas For future use
ExcAir Fraction of excess air For future use
16.2.15 AGA_3_METER()
Function:
This function stores the AGA3 metering specific parameters in the input
parameters area.
Syntax:
<Stat> := AGA_3_METER(<TapP>, <MatP>, <MatO>, <DiaP>,
<DiaO>, <RefT>);
Where:
Stat Status 0 = OK
<0 = Error
TapP Tap position 1 = Upstream
2 = Downstream
MatP Material pipe 1 = Stainless
2 = Monel
3 = Carbon steel
MatO Material orifice plate 1 = Stainless
2 = Monel
3 = Carbon steel

DiaP Diameter pipe US: in

SI: mm
DiaO Diameter orifice plate US: in
SI: mm
RefT Reference temperature US: degF
SI: degC
16.2.16 AGA_CONE()
Function:
This function stores the AGA Cone metering specific parameters in the
Syntax:
<Stat> := AGA_CONE(<DiaP>, <DiaC>, <CD>, <SGRef>,
<MatP>, <MatC>, <FState>, <SGSel>);
Where:
Stat Status 0 = OK
<0 = Error
DiaP Diameter pipe US: in
SI: mm
DiaC Diameter orifice plate US: in
SI: mm
CD V-Cone flowmeter coefficient
SGRef V-Cone reference specific gravity Used when CalSG of
function AGA_INIT() is
“Manual”
MatP Material pipe 1 = Stainless
2 = Monel
3 = Carbon steel
MatC Material orifice plate 1 = Stainless
2 = Monel
3 = Carbon steel


FState Fluid state 0 = Gases and vapors
1 = Liquid
SGSel Specific gravity selection 0 = Ideal
1 = Real
Only used when CalSG
of function AGA_INIT()
is “Calculate”.
16.2.17 AGA_PULSE()
Function:
This function stores the pulse data in the input parameters area.
This pulse data is needed for AGA7, AGA9 and AGA11 calculations.
Syntax:
<Stat> := AGA_PULSE(<Pulses>, <K>, <Period>);
Where:
Stat Status 0 = OK
<0 = Error
Pulses Amount of input pulses count
K Pulses per cubic feet or cubic US: count/f3
meter (For AGA7 and AGA9) SI: count/m3
Pulses per lbm or kg (For US: count/lbm
AGA11) SI: count/kg
Period Accumulation time for these Hours
pulses (= scan rate) When e.g. calculation is done
each 36 seconds specify here
0.01. (When 36 is specified the
calculated flowrate will be in
xxx/sec i.s.o. xxx/hour)

16.2.18 AGA_8_GROSS()
Function:
This function stores the AGA8 gross calculation specific parameters in
These parameters are needed when a gross method for AGA8
calculation is selected in AGA_INIT().
Syntax:
<Stat> := AGA_8_GROSS(<HV>, <RTHV>, <RTMD>, <RTSG>,
<RPMD>, <RPSG>);
Where:
Stat Status 0 = OK
<0 = Error
HV Heating value at reference condition US: BTU/ft3
SI: kJ/m3
RTHV Reference temperature for heating US: degF
value SI: degC
RTMD Reference temperature for molar US: degF
density SI: degC
RTSG Reference temperature for relative US: degF
density SI: degC
RPMD Reference pressure for molar density US: psia
SI: kPa
RPSG Reference pressure for relative den- US: psia
sity SI: kPa
16.2.19 AGA_9_INIT()
Function:
This function stores AGA9 specific parameters in the input parameters
area.

Syntax:
<Stat> := AGA_9_INIT (<CPSM>, <CTSM>, <PrCorr>, <GQRaw>,
<OD>, <ID>, <MCPSM>, <MCTSM>, <MPrCorr>);
Where:
Stat Status 0 = OK
<0 = Error
CPSM CPSM selection 0 = None
1 = Manual
2 = Calculate (needs function
AGA_9_CPSM())
CTSM CTSM selection 0 = None
1 = Manual
AGA_9_CTSM())
PrCorr Profile correction selection 0 = None
1 = Manual
AGA_9_PCORR())
GQRaw Get Raw flowrate selection 0 = AGA7 (needs funtion
AGA_PULSE())
1 = Thermodynamic raw
(needs function
AGA_9_T_RAW())
OD Outside pipe diameter US: in
SI: mm
Only used when CPSM selec-
tion is “calculate”
ID Inside pipe diameter US: in
SI: mm
MCPSM Manual CPSM value Used when CPSM selection
is “manual”
MTPSM Manual TPSM value Used when TPSM selection is
“manual”
MPrCorr Manual Profile correction value Used when PrCorr selection
is “manual”

16.2.20 AGA_9_CPSM()
Function:
This function stores AGA9 CPSM specific parameters in the input
parameters area.
Syntax:
<Stat> := AGA_9_CPSM (<PRatio>, <ModEl>, <RefPress>);
Where:
Stat Status 0 = OK
<0 = Error
PRatio Poisson ratio factor
ModEl Young modulus of elasticity US: psia
SI: kPa
RefPress Reference pressure US: psia
SI: kPa
16.2.21 AGA_9_CTSM()
Function:
This function stores AGA9 CTSM specific parameters in the input
parameters area.
Syntax:
<Stat> := AGA_9_CTSM (<TermExp>, <RefPress>);
Where:
Stat Status 0 = OK
<0 = Error
ThermExp Coefficient of thermal expansion US: /degF
SI: /degC
RefPress Reference pressure US: degF
SI: degC

16.2.22 AGA_9_PCORR()
Function:
This function stores AGA9 profile correction specific parameters in the
Syntax:
<Stat> := AGA_9_PCORR (<WallR>, <PathF>, <Mu>);
Where:
Stat Status 0 = OK
<0 = Error
WallR Wall roughness US: in
SI: mm
PathF Path factor
Mu Dynamic viscosity US: lb/(in.sec)
SI: kg/(mm.sec)
16.2.23 AGA_9_T_RAW()
Function:
This function stores AGA9 thermodynamic raw specific parameters in
Syntax:
<Stat> := AGA_9_T_RAW (<AvgVel>, <LowFlow>);
Where:
Stat Status 0 = OK
<0 = Error
AgvVel Average velocity US: ft/hr
SI: m/hr
LowFlow Low flow velocity tresshold US: ft/hr
SI: m/hr

16.2.24 AGA_R_Z_BASE()
Function:
This function retreives the AGA8 compressibility at base conditions
from the output parameters area.
Syntax:
<Val> := AGA_R_Z_BASE();
Where:
Val Compressibitity at base conditions
16.2.25 AGA_R_Z_FLOW()
Function:
This function retreives the AGA8 compressibility at flowing conditions
Syntax:
<Val> := AGA_R_Z_FLOW();
Where:
Val Compressibitity at flowing conditions
16.2.26 AGA_R_MRHO_BASE()
Function:
This function retreives the AGA8 molar density at base conditions from
the output parameters area.
Syntax:
<Val> := AGA_R_MRHO_BASE();

Where:
Val Molar density at base conditions US: lb-mol/ft3

SI: kg-mol/m3
16.2.27 AGA_R_MRHO_FLOW()
Function:
This function retreives the AGA8 molar density at flowing conditions
Syntax:
<Val> := AGA_R_MRHO_FLOW();
Where:
Val Molar density at flowing conditions US: lb-mol/ft3

SI: kg-mol/m3
16.2.28 AGA_R_RHO_BASE()
Function:
This function retreives the AGA8 mass density at base conditions from
the output parameters area.
Syntax:
<Val> := AGA_R_RHO_BASE();
Where:
Val Mass density at base conditions US: lb/ft3

SI: kg/m3

16.2.29 AGA_R_RHO_FLOW()
Function:
This function retreives the AGA8 mass density at flowing conditions
Syntax:
<Val> := AGA_R_RHO_FLOW();
Where:
Val Mass density at flowing conditions US: lb/ft3

SI: kg/m3
16.2.30 AGA_R_FLOWRATE()
Function:
This function retreives the AGA3, AGA7, V-Cone, Wafer-Cone, AGA9
or AGA11 flowrate at base conditions from the output parameters area.
Syntax:
<Val> := AGA_R_FLOWRATE();
Where:
Val Flowrate at base conditions US: f3/Hour

SI: m3/Hour
(Assuming that time unit
for AGA7, AGA9 and
AGA11 is given in
hours)

16.2.31 AGA_R_ATM_PRESS()
Function:
This function retreives the atmospheric pressure from the output
parameters area.
Syntax:
<Val> := AGA_R_ATM_PRESS();
Where:
Val Atmospheric pressure US: psia

SI: kPa
16.2.32 AGA_R_SG()
Function:
This function retreives the AGA8 specific gravity (= relative density) at
standard conditions from the output parameters area.
Syntax:
<Val> := AGA_R_SG();
Where:
Val Specific gravity (= relative density) When CalSG of function

at standard conditions AGA_INIT() is “manual” the
input value stored by function
AGA_SG() is returned.
16.2.33 AGA_R_SG_REAL()
Function:
This function retreives the AGA8 real specific gravity (= relative
density) from the output parameters area.

Syntax:
<Val> := AGA_R_SG_REAL();
Where:
Val real specific gravity (= relative density)
16.2.34 AGA_R_Y1()
Function:
This function retreives the AGA3 upstream expansion factor from the
output parameters area.
Syntax:
<Val> := AGA_R_Y1();
Where:
Val AGA3 upstream expansion factor
16.2.35 AGA_R_CD()
Function:
This function retreives the AGA3 coefficient of discharge from the
Syntax:
<Val> := AGA_R_CD();
Where:
Val AGA3 coefficient of discharge

16.2.36 AGA_R_EV()
Function:
This function retreives the AGA3 velocity of approach factor from the
Syntax:
<Val> := AGA_R_EV();
Where:
Val AGA3 velocity of approach factor
16.2.37 AGA_R_FPV()
Function:
This function retreives the AGA8 legacy factor Fvp from the output
parameters area.
Syntax:
<Val> := AGA_R_FPV();
Where:
Val AGA8 legacy factor Fvp
16.2.38 AGA_R_RAW_FLOW()
Function:
This function retreives the AGA3, AGA7, V-Cone, Wafer-Cone, AGA9
or AGA11 raw flowrate from the output parameters area.
Syntax:
<Val> := AGA_R_RAW_FLOW();

Where:
Val Uncorrected flowrate US: ft3/hour

SI: m3/hour
16.2.39 AGA_R_SOS()
Function:
This function retreives the AGA10 speed of sound from the output
parameters area.
Syntax:
<Val> := AGA_R_SOS();
Where:
Val AGA10 speed of sound US: ft/sec

SI: m/sec
16.2.40 AGA_R_IDEAL_HV()
Function:
This function retreives the GPA2172 ideal heating value from the output
parameters area.
Syntax:
<Val> := AGA_R_IDEAL_HV();
Where:
Val GPA2172 ideal heating value US: BTU/ft3

SI: MJ/m3

Example calculation AGA calculations
16.2.41 AGA_R_REAL_HV()
Function:
This function retreives the AG5 or GPA2172 real heating value from the
Syntax:
<Val> := AGA_R_REAL_HV();
Where:
Val AGA5 or GPA2172 real heating US: BTU/ft3

value SI: MJ/m3
16.3 Example calculation

CLASS CALC_AGA3;
BODY
var ret integer;
var val;
METHOD init;
{This method runs only once at FAST/TOOLS startup}
ENTRYCONDITION triggered by ONCE;
BODY
{----------------------------------------}
{ Initialise some AGA parameters once. }
{----------------------------------------}
{ initiate AGA calculation block }
ret := AGA_INIT (1,1,2,1,1,2,0.0,101.325);
if (ret < 0) then
AGA_ERROR(ret,1);
else
ret := AGA_3_METER(1,1,1,52.5,23.75,0.0);
endif;
ENDMETHOD init;
METHOD do_calc;
{ This method runs every trigger or x seconds }
BODY
{----------------------------------------}

AGA calculations Example calculation
{ Initialise other AGA parameters. }

{----------------------------------------}
AGA_COMP(0,0.9); { Store gas component 0 }
AGA_COMP(1,0.1); { Store gas component 1 }
AGA_ATM_PRESS(101.325);
AGA_K(1.3);
AGA_MU(0.010268);
AGA_SP(140.00854+101.325);
AGA_DP(27.587891);
AGA_FT(25.90332);
{----------------------------------------}
{ Perform AGA Calculation. }
{----------------------------------------}
ret := AGA_CALC();
if (ret < 0) then aga_error(ret,1); endif;
{----------------------------------------}
{ Print the AGA calculation results. }
{----------------------------------------}
val := AGA_R_Z_BASE();
print "Z Base = ", val;
val := AGA_R_Z_FLOW();
print "Z Flow = ", val;
val := AGA_R_MRHO_BASE();
print "MRHO Base = ", val;
val := AGA_R_MRHO_FLOW();
print "MRHO Flow = ", val;
val := AGA_R_RHO_BASE();
print "RHO Base = ", val;
val := AGA_R_RHO_FLOW();
print "RHO Flow = ", val;
val := AGA_R_FLOWRATE();
print "Flowrate = ", val, " m3/hour";
val := AGA_R_ATM_PRESS();
print "Atm press = ", val;
ENDMETHOD do_calc;
ENDCLASS CALC_AGA3;

Introduction Examples
Appendix A: Examples
A.1 Introduction
This appendix contains examples which demonstrate the use of the
various PROCESS/FAST language constructs. The first example
demonstrates the use of constructs that are available within the basic
language set. The second example demonstrates constructs that are
available in the full language set.
These examples are intended as use for language reference only and in
no way attempt to provide complete system solutions!
A.2 Class TWIN_UNIT_CONTR
CLASS TWIN_UNIT_CONTR;
{
This class controls the twin_unit via the following
methods:
safety_conditions check conditions in each step
shut_down execute an emergency shutdown
raise_temperature raise furnace temperature
}
PROLOG
SIGNAL furnace_temp := "twin_unit.furnace_temp";

{ actual furnace temperature }
SIGNAL left_pressure := "twin_unit.left_pressuretemp";
{ pressure of left vessel }
SIGNAL right_pressure := "twin_unit.right_pressure";
{ pressure of right vessel }
SIGNAL furnace_setp := "twin_unit.furnace_setp";
{ furnace temperature setpoint }
SIGNAL furnace_req := "twin_unit.furnace_req";
{ required end_value for setpoint }
SIGNAL left_flow_H2 := "twin_unit.left_flow_H2";
{ hydrogen flowrate left vessel }
SIGNAL left_flow_oil := "twin_unit.left_flow_oil";
{ oil flowrate left vessel }
SIGNAL right_flow_H2 := "twin_unit.right_flow_H2";
{ hydrogen flowrate right vessel }
SIGNAL right_flow_oil := "twin_unit.right_flow_oil";
{ oil flowrate right vessel }
PROCESS/FAST Language Manual A-1

Examples Class TWIN_UNIT_CONTR
BODY
CONSTANT
seq_init := 0, { initialization }
init_phase := 1, { twin_unit initialization step }
raise_temp := 2, { temperature rasing step }
test_phase := 3; { test phase step }
VAR
emergency_switch; { to activate the shutdown seq }
{ ----------------- }
{ Safety-conditions }
{ ----------------- }
METHOD safety_conditions;
CONSTANT
max_raise := 1800; { seconds allowed for raise_temp }
TIMER
guard_raise; { for raise_temp phase guarding }
{ guard important limit violations }
IF furnace_temp'status = HIGH_HIGH OR
left_pressure'status = HIGH_HIGH OR
right_pressure'status = HIGH_HIGH
THEN
emergency_switch := ON;
ENDIF;
{ guard important elapse times }
IF STEP =: raise_temp
THEN
guard_raise := max_raise; { start timer }
ENDIF;
IF STEP <>: raise_temp
THEN
guard_raise'status := STOPPED; { stop timer }
ENDIF;
IF guard_raise'status =: EXPIRED
THEN
PRINT "Duration alarm on temperature raising phase";
emergency_switch := ON;
ENDIF;
ENDMETHOD safety_conditions;
{ -------- }
{ Shutdown }
{ -------- }
METHOD shutdown;
ENTRYCONDITION emergency_switch;
TIMER
oil_timer, { used to control oil cutoff }
finish_timer; { used to control steady state wait }
PROLOG
oil_timer := 600; { start this timer }
furnace_setp := 25.0; { get the temperature down }
left_flow_H2 := 0; { shut off hydrogen flow }
right_flow_H2 := 0; { ... both vessels ... }
BODY
A-2 PROCESS/FAST Language Manual

Classes SENSOR and FLUID_VESSEL Examples
IF oil_timer'status =: EXPIRED
THEN
left_flow_oil := 0; { shut off oil flow }
right_flow_oil := 0; { ... both vessels ... }
finish_timer := 200; { start timer }
ENDIF;
IF finish_timer'status =: EXPIRED
THEN
emergency_switch := OFF;
STEP := seq_init;
ENDIF;
ENDMETHOD shutdown;
{ ------------------- }
{ raise_temp }
{ ------------------- }
METHOD temperature_raising;
ENTRYCONDITION STEP = raise_temp;
CONSTANT
rate := 0.5, { rate as degrees per second }
band := 10.0; { allowable temperature band }
VAR
start_time, { for start of this step storage }
start_temp; { for temperature at 'start_time'
storage }
PROLOG
start_time := NOW; { remember this time }
start_temp := furnace_temp; { and this temperature }
BODY
furnace_setp := start_temp + rate *(NOW - start_time);
furnace_temp'high_limit := furnace_setp + band/2;
furnace_temp'low_limit := furnace_setp - band/2;
IF furnace_temp >=: furnace_req
THEN
STEP := test_phase; { switch to next phase }
ENDIF;
ENDMETHOD temperature_raising;
ENDCLASS TWIN_UNIT_CONTR;
A.3 Classes SENSOR and FLUID_VESSEL
{---------------------------}
{Class definition for sensor}
{---------------------------}
CLASS SENSOR; { Declare class "sensor" }
PROLOG
ATTRIBUTE delta_alarm FLOAT; { declare attributes for

Examples Classes SENSOR and FLUID_VESSEL
this class}
ATTRIBUTE limit_alarm FLOAT;
ATTRIBUTE sens INTEGER ;

ATTRIBUTE name STRING;
ATTRIBUTE period INTEGER ;
PROMPT name QUERY "Sensor name/function"; {request init values}

PROMPT sens QUERY "Percentage sensitivity";
PROMPT period QUERY "Resolution in seconds";
SIGNAL reading := "inst_1.unit_1." || name TRIGGER STATUS;

{make connection to related item}
BODY {body of class starts here}
{global declarations}
CONSTANT sensor_init := 0; {states for STEP}
CONSTANT sensor_check := 1;
CONSTANT sensor_alert := 2;
VAR delta FLOAT, prev_value FLOAT, new_value FLOAT, range FLOAT;

{sensor value information}
VAR sensor_state STRING; {string representing state}
TIMER period_timer TRIGGER; {trigger method when this}

{timer expires}
{---------------------------}
{method to initialise sensor}
{---------------------------}
METHOD initialize;
ENTRYCONDITION STEP = sensor_init;
BODY
delta := 0.0;
prev_value := 0.0;
new_value := 0.0;
delta := 0.0;
STEP := sensor_check; {jump to next state}

ENDMETHOD initialize;
{------------------------}
{method to monitor sensor}
{------------------------}
METHOD check_sensor;
ENTRYCONDITION STEP = sensor_check;
PROLOG
period_timer := period; {Start sensitivity timer}
range := reading'high_high_limit - reading'low_low_limit;
delta := 0.0;
prev_value := reading;
BODY
{timer expired}
IF TRIGGERED BY TIMER AND TRGTIM(period_timer) THEN

new_value := reading;
delta := (new_value - prev_value)/range * 100;
IF ABS(delta) > sens THEN {fluctuation was too fast}
IF delta = ABS(delta) THEN
sensor_state := "risen";
ELSE
sensor_state := "fallen";
ENDIF;
delta_alarm := ON; {indicate alarm}
STEP := sensor_alert; {jump to alert state}
ELSE
sensor_state := "okay";
ENDIF;
period_timer := period; {restart timer}
prev_value := reading;
ENDIF;
{triggered by status change}
IF TRIGGERED BY SIGNAL AND TRGSIG(reading) THEN
IF reading'status = HIGH THEN
sensor_state := "high";
ELSE
IF reading'status = HIGH_HIGH THEN
sensor_state := "high high";
ELSE
IF reading'status = LOW THEN
sensor_state := "low";
ELSE
IF reading'status = LOW_LOW THEN
sensor_state := "low low";
ENDIF;
ENDIF;
ENDIF;
ENDIF;
limit_alarm := ON; {indicate alarm state}
STEP := sensor_alert; {jump to alert state}
ENDIF;
ENDMETHOD check_sensor;
{----------------------}
{method to signal alert}
{----------------------}
METHOD signal_alert;
ENTRYCONDITION STEP = sensor_alert;
BODY
IF ABS(delta) > sens THEN {indicate change}
PRINT name || " has " || sensor_state || " by " , delta , "%";
PRINT " from ", prev_value, " to ", new_value;
ENDIF;
PRINT name, " current status is ",sensor_state;
{indicate current status}
STEP := sensor_check; {keep monitoring sensor}
ENDMETHOD signal_alert;
ENDCLASS SENSOR;

{---------------------------------}
{Class definition for fluid vessel}
{---------------------------------}
CLASS FLUID_VESSEL; {declare fluid vessel class}
PROLOG
CONTAINS flow_sensor := sensor; {include class sensor}
ATTRIBUTE fluid_rate FLOAT; {define attributes}

ATTRIBUTE vessel_name STRING;
ATTRIBUTE vessel_status FLOAT ;
NOPROMPT flow_sensor.name; {fill these in ourseleves later}

NOPROMPT flow_sensor.sens;
NOPROMPT flow_sensor.period;
PROMPT vessel_name QUERY "Enter vessel name/function";

PROMPT fluid_rate QUERY "Enter flow rate (litres/minute)";
SIGNAL fluid_flow := "inst_1.unit_1." || vessel_name;

vessel_status := OFF;
{fill in sensor attributes}
flow_sensor.name := vessel_name || "_sensor";
flow_sensor.period := 60;
flow_sensor.sens := 25;
BODY
TIMER timeout TRIGGER; {global declarations}
{define flow constants}
CONSTANT time_format := "DD/MM/YY hh:mm:ss";
CONSTANT high_rate := 1.5;
CONSTANT high_high_rate := 2.0;
CONSTANT low_rate := 2/3;
CONSTANT low_low_rate := 0.5;
VAR shut FLOAT;
METHOD fluid_handler; {handle fluid control}

ENTRYCONDITION vessel_status = ON;
BODY
{flow rate is normal}
IF flow_sensor.reading'status =: NORMAL THEN
timeout := STOPPED;
fluid_flow := fluid_rate;
ENDIF;
{flow rate high so reduce it}

IF flow_sensor.reading'status =: HIGH THEN
fluid_flow := fluid_rate * low_rate;
timeout := 30;
ENDIF;
{flow rate high high so reduce it}

IF flow_sensor.reading'status =: HIGH_HIGH THEN
fluid_flow := fluid_rate * low_low_rate;

timeout := 30;
ENDIF;
{flow rate low so raise it}

IF flow_sensor.reading'status =: LOW THEN
fluid_flow := fluid_rate * high_rate;
timeout := 30;
ENDIF;
{flow rate low low so raise it}

IF flow_sensor.reading'status =: LOW_LOW THEN
fluid_flow := fluid_rate * high_high_rate;
timeout := 30;
ENDIF;
{flow adjustment failed - shutdown}

IF TRIGGERED BY TIMER AND TRGTIM(timeout) THEN
fluid_flow := 0;
vessel_status := OFF;
shut := NOW;
PRINT "Vessel ",vessel_name," shutdown at " ,
STRING(shut,time_format);
ENDIF;
ENDMETHOD fluid_handler;
ENDCLASS FLUID_VESSEL;


Reserved Words
Appendix B: Reserved Words

The following list contains words and symbols that are recognized by
the PROCESS/FAST language and have some special significance.
These words should not be used as identifiers or for anything other than
their intended purpose.
'
+
:+
-
:=
<
<:
<=
<=:
<>
<>:
=
=:
>
>:
>=
>=:
ABS
ACKNOWLEDGE
ACKNOWLEDGED
ADDMONTH
ALARM
ALARM_STATE
ALARM_TYPE
APPLICATION_FLAGS
APPLICATION_INFO
APPLICATION_SIZE
ARCCOS
ARCSIN
ARCTAN
ARG
ATTACHED
ATTRIBUTE
BODY
BY
CLASS
CONSTANT
CONTAINS
CONTROL_STATUS
COS
COSHYP
PROCESS/FAST Language Manual B-1

Reserved Words
DAYS
DEADBAND
DIED
ELSE
ENDCLASS
ENDFUNCTION
ENDIF
ENDMETHOD
ENDSEQUENCE
ENDSUBSEQUENCE
ENTRYCONDITION
EPILOG
ERROR
EXP
EXPIRED
FALSE
FIRST
FLOAT
FOR
FROM
FUNCTION
FUNCTIONS
GMT
HIGH
HIGH_HIGH
HIGH_HIGH_LIMIT
HIGH_LIMIT
ID_GROUP
ID_NODE
ID_NUMBER
IF
INSTALLATION
INTEGER
ITEM
LCT
LEFT
LIMIT
LOG
LOG10
LOW
LOW_LIMIT
LOW_LOW
LOW_LOW_LIMIT
MAKE
MERGED_STATUS
METHOD
MIDDLE
NODE
NO
B-2 PROCESS/FAST Language Manual

Reserved Words
NOPROMPT
NOT
NOW
OBJECT
OFF
OFFLINE
OLD_VALUE
ON
OPT_ACKNOWLEDGED
OPT_BLOCKED
OPT_OFFLINE
OPT_UPDATED_BLOCKED
OPT_UPDATED_OFFLINE
OPTION
OPTION_STATUS
OVERRANGED
PIT
POWER
PRINT
PROLOG
PROMPT
QUALITY
QUERY
RANDOM
RESPONDED
RETURN
RIGHT
RUNNING
SECTION
SEQUENCE
SIGNAL
SIN
SINHYP
SQRT
STATUS
STEP
STOPPED
STRING
SUB
SUBSEQUENCE
TAG
TAN
TANHYP
THEN
TIME
TIMER
TRGALM
TRGSIG
TRGSIG_ACKNOWLEDGED
PROCESS/FAST Language Manual B-3

Reserved Words
TRGSIG_ALARM_TYPE
TRGSIG_CONTROL_STATUS
TRGSIG_DEADBAND
TRGSIG_HIGH_LIMIT
TRGSIG_HIGH_HIGH_LIMIT
TRGSIG_LOW_LIMIT
TRGSIG_LOW_LOW_LIMIT
TRGSIG_MERGED_STATUS
TRGSIG_OLD_VALUE
TRGSIG_OPTION_STATUS
TRGSIG_QUALITY
TRGSIG_STATUS
TRGSIG_STR_VALUE
TRGSIG_STR_OLD_VALUE
TRGSIG_UPDATE_TIME
TRGSIG_VALUE
TRGTIM
TRIGGER
TRIGGERED
TRUE
TRUNC
UNDERRANGED
UNINITIALIZED
UNIT
UPDATE
UPDATED_BLOCKED
UPDATED_OFFLINE
VALUE
VAR
VOID
YES
XOR
B-4 PROCESS/FAST Language Manual

Index
Symbols ALARM_DETECTION 9-9, 14-22

ARCCOS 14-40
, 14-22, 14-39, 14-46 ARCSIN 14-40
|| 14-22, 14-39, 14-46
ARCTAN 14-40
arithmetic operators 7-1, 14-37
A array items 4-3, 14-16
ABS 14-40 assignment 5-1, 14-32
addition assignment 5-1, 14-33 attribute declaration 11-2
ADDMONTH 14-41 attributes 11-1, 12-2, 14-11
AGA_3_METER 16-11 using attributes with signals 11-3
AGA_8_GROSS 16-14
AGA_9_CPSM 16-16 B
AGA_9_CTSM 16-16 bitwise operators 7-3, 14-37
AGA_9_INIT 16-15 blocked 3-2
AGA_9_PCORR 16-17 body 3-3
AGA_9_T_RAW 16-17 boolean operators 14-37
AGA_ATM_PRESS 16-9 built-in functions 8-3, 13-3, 13-4, 14-40
AGA_CALC 16-4
AGA_COMP 16-4
AGA_CONE 16-12
C
AGA_DEADBAND 16-10 CLASS 9-6, 14-53
AGA_DP 16-6 class 1-1, 3-1, 9-1, 14-1
AGA_ERROR 16-3 class inclusion 12-1
AGA_FT 16-6 class prolog 9-2, 9-8, 14-7, 14-12, 14-
AGA_GPA2172 16-11 14, 14-18, 14-20, 14-34
AGA_INIT 16-2 class-wide attribute 11-1, 14-12
AGA_K 16-7 comment 14-47
AGA_MU 16-7 constants 4-1, 14-13, 14-53
AGA_POSITION 16-9 contains 12-2, 14-14
AGA_PULSE 16-13 control item 3-2
AGA_R_ATM_PRESS 16-21 COS 14-40
AGA_R_CD 16-22 COSHYP 14-40
AGA_R_EV 16-23 CREATE_ITEM 9-9, 14-22
AGA_R_FLOWRATE 16-20 current time 14-48
AGA_R_FPV 16-23
AGA_R_IDEAL_HV 16-24 D
AGA_R_MRHO_BASE 16-18 DAYS 14-41
AGA_R_MRHO_FLOW 16-19 declaration 4-1, 10-2, 11-2, 14-10
AGA_R_RAW_FLOW 16-23 delegate object 9-8
AGA_R_REAL_HV 16-25 DELEGATE_ONLY 9-9, 14-22
AGA_R_RHO_BASE 16-19
AGA_R_RHO_FLOW 16-20 E
AGA_R_SG 16-21 enterprise 9-8
AGA_R_SG_REAL 16-22 Enterprise classes 9-8
AGA_R_SOS 16-24 Enterprise Engineering Module 9-8
AGA_R_Y1 16-22 Enterprise Engineering Server 9-8
AGA_R_Z_BASE 16-18 enterprise object 14-22
AGA_R_Z_FLOW 16-18 Enterprise objects 9-8
AGA_SG 16-8 entry-condition 3-2, 6-1, 7-3, 14-30, 14-
AGA_SP 16-5
PROCESS/FAST Language Manual 1

Index
52 noprompt 14-18
epilog 3-3, 14-3 NOW 9-6, 14-48
error statement 5-2, 9-8, 11-2, 14-34
EXP 14-40 O
objects 1-1, 9-1
F off-line 3-2
FLOAT 14-41 ONCE 13-4
for 8-2, 14-15, 14-16 on-line 3-2
function arguments 14-4 operator
function class 10-1, 14-4 , 14-22, 14-39, 14-46
function declaration 10-1 || 14-22, 14-39, 14-46
functions 14-4 operators 7-1, 14-37
G P
GMT 14-41, 14-48 POWER 14-40
guards 6-1, 14-30 precedence 14-46
print statement 5-2, 14-35
I prolog 3-3, 14-7
identifier 4-1, 7-1 prompts 11-2, 14-18
identifier limits 8-3 PUT_IN_HISTORY 9-9, 14-22
if construct 6-1, 14-31
inclusion path 12-3 Q
INSTALLATION 9-6, 14-53 quote operator 14-51
INTEGER 14-41
items 4-2, 8-2, 9-3, 14-16, 14-51 R
RANDOM 14-41
L relational operators 7-2, 14-38
LCT 14-41 return statement 14-4
LEFT 14-41 RIGHT 14-41
LENGTH 14-41
local attribute 11-1, 14-12, 14-18 S
Local Engineering Module 9-8 SECTION 9-6, 14-53
LOG 14-40 SECTION_DF 15-1
LOG10 14-40 sequence 14-9
SIG_FORCE_ALARM_STATE 14-45
M SIG_GET_FLOAT 14-45
master object 9-8 SIG_GET_INTEGER 14-45
MASTER_AND _DELEGATE 9-9, 14- SIG_GET_STRING 14-45
22 SIG_GETSUB 14-43
MASTER_ONLY 14-22 SIG_LOCK 14-45
method 3-1, 9-1, 14-6 SIG_OFFLINE 14-44
method prolog 14-7 SIG_SET_FLOAT 14-45
MIDDLE 14-41 SIG_SET_INTEGER 14-45
monadic operators 7-1, 14-38 SIG_SET_STRING 14-46
SIG_UPDATE 9-5, 14-21, 14-44
N SIG_UPDATE_TIME 14-44
nested included classes 12-1, 12-3 signal attributes 9-4, 14-20
NODE 9-6, 14-53 signals 9-3, 12-2, 14-19, 14-28, 14-51
2 PROCESS/FAST Language Manual

Index
SIN 14-40 UNIT 9-6, 14-53

SINHYP 14-40 user defined functions 10-1
SQRT 14-40 USER/FAST 9-8
statements 5-1, 9-7, 14-31
step 8-1, 14-30, 14-52 V
STRING 14-41 variables 4-1, 14-30
string operators 7-3, 14-39
sub-sequence 14-10
T
TAG 9-6, 14-53
TAN 14-40
TANHYP 14-41
timers 4-2, 14-28, 14-51
transitional operators 7-2, 14-39
TRGALM 13-4, 14-43
TRGSIG 13-4, 14-41
TRGSIG_ACKNOWLEDGED 14-42
TRGSIG_ALARM_TYPE 14-42
TRGSIG_CONTROL_STATUS 14-42
TRGSIG_DEADBAND 14-43
TRGSIG_HIGH_HIGH_LIMIT 14-42
TRGSIG_HIGH_LIMIT 14-43
TRGSIG_LOCKED 14-43
TRGSIG_LOW_LIMIT 14-43
TRGSIG_LOW_LOW_LIMIT 14-43
TRGSIG_MERGED_STATUS 14-42
TRGSIG_OLD_VALUE 14-42
TRGSIG_OPTION_STATUS 14-42
TRGSIG_QUALITY 14-43
TRGSIG_STATUS 14-42
TRGSIG_STR_OLD_VALUE 14-42
TRGSIG_STR_VALUE 14-42
TRGSIG_UPDATE_TIME 14-43
TRGSIG_VALUE 14-41
TRGTIM 13-4, 14-43
trigger group 13-1
trigger items 13-3
trigger signals 13-2, 14-21
trigger statement 13-1, 14-36
trigger timers 13-3
triggered by construct 13-3, 14-36
triggering classes 13-2
triggers 9-4, 9-7, 12-2, 13-1, 14-11, 14-
16, 14-29, 14-36, 14-51, 15-1
TRUNC 14-40
U
unblocked 3-2
PROCESS/FAST Language Manual 3

Index

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction REPORT/FAST FAST/TOOLS
Manual Language Manual
IM50Q06Q00-01EN/R10.03

IM50Q06Q00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction ..........................................................................1-1
1.1 Introduction ...............................................................1-1
1.2 Reports .......................................................................1-1
1.3 The REPORT/FAST Query Language ......................1-1
1.4 General report description layout ..............................1-2
1.5 The RQL statements ..................................................1-2
1.6 The REPORT/FAST modes ......................................1-3
1.7 The set-up description ...............................................1-5
1.8 Error handling ............................................................1-5
1.9 ISAM and DSS datasets ............................................1-5
2 Data sets .................................................................................2-1
2.1 Introduction ...............................................................2-1
2.2 What are data sets? ....................................................2-1
2.3 Data dictionaries ........................................................2-4
2.4 How to define data sets ..............................................2-5
2.5 Old-style data sets ......................................................2-5
3 Retrieving data .....................................................................3-1
3.1 Introduction ...............................................................3-1
3.2 Basic elements of a query ..........................................3-1
3.3 Narrowing the query, the WHERE clause .................3-4
3.3.1 Conditions .....................................................3-4
3.3.2 String comparison with wildcards ................3-6
3.3.3 Connecting several conditions ......................3-6
3.4 Ordering the results ...................................................3-7
3.5 Connecting data sets, joins ........................................3-9
3.6 Displaying other data ...............................................3-11
4 Formatting the report ..........................................................4-1
4.1 Introduction ...............................................................4-1
4.2 Column formatting, the COLUMN statement ...........4-1
4.3 Page formatting ..........................................................4-4
REPORT/FAST Language Manual iii

Table of Contents
4.4 Flagging the report .................................................... 4-8

4.5 Breaking up the report .............................................. 4-8
5 Advanced queries ................................................................. 5-1
5.1 Introduction ............................................................... 5-1
5.2 Conditional execution ............................................... 5-1
5.3 Loops ......................................................................... 5-2
5.4 Row-by-row operation .............................................. 5-3
5.4.1 Introduction .................................................. 5-3
5.4.2 Declare a cursor - the DECLARE statement 5-3
5.4.3 Open a cursor - the OPEN statement ........... 5-4
5.4.4 Fetch rows - the FETCH statement .............. 5-4
5.4.5 Close a cursor - the CLOSE statement ......... 5-4
5.4.6 Indication - the @RQLERROR variable ..... 5-5
5.4.7 Row counter - the @RQLCOUNT variable . 5-5
5.5 Example .................................................................... 5-5
6 Manipulate data ................................................................... 6-1
6.1 Introduction ............................................................... 6-1
6.2 Arithmetic operations ................................................ 6-1
6.3 Functions ................................................................... 6-3
6.3.1 Group functions ............................................ 6-4
6.3.2 Non-group functions .................................... 6-5
6.4 Variables ................................................................... 6-7
7 Communications .................................................................. 7-1
7.1 Introduction ............................................................... 7-1
7.2 Sending data, the SEND statement ........................... 7-1
7.3 Receiving data, the RECEIVE statement .................. 7-3
8 Miscellaneous ....................................................................... 8-1
8.1 Introduction ............................................................... 8-1
8.2 Selecting a dictionary, the DICTIONARY
statement ................................................................... 8-1
8.3 Including reports, the INCLUDE statement ............. 8-1
8.4 Logging in, the LOGIN statement ............................ 8-2
8.5 Ending a report description ....................................... 8-3
8.6 Showing status, the SHOW statement ...................... 8-3
9 Reference .............................................................................. 9-1
9.1 Introduction ............................................................... 9-1
9.2 Naming conventions ................................................. 9-1
9.3 Reserved words ......................................................... 9-2
9.4 Data types .................................................................. 9-3
9.4.1 Strings .......................................................... 9-3
iv REPORT/FAST Language Manual

Table of Contents
9.4.2 Integer ...........................................................9-3

9.4.3 Real ...............................................................9-3
9.5 Type conversion ........................................................9-4
9.6 Variables ....................................................................9-4
9.6.1 @BOTTOM_MARGIN ...............................9-4
9.6.2 @CONCEAL ................................................9-5
9.6.3 @CUSTOMER .............................................9-5
9.6.4 @DATE ........................................................9-5
9.6.5 @DECIMAL ................................................9-5
9.6.6 @EXPORT ...................................................9-5
9.6.7 @FORMFEED .............................................9-6
9.6.8 @GEN_TIME ...............................................9-6
9.6.9 @LEFT_MARGIN .......................................9-6
9.6.10 @LINE .........................................................9-6
9.6.11 @NEXT ........................................................9-6
9.6.12 @PAGE ........................................................9-7
9.6.13 @PAGE_SIZE ..............................................9-7
9.6.14 @RIGHT_MARGIN ....................................9-7
9.6.15 @RQLCOUNT .............................................9-7
9.6.16 @RQLERROR .............................................9-7
9.6.17 @SORTSPACE ............................................9-7
9.6.18 @TIME .........................................................9-8
9.6.19 @TOP_MARGIN .........................................9-8
9.6.20 @VERSION .................................................9-8
9.6.21 @WIDTH .....................................................9-8
9.6.22 @WORKSPACE ..........................................9-8
9.6.23 @WC_ANY .................................................9-9
9.6.24 @WC_SINGLE ............................................9-9
9.6.25 Report-dependent variables ..........................9-9
9.7 Formatting rules .........................................................9-9
9.7.1 Formatting of integer data types .................9-10
9.7.2 Formatting of real data types ......................9-11
9.7.3 Formatting of string data types ...................9-12
9.8 Expressions and operators .......................................9-13
9.9 Field specifications ..................................................9-15
9.10 Errors .......................................................................9-16
9.11 Functions .................................................................9-22
9.11.1 ABS ............................................................9-23
9.11.2 ADD_MONTHS .........................................9-24
9.11.3 ASCII_FILE ...............................................9-25
9.11.4 AVG ............................................................9-26
9.11.5 BAND .........................................................9-27
9.11.6 BNOT .........................................................9-28
REPORT/FAST Language Manual v

Table of Contents
9.11.7 BOR ........................................................... 9-29

9.11.8 BSHIFT ...................................................... 9-30
9.11.9 BXOR ......................................................... 9-31
9.11.10 CHAR ......................................................... 9-32
9.11.11 CHR ........................................................... 9-33
9.11.12 COUNT ...................................................... 9-34
9.11.13 DECODE ................................................... 9-35
9.11.14 DRAW ....................................................... 9-36
9.11.15 GPV_QUALITY ........................................ 9-37
9.11.16 GPV_STATUS ........................................... 9-38
9.11.17 GPV_VALUE ............................................ 9-39
9.11.18 LENGTH .................................................... 9-40
9.11.19 LINE ........................................................... 9-41
9.11.20 LOGBOOK_TEXT .................................... 9-42
9.11.21 LOWER ..................................................... 9-43
9.11.22 MAX .......................................................... 9-44
9.11.23 MIN ............................................................ 9-45
9.11.24 MONTH_DAYS ........................................ 9-46
9.11.25 NUMBER ................................................... 9-47
9.11.26 SPV_QUALITY ......................................... 9-48
9.11.27 SPV_STATUS ........................................... 9-49
9.11.28 SPV_VALUE ............................................. 9-50
9.11.29 STDDEV .................................................... 9-51
9.11.30 SUBSTR ..................................................... 9-52
9.11.31 SUM ........................................................... 9-53
9.11.32 TO_GMT ................................................... 9-54
9.11.33 TO_INTEGER ........................................... 9-55
9.11.34 TO_LCT ..................................................... 9-56
9.11.35 TO_REAL .................................................. 9-57
9.11.36 UPPER ....................................................... 9-58
9.11.37 VARIANCE ............................................... 9-59
9.12 Statements ............................................................... 9-59
9.12.1 BREAK ...................................................... 9-60
9.12.2 CLOSE ....................................................... 9-61
9.12.3 COLUMN .................................................. 9-62
9.12.4 COMMENT ............................................... 9-64
9.12.5 DECLARE ................................................. 9-65
9.12.6 DICTIONARY ........................................... 9-66
9.12.7 EXIT ........................................................... 9-67
9.12.8 FETCH ....................................................... 9-68
9.12.9 FLAG PAGE .............................................. 9-69
9.12.10 FOOTER .................................................... 9-70
9.12.11 HEADER ................................................... 9-72
vi REPORT/FAST Language Manual

Table of Contents
9.12.12 IF-THEN-ELSE-ENDIF .............................9-74

9.12.13 INCLUDE ...................................................9-75
9.12.14 LOGIN .......................................................9-76
9.12.15 LOOP - ENDLOOP ....................................9-77
9.12.16 OPEN ..........................................................9-78
9.12.17 QUIT ...........................................................9-79
9.12.18 RECEIVE ...................................................9-80
9.12.19 SELECT ......................................................9-82
9.12.20 SEND ..........................................................9-86
9.12.21 SET .............................................................9-87
9.12.22 SHOW ........................................................9-88
9.12.23 SPOOL ........................................................9-90
10 DSS data sets .......................................................................10-1
10.1 Introduction .............................................................10-1
10.2 What’s the difference between DSS data sets and ISAM
data sets? 10-1
10.3 Configuration for DSS queries ................................10-2
10.4 Using DSS queries ...................................................10-2
10.5 Concealed dataset fields ..........................................10-3
Appendix A: A-1
Appendix A:Examples ...................................................................A-1
A.1 Draw a graph from historical data ............................A-1
A.2 Report the current alarms .........................................A-3
A.3 Building your own queries .......................................A-3
REPORT/FAST Language Manual vii

Table of Contents
viii REPORT/FAST Language Manual

Objectives Preface
0 Preface
0.1 Objectives
This manual has the following objectives:
• To introduce system managers to the functionality covered by the
REPORT/FAST Query Language.
• To provide system managers with all the necessary information to
define reports.
• To provide system integrators with all the necessary information to
integrate REPORT/FAST with their application.
All information in this book which is supplied for the system
integrator only will be marked by the footnote ‘System integrator
only’.

This manual is intended for system managers and maintenance
engineers. It is recommended to have some knowledge of the
information covered by the USER/FAST, FAST/TOOLS User Manual
(new HMI style).
Experienced users of the REPORT/FAST Query Language will find
more information in the DATABASE/FAST Language Manual.

This manual contains 9 chapters and an appendix.
• Chapter 1 introduces the reader to the REPORT/FAST Query
Language.
• Chapter 2 describes the interaction with data sets.
• Chapter 3 describes how to retrieve data from the various data sets.
• Chapter 4 describes various ways to customize the layout of the
report.
• Chapter 5 describes how to make advanced queries.
• Chapter 6 describes how to manipulate the retrieved data.
REPORT/FAST Language Manual 0-1

• Chapter 7 describes the methods for communicating with

applications.
• Chapter 8 discusses miscellaneous REPORT/FAST Query
Language statements not mentioned in the previous chapters.
• Chapter 9 is a reference guide in which conventions and error
handling are described. Statement syntax is summarized in
alphabetical order.
• Appendix A supplies some examples of report descriptions.

• FAST/TOOLS User Manual Volume 2
This manual provides information necessary to access
REPORT/FAST on your system.
• DATABASE/FAST Language Manual*
This manual describes the language used to define the data sets
accessible by REPORT/FAST. It provides the experienced user of
the REPORT/FAST Query Language with additional information
for fully understanding the interaction between REPORT/FAST
and data sets.
• BUS/FAST Programmer’s Manual Volumes 1 and 3*
REPORT/FAST enables communication between REPORT/FAST
and applications using the BUS/FAST message passing facilities.
These manuals provide additional information about the message
passing facilities and system conversion.
• FAST/CONVENTIONS Reference Guide
This manual supplies information about the standard message
layouts used within the FAST/TOOLS.
• A C Language Reference Manual*
The appearance of data in a report can be controlled using format
descriptions. As well as the format description supplied by
REPORT/FAST, the standard C language output formats can be
used. A C Language Reference Manual supplies information about
these formats.
*System integrator only
0-2 REPORT/FAST Language Manual

Conventions and abbreviations Preface

The following conventions and abbreviations are used in this manual:
CONVENTION MEANING
() Used in routine syntax to indicate a list of
arguments that have to be passed.
<name> Indicates that <name> has to be replaced by
the actual function or statement argument.
[] Indicates that the enclosed item is optional.
[,...] Indicates that the previous item may be
repeated one or more times
{ }.. Indicates that the previous enclosed items may
be repeated one or more times
... Indicates that not all of the items are shown.
UPPERCASE Indicates reserved words and pre-defined
letters names, e.g. NULL, TRUE,
DUR_NOWAIT.
n.u. not used
output This typesetting is used to indicate output on a
terminal
input This typesetting is used to indicate input from
the user
ABBREVIATION MEANING
DDL The DATABASE/FAST Data Description
Language
RQL The REPORT/FAST Query Language


Introduction Introduction
1 Introduction
1.1 Introduction
REPORT/FAST is a powerful tool for generating reports from system
configuration and process data. This chapter introduces the reader to
REPORT/FAST. It covers:
• Reports
• The REPORT/FAST Query Language
• General report description layout
• The RQL statements
• Error handling
• The REPORT/FAST modes
• The set-up description
1.2 Reports
Report What is a report? A report is simply a presentation of various
Table FAST/TOOLS configuration and process data by means of a table.
Data set This data is collected together in so-called data sets. Each data set
represents a type of data. Examples of FAST/TOOLS data sets are:
• Installation, unit and item definitions
• Item history
• Current alarms and alarm history
The data to be presented in tables and the layout of the tables are defined
Query language using the REPORT/FAST Query Language.
1.3 The REPORT/FAST Query Language

This language manual describes how the REPORT/FAST Query
RQL Language (RQL) enables you to define reports. RQL is a powerful
language based upon the well known query language SQL. A simple
report can be defined using a few statements. In such a case,
REPORT/FAST generates a report using defaults. These defaults can be
overruled as required.

Introduction General report description layout
1.4 General report description layout

Report A report description is a collection of RQL statements. Generally, such
description a collection of RQL statements can be divided into the following steps:
• Statements modifying the layout of the report
• Statements defining calculations
• Statements to select and retrieve the desired data
• A statement to end the description
This order need not to be followed strictly.
1.5 The RQL statements

RQL A report description is a collection of RQL statements defining the data
statement to retrieve and defining the layout of the report. An RQL statement has
the layout:
KEYWORD [argument[s]] ;
A statement may have no arguments (for example QUIT) or it may have
a number of arguments (for example, the SELECT statement). Some
examples of statements are:
COLUMN item_value HEADING ’Value’;
SELECT name, item_value+0.05 item_value
FROM item_val
WHERE name = ‘INSTALLATION.MY_UNIT.TEMPERATURE’;
SELECT SET @max AVG(item_value) + 2,
SET @min AVG(item_value) - 2
FROM item_history
WHERE
name = ’INSTALLATION.MY_UNIT.TEMPERATURE’ AND
sample_time > @DATE - 3600*24 AND
sample_time < @DATE;
QUIT;
The RQL statements are divided into the following groups:
• Statements to select and retrieve the data for the report from various
data sets.
• Statements to modify the default layout of the report.
• Statements to manipulate the retrieved data.
• Various statements to communicate with applications (although
these do not directly affect the report).
• Miscellaneous statements not covered by the above-mentioned
groups.

The REPORT/FAST modes Introduction
In this manual, one chapter is devoted to each one of these groups.

Chapter 2 ‘Data Sets’ discusses the FAST/TOOLS data sets and Chapter
9 ‘Reference’ is a reference guide where specific information can be
found.
The following section discusses topics the reader should have
knowledge about before advancing to the next chapters.
1.6 The REPORT/FAST modes

Normally, reports are defined using the standard FAST/TOOLS user
interface. By selecting forms, the user is able to define a report. The
definition consists of a report name, a short description, a priority and
the destination for the report when generated. The actual report
description, i.e. the collection of RQL statements that make up a report,
can be entered via the ‘EDIT’ soft key. The ‘EDIT’ soft key activates an
interactive text editor allowing the user to enter the description quickly.
When entered, the report can be generated periodically by specifying
schedule parameters, on event by specifying event parameters, or it can
be generated ad hoc. The so-called background REPORT/FAST
generator takes care of generating the report when it is needed. If
specified, the report is output to a printer when generation is completed.
Ad hoc Another method for generating a report is the ad hoc query. Interactive
Interactive session is another name for an ad hoc query. Using the FAST/TOOLS
user interface, the ad hoc query can be activated. In the ad hoc query, an
interactive REPORT/FAST generator prompts on the terminal’s screen
for input:
RPT>
RQL statements can be inputted. When a complete statement is entered
it is executed immediately by the generator. Any output from the
statement goes to the screen. For example Figure 1-1 overleaf:

Introduction The REPORT/FAST modes
RPT> SELECT name FROM install_df;
Installation
================
INSTALLATION
INSTALL_2
HIS_INSTALL
MY_INS
RPT> _
Figure 1-1 Example of an ad hoc query on the screen

When a long RQL statement has to be entered, it can be entered on
several lines. For instance, the example in Figure 1-1 might also look
like the example in Figure 1-2.
RPT> SELECT
> name FROM
> install_df;
Installation
================
INSTALLATION
INSTALL_2
HIS_INSTALL
MY_INS
RPT> _
Figure 1-2 The RQL statement spread over more than one line
REPORT/FAST keeps prompting for a complete statement until the end

of the statement is encountered. The end of a statement is indicated by
the semi colon ‘;’. It is allowed to enter multiple statements on a single
line. An interactive session is exited by the QUIT statement.
The ad hoc query is very useful for quick, unexpected data set

The set-up description Introduction
inspections.
1.7 The set-up description

Set-up A special report description exists called the set-up description. This
description set-up description contains normal RQL statements. It is executed by the
REPORT/FAST generator while initializing at system start-up. All
descriptions encountered in this set-up description will be valid for all
successive reports generated. The set-up description is normally used to
overrule default REPORT/FAST settings for, for example, page layouts.
Also, the header and footer appearing on the reports can be defined in
this set-up description. Note that these set-up settings can be overruled
in the actual report description. If a statement is encountered in the
set-up description which generates output, (for example, the SELECT
statement) the output from that statement is directed to the system’s
error logging device.
1.8 Error handling

Errors encountered by REPORT/FAST during generation can be
Statement divided into two classes: statement errors and execute errors.
Execute error
A statement error is an error due to an incorrect statement specification,
for example a typing error.
An execute error is an unexpected error encountered during the
execution of a statement. Examples of execute errors are:
• No connection with another node
• Problems reading data from disks
All errors, except fatal errors preventing REPORT/FAST from finishing
the report, are logged in the report being generated. These fatal errors are
logged to the system’s error logging device.
A list of possible errors can be found in Chapter 9 ‘Reference’.
1.9 ISAM and DSS datasets

The arrival of the DSS (Data Set Services) layer in FAST/TOOLS 8.0
introduced a completely new way to access FAST/TOOLS data. The
reports described in this manual are based on the older ISAM datasets.

Introduction ISAM and DSS datasets
DSS datasets are organized is a fundamentally different way then ISAM

data sets. This means that report queries on ISAM datasets use a
different syntax than queries on a DSS data set. Chapter 10 of this
manual describes the differences between DSS and ISAM datasets in
more detail.

Introduction Data sets
2 Data sets
2.1 Introduction
This chapter introduces the reader to the FAST/TOOLS data sets. RQL
facilitates access to the data in the data sets. This chapter covers the
following aspects:
• What are data sets?
• Data dictionaries
• How to define data sets
2.2 What are data sets?

A data set is a collection of data of the same type. For instance, the data
set ‘item_df’ contains the definitions of all process variables. A single
Record definition is called a record. An item definition record contains
information like: the name of the process variable, its limits, its alarm
Field parameters, etc. Such an information unit in a record is a field. A field
itself may contain other fields. For example, the item name field consists
of the installation name, unit name, tag name and sub name. The whole
record itself can be treated as a field. See Figure 2-1 and Figure 2-2 for
a more detailed picture.

Data sets What are data sets?
DATA SET
record 1
record 1 data
record 1 2
record set
record 2 block
record 2 3
record
record 3
record 3
record n
record n
record n
Figure 2-1 The components (blocks and records within blocks)

of a data set
Figure 2-1 also shows that a collection of records may occur more than
once in a data set. For example, the data set ‘item_df’ may contain
instances of process variable definitions of different systems. Such an
Data set block occurrence or instance is called a data set block. In the above example
a data set block corresponds with a DATABASE/FAST database file
and the name of the data set block is the name of the database file.
However, a data set block need not be a database file. For instance, the
data set ‘item_val’ defines the real time item database. In many cases
there is only one data set block and the name of the data set block has no
meaning. A data set block is identified by:
• The name of the data set
• The name of the node on which the data set block is located
• The name of the data set block itself. For database files, it is the
name of the database file.
Server The data sets are accessed within REPORT/FAST by means of servers.
Therefore a complete data block identification also includes the node on
which the server is active and the name of the server.

What are data sets? Data sets
A record is highlighted in Figure 2-2.
field 1
field 2
field 6 field 3 field 4
field 5
field 7 field 8
Figure 2-2 The layout of a record

Unit The units in a record are fields. A field itself can be divided into other
fields. The record itself is also a field (field 1). A field which itself
contains other fields is called the parent of those other fields. Thus field
Parent & Child 6 is the parent of field 7 and 8. A field having a parent is a child field.
Fields have the following attributes:
• Name
Each field has a name. Fields may have the same name as long as
they do not have the same owner. In most cases, the name of the
record (field 1) is the same as the name of the data set.
• Type
The data in a field is stored in a certain representation (data type).
A field with children always has the representation ‘structured’.
• Format
The format defines the appearance of the data in the field when it is
output to the report. Structured fields do not have formats.
• Heading
The heading defines the text in the heading for a field when output
to the report. Structured fields do not have headings.
• An alias field name
The previously mentioned name of the field is a technical name and
in many cases it does not make the purpose of the field clear. A
more user friendly alias name can be given to the field. Structured
fields do not have alias field names.
• A value
A field contains a value for each record in the data set block
(structured fields do not). Such a value can be numeric, text (string)
or boolean, depending on the field type.

Data sets Data dictionaries
Figure 2-2 is repeated with more realistic field names in Figure 2-3.
my_record
status
level value_1 value_2
status
status option
Figure 2-3 Fields in a record
The name ‘status’ is used three times. Specifying the name ‘status’ does
not identify the field. The field name can be made unique by preceding
the field name by its parents until a non-ambiguous name is created. The
three names for the ‘status’ fields will become ‘my_record.status’,
‘status.status’ and ‘level.status’. Such an unambiguous name is a field
specification.
A data set block can contain many records. Specific records can be
Key field accessed by a key field. Thus suppose that field ‘status.status’ in the
above example is a key. We can retrieve specific records by asking:
Give me the records where ‘status.status’ is the alarm ‘high’.
If a record has to be found in which a non-key field has a certain value
we have to ask:
Give me all records.
I will check all records myself to find those where ‘value_1’ is 12.4.
Generally speaking, data set accesses based on keys are much more
efficient than non-key based accesses.
2.3 Data dictionaries

Dictionary The definitions of data sets are stored in one or more data dictionaries.
A dictionary contains the descriptions of the data sets. Such a description
contains:
• The name of the data set.
• The node location and name of a server interfacing between the
data set and REPORT/FAST.
• The node location and name of the default data set block. In many
cases the data set block is a DATABASE/FAST file.
• The layout of the record, its fields and attributes.
• The names of the fields which are keys.

How to define data sets Data sets
REPORT/FAST uses this information to retrieve the required data for

the report.
There may be more than one data dictionary available in the system. A
dictionary is specified by its node location and name. For the data
dictionary accesses, REPORT/FAST also uses a server, interfacing
between one or more data dictionaries and REPORT/FAST. Such a
server is identified by its node location and name.
2.4 How to define data sets*

Each data set that is accessible by REPORT/FAST must be defined in
the data dictionary. The Data Set Services facility of
DATABASE/FAST is used to define data sets. Each data set is described
in a special notation, the Data Set Services language and stored in a so-
called DSS file. By defining your data sets using the DSS language, this
information automatically becomes available via other programs using
data set services such as the quickload facility DSSQLD, the
ACCESS/FAST ODBC interface or application programs written using
the DSS API.
All FAST/TOOLS definitions are available via DSS, as well as current
tag data and historical data such as alarm history, item history and audit
trail. You only need to define you own data sets in case you are creating
information sources specific to your application. More information on
defining data sets is described in chapter 10. The description language
for defining data set definitions is described in the DATABASE/FAST
DSS Language Manual.
2.5 Old-style data sets

Prior to Data Set Services, the DDL compiler was used to define data
sets which used its own Data Description Language (DDL). The DDL
compiler is still available for compatibility and system upgrade
purposes, but it is recommended to use Data Set Services as much as
possible.
In this section, an example is given of the DDL compiler input, a data

Data sets Old-style data sets
set description, including an explanation of how REPORT/FAST uses

this data set. For more information about the DDL and the DDL
compiler, see the DATABASE/FAST Language Manual. An example of
DDL:
set unit_df, , rpifil, , 5, "item_name2.dat", key;
record: unit_df
{
struct unit
{
char nam1[16]; "%-16s" "install" "Installation"
char nam2[16]; "%-16s" "unit" "Unit"
} unit;
long status; "999" "status" "Block|status"
};
key: unit = (unit) nodup

• The first line specifies general information about the set.
• ‘unit_df’ is the name of the data set
• ‘rpifil’ specifies the name of the server interfacing between
REPORT/FAST and the data set block.
• ‘5’ and ‘item_name2.dat’ specifies directory path, and the name of
the data set block. In this case, the data set block is a database file.
• ‘key’ is of no concern here.
• The ‘record’ specifies the layout of all records in the data set. The
name of the record will be ‘unit_df’. We have seen in a previous
section that a record is a field on its own. Thus the field name for
the record is also ‘unit_df’. ‘unit_df’ has two children, ‘unit’ and
‘status’. In turn, ‘unit’ also has two children, ‘nam1’ and ‘nam2’.
These names are the technical names.
• ‘char’ and ‘long’ specify the data type of these fields.
Following the field name and data type specification, the default
appearance of the data is specified, the alias name and the heading for
the field. If the default appearance is omitted (empty string) then
REPORT/FAST uses default format rules. If there is an alias name
specified, this field alias name will be known to REPORT/FAST. In this
case REPORT/FAST has no knowledge about the technical name.
However, the alias name specification is optional. If omitted,
REPORT/FAST uses the technical name. An omitted heading
suppresses the output of the heading for the field. Meanwhile, it can be
overruled by RQL statements, used in the report query.
The last line
key: unit = (unit) nodup

Old-style data sets Data sets
specifies the fields which are keys. Note that the parenthesized name
must always be the technical name of the field which is a key, i.e. alias
names are not allowed here. In this case, the key is a structured field.
The DDL offers many features, some of which are not handled by
REPORT/FAST. They are:
• A key must contain one field. However, this field may be a
structured field.
• Unions are supported by REPORT/FAST. However, the user of
REPORT/FAST has to specify which union member has to be
output. In addition, problems can occur when moving records from
a system of a different architecture than the one REPORT/FAST is
running on. For more information about system conversion, see the
BUS/FAST Programmer’s Guide Volume 3 (FSL).

Data sets Old-style data sets

Introduction Retrieving data
3 Retrieving data
3.1 Introduction
Query Fetching data from the various data sets is realized by queries. In this
chapter, we explore the basic elements of the query, including the two
essential clauses every query must have and a third clause that specifies
particular records to fetch.The topics covered are:
• Basic elements of a query
• Narrowing the query
• Ordering data
• Connecting data sets
• Displaying other data
3.2 Basic elements of a query

In its most basic form, a query has just two components, a SELECT
clause and a FROM clause. In a simple query, the SELECT clause lists
the names of the fields containing the data to fetch, and the FROM
clause specifies the data sets in which these fields are located.
The simplest query selects all data in all fields of one data set. The
SELECT clause can be narrowed, however, to select data only from
particular fields, and the selection can be narrowed in other ways by
attaching various qualifications. Fields can be named in the SELECT
clause from more than one data set and various operations can be
specified to be performed on the data and display the results of these
operations.
The result of a query is output to the report in table form and is
sometimes called the result table. The rows in the result represent the
data that meets the conditions or has undergone the operations specified
in the query. If no data qualifies, there will be no row in the report.
The following example shows a query and its result. It asks for all fields
of data from all records of data set ‘unit_df’. No qualifications are
attached, so all the data in the data set is in the result:
SELECT install, unit, status FROM unit_df;

Installation Unit Block

Retrieving data Basic elements of a query
status
================ ================ ======
INSTALLATION HIS_UNIT 0
INSTALLATION MY_UNIT 0
INSTALLATION UNIT_5 0
TEST_INS UNIT_1 2
Quite often, only field names appear in the select clause, as in the
preceding query. But field names are just one of several items that can
appear there. More generally, the SELECT clause specifies expressions
to be evaluated for each qualifying field. The FROM clause specifies the
data sets used in evaluating these expressions.
An expression is a word or phrase that yields a value. Thus, a field name
is an expression, in the context of the SELECT clause, because it yields
a value for each record of the data set to which the field belongs. For
instance, the ‘install’ field in the preceding query yields the name of an
installation for each record of the data set.
There are several kinds of expressions besides field names.
Consequently, there are several kinds of things that can appear in the
SELECT clause.
The result table contains a column for each expression listed in the
SELECT clause. This column displays the value of the expression for
each record of the specified data set. In the last example, the expressions
are all field names and appear in the same order in which they occur in
the data set being queried, so the result table of the query is identical to
data set ‘unit_df’ itself.
In brief, then, a query consisting of only a SELECT clause and a FROM
clause essentially says: ‘for all records, SELECT the values of these
expressions FROM these data sets’.
The types of expressions in a SELECT clause can be broadly classified
into two kinds: those that simply yield the value of a field in each
qualifying record, and those that yield the value of operations. The latter
Arithmetic are again, broadly speaking, of two kinds: arithmetic operations and
operations and functions. For the time being, we will deal with field name expressions
functions in the SELECT clause. Other kinds of expressions that can appear in a
SELECT clause will be discussed in Chapter 6 ‘Manipulate Data’.‘
Note that in queries a parent field name can be used rather than
specifying all child field names in the SELECT clause. A parent field
name means ‘the values of all children’:
SELECT unit_df FROM unit_df;

Basic elements of a query Retrieving data
status
================ ================ ======
TEST_INS UNIT_1 2
Data from certain fields only can be selected and others can be omitted.
The next query only draws data from field ‘install’:
SELECT install FROM unit_df;
Installation
================
INSTALLATION
INSTALLATION
INSTALLATION
TEST_INS
Notice that field ‘install’ contains some duplicates: there are three
entries for ‘install’. The special keyword DISTINCT immediately after
the word SELECT in the SELECT clause suppresses duplicate rows in
the result, that is, rows having the same value for each expression listed
in SELECT list as the previous row. In the following example, the
DISTINCT keyword is added to the preceding query:
SELECT DISTINCT install FROM unit_df;
Installation
================
INSTALLATION
TEST_INS
The DISTINCT keyword suppresses only duplicate rows in the result,
not duplicate values. In the following query, the duplicate values in field
‘install’ are back, but each is paired with a different value in ‘unit’, so
the rows themselves are not duplicates. Consequently, no rows are
suppressed:
SELECT DISTINCT install, unit FROM unit_df;
Installation Unit
================ =================
INSTALLATION HIS_UNIT
INSTALLATION MY_UNIT
INSTALLATION UNIT_5
TEST_INS UNIT_1

Retrieving data Narrowing the query, the WHERE clause
3.3 Narrowing the query, the WHERE clause

The WHERE clause narrows the scope of the query by focusing only on
certain records. Instead of returning the values of the expressions in the
SELECT clause for all records, a query with a WHERE clause returns
only for records that meet the conditions specified in the WHERE
clause. In other words, a query containing a WHERE clause essentially
says: ‘SELECT the values of these expressions FROM these data sets in
just the records WHERE these conditions are met’.
The conditions in the WHERE clause are called search conditions.
For instance, the next query selects data in field ‘install’ and ‘unit’ of
‘unit_df’ in just those records where the ‘status’ is 1. In other words, the
query lists the units which are on line:
SELECT unit_df FROM unit_df
WHERE status = 0;
status
================ ================ ======
It is allowed to use fields in the WHERE clause that do not appear in the
SELECT clause:
SELECT unit FROM unit_df
WHERE install = ’TEST_INS’;
Unit
================
UNIT_1
The apostrophes surrounding ‘’TEST_INS’’ are necessary because
‘’TEST_INS’’ is a character string. Also, the whole name must be
entered in upper case because that is the way the name appears in the
data set. If ‘’TEST_INS’’ was specified instead, the query would return
zero rows because there is no value ‘’TEST_INS’’ in the field
INSTALL.
3.3.1 Conditions
In the preceding example, ‘install = ’TEST_INS’’ is a condition. The

equal sign ‘=’ in the middle is a relational operator.
There are 6 relational operators. These can be used to form 6 types of

Narrowing the query, the WHERE clause Retrieving data
conditions for use in the WHERE clause. The operators are:

= is equal/identical to
!= or <> is not equal/identical to
> is greater than
>= is greater than or equal to
< is less than
<= is less than or equal to
Each of these can be used in the WHERE clause to form conditions like
the one in the preceding query.
For example, the following query selects all units whose status is not on
line:
WHERE status != 0;
status
================ ================ ======
TEST_INS UNIT_1 2
The ‘1’ does not have to be surrounded by apostrophes because it is
numeric data, not string data.
The operators work with numeric data as well with strings:
WHERE unit.unit > ’MY_UNIT’;
status
================ ================ ======
TEST_INS UNIT_1 2
‘’MY_UNIT’’ and 1 are constants. 1 is an integer numeric constant. It
has no decimal fraction. 1.2 has a decimal fraction. It is a real numeric
constant. A numeric constant containing a decimal sign is a real. Thus 1.
is a real. String, integer and real are also called data types.
Integers can also be specified as a date or time:
SELECT item_value FROM item_history WHERE
sample_time > 12-may-90 12:00 AND
item_name = ’INSTALLATION.MY_UNIT.TEMPERATURE’;
Value
======
12.8
16.7
23.5

Retrieving data Narrowing the query, the WHERE clause
..
In this query ‘12-may-90 12:00’ is an integer constant. RQL does not
have a special date data type. Date specifications are converted by RQL
to integer constants. The value for a date will be the number of seconds
between ‘1-Jan-1970 00:00:00’ and the specified date. This value can be
represented by a date string.
3.3.2 String comparison with wildcards
Sometimes it can be very helpful to do string comparison using

wildcards. To do this the LIKE-operator can be used in the WHERE
clause. The LIKE operator combines a field specification with a search
pattern. The search pattern is a string expression in which the wildcard
characters ‘%’ and ‘_’ are allowed. The ‘%’ matches any string of zero
or more characters, the ‘_’ matches any single character.
WHERE install LIKE ’_OHN’;

status
================ ================ ======
JOHN ROGERS 0
JOHN SMITH 0
JOHN WHITESNAKE 0
By using the SET statement on variable @WC_ANY an other character
can be selected for the ‘%’ function. By using the SET statement on
variable @WC_SINGLE an other character can be selected for the ‘_’
function.
3.3.3 Connecting several conditions
The following example uses more than one condition in the WHERE
clause. The query can be narrowed by attaching conditions using the
operators AND and OR. Numerous conditions can be added to the
WHERE clause using AND and OR.
item_name = ’INSTALLATION.MY_UNIT.TEMPERATURE’ AND
sample_time > 12-may-90 12:00;
Value
======

Ordering the results Retrieving data
12.8
16.7
23.5
..
An attached condition can itself be a combination of several conditions
by enclosing it in parentheses:
WHERE status = 0 AND
(unit = ’UNIT_5’ OR
unit = ’MY_UNIT’);
status
================ ================ ======
3.4 Ordering the results

Sometimes, the results of a SELECT query must be put into a specific
order. Using the ORDER BY clause it is possible to sort on any column
or on multiple columns, either ascending or descending.
The ORDER BY clause is followed by either a field specification or
column position that indicates where to sort on. The position is a number
identifying the position of the column in the SELECT clause (beginning
with 1).
The next query displays the installations and unit of the unit data set,
sorted according to unit name:
SELECT unit_df FROM unit_df ORDER BY unit;
status
================ ================ ======
PAUL DA_COSTA 0
HVS HVS 0
HVS HVSUNIT 0
HVS HVSUNIT2 0
HVS HVSUNIT3 0
PAUL MCENROE 0
PAUL PHILLIPS 0
JOHN ROGERS 0
JOHN SMITH 0
INSTALLATION UNIT 0
INSTALLATION UNIT_II 0
JOHN WHITESNAKE 0

Retrieving data Ordering the results
The output table is sorted according to unit name, whereas omitting the
ORDER BY clause would result in the output table sorted according to
installation name.
If instead of field specification the column position was used, the value
of 2 (unit.unit is the second column position) must in this case be
supplied to get the same results.
Optionally the ORDER BY clause can be followed by the keywords
ASC indicating ascending order or DESC descending order. If omitted,
the ordering is ascending.
WHERE install = ’JOHN’
ORDER BY 2 DESC;
status
================ ================ ======
JOHN WHITESNAKE 0
JOHN SMITH 0
JOHN ROGERS 0
Another way of ordering the results can be achieved by using the

GROUP BY clause and, optionally, the HAVING clause. The GROUP
BY clause allows you to group rows in the result and the HAVING
clause lets you apply search conditions to the rows yielded by the
GROUP BY clause.
The GROUP BY clause groups distinct result rows of a query in sets
according to the columns, called grouping columns. These grouping
columns may be used for all kinds of operations.
Suppose you want to know how many units are defined for each
installation. This can be done by using the COUNT() RQL function, to
count the units for an installation. What must be done first, is to store the
result of the query in these grouping columns before the COUNT()
function is used. This is achieved by the following query:
SELECT install, COUNT( unit )
FROM unit_df
GROUP BY 1;
Installation COUNT( unit )
================ ==================
HVS 4
INSTALLATION 2
JOHN 3
PAUL 3

Connecting data sets, joins Retrieving data
Here it can be seen that first the results of the query are grouped (by
installation), and then the COUNT() function is performed. This query
without the GROUP BY clause is illegal, since install asks for a value
for each row, and for COUNT( unit ) a single value derived from all
rows taken together is asked for. Therefore this syntax is incoherent.
If the COUNT( unit ) was omitted, the same result could be achieved by
the query:
SELECT DISTINCT install FROM unit_df
ORDER BY install;
The HAVING clause is used to restrict the results of the GROUP BY
clause, similar to the way in which the WHERE clause narrows the focus
on the SELECT clause. If the previous query should only output the
installations that contain 3 units, the statement will be:
SELECT install, COUNT( unit ) “COUNT”
FROM unit_df
GROUP BY 1
HAVING COUNT( unit ) = 3;
Installation COUNT
================ =====
JOHN 3
PAUL 3
The search condition in the HAVING clause is just like the condition for
the WHERE clause, but it may also contain aggregates - as in this
example the result of COUNT( unit ). This is impossible in the WHERE
clause.
3.5 Connecting data sets, joins

Very often, the data to select will not always be in one data set. For
instance, in the previous example the status of a unit is presented by a
number. However, suppose a data set ‘status_df’ is available containing
status numbers and their associated status text:
SELECT status_number, name FROM status_df;
Status System text
number
====== ================
0 On line
1 Not initialized
2 Off line
3 Fault

Retrieving data Connecting data sets, joins
We can, however, get this information in one go by using a query called

Join a join. A join is a query that draws data from more than one data set at
once, pivoting on a connect condition in the WHERE clause. Here is a
join that gives the units and their status:
SELECT install, unit, status_df.name
FROM unit_df, status_df
WHERE unit_df.status = status_df.status_number;
Installation Unit Status text
================ ================ ================
INSTALLATION HIS_UNIT On line
INSTALLATION MY_UNIT On line
INSTALLATION UNIT_5 On line
TEST_INS UNIT_1 Off line
The query says, in effect, ‘For all records in UNIT_DF, get the record in
STATUS_DF where the status in STATUS_DF is the same as the status
in UNIT_DF, return the respective values of INSTAL and UNIT from
UNIT_DF and of NAME from STATUS_DF’.
The join condition in the WHERE clause is a search condition like those
already discussed. It is built around the relational operator ‘=’.
To avoid ambiguity, three of the field names are prefixed with the name
of their respective data sets, as follows: ‘status_df.name’,
Field ‘unit_df.status’, ‘status_df.status’. ‘unit_df.status’ is called a field
specification specification.
The prefixes are necessary because the two field names are the same.
Prefixes are not ordinarily necessary except to avoid this sort of
ambiguity.
The join condition is always necessary to connect the specified data sets.
The first named data set in the FROM clause is called the primary data
set. Records from subsequent data sets are always related to a field in the
primary set. There are more restrictions:
• The join conditions must be specified in the WHERE clause in front
of normal conditions.
• If more than one set is connected, the join conditions must be
connected by the AND operator.
• Join conditions must be connected to normal conditions by the
AND operator.
Sometimes it is necessary to connect a data set to itself. This is a way of
treating one data set as, in effect, two data sets in order to make possible
certain types of queries.
Set alias names can be used to reduce the typing of queries:

Displaying other data Retrieving data
SELECT install, unit, status_df.name

FROM unit_df a, status_df b
WHERE a.status = b.status_number;
3.6 Displaying other data

In the previous sections the use of the SELECT statement to retrieve and
display data from data sets was described. The SELECT statement
without other clauses acts as a simple print. For instance:
SELECT ’Hello’, ’world’;
Hello world
outputs just the strings ‘hello’ and ‘world’. Field names are not allowed
in such a SELECT statement. A SELECT statement without a FROM
clause does not output column headings.

Retrieving data Displaying other data

Introduction Formatting the report
4 Formatting the report
4.1 Introduction
In the previous chapter, the methods for retrieving data from the various
data sets were described. This chapter describes statements to improve
the appearance of the information retrieved by queries. It explains how
to:
• Define the appearance of columns
• Specify the layout of a report page
• Add a flag page
• Break up the report for calculations
4.2 Column formatting, the COLUMN

statement
When an expression in a SELECT clause contains only a field
specification, REPORT/FAST retrieves formatting information for the
field from the data dictionary. This formatting information contains the
heading to be output above the column and it specifies the appearance of
the data in the column. However, when this information is not available
in the data dictionary or when an expression is specified containing
operators or functions, REPORT/FAST uses a default formatting. The
following example contains a column for a field specification only and
an expression containing an operator (operators are discussed in Chapter
6 ‘Manipulate Data’):
SELECT name, item_value+0.05 FROM item_val WHERE name
= ’INST.UNIT.TEMPERATURE’;
Item name
================
INST.UNIT.TEMPERATURE 12.05
No heading is displayed for the second column. Specifying a column

alias for the second column instructs REPORT/FAST to use that name
as column heading:

Formatting the report Column formatting, the COLUMN statement
SELECT name, item_value+0.05 Value FROM item_val

WHERE name = ’INST.UNIT.TEMPERATURE’;
Item name VALUE
============================================= =====
Note that although ‘Value’ was specified starting with an upper case
letter, REPORT/FAST output the heading completely in upper case.
This default behavior can be overruled by the COLUMN statement:
COLUMN value HEADING ’Value’;
SELECT name, item_value+0.05 value FROM item_val
Item name Value
============================================= =====
The ‘|’ can be used in the heading to break up a heading into more than
one line:
COLUMN value HEADING ’Value|oC’;
Item name Value
oC
============================================= ======
The COLUMN statement is also used to specify the position of a column
and the appearance of the data in a column for column aliases. The
column position can be specified by:
COLUMN value AT 70 HEADING ’Value’;
Item name Value
============================================= =====
The default position for a column is just after the previous column
separated by a single space. Using the AT clause, this spacing can be
modified to zero spaces or more. However, the column will never write
over a previous column:
COLUMN value AT 5 HEADING ’Value’;


Column formatting, the COLUMN statement Formatting the report
Item name Value

=============================================
The appearance of the data in the column can also be specified by the
COLUMN statement. For example:
COLUMN value AS ’999.9 oC’ HEADING ’Value’;
Tag Value
===================================== ========
INST.UNIT.TEMPERATURE 12.1 oC
Format ‘999.0 oC’ is called a format specification. A format specification is a
specification string. This string contains characters which are interpreted by
REPORT/FAST to be a visual representation of the data to be output.
One of those characters is the ‘9’. The ‘9’ defines the positions of the
digits of a number. A ‘+’, ‘0’ or both characters can be put in front of the
‘9’. The ‘+’ instructs REPORT/FAST always to display the sign. The ‘0’
specifies the visibility of leading zeros. The ‘.’ specifies the position of
the decimal sign. Some examples:
Format Value Result
99.9 12.45 12.5
0999.9 12.45 0012.5
+99.9 12.45 +12.5
+099.999 12.45 +012.450
An exponential notation can also be specified by ‘EEEE’:
Format Value Result
9.99EEEE 12.45 1.25e+01
When the type of data to output is integer, the ‘.’ and ‘EEEE’ are not
valid in the format specification. Not valid format characters are copied
without interpretation to the output:
Format Value Result
99 12 12
0999 12 0012
+99.9 12 +12.12
+99.9 12. +12.0
+099.999 12 +012. 12
99EEEE 12 12EEEE
In the third line of the above example something strange happened.
Because the value is an integer the ‘.’ is not a valid format character. It
is copied to the output. The following ‘9’ is a valid format character and

Formatting the report Page formatting
the integer value is output again. However, this single ‘9’ did not specify
enough digits to output 12. In such a case, REPORT/FAST extends the
format to be able to output the number without losing digits. Thus,
formats do specify a minimum width.
An integer value can also be output in a date and/or time representation.
Some examples:
Format Value Result
DD-MMM-YY 641916900 07-May-90
D/MM/YY 7/05/90
DDD YYYY Mon 1990
hh:mm 12:15
It is hh:mm It is 12:15
Y YY YYYY 90 90 1990
M MM MMM 5 05 May
D DD DDD 7 07 Mon
hh mm ss 12 15 00
The ‘A’ is used for string format specifications:
Format Value Result
AAAAAA Hello Hello
AA Hello
AAAAAAAR Hello
AAAAAAAC Hello
The ‘R’ specifies right justification of the string in the field. The ‘C’
modifier specifies centered justification. The ‘L’, left justification, can
also be used but is not required since it is the default.
The ‘\’ can be used to instruct REPORT/FAST not to interpret the
following character, but just to copy it to the output:
Format Value Result
Day DDD 641916900 7ay Mon
\Day DDD Day Mon
In addition to the formats just described, most standard C-language
formats can also be used.
4.3 Page formatting

The result of queries is output to pages of the report. The general layout
of a report can be defined within RQL. This layout is shown in the

Page formatting Formatting the report
following figure:
left margin right margin
top margin
header
query result
page size
footer
bottom margin
page width
Figure 4-1 Formatting a report
The layout of a report page depends on the following parameters:

• Page size
The page size specifies the length of a page in lines.
REPORT/FAST handles page sizes ranging from 20 lines up to 255
lines. The default is 72 lines. A value of 0 (zero) means that a page
can hold an unlimited number of lines. This is very useful to avoid
new page control characters in the report output if, for example,
HTML code needs to be generated.
• Top margin
The top margin specifies the number of lines on the top of the page
which will always be left blank. It also specifies the position of the
page header. The default is 3 lines.
• Bottom margin
Bottom margin specifies the number of lines on the bottom of the
page reserved for the footer. The default is 6 lines.
• Page width
The page width specifies the width of a page in characters. The

Formatting the report Page formatting
valid range is 40 to 512 characters. The default is 80 characters.

• Left margin
The left margin specifies the number of characters left blank on the
left side of each line. No left margin is the default.
• Right margin
The right margin specifies the number of characters left blank on
the right side of each line. No right margin is the default.
• Header
The header is positioned just after the top margin. The default is no
header defined.
• Footer
The footer starts at the beginning of the bottom margin. The default
is no footer defined.
• Query result
The result of the queries is output between the header and footer.
The sizes and margins are represented by RQL variables (see Chapter 6
‘Manipulate Data’ for more information about variables). By changing
the contents of such variables, the layout of the page can be modified.
The table below shows the variables involved:
Page item Variable name
page size @PAGE_SIZE
top margin @TOP_MARGIN
bottom margin @BOTTOM_MARGIN
page width @WIDTH
left margin @LEFT_MARGIN
right margin @RIGHT_MARGIN
The SET statement is used to modify such a variable. For example to
change the width of a report to 132 characters, the following statement
is issued:
SET @WIDTH 132;
In most cases, such statements are located in the set-up description to
define the page layout for all reports to be generated.
The layout of the header and footer can be defined with the HEADER
and FOOTER statements. Only the HEADER statement will be
discussed. The FOOTER statement requires the same arguments as the
HEADER statement does. For example the header:
Yokogawa System Center Europe B.V.
Date 05-May-1990 Page 1
header fragments

Page formatting Formatting the report
Header Each text unit is called a header fragment. Using the HEADER
fragment statement these fragments, their position and appearance can be
specified. All fragments are specified in a single HEADER statement.
Thus the layout of the HEADER statement looks like this:
HEADER fragment 1, fragment 2, ...., fragment n;
Each fragment specifies the data to be output, its positions on the line,
the format specification and whether or not to skip one or more lines.
The data can be any constant or expression.
The position specification can be AT nn, LEFT, CENTER or RIGHT.
AT nn specifies the character position of the fragment on the line. Note
that this position nn is relative to the left margin. LEFT positions the
fragment to the left side of the line, CENTER centers the fragment on
the line, and RIGHT positions the fragment to the right of the line. The
position specification may be omitted. When omitted, the fragment is
positioned to the left of the previous fragment.
The format is specified as AS format specification. It defines the
appearance of the fragment. All format rules as described in the previous
section apply to format specification of header fragments. When the
format specification is omitted, REPORT/FAST uses default format
rules.
The SKIP specifies the line of the item being output to the report. This
next item can be a next header part or a result of a query. A skip of zero
lines has the same effect as omitting the skip specification. The next item
to be output will be positioned on the same line as the current fragment.
A skip of one line will output the next item on the next line. A skip of
two lines means that an extra blank line is inserted, and so on.
The next statement shows how the previous example header was
created:
HEADER ’Yokogawa System Center Europe B.V.’ CENTER
AS ’%s’ SKIP 1,
’Date 05-May-1990’ LEFT AS ’%s’,
1 RIGHT AS ’Page 99’ SKIP 2;
A more convenient way of specifying this header is discussed in Chapter
6 ‘Manipulate Data’.
When a SELECT statement generates more output than fits on a single
page, the column heading is reprinted on each page.

Formatting the report Flagging the report
4.4 Flagging the report

A flag page includes one or more pages with additional information
which is output to the report before any other data. Such a flag page is
normally used to make a clear identification of the report being
generated or it may contain information about who, when and why a
report was generated. However, the contents of the flag page can not be
specified by REPORT/FAST. REPORT/FAST can only be told which
flag page to output. The statement FLAG PAGE is used to do this. It
specifies the name of a plain text file which is copied to the output
(inclusive any formfeed) before any other output. This statement must
occur in the report description before any output is generated. Output is
generated by the SELECT and SHOW statements. An example of the
FLAG PAGE statement is:
FLAG PAGE ’my_flag_page.txt’;
4.5 Breaking up the report

Sometimes a report must be broken up for intermediate calculations. The
BREAK statement allows you to do so. It influences the SELECT
statements following the BREAK statement.
The BREAK statement specifies a column to break reports upon. It
affects the output of all the SELECT statements following the BREAK
statement. The column specified by the BREAK statement can be
referenced by the following SELECT statement via the column alias. It
is not required that all columns named by the BREAK statement are
referenced by following SELECT statements.
Suppose we want to break a report of installations and units between two
different installations and then calculate the number of units for each
installation.
The query could look like this:
BREAK install SKIP 1 CALCULATE COUNT unit;
SELECT install install, unit unit FROM unit_df
ORDER BY install;
Installation Unit
================ ================
HVS HVS
HVSUNIT
HVSUNIT2

Breaking up the report Formatting the report
HVSUNIT3
----------------
COUNT 4
INSTALLATION UNIT
UNIT_II
----------------
COUNT 2
JOHN ROGERS
SMITH
WHITESNAKE
----------------
COUNT 3
PAUL DA_COSTA
MCENROE
PHILLIPS
----------------
COUNT 3
Note that the calculation outputs a heading equal to the calculation

performed. The result of the calculation is lined up with the column
involved in the calculation. Duplicate column values for columns for
which a break is specified are suppressed.

Formatting the report Breaking up the report

Introduction Advanced queries
5 Advanced queries
5.1 Introduction
Typically, a REPORT/FAST query file contains a number of formatting
commands, and a number of queries with the SELECT statement. Result
reports that are generated can be viewed or printed.
This chapter shows the RQL statements to do some extra report ‘flow
control’ using queries. The statements cover:
• conditional execution (IF-THEN-ELSE-ENDIF)
• loops (LOOP-ENDLOOP)
• row-by-row operation (CURSOR and FETCH)
The next sections discuss these statements.
5.2 Conditional execution

In the query file, statements can be conditionally executed when using
the IF-THEN-ELSE-ENDIF statements. The syntax of this statement is
IF <condition> THEN <statements> [ELSE <statements>] ENDIF;.
The condition part may contain a number of conditions, combined with
the boolean operators AND/OR. A single condition again, consists of
two expressions separated by a relational operator. The expressions
must be of the same type. Fields may not be referenced within the
expression. The LIKE operator is allowed.
IF @P1 = ’units’ OR @P1 LIKE ’unit_%’ THEN
SELECT unit_df FROM unit_df;
ENDIF;
The ELSE clause is optional. If the condition is true, the statements
between the THEN and ELSE/ENDIF are executed. If not, the
statements between the ELSE and ENDIF are executed, if there are any.
The evaluation order of the AND/OR conditions may be modified by
enclosing it in parentheses.
It is allowed to nest the IF statement.

Advanced queries Loops
5.3 Loops
The LOOP statement allows looping within a report description. It is an
unconditional loop. However, in combination with the IF and EXIT
statement, a conditional loop can be constructed. The statements in the
loop between LOOP and ENDLOOP are executed until the loop is
terminated with the EXIT statement. The LOOP statement may be
nested.
SET @aa 1;
SET @bb 1;
LOOP
LOOP
SELECT @bb, ’*’, @aa, ’=’, @bb*@aa;
SET @bb @bb+1;
IF @bb > 10 THEN
SET @bb 1;
EXIT;
ENDIF;
ENDLOOP;
SELECT ’’;
SET @aa @aa+1;
IF @aa > 10 THEN
EXIT;
ENDIF;
ENDLOOP;
1 * 1 = 1
2 * 1 = 2
3 * 1 = 3
4 * 1 = 4
5 * 1 = 5
6 * 1 = 6
7 * 1 = 7
8 * 1 = 8
9 * 1 = 9
10 * 1 = 10
1 * 2 = 2
2 * 2 = 4
..
6 * 10 = 60
7 * 10 = 70
8 * 10 = 80
9 * 10 = 90
10 * 10 = 100

Row-by-row operation Advanced queries
5.4 Row-by-row operation
5.4.1 Introduction
Cursors Using cursors greatly increases the flexibility of defining reports. The
SELECT statement generates a table with rows. It is not possible to
handle each row independently and to perform certain actions depending
on the value of certain columns within a row. Using cursors enables
fetching row by row into variables and the use of these variables by other
statements. The following statements are used to manipulate cursors:
• The DECLARE statement declares a cursor and its associated
SELECT statement.
• The OPEN statement opens a declared cursor.
• The FETCH statement fetches the first or next row and stores the
result in variables.
• The CLOSE statement closes an open cursor.
In addition, two system variables are available:
• @RQLERROR indicates whether the previous statement was
executed successfully or not. It is incremented by one when a
statement is not executed successfully. It is left unmodified when a
statement is successfully executed.
• @RQLCOUNT indicates the number of rows processed by the
SELECT or FETCH statement.
Of course the FETCH statement will usually be combined with the
LOOP-ENDLOOP statements, to retrieve rows in a loop.
5.4.2 Declare a cursor - the DECLARE statement
The DECLARE statement declares a cursor (a variable) associated to a

SELECT clause. The SELECT statement is not executed; the SELECT
clause may not contain the SET clause. Column aliases are allowed.
However, they will have no relation with columns defined by the
COLUMN and BREAK statements.
A cursor variable cannot be written over by the SET, DECLARE and
SELECT statements.
The following example illustrates how a cursor can be declared:
DECLARE @units IS SELECT unit_df FROM unit_df;
The next section shows how to open the cursor and use it in the FETCH

Advanced queries Row-by-row operation
statement.
All declared cursors can be deleted by a single DECLARE statement
without arguments:
DECLARE;
5.4.3 Open a cursor - the OPEN statement
The OPEN statement opens a previously declared cursor. This must be

done before the FETCH statement related to the cursor can be executed.
Example how to open the previously declared cursor:
OPEN @units;
Warning: Cursors that have not been closed after usage, continue to exist
even during subsequent report generation sessions. It is therefore good
practice, to add an empty declare at the end of a report definition.
5.4.4 Fetch rows - the FETCH statement
The FETCH statement upon an open cursor returns data of just one row
of the SELECT statement associated to the cursor. While fetching rows
in a loop, the data can be processed row by row. The column data of that
row must be put into as many variables as there are columns; these
variables are specified in the FETCH statement. The cursor declared and
opened in the previous sections can be used in the following FETCH
statement:
FETCH @units INTO @install, @unit, @status;
Note that the variables @install, @unit and @status must have been
previously set.
The FETCH statement influences the value of the RQL variable
@RQLCOUNT. This is set to 0 if the FETCH statement did not return a
row. This variable can be tested within the loop to break it when there
are no more rows to fetch.
5.4.5 Close a cursor - the CLOSE statement
The CLOSE statement closes an open cursor and releases all system
resources reserved for the open cursor. After being closed, a cursor can
be re-opened by the OPEN statement.
Example:

Example Advanced queries
CLOSE @units;
5.4.6 Indication - the @RQLERROR variable
The RQL reserved variable @RQLERROR indicates whether or not the

previously executed RQL statement was executed successfully. It is
incremented by one when an error is detected. It is left unmodified when
the statement is executed successfully. The error itself will be output by
the statement which detected the error. Initially when the generation
starts, the variable holds zero.
5.4.7 Row counter - the @RQLCOUNT variable
The RQL variable @RQLCOUNT holds the number of rows returned by

the previously executed SELECT or FETCH statement. This variable is
used mostly for fetching rows in a loop.
5.5 Example
The following example shows how to use the statements discussed in
this chapter to make an advanced report:
SET @name '';
SET @install '';
SET @unit '';
SET @status 0;
SET @opc_visible 0;
SET @description '';
DECLARE @units IS SELECT unit_df FROM unit_df;
OPEN @units;
LOOP
FETCH @units INTO @name, @install, @unit, @status,
@opc_visable, @description;
IF @RQLCOUNT = 0 THEN
EXIT;
ENDIF;
/*

Advanced queries Example
process column values here

*/
ENDLOOP;
CLOSE @units;
DECLARE; /* Cleanup all cursors */

Introduction Manipulate data
6 Manipulate data
6.1 Introduction
RQL is not limited to selecting data in the form in which it appears in the
data sets. As described at the beginning of Chapter 3 ‘Retrieving Data’,
queries are used to select the results of performing various operations on
the data.
In this chapter, three devices are described for performing operations on
data in query. These are
• Arithmetic operators
• Functions
• Variables
In each case, the operator, function or variable is used with constants,
field specifications, and so on to form a new expression. This expression
is then used in the same way as field specifications: in the SELECT list
of a query or in a search condition. Just as with field specification
expressions, using the expression in the SELECT list generates a column
in the result report for the value of the expression. The usage of
expressions is not limited to queries. Many other RQL statements accept
expressions.
6.2 Arithmetic operations

Four arithmetic operators can be used to form expressions:
• + addition
• - subtraction
• * multiplication
• / division
These operators can be used with constants, field specifications,
functions, special keywords, more complex expressions, and variables.
Their use with field specifications and constants is shown first.
In the following query, we use the addition operator to add .05 (a
constant) to the current value of a process variable in the ‘item_val’. The
SELECT clause contains two expressions: ‘tag’ and the expression
formed with the arithmetic operator, ‘value+0.05’. The result table thus

Manipulate data Arithmetic operations
contains two columns, one for each.

SELECT name, item_value+0.05 FROM item_val WHERE
name= ’INST.UNIT.TEMPERATURE’;
Item name
=======================
The query directs that a value be returned for the two expressions ‘name’
and ‘item_value +0.05’ for each record of ‘item_val’ where the value of
‘name’ is ‘INST.UNIT.TEMPERATURE’.
There is one record for ‘name’ in ‘item_val’; getting the value for
‘name’ in that record is straightforward. To get the value for the
expression ‘item_value +0 .05’, the value for ‘item_value’ is fetched, the
specified operation (adding .05) is performed on this value, and then the
result is displayed.
In ‘item_val’ itself, INST.UNIT.TEMPERATURE’s value remains
unchanged: it is still 12. No SELECT statement ever changes data in a
data set, no matter what operations are performed on the data before it is
displayed in the result. All that happens is that values of expressions in
the SELECT list are returned in the result report for each qualifying
record of the data set queried.
Arithmetic operators can be used on more complex expressions, too:
SELECT name, (item_value+0.05)/2 FROM item_val WHERE
name= ’INST.UNIT.TEMPERATURE’;
Item name
========================
Arithmetic operators can be used with the name of any field having a
numeric data type, including groups of fields whose numeric data types
are not the same. For example, integer data can be added to real data, and
so forth. REPORT/FAST tries to evaluate an expression to an integer
result as long the expression does not contain reals. The result of the
expression will be converted to real as soon as the first real value is
encountered.
RQL also allows use of arithmetic operations with date and time
constants because date and time constants are handled by
REPORT/FAST as integers. For example the following query returns
the number of days between two dates:
SELECT (13-Jan-92 - 7-Dec-88) / 24 / 60 / 60;
1132

Functions Manipulate data
RQL offers a variable containing the current date and time. The
following query calculates the number of days between this moment and
a date in the future:
SELECT (13-Jan-99 - @DATE) / 24 / 60 / 60;
2322
A special operator for strings is the concatenate operator, represented by
two bar characters ‘||’. The syntax for using this operator is
string||string
where the arguments can be either string constants or field
specifications. The operator concatenates the arguments, that is,
juxtaposes them, in the result. For instance, the following query
concatenates the strings in ‘tag’ with the string ‘blocked’ for all those
process variables which are blocked:
SELECT name || ’ is blocked’
FROM item_val WHERE status = 3;
TEMPERATURE is blocked
pH is blocked
6.3 Functions
Functions provide another means of using queries to perform
manipulations to the data in data sets.
A function returns a value by performing a certain operation on the
function’s argument (or arguments). A function together with its
argument yields a value and is thus an expression.
The argument of a function is also an expression. Depending on the
function, an argument may be either a constant (string or numeric)
returning a single value, or an expression containing a field specification
and capable of returning different values for different records. The
expression ‘UPPER(’temperature’)’ is an example of a function (namely
UPPER) taking a constant as its argument; the expression ‘UPPER(tag)’
shows the same function taking field specification ‘tag’ as its argument.
Most functions have only one argument.
In the following sections, we discuss two types of functions: group
functions and non-group functions.

Manipulate data Functions
6.3.1 Group functions
The distinctive feature of group functions is that they compute one

single value from all records of a field. Thus, where every other type of
expression returns a value for each record specified by a query, group
functions return a value that represents a single group of the values in a
number of records.
There are seven group functions:
• AVG() Returns the average of a column.
• COUNT() Returns the number of rows in a column.
• MAX() Returns the maximum value of a column.
• MIN(() Returns the minimum value of a column.
• STDDEV() Return the standard deviation of a column.
• SUM(() Returns the sum of the values of a column.
• VARIANCE() Returns the variance of a column.
Group functions most often take as their argument either a field
specification by itself or an expression having a field specification as a
component - for example, ‘valued + 0.05’ - but they can be used with any
numeric expression. In the case of AVG, MAX, MIN and SUM, the
argument must be a numeric expression. It cannot be a string. COUNT,
however, also accept strings.
All the functions ignore null values and they are only allowed in the
SELECT clause of the SELECT statement. Because a group function
returns a single value for all records it can not be mixed with a column
expression not containing a group function.
The keyword DISTINCT can be used with group functions. The
keywords are placed preceding the argument inside the parentheses: for
example, COUNT (DISTINCT TAG). This keyword has a function
analogous to that of the DISTINCT keyword that can be used
immediately after the word ‘SELECT’ in the SELECT clause: the
DISTINCT keyword causes sequential duplicate values to be ignored.
The following example illustrates the use of the group functions:
SELECT AVG(item_value) FROM item_history WHERE
19.35
This example returns the average of the values for the item
‘INSTALLATION.MY_UNIT.TEMPERATURE’ during the last day.

Functions Manipulate data
The following example also returns also the number of samples during
that day and the minimum and maximum value:
SELECT COUNT(item_value), MIN(item_value),
MAX(item_value), AVG(item_value) FROM item_history WHERE
512 12.15 25.40 19.35
It is allowed to combine group functions in expressions:
SELECT MAX(item_value)-MIN(item_value/2) FROM
item_history WHERE
15.725
Group functions cannot themselves appear in a WHERE clause,
however, as the following query demonstrates:
sample_time < @DATE AND
item_value > AVG(item_value) - 2 AND
item_value < AVG(item_value) + 2;
Group function not allowed
This query asks for all history values of a specified process variable of
the last day with a value around the average. The group function in the
search condition causes the query to generate the error.
Fortunately, there is, in effect, a way around this prohibition against
including a group function in a search condition. It will be discussed in
section 6.4: Variables.
If the first function mentioned in a SELECT clause is a group function,
all other columns in that SELECT clause must be group functions too.
SELECT AVG(item_value), LENGTH(item_value) FROM ...
is not allowed, because LENGTH is a non-group function (see also the
next subsection).
6.3.2 Non-group functions
Non-group functions differ from group functions in that they do not

compute a single value from all records of a field. Instead, non-group

Manipulate data Functions
functions, like all other expressions we have discussed (except group

functions), return a value for each record.
Unlike group functions, non-group functions can be nested in other
non-group functions such that the output of the inner function is used as
an argument by the outer function. For example, in the nested function
UPPER(LOWER(’HELLO WORLD’))
LOWER returns HELLO WORLD in lower case letters, and UPPER
makes them upper case again.
Non-group functions can take either a constant (for example, any of the
following types of values: ’hello world’, 25, 19-JUN-1988 or @DATE)
or a field specification (for example, ‘name’) as an argument. If a field
specification is given, then, for each record, the function takes as its
argument the value of the field in that record.
Unlike group functions, non-group functions can be used in the WHERE
clause and all other statements where expressions are allowed as well as
in the SELECT clause.
The following example uses the function LENGTH(string). Function
LENGTH returns the number of characters in its argument. In this
instance, we use the function to return the number of characters in each
name in ‘name’ in ‘item_df’:
SELECT name, LENGTH(name) FROM item_df;
Item name
===========================
INST.UNIT.TEMPERATURE 11
INST.UNIT.pH 2
INST.UNIT.SPEED 5
To give another example, function NUMBER(string) converts a
character string of digits into the number represented by that string. As
described in section 6.4: Variables, this function is very useful for
converting the so-called parameter strings into numeric values. It is
allowed to specify a date or time as an argument:
SELECT NUMBER(’12-Jan-90’);
632102400
The last example shows the usage of the DECODE function. The
DECODE is a kind of look-up table:
SELECT unit,
DECODE(status, 0, ’On line’, 2, ’Off line’, ’UNKNOWN’)
FROM unit_df;
Unit
================

Variables Manipulate data
HIS_UNIT On line
MY_UNIT On line
UNIT_5 On line
UNIT_1 Off line
The ‘status’ in each record is compared with successive values. If a
match is found, the associated value is output.
Other non-group functions are:
• ABS() Returns the absolute value of the input.
• ADD_MONTHS() Returns a date to which a number of months
has been added.
• CHAR() Returns a number converted to a string.
• CHR() Returns a number converted to its ASCII
value.
• DRAW() To construct a string from a template string.
• GPV_QUALITY() Returns the quality code of a process
variable
• GPV_STATUS() Returns the status of a process variable.
• GPV_VALUE() Returns the value of a process variable.
• LINE() Returns a string containing the specified
count of ‘-’ characters.
• LOWER() Returns the input string with all characters
converted to lower case.
• MONTH_DAYS() Returns the number of days in a month.
• SPV_QUALITY() Sets the quality code of a process variable
• SPV_STATUS() Sets the status of a process variable.
• SPV_VALUE() Sets the value of a process variable
• TO_GMT() Returns the GMT time of a date.
• TO_LCT() Returns the LCT time of a date.
• UPPER() Returns the input string with all characters
converted to upper case.
If the first function mentioned in a SELECT clause is a non-group
function, all other columns in that SELECT clause must be non-group
functions too.
SELECT LENGTH(value), AVG(value1) FROM ...
is not allowed, because AVG is a group function.
6.4 Variables
Besides using constants like 12, ’hello world’, 12-Jan-90, RQL also

Manipulate data Variables
handles variables. A variable holds a certain value and this value can be
modified. A variable is created by the SET statement:
SET @tag ’INST.UNIT.TEMPERATURE’;
The variable can be used at those places where expressions are allowed.
The variable just defined can be used, for example, in a SELECT
statement:
SELECT name, item_value FROM item_val WHERE name =
@tag;
Item name Value
============================== =====
Another method to give a variable a value is by using the SELECT
statement:
SET @value 0;
SELECT SET @value item_value FROM item_val WHERE name
= ’INST.UNIT.TEMPERATURE’;
The query does not output any data to the report. However, the variable
‘@value’ receives the result of the query. Note that ‘@value’ must be
pre-defined by the set statement. If a column alias is specified, the result
of the query will be also output to the report:
SELECT SET @value item_value my_column FROM item_val
Value
=========
12.0
If more records are selected, the variable receives the result of the last
record.
The next example shows a solution to the problem of being unable to use
group functions in the WHERE clause:
SET @max 0;
SET @min 0;
SELECT SET @max AVG(item_value) + 2,
SET @min AVG(item_value) - 2
FROM item_history
WHERE
sample_time < @DATE AND

item_value > @min AND

item_value < @max;
Another possibility is offered by using the GROUP BY clause,
discussed in Chapter 5 ‘Advanced Queries’.
Some variables are pre-defined by REPORT/FAST. For example
@DATE contains the current date (stored as number of seconds since
1970). This date can be output by:
COLUMN date as ’DD-MMM-YYYY’;
SELECT @DATE date;
05-May-1990
The pre-defined variables are often used in header and footer definitions,
for example:
HEADER @CUSTOMER CENTER SKIP 1,
@DATE LEFT AS ’\Date DD-MMM-YYYY’,
@PAGE RIGHT AS ’Page 99’ SKIP 1,
LINE(0) SKIP 1;
The header
Yokogawa System Center Europe B.V.
Date 05-May-1990 Page 1
will appear above each report page.
This example shows the usage of two other pre-defined variables,
@CUSTOMER and @PAGE. @CUSTOMER contains the name of the
system on which REPORT/FAST is running and @PAGE holds the
current page number being output to the report. Note that LINE(0)
returns a string of ‘-’ characters with a total length equal to the page
width decreased by the left and right margin.
Chapter 4 ‘Formatting the Report’ discussed the usage of the variables
@WIDTH, @LEFT_MARGIN, @RIGHT_MARGIN, @PAGE_SIZE,
@TOP_MARGIN and @BOTTOM_MARGIN. They specify the size
of a report page and position of the header and footer. Using the SET
statement on the variables, the layout of the pages can be modified.
The @DECIMAL variable specifies the decimal sign to be used by
REPORT/FAST when output decimal numbers. Using the SET
statement the decimal sign can be modified:
SET @DECIMAL 44;
SELECT 12.3;
12,3
The variables @NAME, @DESCRIPTION and @P0 to @P7 depend on
the report being generated. @NAME contains the name of the report

being generated. @DESCRIPTION contains the one line report

description. @P0 to @P7 contain the input parameters as inputted by the
user at the FAST/TOOLS standard interface when activating an ad hoc
generation. Note that @P0 to @P7 variables are of type string. The
following example shows their usage:
SELECT AVG(item_value) FROM item_history WHERE
name = ’INSTALLATION.MY_UNIT.TEMPERATURE’ AND
sample_time > NUMBER(@P0) AND
sample_time < NUMBER(@P1);
12.14
Note that these report-dependent variables are not available in the set-up
description or when the generator is in interactive mode.
A rarely-used variable is the @WORKSPACE. It defines the amount of
memory allowed to be used by REPORT/FAST to store dynamic data
internally, like strings. The default size of this area is for most cases
sufficient. However, the error ‘No more free space is available in the
dynamic storage area’ indicates that this default size is not enough to
handle the report description. In such a case, the SET @WORKSPACE
statement in the set-up description can be used to increase the work
space.
@SORTSPACE is used similar to @WORKSPACE. It defines the
amount of memory allowed to be used by REPORT/FAST to sort rows
(the SORT BY and GROUP BY clauses). However, when this amount
is not sufficient, REPORT/FAST will continue sorting using disk space,
thereby increasing the time needed to generate the report.
Sometimes FAST/TOOLS data is required to be transported to foreign
systems. REPORT/FAST supports the ASCII(DELIMITED) format to
do so. When the @EXPORT variable has been set to ‘1’ the report
output conforms to the ASCII(DELIMITED) standard, e.g. each column
will be separated from its previous column by a comma, each string
column will be surrounded by quotes and only table rows will be output.
For example:
SET @EXPORT 1;
SELECT install, unit, status FROM unit_df;
"INSTALLATION","HIS_UNIT",0
"INSTALLATION","MY_UNIT",0
"INSTALLATION","UNIT_5",0
"TEST_INS","UNIT_1",2
The SPOOL statement can be used to output the result to any disk and
file.
Some pre-defined variables can not be modified by the SET statement.

For example the statement:

SET @CUSTOMER ’My name’;
generates the error:
This variable may not be modified
It is allowed to modify the type of a variable:
SET @my_var 12;
SET @my_var ’my value’;
Note that variables that have been set once can not be deleted any more
within the current description.
The wildcard characters ‘%’ and ‘_’ can be changed by modifying the
variables @WC_ANY and @WC_SINGLE respectively.


Introduction Communications
7 Communications*
7.1 Introduction
This chapter contains information about the communications features of
REPORT/FAST. The information in this chapter is not of interest for the
majority of users of REPORT/FAST. The communication features allow
REPORT/FAST to communicate with application processes while it is
generating a report. Information can be sent to an application and
information can be received from an application. The BUS/FAST
message passing facilities are used to realize the communication.
Additional information can be found in the BUS/FAST Programmer’s
Guide Volume 1 (DUR).
This chapter covers:
• Sending data
• Receiving data
7.2 Sending data, the SEND statement

The BUS/FAST message passing facilities are used by REPORT/FAST
to allow data to be passed to an application while a report is being
generated.
The result of expressions can be transferred to an application. This result
can be sent in a binary or ASCII format. These specifications are used to
specify the format of the data to transfer.
The name of the application (process name) must be specified in the
SEND statement. Optionally, a node name can be specified to allow
communication with an application on a node other than one where
REPORT/FAST is active. As default, REPORT/FAST assumes the
same node as the one it is active on. Note that REPORT/FAST does not
take care of system conversions when inter-node communication is
performed. The application itself has to take care of the system
conversion (for more information about system conversion, see
BUS/FAST Programmer’s Guide Volume 3 (FSL)).

Communications Sending data, the SEND statement
Optionally, the message code can be specified. If omitted, the code of

the previous SEND will be used. However, if there is no previous send
and the message code is omitted, REPORT/FAST will give it an
arbitrary value.
The BUS/FAST message sent is a request message. It can be specified
whether or not the application has to return a reply.
The general layout of the message can be according to the
FAST/CONVENTIONS or the message can have an arbitrary layout if
such a layout is required. However, it is advised to follow the
FAST/CONVENTIONS.
The normal format specification as described in a previous chapter
formats output to ASCII. Some special formats are available to format
output to a binary representation. These special formats are:
• I1
converts the result of a numeric expression to a TLS_BYTE and
stores it sequentially in the send buffer.
• I2
converts the result of a numeric expression to a TLS_SHORT and
• I4
converts the result of a numeric expression to a TLS_LONG and
• F4
converts the result of a numeric expression to a TLS_FLOAT and
• F8
converts the result of a numeric expression to a TLS_DOUBLE and
• Ann
converts the result of a string expression to a zero terminated string
with a length of nn bytes. If the expression results in a string with a
length greater than nn, nn is incremented by REPORT/FAST to
store the whole length.
Note that the result of the I and F formats is system type dependent.
All other format specifications are also allowed and the result of those
will always be a string.
An example of the SEND statement:
SEND my_process REPLY CODE 12 PACKING
12*4 AS ’I4’, ’hello world’ AS ’A16’,
7.3/5 AS ’F4’;

Receiving data, the RECEIVE statement Communications
The message sent has the following layout (described as a C structure):

struct
{
TLS_SHORT size; = 28
TLS_SHORT code; = 13
TLS_LONG val1; = 48
char val2[16]; = ’hello world’
TLS_FLOAT val3; = 1.46
};
If NO PACKING was specified it will have the layout:
struct
{
TLS_LONG val1; = 48
char val2[16]; = ’hello world’
TLS_FLOAT val3; = 1.46
};
7.3 Receiving data, the RECEIVE statement

In contrast to the SEND statement, the RECEIVE statement allows the
receiving of BUS/FAST messages.
A receive of any message or a selection by process name and/or message
code can be specified.
A time-out can be specified. This time-out specifies the time in seconds
REPORT/FAST will wait for a (specific) message to be received. When
the time has elapsed, the receive is cancelled and an error message is
output to the report. When the time-out specification is omitted,
REPORT/FAST uses a default time-out.
The message received is unpacked into specified variables using the
specified input formats. These input formats are:
• I1
converts the next TLS_BYTE in the receive buffer to an integer and
stores it in the specified variable.
• I2
converts the next TLS_SHORT in the receive buffer to an integer
and stores it in the specified variable.
• I4
converts the next TLS_LONG in the receive buffer to an integer

Communications Receiving data, the RECEIVE statement
and stores it in the specified variable.

• F4
converts the next TLS_FLOAT in the receive buffer to a real and
• F8
converts the next TLS_DOUBLE in the receive buffer to a real and
• Ann
converts the next nn characters in the receive buffer to string and
No other formats are allowed in an input format other than those listed
above. The variables specified to receive the result must exist.
The following example receives a message as sent in the previous
section:
SET @val1 0;
SET @val2 0;
SET @val3 0;
RECEIVE CODE 13 PACKING @val1 AS ’I4’ @val2 AS ’A16’
@val3 AS ’F4’;

8 Miscellaneous
8.1 Introduction
This chapter contains information that has not been discussed in the
previous sections. The chapter covers:
• Selecting a dictionary
• Including reports
• Logging in
• Ending a report description
• Showing status
8.2 Selecting a dictionary, the DICTIONARY

statement
REPORT/FAST retrieves data about fields and data sets referenced in a
SELECT statement from a data dictionary. The name of the data
dictionary and the name of a server interfacing between REPORT/FAST
and the dictionary must be known to REPORT/FAST. As default,
REPORT/FAST uses the data dictionary ‘tlsdic’ and interfaces to it by
the server ‘rpidic’ both located on the same node as REPORT/FAST is
running on.
The DICTIONARY statement overwrites the REPORT/FAST defaults.
The nodes on which the data dictionary and the server are located can
also be modified by the statement. The DICTIONARY statement is
normally located in the set-up description overwriting the defaults as
required. In most cases, the name of the server will not be modified.
Node changes are most common. An example of the DICTIONARY
statement is:
DICTIONARY my_node:rpidic.his_node:his_dictionary;
8.3 Including reports, the INCLUDE statement

Very often, many report descriptions contain the same statement

Miscellaneous Logging in, the LOGIN statement
sequence. Such sequences can be gathered in another report description.

This description can be included in the reports in which the sequences
were originally located. For example: a week report contains the results
of seven days. The description for the week report may look like this:
set @start_of_week @DATE - 7*24*3600;
/* Get time start of week */
set @start_of_day @start_of_week;
/* The start of the first day in the week */
include ’day_report’;/* Do the day report */
set @start_of_day @start_of_day + 24*3600;
/* Start of the next day */
include day_report;/* Do the next day */
..
A fragment of the ‘day_report’ description may look like this:
SELECT.... WHERE time >= @start_of_day AND
time < @start_of_day+24*3600;
Defined variables are accessible in the report descriptions being
included. It is allowed to include reports in report descriptions being
included.
8.4 Logging in, the LOGIN statement*

REPORT/FAST basically consists of two functional blocks. The
REPORT/FAST generator is responsible for the actual report
generation. The REPORT/FAST manager manages the definition,
scheduling, initialization of ad hoc generations and generated reports. It
issues commands to the REPORT/FAST generator to generate a certain
report. There is always one manager active. However, more than one
generator may be active allowing reports to be generated concurrently.
The manager has to have knowledge about the active generators to
which it can issue generate commands.
In practice, there are important reports and less important reports
indicated by the priority. Less important reports may not block the
generation of an important report. To prevent this, more than one
generator can be activated. An activated generator can be given a
priority level. It will not receive generate commands from the manager
for reports with a priority lower than the generator’s priority. In this way,
generators can be reserved for high priority reports.

Ending a report description Miscellaneous
The activation modes, interactive or background mode, of the generator

have already been described.
Using the LOGIN statement, the situation described above can be
specified. Summing up: the LOGIN command takes care of making a
generator known to the manager, specifies the priority for the generator
and defines the interactive or background mode. The statement is
normally located in the set-up description. When there is no LOGIN
statement specified in the set-up description, the generator will activate
its interactive mode prompting the user for input. When a LOGIN
statement is encountered in the set-up session, the generator makes itself
known to the manager and it will activate its background mode awaiting
generate commands from the manager.
An example of a LOGIN statement is:
LOGIN rptman, 5;
8.5 Ending a report description

A report description can be a file created during the definition of a report
or it can be user input when in interactive mode. The report generation
is finished when the end of the input description is encountered or when
a QUIT statement is encountered. The common use of the QUIT
statement is to leave the generator when in interactive mode.
The QUIT statement has no arguments.
8.6 Showing status, the SHOW statement

Using the SHOW statement the defined columns, header, footers,
cursors and variables can be displayed. For example:
SHOW VARS;
Variables:
----------
@BOTTOM_MARGIN : 0
@CUSTOMER : 'Yokogawa System Center Europe B.V.'
@DATE : 715514117
@DECIMAL : 46
@EXPORT : 0
@FORMFEED : 0
@GEN_TIME : 715511305

Miscellaneous Showing status, the SHOW statement
@LEFT_MARGIN : 0
@LINE : 11
@NEXT : 0
@PAGE : 2
@PAGE_SIZE : 23
@RIGHT_MARGIN : 0
@RQLCOUNT : 1
@RQLERROR : 0
@SORTSPACE : 100
@TIME : 715514117
@TOP_MARGIN : 0
@VERSION : '2.0'
@WIDTH : 80
@WORKSPACE : 100
DECLARE @unit IS SELECT unit_df FROM unit_df WHERE
status > 1 ORDER BY install;
SHOW FULL CURSOR;
Cursors:
--------
@UNIT :
Status: CLOSED
Columns:
Type: OUTPUT
Exp: UNIT.INSTALL
Type: OUTPUT
Exp: UNIT.UNIT
Type: OUTPUT
Exp: STATUS
Sets:
(Alias) Name: UNIT_DF
Set name: UNIT_DF
Joins:
Conditions (WHERE):
Left level: 0
Right level: 0
Left: STATUS
Right: 1
Operator: >
Conditions (HAVING):
Sorts:
Field: UNIT.INSTALL
Sorting: ASC
Sort for: ORDER BY

9 Reference
9.1 Introduction
This chapter contains reference information about all aspects of RQL. It
covers:
• Naming conventions
• RQL reserved words
• Data types
• Variables
• Type conversion
• Formatting rules
• Expression and operators
• Field specifications
• Error messages
• Functions
• Statements
9.2 Naming conventions

The following objects may be given names:
• Variables
• Data sets
• Columns
• Fields
• Nodes
• Servers
• Reports
• Processes.
A name must:
• start with a letter unless it is a variable name, in which case it starts
with the ‘@’ sign
• contain the characters ‘a’-‘z’, ‘A’-‘Z’, ‘0’-‘9’ and ‘_’ only
• not duplicate an RQL reserved word (see next section)
The maximum size for a variable name is 32 characters excluding the
‘@’ sign. The maximum node name length is 24 characters. Report

Reference Reserved words
names are limited to 16 characters. All others are limited to 32

characters.
9.3 Reserved words
The following words are reserved in RQL1:
AND INTO ABS TO_LCT

AS IS ADD_MONTHS TO_REAL
ASC LEFT ASCII_FILE UPPER
AT LIKE AVG VARIANCE
BREAK LOGIN BAND
BREAKS LOOP BNOT
BY NO BOR
CALCULATE NOT BSHIFT
CENTER OPEN BXOR
CLOSE OR CHAR
CODE ORDER CHR
COLUMN PACKING COUNT
CURSOR PAGE DECODE
DECLARE QUIT DRAW
DESC RECEIVE GPV_STATUS
DICTIONARY REPLY GPV_VALUE
DISTINCT REPORT GPV_QUALITY
ELSE RESERVED LENGTH
ENDIF RESOURCES LINE
ENDLOOP RIGHT LOGBOOK_TEXT
EXIT SELECT LOWER
FETCH SEND MAX
FILE SET MIN
FLAG SHOW MONTH_DAYS
FOOTER SKIP NUMBER
FROM SPOOL SPV_STATUS
FULL STAT SPV_VALUE
GROUP THEN SPV_QUALITY
HAVING TIMEOUT STDDEV
HEADER VARS SUBSTR
HEADING WHERE SUM
IF WORKSPACE TO_GMT
INCLUDE TO_INTEGER
It is normally not allowed for them to be used as names for data sets,
columns, fields, nodes, servers, reports or processes. However, it is
1. This table can be obtained by the SHOW RESERVED statement

Data types Reference
allowed to use them when they are surrounded by double quotes. For
example:
SELECT "number" FROM ...;
9.4 Data types

REPORT/FAST maintains three types of data which may appear in the
report: strings, integers and reals.
9.4.1 Strings
A string is a sequence of characters not interpreted as a number. A string

is specified within RQL statements by enclosing it in apostrophes. If the
string itself has to contain an apostrophe it has to be duplicated.
Examples of string specifications are ’hello world’, ’123’, ’John’’s’,
9.4.2 Integer
An integer number ranges from -2147483648 to + 2147483647. Its

precision is 10 digits without any decimals.
An integer is specified in RQL statements as ‘[-]n’ where n can be up to
10 digits. An integer can also be specified using the date format. When
RQL recognizes a valid date specification it translates the date
specification into an integer number containing the number of seconds
since 1-Jan-1970 00:00. A date is specified like ‘[dd-mmm-yy[yy]]
[hh:mm[:ss]]’. ‘mmm’ can be one of ‘JAN’, ‘FEB’, ‘MAR’, ‘APR’,
‘MAY’, ‘JUN’, ‘JUL’, ‘AUG’, ‘SEP’, ‘OCT’, ‘NOV’ or ‘DEC’. Year
specifications below 70 are interpreted as years after 2000. If the date is
omitted the current date is assumed. If the time is omitted ‘00:00:00’ is
assumed. Examples of integer numbers are: ‘123’, ‘-1056’, ‘12-Jan-90’,
‘12:00’, and ‘13-Feb-1990 13:21’.
9.4.3 Real
A real number ranges from about ‘-1e35’ to about ‘1e35’. The precision
is about 14 digits. The smallest number which can be specified is about
‘1e-35’. The actual values for the different hardware architectures on
which REPORT/FAST is running may differ a little. Within an RQL

Reference Type conversion
statement a real number is specified by the syntax ‘[-][n].[e[-+]n]’. The

decimal point is always required. Examples of real numbers are ‘12.’,
‘23.34e2’, ‘12.25’.
9.5 Type conversion

Data set fields typing differs from the types available within RQL. Data
set field data is converted by RQL to one of the above RQL data types
using the following table:
Data set field type RQL data type
char string
BOOLEAN integer
SHORT integer
USHORT integer
LONG integer
ULONG integer
UBYTE integer
FLOAT real
DOUBLE real
9.6 Variables
A variable can hold data of one of the three RQL data types. A variable
can be specified in an RQL statement instead of a string, integer or real
specification. A variable name starts with the ‘@’ sign. All variables
referenced within the RQL statements must be made known to
REPORT/FAST using the SET statement prior to referencing it in other
statements. Some variables are pre-defined by REPORT/FAST.
9.6.1 @BOTTOM_MARGIN
The integer @BOTTOM_MARGIN specifies the number of lines from

the bottom of the page where the footer is started. This variable can be
modified by the SET statement. The system’s default is 6 lines.

Variables Reference
9.6.2 @CONCEAL
The integer @CONCEAL specifies whether concealed DSS dataset

fields are to be made available in the report query. If the value is set to
1 concealed fields are not included, if set to 0 concealed fields are
included. By default the value of @CONCEAL is 1.
9.6.3 @CUSTOMER
String @CUSTOMER contains the customer name of the system on

which REPORT/FAST is running. This variable can not be modified by
the SET statement.
9.6.4 @DATE
Integer @DATE contains the number of seconds since 1-Jan-1970

00:00:00 of the current date and time. It can not be modified by the SET
statement.
9.6.5 @DECIMAL
The integer @DECIMAL variable specifies the decimal point by its

ASCII value to be used by REPORT/FAST when output real numbers to
the report. The default value is 46 which represents ‘.’. This variable can
be modified to contain the correct decimal sign. For example: SET
@DECIMAL 44; sets the decimal sign to ‘,’. The system’s default is 46.
9.6.6 @EXPORT
The RQL variable @EXPORT indicates global report output formatting.

When set to one the output will conform to the ASCII(DELIMITED)
standard. This implies:
• Only table rows will be output. No page headers and footers,
column headings, empty lines will be output.
• Each row will be output on a single row. Each column will be
separated from its previous column by a comma. Each string
column will be surrounded by quotes.
When @EXPORT is set to zero (the default value) normal output is

Reference Variables
generated.
9.6.7 @FORMFEED
REPORT/FAST advances to the next report page by output the required

amount of blank lines or by output a form-feed printer command. The
integer @FORMFEED variable specifies the method being used. If
@FORMFEED is equal to 0, blank lines are used. In all other cases the
form-feed is used. The variable can be modified by the SET statement.
The system default is 1, thus using the form-feed method.
9.6.8 @GEN_TIME
The RQL system variable @GEN_TIME holds the time (in LCT) the
report should be generated (@TIME holds the current time while
generating). When generating a report ad-hoc this variable holds the
time of the ad-hoc request. When using the generator interactively, it
holds the time the generator was started.
9.6.9 @LEFT_MARGIN
The integer @LEFT_MARGIN specifies the position on a line where

the actual report data starts. This variable can be modified using the SET
statement. The system’s default is position 0 (start of the line).
9.6.10 @LINE
This integer variable contains the current line number within the report
being generated. This variable can not be modified by the set statement.
9.6.11 @NEXT
This integer variable specifies whether or not terminal report output is

paused with the text:
Press <RETURN> to continue or Q<RETURN> to quit
If @NEXT is 0, terminal output is not paused.

Variables Reference
9.6.12 @PAGE
The integer @PAGE variable contains the current page number. This
variable can not be modified by the SET statement.
9.6.13 @PAGE_SIZE
The integer @PAGE_SIZE variable specifies the page size in lines. The
system’s default is 72 lines. The page size can be modified by the
SELECT statement. The valid range for the page size is 20 to 255 lines.
A value of 0 (zero) means that a page can hold an unlimited number of
lines. This is very useful to avoid new page control characters in the
report output if, for example, HTML code needs to be generated.
9.6.14 @RIGHT_MARGIN
The integer @RIGHT_MARGIN specifies the position from the right of

the line where line output stops. It is allowed to modify the variable. The
system’s default is 0.
9.6.15 @RQLCOUNT
The RQL variable @RQLCOUNT holds the number of rows returned by

the previously executed SELECT or FETCH statement.
9.6.16 @RQLERROR
The RQL variable @RQLERROR indicates whether or not the previous

executed RQL statement was executed successfully. It is incremented by
one when an error was detected. It is left unmodified when the statement
is executed successfully. The error itself will be output by the statement
which detected the error. Initially when the generation starts, the
variable holds zero.
9.6.17 @SORTSPACE
The integer @SORTSPACE variable specifies the size of the workspace

used by REPORT/FAST to sort rows (the SORT BY and GROUP BY

Reference Variables
clauses). The workspace is specified in Kilobytes. The system’s default

is 100 Kilobytes and suitable for most situations. However,
REPORT/FAST continues sorting using disk space when there is not
sufficient workspace. In this case, it creates a temporary work file in the
FAST/TOOLS list directory.
9.6.18 @TIME
Currently, the integer @TIME variable contains the same value as the
@DATE variable.
9.6.19 @TOP_MARGIN
The integer @TOP_MARGIN specifies the number of lines from the

beginning of the page where the header is started. This variable can be
modified by the SET statement. The system’s default is 3 lines.
9.6.20 @VERSION
This string variable contains the current REPORT/FAST version and

can not be modified by the SET statement.
9.6.21 @WIDTH
The integer @WIDTH variable specifies the width of the report. The
width can be modified by the SET statement. The system’s default is 80
characters. The valid range for the report width is from 40 characters to
5000 characters.
9.6.22 @WORKSPACE
The integer @WORKSPACE variable specifies the size of the

workspace used by REPORT/FAST to handle strings and data set
records. The workspace is specified in Kilobytes. The system’s default
is 16 Kilobytes and suitable for most situations. The error ‘No more free
space available in the dynamic storage area’ indicates insufficient
workspace.

Formatting rules Reference
9.6.23 @WC_ANY
The integer @WC_ANY variable specifies the character to be used for

the wildcard function ‘any character(s)’. By default the character ‘%’ is
used.
9.6.24 @WC_SINGLE
The integer @WC_SINGLE variable specifies the character to be used

for the wildcard function ‘one character’. By default the character ‘_’ is
used.
9.6.25 Report-dependent variables
In addition to the above-mentioned variables, other variables may be

pre-defined:
• @NAME (string):
The name of the report being generated.
• @DESCRIPTION (string):
The report description.
• @P0 to @P7 (strings):
The report parameters.
These variables are not available when the generator is in interactive
mode because in such a case the report has no name, description or
parameters.
9.7 Formatting rules

REPORT/FAST always outputs data to the report in one of the three data
types. The actual appearance of the data in the report can be defined
using formats. A format itself is a string. A string containing a format is
called a format specification. When data has to be output to the report its
associated format specification is scanned for a valid format. If the
format specification contains invalid format characters, these characters
are output to the reports as being data.

Reference Formatting rules
9.7.1 Formatting of integer data types
The following format rules apply to integer data types:

Character Example Description
9 999 Number of digits determines display width.
0 099 Display leading zeroes.
+ +999 Display leading sign.
D D The value is interpreted as a date (seconds
since 1970) and the day of the month is
displayed.
DD DD The day of the month is displayed with a
leading zero in the case of a day below 10.
DDD DDD The day in the week is displayed as ‘Sun’,
‘Mon’, etc.
M M The month number is displayed.
MM MM The month number is displayed with a leading
zero in case of a month below 10.
MMM MMM The month number is displayed as ‘JAN’,
‘FEB’, etc.
Y Y The year number is displayed in one or two
digits. Years above 1999 are also displayed in
one or two digits.
YY YY The year number is displayed in two digits.
YYYY YYYY The year number is displayed in four digits.
hh hh The hour number is displayed.
mm mm The minute number is displayed.
ss ss The seconds number is displayed.
\ \Day The character following the back slash is not
interpreted as a valid format character. It is
copied to the output without the back slash.
I1 I1 The integer is output in an internal byte
representation. This format is used within the
SEND statement.
I2 I2 The integer is output in an internal short
SEND statement.

Formatting rules Reference
I4 I4 The integer is output in an internal long

SEND statement.
% %5d The standard C format conventions are used.
The supported conversion operations are ‘d’,
‘i’, ‘u’, ‘o’, ‘x’, ‘X’. The ‘l’ modifier is not
allowed.
When REPORT/FAST tries to output an integer and no format is

specified, ‘%d’ is used which displays as many digits as required to
display the whole number.
9.7.2 Formatting of real data types
The following format rules apply to real data types:

9 999 Number of digits determines display width.
0 099 Display leading zeros.
+ +999 Display leading sign.
. 99.99 Determines the position of the decimal sign.
EEEE 99.99EEEE Determines display of exponential notation.
D D The value is interpreted as a date (seconds
since 1970) and the day of the month is
displayed.
DD DD The day of the month is displayed with a
leading zero in the case of a day below 10.
DDD DDD The day in the week is displayed as ‘Sun’,
‘Mon’, etc.
M M The month number is displayed.
MM MM The month number is displayed with a leading
zero in case of a month below 10.
MMM MMM The month number is displayed as ‘JAN’,
‘FEB’, etc.
Y Y The year number is displayed in one or two
digits. Years above 1999 are also displayed in

Reference Formatting rules
one or two digits.

YY YY The year number is displayed in two digits.
YYYY YYYY The year number is displayed in four digits.
hh hh The hour number is displayed.
mm mm The minute number is displayed.
ss ss The seconds number is displayed.
i iii The value is interpreted as a time interval and
the interval count is displayed. The number of
‘i’ specifies the number of digits used to show
the interval count.
u uuuuuuuu The value is interpreted as a time interval and
the interval units (‘seconds’, ‘minutes’,
‘hours’, ‘days’, ‘months’ or ‘years’) is
displayed. The number of ‘u’ specified the
width of the column.
\ \9 The character following the back slash is not
F4 F4 The real is output in an internal float format.
This format is used within the SEND
statement.
F8 F8 The real is output in an internal double format.
This format is used within the SEND
statement.
% %3.2f The standard C format conventions are used.
The supported conversion operations are ‘f’,
‘e’, ‘E’, ‘g’, ‘G’.
When REPORT/FAST tries to output a real and no format is specified,
‘%g’ is used which displays the real using 6 digits and using the
exponential notation if such a notation requires fewer characters to
output the number than the normal notation.
9.7.3 Formatting of string data types
The following format rules apply to string data types:

A AAA Number of A’s determines display width.

Expressions and operators Reference
R AAR The text is right justified.

L AAL The text is left justified (default).
C AAC The text is centered.
n A20 The number determines display width.
AL20
\ \Auto The character following the back slash is not
% %5s The standard C format conventions are used.
The supported conversion operation is s.
When REPORT/FAST tries to output a string and no format is specified,
‘%s’ is used which displays the string left justified and uses as many
characters as required.
As mentioned before, invalid format characters in the format
specification are copied to the output. Examples of formats are:
Value Format Display

12 0999 0012
12 +999 +12
12 99 and again 99 12 and again 12
650000000 The \Date is DD-MMM-YY The date is 07-Aug-90
650000000 and the time hh:mm:ss and the time 03:33:20
12.34 0999.9999 0012.2300
12.34 9.99EEEE 1.234e01
world Hello AAAAAA hello world
world A10 world
Besides output data, formats are also used by REPORT/FAST for input
using the READ statement. Within the read statement the following
input formats are defined ‘I1’, ‘I2’, ‘I4’, ‘F4’, ‘F8’ and ‘Ann’. No other
characters are allowed in input formats.
9.8 Expressions and operators

Within RQL statements it is allowed to perform calculations. Such a
calculation specification is an expression. There are two types of
expressions: numeric and string. The result of a numeric expression is an
integer or real. The result of a string expression is a string. It is not

Reference Expressions and operators
allowed to mix integers and reals with strings in a single expression

unless a function is included which transfers a data type to the correct
type. When a numeric expression contains at least one real, then the
result of the expression will be a real. When REPORT/FAST evaluates
an expression it assumes an integer expression. As soon as it encounters
a real, the result so far is converted to a real and the rest of the expression
is evaluated in real mode.
The following value operators are valid within expressions (in order of
descending precedence):
Operator Function Example
() Overrides normal operator SET (@a @b+12)*3;
precedence rules.
- Prefixed sign for a number SET @a -12;
expression
*/ Multiplication and division SET @a 12.3*12.4;
+- Addition and subtraction SET @a 13-5;
|| String concatenation SET @a ’Hello ’||’world’;
The following conditional operators are valid within conditions in the
WHERE or HAVING clause of the SELECT statement or in the IF
statement (in order of descending precedence):
() Overrides normal operator
precedence rules
= Test for equality ..WHERE tim = 12:14
!= <> Test for inequality ..WHERE tim != 12:14
> Greater than test ..WHERE tim > 12:14
>= Greater than or equal to test
< Less than test
<= Less than or equal to test
LIKE Test for equality taking the
wildcard characters ‘%’ (or
@WC_ANY) and ‘_’ (or
@WC_SINGLE) into account
(only for strings) ..WHERE name LIKE
’Jon%’
The following logical operators are valid to connect several conditions
in the WHERE clause of the SELECT statement (in order of descending
precedence):
AND Combines two conditions ..WHERE a < 12 AND
to be TRUE if both are TRUE a > 10

Field specifications Reference
OR Combines two conditions

to be TRUE if either is TRUE
As mentioned before, REPORT/FAST tries to evaluate a numeric
expression in integer mode as long as possible. This can lead to
unexpected results. For example the expression ‘12/5+10.0’ will result
in 12 while the expression ‘12/5.0+10.0’ results in 12.4.
When a field name is allowed in an expression the expression is called a
numeric or string field expression. Field expressions are allowed in the
SELECT, WHERE, ORDER BY and GROUP BY clause of the
SELECT statement.
9.9 Field specifications

The SELECT and WHERE clause of the SELECT statement may
contain field specifications. A field specification is a name of a field or
several field names separated by dots. It may be preceded by a data set
name or data set alias name separated from the rest of the specification
by a dot. A field specification must be unambiguous. If a field appears
more than once in a data set, the preceding field level has to be specified.
In addition, when two different data sets contain a field with the same
name and both data sets are accessed in a SELECT statement, the fields
must be preceded by the data set name or alias name.
If a field is an array, only the first element (index 0) is shown when just
the field name is specified. If other array elements should be shown, they
must be indexed explicitly, using the square brackets ‘[’ and ‘]’.
Multi dimensional array fields can also specified using square brackets.
Indexes can be omitted from the right and index ‘0’ will be used for
omitted indexes. For example, a field which is specified as ‘LONG
field_a[4][4][20]’ in the data dictionary can be referenced as follows:
field_a = field_a[0][0][0]
field_a[3] = field_a[3][0][0]
field_a[3][2][5] = field_a[3][2][5]
However, the last index of (multi dimensional) string array can not be
specified because it defines the length of the string.

Reference Errors
9.10 Errors
The following errors may appear in the report or on the systems error
device:
• A BREAK is attached to column COLUMN_NAME
It is not allowed to remove columns by the COLUMN statement
which are referenced by a BREAK.
• Arithmetic operator not allowed in string expression
Only the ‘||’, ‘LIKE’, ‘OR’ and ‘AND’ operators are allowed within
a string expression.
• Attempt to divide by zero
An expression specifies a divide by zero.
• Bad flag page file specification
The specified flag page is not a string expression.
• Can not convert a number to a string
A numeric expression is specified where a string expression is
required.
• Can not convert a string to a number
A string expression is specified where a numeric expression is
required.
• Can not group on a column containing a group function
Only grouping on columns not containing group functions is
allowed.
• Can not handle so many fields while sorting
The maximum number of field to sort on is 100.
• Can not open file FILE_NAME for output
The opening of the report output file has failed.
• Can not open source file FILE_NAME for input
The opening of a report description file has failed.
• Can not read RQL source
The report description can not be read.
• Can not retrieve dictionary info for data set
DATA_SET_NAME
The data set specified in the FROM clause does not exist or a
non-existing node or server has been specified in the
DICTIONARY statement.
• Can not sort, unknown length of column
The length of a string column could not be determined. Use the
COLUMN statement to define the width for the column via the AS
clause.
• Could not set variable

Errors Reference
The variable could not be modified. For example, it is not possible

the modify the @DATE variable via the SET statement.
• Cursor variable referenced where not allowed
A cursor variable can only be referenced within the OPEN, FETCH
and CLOSE statements.
• ’DISTINCT’ parameter is not allowed for this function
The DISTINCT keyword is only allowed in group functions.
• ENDLOOP clause was not found
A LOOP statement has been specified without its ENDLOOP
clause.
• EXIT only allowed in report definition FILES
The EXIT statement is only allowed in report descriptions stored in
files.
• Error during receive-message initialization
An error has occurred in the RECEIVE statement.
• Error during send-message initialization
An error has occurred in the SEND statement.
• Error during (un)buffering of message data
An error has occurred in the SEND or RECEIVE statement.
• Error while accessing data set DATA_SET_NAME
While a data set server is being accessed to retrieve records, an error
occurred. Typically, a non-existing node or server has been
specified in the FROM clause.
• Error while output heading for column COLUMN_NAME
An error has occurred while a column heading was being output.
• Error while output value for column COLUMN_NAME
An error has occurred while a column value was being output.
• Error while reading form report source
An error has occurred while reading the report description.
• Error while writing report
An error has occurred while the report was being output.
• Fatal error while starting, process aborted
The initialization of a REPORT/FAST generator has failed.
• Field FIELD_NAME is unknown
The specified field does not occur in the specified data sets.
• Field FIELD_NAME points to a structured field
A specified field in a structured field. For example, in WHERE
field = 12, field may not be a structured field, i.e. a field having
children.
• Field name not allowed
A field name has been specified where not allowed. For example in

Reference Errors
the SET or IF statement.

• Field specification FIELD_NAME is not unique
A field has been specified, occurring more than once in a data set.
Preceding the name with its parent name makes the name unique.
• Flag page FLAG_PAGE_FILE_NAME not found
The specified flag page could not be opened.
• Format specification is not a string
A format has been specified that is not a string expression.
• Group function not allowed
It is not allowed to mix expressions in the SELECT clause where
some contain group functions and others do not when no GROUP
BY clause is specified.
• Illegal ENDLOOP specified
The ENDLOOP clause is encountered without the LOOP clause.
• Incompatible field types for join SET_NAME
The fields by means of which sets are connected must be of the
same type.
• Incompatible or invalid arguments for operation
An expression contains numeric data as well as string data. For
example 12 / ’string’.
• Invalid date specified
The specified date is not a valid date.
• Invalid real number specified
An invalid real number has been specified in the report description.
• Invalid time specified
The specified time is not a valid time, for example 12:62.
• Login at the REPORT/FAST manager has failed
The LOGIN statement did not succeed. In most cases an unknown
node or manager has been specified.
• LOOP / ENDLOOP clause in different source files
Both LOOP and ENDLOOP clauses of the LOOP statement must
be specified in the same report source file.
• LOOP only allowed in report definition FILES
The LOOP statement is only allowed in report descriptions stored
in files.
• Memory allocation failure while allocating NUMBER
bytes
The amount of required memory is not available.
• Message was not sent
An error has occurred in the SEND statement.
• Missing or invalid format specification FORMAT_STRING

Errors Reference
In a RECEIVE, a format specification contains invalid format

characters.
• Missing variable name
A @ has been specified without a name.
• Node name too long
The name of the specified node is too long. A node name is limited
to 24 characters.
• Not enough memory to allocate dynamic storage area of
NUMBER Kbytes
Number specified in a SET @WORKSPACE NUMBER statement
was too big.
• No message received
An error has occurred in the RECEIVE statement.
• No more free space available in the dynamic storage
area
The current size of the dynamic storage area is too small to handle
the current report. Specify a SET @WORKSPACE statement to
define a large work space size.
• Non-group function not allowed in the CALCULATE
clause
Only group functions are allowed in the CALCULATE clause of
the BREAK statement.
• Not all columns which do not contain group functions
are referenced by the GROUP BY clause
All columns in the SELECT clause which do not reference group
functions must be referenced by the GROUP BY clause.
• Real value too large or too small to convert to an
integer
The result of a real expression can not be converted to an integer.
Such an error can occur in, for example: COLUMN text AT 10e20;.
• Set alias has already been used
Each specified set alias name in the FROM clause must be unique.
• SET clause not allowed within DECLARE statement
The SET clause is only allowed in the SELECT statement which is
not a clause of the DECLARE statement.
• Set SET_NAME already joined
The specified set has been connected already.
• Set SET_NAME can not be joined
The primary set can not be connected to another set.
• Set SET_NAME is not joined
The FROM clause specifies a set which has not been connected in
the WHERE clause.

Reference Errors
• Set SET_NAME is being joined to a set not joined to

another set
A set is being connected to a set which is not the primary set and
which is not connected to another set.
• Specified alias was already used in a SELECT
statement
Each specified column alias name in the SELECT clause must be
unique.
• Specified data set DATA_SET_NAME is not unique
When a data set has been specified more than once in the FROM
clause, one of them should have a unique alias name.
• Specified node is unknown
A non-existing node name has been specified.
• Syntax error
This is a general error if the generator does not understand a
statement.
• The HAVING expression does not contain a group
function
The HAVING clause of the SELECT statement must contain a
group function.
• The column number is out of range
The column number in the SORT BY or GROUP BY clause is too
low or too high.
• The cursor is not open
The FETCH or CLOSE statement references a cursor which has not
been opened by the OPEN statement.
• The number of variables does not match the number of
columns
The number of variables in the INTO clause of the FETCH
statement does not match the number of columns specified in the
SELECT clause of the DECLARE statement.
• The specified index is out of range
An array field is referenced via an index which is too low or too
high.
• This variable may not be modified
Some pre-defined variables, e.g. @DATE, may not be modified by
the SET statement.
• Unable to retrieve information about report
REPORT_NAME
The INCLUDE statement specified an unknown report name.
• Unknown node NODE_NAME specified
An unknown node has been specified or there is no connection with

Errors Reference
the specified node.

• Unterminated string encountered or string contains
non-printable characters
A string starts with an apostrophe. The terminating apostrophe has
not been found. Or the string contains a so called non-printable
character, for example a tab.
• Variable VARIABLE_NAME is not a cursor
The OPEN, FETCH or CLOSE statement references a variable
which is not a cursor.
• Variable VAR_NAME is not defined, use SET to define
An unknown variable is referenced.
• Wrong argument(s) supplied to function FUNCTION_NAME
An argument with an incorrect data type has been supplied to a
function.
• Wrong number of arguments (SUPPLIED_NUMBER) supplied
to function FUNCTION_NAME
An incorrect number of arguments has been specified in a function.
Note: All the above errors will terminate the
current statement being processed.
Some will even terminate the current
generation.
The following warnings do not terminate a statement or generation:
• Identifier name truncated
The length of most names is limited to 32 characters.
• Line width forced to NUMBER
An line width out of range has been specified. It is forced in range
by REPORT/FAST.
• Page margins forced into range
When modifying the page sizes and margins, REPORT/FAST
makes sure that all associated values are in range.
• Page size forced to NUMBER
An out of range page size has been specified. It is forced in range
by REPORT/FAST.
• String truncated
A string constant is limited to 512 characters.
• Unterminated index specification
An index specification has been encountered without its associated
‘]’ character.
• Variable name truncated
The length of a variable name is limited to 32 characters.

Reference Functions
9.11 Functions
In general, functions may be used anywhere expressions are allowed. A
function can be a group or non-group function. A group function
performs an action on a column for each row. The result of such an
action on all rows of a column is a single value. Group functions are only
valid in the SELECT clause within the SELECT statement. A non-group
function returns a value for each reference. The functions are described
in the subsections that follow.

Functions Reference
9.11.1 ABS
SYNTAX ABS(<value>)
ARGUMENTS <value> A numeric.
OUTPUT An integer or real value containing the absolute value of the supplied
integer or real expression.
SEMANTICS The non-group ABS function outputs an integer or real containing the
absolute value of the supplied integer or real expression respectively.
NOTES None
EXAMPLE SELECT ABS(field_a + field_b / 4) FROM test;

Reference Functions
9.11.2 ADD_MONTHS
SYNTAX ADD_MONTHS(<date>, <months>)

ARGUMENTS <date> A numeric expression containing the number of seconds
since 1970 (LCT).
<months> A numeric expression containing the number of months
to add to date.
OUTPUT A number containing the number of seconds since 1970 (LCT).
SEMANTICS The non-group ADD_MONTHS functions outputs an integer which is
the sum of the supplied date and months where the number of months
has been converted to the correct number of seconds.
NOTES None
EXAMPLE SET @start @date;
SET @stop ADD_MONTHS(@start, 6);

Functions Reference
9.11.3 ASCII_FILE
SYNTAX ASCII_FILE(<file_name>)
ARGUMENTS <file_name> A string expression resulting in a file name.
OUTPUT A string which contains the contents of an ASCII file which name is
specified by <file_name>.
SEMANTICS The non-group ASCII_FILE reads the contents of an ASCII file
specified by <file_name> and returns it as a string.
Using this function the contents of a file can be included in the report for
example.
NOTES The length of the string returned has a maximum of 511 characters.
The INCLUDE statement can be used to include a file which contains a
report description.
EXAMPLE SELECT ASCII_FILE(’/tls/lst/logfile.asc’);

Reference Functions
9.11.4 AVG
SYNTAX AVG([DISTINCT]<value>)
ARGUMENTS <value> A numeric field expression resulting in a value to be
averaged.
OUTPUT The average of all records of the specified expression. The output are
always of type real.
SEMANTICS The group AVG function outputs a real containing the average for all
records of the supplied expression. NULL values are ignored. When
DISTINCT is specified, only those values different from the previous
record are averaged.
NOTES None
EXAMPLE SELECT 12*AVG(field_a + field_b / 4) FROM test;

Functions Reference
9.11.5 BAND
SYNTAX BAND(<value1>, <value1>)

ARGUMENTS <value1> A numeric expression.
<value2> A numeric expression.
OUTPUT The result containing the binary AND of the two values.
SEMANTICS The non-group BAND performs a binary AND operation on the two
arguments. The output of the function is always an integer. Before the
AND is performed the two arguments are converted to integer values.
NOTES None
EXAMPLE SELECT BAND(16, 4);

Reference Functions
9.11.6 BNOT
SYNTAX BNOT(<value1>)
OUTPUT The result containing the binary NOT of the value.
SEMANTICS The non-group BONT performs a binary NOT (negate) operation on the
argument. The output of the function is always an integer. Before the
NOT is performed the argument is converted to an integer value.
NOTES None
EXAMPLE SELECT BNOT(16);

Functions Reference
9.11.7 BOR
SYNTAX BOR(<value1>, <value1>)

OUTPUT The result containing the binary OR of the two values.
SEMANTICS The non-group BOR performs a binary OR operation on the two
OR is performed the two arguments are converted to integer values.
NOTES None
EXAMPLE SELECT BOR(16, 4);

Reference Functions
9.11.8 BSHIFT
SYNTAX BSHIFT(<value1>, <value2>)

OUTPUT The result containing the binary SHIFT of the two values.
SEMANTICS The non-group BSHIFT performs a binary SHIFT operation on the first
argument. The number of bit positions to shift is indicated by the second
argument. A positive value shifts the bits to the left from lsb to the msb
direction. A negative value shifts the bits to the right form msb to the lsb
direction.
The output of the function is always an integer. Before the SHIFT is
performed the two arguments are converted to integer values.
NOTES None
EXAMPLE SELECT BSHIFT(1, 4);

Functions Reference
9.11.9 BXOR
SYNTAX BXOR(<value1>, <value1>)

OUTPUT The result containing the binary XOR of the two value.
SEMANTICS The non-group BXOR performs a binary XOR operation on the two
XOR is performed the two arguments are converted to integer values.
NOTES None
EXAMPLE SELECT BXOR(16, 4);

Reference Functions
9.11.10 CHAR
SYNTAX CHAR(<value>[,<format>])
ARGUMENTS <value> A numeric expression whose result has to be converted
to a string.
<format> A string expression resulting in a format specification.
OUTPUT The result containing the value represented as a string.
SEMANTICS The non-group CHAR function converts a number to a string
representation according to the specified format. If the format is
committed then ‘%d’ is used for integer data types and ‘%g’ is used for
real data types.
NOTES None
EXAMPLE SET @outputfile CHAR(@date, ’tls_data:rpt%d.dat’);
SPOOL @outputfile;

Functions Reference
9.11.11 CHR
SYNTAX CHR(<value>)
ARGUMENTS <value> A numeric expression in the range 0 to 255.
OUTPUT The result containing a string of one character which represents the
value as an ASCII value.
SEMANTICS The non-group function CHR is used to create a string containing ASCII
values which can not be represented by printable characters.
NOTES CHR(12) advances the report to the next page. CHR(10) advances the
report to the next line.
EXAMPLE SELECT CHR(27)||’[23h’;

Reference Functions
9.11.12 COUNT
SYNTAX COUNT([DISTINCT]<value>)
counted.
OUTPUT The count of the number of supplied expressions. The output are always
of type integer.
SEMANTICS The group COUNT function outputs an integer containing the count for
all records of the supplied expression. NULL values are ignored. When
DISTINCT is specified, only those values different from the previous
record are counted.
NOTES None
EXAMPLE SELECT SUM(field_1)/COUNT(field_2) FROM test;

Functions Reference
9.11.13 DECODE
SYNTAX DECODE (<value>, <comp>, <result>, <comp>, <result>,...

[, <default>])
ARGUMENTS <value> A numeric or string expression.
<comp> An expression of the same type as value.
<result> A numeric or string expression.
<default> A numeric or string expression.
OUTPUT Value, result or default.
SEMANTICS The non-group DECODE function compares the result of the value
expression with successive comps. If a match is found, the result will be
the result of the function. If no match is found, the default will be
returned. If no default is supplied, the value itself is returned.
NOTES None
EXAMPLE SELECT DECODE(field_1, 1, ’One’, 2, ’Two’, 3, ’Three’,
’Too low or too high’) FROM test;

Reference Functions
9.11.14 DRAW
SYNTAX DRAW(<count>, <symbol> [,<layout>])

ARGUMENTS <count> A numeric expression.
<symbol> A string expression.
<layout> A string expression.
OUTPUT A string containing one or more <symbol> characters or the modified
<layout>.
SEMANTICS The non-group DRAW function returns a string containing as many
<symbol> characters as specified by <count>. Only the first character of
the result of the <symbol> expression is taken.
When <layout> is specified, only the character at position <count> is
replaced by the <symbol> character.
However, the maximum length of the generated string is the current line
width minus the line margins (@WIDTH - @LEFT_MARGIN -
@RIGHT_MARGIN). This will also be the length of the string when a
count less than 1 is specified.
NOTES None
EXAMPLE SELECT DRAW(field_a, ’*’) FROM test;
SELECT DRAW(field_a, ’*’, ’|....|....|....|’) FROM
test;
For more examples, see Appendix A.

Functions Reference
9.11.15 GPV_QUALITY
SYNTAX GPV_QUALITY(<item name>)

ARGUMENTS <item name> A string expression containing an item name or
sub-item name, including its section path.
OUTPUT A number containing the quality code of the process variable.

SEMANTICS The non-group GPV_QUALITY returns the quality code of the
specified process variable.
NOTES <item_name> must always be specified in upper case.
EXAMPLE SELECT GPV_QUALITY(’INSTALLATION.ITEM1’);

Reference Functions
9.11.16 GPV_STATUS
SYNTAX GPV_STATUS(<item_name>)
ARGUMENTS <item_name> A string expression containing the name of an item or
sub-item, including its section path
OUTPUT A number containing the status of the process variable.
SEMANTICS The non-group GPV_STATUS function returns the merged status of the
specified process variable.
EXAMPLE SELECT GPV_STATUS(’INSTALLATION.ITEM1’);

Functions Reference
9.11.17 GPV_VALUE
SYNTAX GPV_VALUE(<item_name>, <reset>)

ARGUMENTS <item_name> A string expression containing the name of the item or
sub-item, including its section path.
<reset> A numeric expression resulting in a zero or non-zero
value.
OUTPUT A number containing the value of the process variable.
SEMANTICS The non-group GPV_VALUE returns the value of the specified process
variable. The process variable is reset to zero after the read when reset
contains a non-zero value. The result is of an integer data type when the
process variable has a representation of the type (U)BYTE, (U)SHORT,
(U)LONG or BOOLEAN. The result is a real when the process variable
representation is FLOAT or DOUBLE.
Be very careful when using the reset parameter. This flag is intended to
reset counter values when running daily or shift based reports. When this
function is simply used to read the value, always set this flag to 0.
EXAMPLE SELECT GPV_VALUE(’INSTALLATION.ITEM1’, 0);

Reference Functions
9.11.18 LENGTH
SYNTAX LENGTH(<string>)
ARGUMENTS <string> A string expression.
OUTPUT An integer containing the length of the string.
SEMANTICS The non-group LENGTH function returns the length of the supplied
string.
NOTES None
EXAMPLE SELECT LENGTH(field_1) FROM test;

Functions Reference
9.11.19 LINE
SYNTAX LINE(<count>)
ARGUMENTS <count> A numeric expression.
OUTPUT A string containing one or more ‘-’ characters.
SEMANTICS The non-group LINE function returns a string containing as many ‘-’
characters as specified by count. However, the maximum length of the
generated string is the current line width minus the line margins
(@WIDTH - @LEFT_MARGIN - @RIGHT_MARGIN). This will also
be the length of the string when a count less than 1 is specified.
NOTES The function DRAW(<count>, ’-’) produces the same output as
LINE(<count>).
EXAMPLE HEADER @DATE LEFT AS ’\Date DD-MMM-YY’,
@PAGE RIGHT AS ’Page 09’ SKIP 1,
LINE(0) skip 2;

Reference Functions
9.11.20 LOGBOOK_TEXT
SYNTAX LOGBOOK_TEXT(<report_name>)
ARGUMENTS <report_name> A string expression resulting in a report name.
OUTPUT A string which contains the contents of the logbook of the specified
report.
SEMANTICS The non-group LOGBOOK_TEXT reads the contents of the logbook of
the specified report and returns it as a string.
Using this function the contents of a logbook can be included in the
report for example.
NOTES The length of the string returned has a maximum of 511 characters.
EXAMPLE SELECT LOGBOOK_TEXT(’my_report’);

Functions Reference
9.11.21 LOWER
SYNTAX LOWER(<string>)
OUTPUT A string with only lower case characters.
SEMANTICS The non-group LOWER function returns a string equal to the supplied
string, but all upper case characters of the supplied string have been
converted to lower case characters.
NOTES None
EXAMPLE SELECT LOWER(field_1) FROM test;

Reference Functions
9.11.22 MAX
SYNTAX MAX([DISTINCT]<value>)
compared.
OUTPUT The maximum of all records of the specified expression. The output will
always be of type real.
SEMANTICS The group MAX function outputs a real containing the maximum for all
DISTINCT is specified, only those values different to the previous
record are compared.
NOTES None
EXAMPLE SELECT MAX(field_1 + field_2 / 4) FROM test;

Functions Reference
9.11.23 MIN
SYNTAX MIN([DISTINCT]<value>)
compared.
OUTPUT The minimum of all records of the specified expression. The output will
SEMANTICS The group MIN function outputs a real containing the minimum for all
DISTINCT is specified, only those values different to the previous
record are compared.
NOTES None
EXAMPLE SELECT MIN(field_1 + field_2 / 4) FROM test;

Reference Functions
9.11.24 MONTH_DAYS
SYNTAX MONTH_DAYS(<date>)
since 1970 (LCT).
OUTPUT A number containing the number of days in the month.
SEMANTICS The non-group function MONTH_DAYS returns the number of days in
the month indicated by <date>. To obtain the length of the current
month, the pre-defined variable @DATE can be specified.
NOTES None
EXAMPLE SELECT MONTH_DAYS(@DATE);

Functions Reference
9.11.25 NUMBER
SYNTAX NUMBER(<string>)
OUTPUT An integer or real.
SEMANTICS The non-group NUMBER function converts a string containing a valid
number to a number.
NOTES Date notation is allowed. This function is useful to convert parameter
variables (which are always strings) to numbers.
EXAMPLE SELECT field_1 FROM test WHERE time = NUMBER(@P0);
SELECT NUMBER(’13-NOV-1990’);

Reference Functions
9.11.26 SPV_QUALITY
SYNTAX SPV_QUALITY(<item_name>, <value>)

ARGUMENTS <item_name> A string expression containing the name of the item
name or sub-item name including its section path.
<value> A numeric expression containing the new quality for the
process variable.
OUTPUT A number containing the quality code of the process variable prior to
setting it to the specified value.
SEMANTICS The non-group function SPV_QUALITY sets the quality code of the
specified process variable. The result contains the quality code of the
process variable prior to the modification.
EXAMPLE SELECT SPV_QUALITY(’INSTALLATION.ITEM1’, 12);

Functions Reference
9.11.27 SPV_STATUS
SYNTAX SPV_STATUS(<item_name>, <status>)

ARGUMENTS <item_name> A string expression containing the item name or
sub-item name including its section path.
<status> A numeric expression containing the new status (range
0-255) for the specified process variable.
OUTPUT A number containing the status of the process variable prior to
modifying it to the specified status.
SEMANTICS The non-group function SPV_STATUS forces the status of a process
variable to a certain value. The result of the function is the status prior
to the new status.
EXAMPLE SELECT SPV_STATUS(’INSTALLATION.ITEM1’, 9);

Reference Functions
9.11.28 SPV_VALUE
SYNTAX SPV_VALUE(<item_name>, <value>)

ARGUMENTS <item_name> A string expression containing the item name or
sub-item including its section path.
<value> A numeric expression containing the new value for the
process variable.
OUTPUT A number containing the value of the process variable prior to setting it
to the specified value.
SEMANTICS The non-group function SPV_VALUE sets the value of the specified
process variable.The result contains the value of the process variable
prior to the modification. It is of an integer data type when the process
variable has a representation of the type (U)BYTE, (U)SHORT,
(U)LONG or BOOLEAN. The result is a real when the process variable
representation is FLOAT or DOUBLE.
EXAMPLE SELECT SPV_VALUE(’INSTALLATION.ITEM1’, 12);

Functions Reference
9.11.29 STDDEV
SYNTAX STDDEV([DISTINCT]<value>)
ARGUMENTS <value> A numeric field expression.
OUTPUT A number containing the standard deviation.
SEMANTICS The group function STDDEV outputs a real containing the standard
deviation for all records of the supplied expression. NULL values are
ignored. When DISTINCT is specified, only those values different from
the previous record are taken in account. The formula used is based on
an n-1 (samples) calculation:
∑ ( xi – x )2
i=1
------------------------------
-
n–1
NOTES None
EXAMPLE SELECT STDDEV(value);

Reference Functions
9.11.30 SUBSTR
SYNTAX SUBSTR(<string>, <offset>, <length>)

<offset> A numeric expression which identifies the start of the
sub-string. Counting starts at 1 (one).
<length> A numeric expression which gives the number of
characters to take.
OUTPUT A string containing the sub-string pointed by <offset> with a length
<length>.
SEMANTICS The SUBSTR function has a string as input. From this string a sub-string
is extracted and returned to the called.
NOTES None
EXAMPLE SELECT SUBSTR(’This is my day’, 6, 2);

Functions Reference
9.11.31 SUM
SYNTAX SUM([DISTINCT]<value>)
summed.
OUTPUT The sum of all records of the specified expression. The output will
SEMANTICS The group SUM function outputs a real containing the sum of all records
of the supplied expression. NULL values are ignored. When DISTINCT
is specified only those values different from the previous record are
summed.
NOTES None
EXAMPLE SELECT SUM(field_1)/COUNT(field_1) FROM test;

Reference Functions
9.11.32 TO_GMT
SYNTAX TO_GMT(<date>)
since 1970 in LCT.
OUTPUT A number containing the number of seconds since 1970 in GMT.
SEMANTICS REPORT/FAST dates are always in LCT. The non-group function
TO_GMT converts an LCT date to GMT representation when GMT is
required.
NOTES None

Functions Reference
9.11.33 TO_INTEGER
SYNTAX TO_INTEGER(<value>)
ARGUMENTS <value> A real.
OUTPUT An integer value containing the truncated value of the supplied real.
SEMANTICS The non-group TO_INTEGER function outputs an integer containing
the truncated value of the supplied real expression.
NOTES None

Reference Functions
9.11.34 TO_LCT
SYNTAX TO_LCT(<date>)
since 1970 in GMT.
OUTPUT A number containing the number of seconds since 1970 in LCT.
SEMANTICS The non-group function TO_LCT converts a GMT date to LCT
representation.
NOTES None

Functions Reference
9.11.35 TO_REAL
SYNTAX TO_REAL (<value>)

ARGUMENTS <value> An integer.
OUTPUT A real value containing the value of the supplied integer.
SEMANTICS The non-group TO_REAL function outputs a real containing the value
of the supplied integer expression.
NOTES None

Reference Functions
9.11.36 UPPER
SYNTAX UPPER(<string>)
OUTPUT A string with only upper case characters.
SEMANTICS The non-group UPPER function returns a string equal to the supplied
string, but all lower case characters of the supplied string have been
converted to upper case characters.
NOTES None
EXAMPLE SELECT UPPER(field_1) FROM test;

9.11.37 VARIANCE
SYNTAX VARIANCE([DISTINCT]<value>)
ARGUMENTS <value> A numeric field expression.
OUTPUT A number containing the standard deviation.
SEMANTICS The group function VARIANCE outputs a real containing the variance
for all records of the supplied expression. NULL values are ignored.
When DISTINCT is specified only those values different from the
previous record are taken into account. The formula used is based on an
n-1 (samples) calculation:
∑ ( xi – x ) 2
i=1
------------------------------
-
n–1
NOTES None
EXAMPLE SELECT VARIANCE(value);
9.12 Statements
The RQL statements are described in the following subsections.

9.12.1 BREAK
SYNTAX BREAK [
{<column_name> | REPORT}
[SKIP <lines> | SKIP PAGE]
[{CALCULATE {SUM | AVG | MIN | MAX |
STDDEV | VARIANCE | COUNT}
<column_names>}..
[HEADING heading]]
];
ARGUMENTS <column_name> The alias name of the column to specify a
break for.
<lines> The number of empty lines to insert in the
output.
<column_names> The alias names of the columns to calculate.
SEMANTICS The BREAK statement specifies a column to break reports upon. It
affects the output of all the SELECT statements following the BREAK
statement. The column specified by the BREAK statement can be
referenced by the following SELECT statement via the column alias
(similar to referencing columns defined by the COLUMN statement). It
is not necessary for all columns named by the BREAK statement to be
referenced by following SELECT statements.
When the value of the specified column changes from one row to the
other, the action specified by the SKIP and/or CALCULATE statement
are taken. It is wise to sort the BREAK columns in the SELECT
statement using the ORDER BY clause.
When both SKIP and CALCULATE clauses are specified for a certain
break column, the specified calculations are output before the skip
action is executed. A number of lines can be skipped or the report can be
advanced to the next page using PAGE.
A BREAK statement without arguments clears all current defined
breaks.
NOTES Note that the calculation outputs a heading equal to the calculation
performed or equal to the specified heading. The result of the calculation
is lined up with the column involved in the calculation. Duplicate
column values for columns for which a break is specified are suppressed.
EXAMPLE BREAK a SKIP 1 CALCULATE SUM b;
BREAK c SKIP 1 CALCULATE AVG d;
SELECT department a, job b, name c, salary d FROM
employees ORDER BY department, job;

9.12.2 CLOSE
SYNTAX CLOSE <cursor_name>;

ARGUMENTS <cursor_name> The name of an open cursor
SEMANTICS The CLOSE statement closes an open cursor releasing all system
resources occupied by the open cursor. When closed it can be re-opened
by the OPEN statement positioning the fetch pointer to the first record.
NOTES None
EXAMPLE CLOSE @units;

9.12.3 COLUMN
SYNTAX COLUMN [
<column_name> [AT <column_position>]
[AS <format_specification>]
[HEADING <column_heading>]
];
ARGUMENTS <column_name> The alias name of the column to define.
<column_position> A numeric expression specifying the position
of the column.
<format_specification> A string containing the output format
specification.
<column_heading> A string expression containing the heading for
the column.
SEMANTICS The COLUMN statement specifies the appearance of a column in the
report. COLUMN statements are not required. REPORT/FAST uses
defaults for columns when no alias in the SELECT clause is specified.
Any number of COLUMN statements may be entered for different
columns. A COLUMN statement applying to the same column
overwrites the previous specification. A COLUMN statement without
any parameters clears all previously defined columns. The defined
columns can be referenced in the SELECT clause of the SELECT
statement as alias columns.
The <column_position> specifies the character position on a report line.
This position is relative to the left line margin. REPORT/FAST moves
columns to the right if such a column should overwrite a previous
column. If no <column_position> is specified, the column will be placed
after the previous one separated by one space.
The <format_specification> defines the appearance of each column
value for each row. When the <format_specification> is omitted, the
default format rules are applied: when the column is referenced by a
column in the SELECT clause which contains a single field
specification, and a default format is specified in the data dictionary for
that field, this format will be used. If the column does not contain a
single field specification or when there is no default format specified in
the data dictionary for the field, REPORT/FAST uses the default
formatting as already described.
The <column_heading> defines the heading for the column.

‘|’ characters in the <column_heading> will break the heading in parts

which are output below each other. When the <column_heading> is
omitted, the default heading rules are applied: when the column is
referenced by a column in the SELECT clause which contains a single
field specification and a default heading is specified in the data
dictionary for that field, this heading will be used. If the column does not
contain a single field specification or when there is no default heading
specified in the data dictionary for the field, REPORT/FAST does not
output a heading.
Each time a heading has to be output to the report, REPORT/FAST
evaluates the column_heading. Each time a row value has to be output,
REPORT/FAST evaluates the <format_specification>. The
<column_position> is evaluated once when output the heading the first
time.
NOTES None
EXAMPLE COLUMN time AS ’hh:mm’ HEADING ’Current|time’;
SELECT field_1 time FROM test;

9.12.4 COMMENT
SYNTAX /* <comment> */
ARGUMENTS <comment> The comment text
SEMANTICS The COMMENT statement is not a keyword. All text enclosed by ‘/*’
and ‘*/’ is ignored by REPORT/FAST.
NOTES A single comment may occupy more than a single line.
EXAMPLE /* Define the format for the column */
COLUMN time AS ’hh:mm’ HEADING ’Current|time’;
/* Do the output */
SELECT field_1 time FROM /* get the data from */ test;
/*
Comment including
more than
one
line
*/

9.12.5 DECLARE
SYNTAX DECLARE [
<cursor_name> IS SELECT ...
];
<cursor_name> The name of the cursor (a variable name)
which is associated with the SELECT
statement.
SEMANTICS The DECLARE statement declares a special type of RQL variable, a
cursor. The cursor is associated to the specified SELECT clause. The
SELECT clause is not executed. It will be initialized by opening the
cursor using the OPEN statement and rows can be read one by one via
the FETCH statement.
The SELECT clause may not contain the SET clause. The columns
defined by the BREAK and COLUMN statement are ignored when
referenced via the column alias. Column headings are not retrieved by
the FETCH statement.
The DECLARE statement without arguments closes all open cursors
and removes all declared cursors.
NOTES A cursor variable cannot be overwritten by the SET, DECLARE and
SELECT statements.
More than one cursor can be declared concurrently.
EXAMPLE DECLARE @units IS SELECT unit_df FROM unit_df;

9.12.6 DICTIONARY
SYNTAX DICTIONARY [<server_node>:]<dictionary_server_process>

[.[<dictionary_node>:]<dictionary_name>];
ARGUMENTS <server_node> The name of the node on which the
dictionary_server_process is running.
<dictionary_server_process>
The name of the dictionary server process.
<dictionary_node> The name of the node on which the data
dictionary resides.
<dictionary_name> A string containing the name of the data
dictionary file or the name of the dictionary
file. This file name must include the
complete path specification.
SEMANTICS The DICTIONARY statement specifies the data dictionary to be used
and the name of the server process capable of handling the dictionary.
REPORT/FAST uses this information to obtain information about data
sets and fields referenced in the SELECT statement. A DICTIONARY
statement overwrites any previous DICTIONARY statement.
The <server_node> is the name of the processor on which the server
process is active. If the <server_node> specification is omitted, the node
on which REPORT/FAST is running will be used.
The <dictionary_server_process> is the name of the process interfacing
REPORT/FAST with the dictionary. Note that this name is not optional.
The <dictionary_node> specifies the name of the node on which the data
dictionary resides. If omitted, the node on which the
<dictionary_server_process> is running will be used.
The <dictionary_name> specifies the name of the data dictionary file. A
string specifying the name is required when the file name includes
characters other than letters, digits and the underscore. The complete file
path is required. If omitted, the current value for the dictionary_name
will be maintained.
If the DICTIONARY statement is omitted REPORT/FAST uses
‘own_node:rpidic.own_node:’tls_data:tlsdic’’.
NOTES The DICTIONARY statement is normally used in the setup description.
EXAMPLE DICTIONARY sting:rpidic.rnd:’my_dic’;

9.12.7 EXIT
SYNTAX EXIT ;
ARGUMENTS None.
SEMANTICS The EXIT statement breaks the innermost loop in a query. If there is no
loop, the query itself is terminated.
NOTES None
EXAMPLE EXIT ;

9.12.8 FETCH
SYNTAX FETCH <cursor_name> INTO <variable_name>[,..];

ARGUMENTS <cursor_name The name of the cursor previously opened
by the OPEN statement.
<variable_name> The name of an existing variable.
SEMANTICS The FETCH statement returns data of the opened cursor row by row.
Thus, to return multiple rows the FETCH statement must be part of a
loop. The columns are returned in the specified variables. The number
of specified variables must be equal to the number of columns specified
by the SELECT clause of the DECLARE statement. The variable
@RQLCOUNT is set to zero when the FETCH did not return a row. It
is set to one when a row is returned.
NOTES None
EXAMPLE FETCH @units INTO @install, @unit, @status;

9.12.9 FLAG PAGE
SYNTAX FLAG PAGE [<flag_page_name>];

ARGUMENTS <flag_page_name> A string expression containing the name of
the flag page file.
SEMANTICS The FLAG PAGE statement specifies the name of the flag page file.
The flag page is output to the report before any other output. It is used
to identify the report easily when being browsed or printed. A FLAG
PAGE statement overwrites any previous FLAG PAGE statement.
The <flag_page_name> is a string expression containing the name of a
plain text file which is output to the report before any other output. The
string expression is evaluated at the moment the flag page has to be
output. If the name is omitted, no flag page will be output.
Specifying a flag page when a SELECT statement has been output has
no effect.
NOTES The FLAG PAGE statement is normally used in the set-up description
or it is the first statement in a report description.
EXAMPLE FLAG PAGE @P0;

9.12.10 FOOTER
SYNTAX FOOTER [
{<data>
[AT <position> | LEFT | CENTER | RIGHT]
[SKIP <lines>]}[,...]
];
ARGUMENTS <data> An expression defining a part for the footer.
<position> A numeric expression defining the position
of the footer part on a line.
<format_specification> A string expression specifying the
appearance of the data part.
<lines> A numeric expression specifying the
number of lines to skip before output the
next header part.
SEMANTICS The FOOTER statement specifies the appearance of the footer on each
report page.
The FOOTER statement overwrites any previous FOOTER statement.
One or more footer parts can be specified by a FOOTER statement. Each
part is separated by a comma. The number of parts is not limited.
A FOOTER statement without parameters clear the current FOOTER
specification. No footer will be output any more.
The footer will start on the line specified by the bottom margin.
The result of the <data> expression is output at the specified line
position using the specified format and a number of lines is skipped.
The <position> is relative to the left margin. If no <position> is
specified, the part will be output to the right of the previous footer part
or, if there is no previous footer part or if lines were skipped, LEFT is
assumed.
The <format_specification> specifies the appearance of the part. If
omitted, default formatting is used.
When <lines> is equal to 1, the next footer part will be output on the next
line. Any larger skip size will insert blank lines in front of the next footer
part. If the skip is omitted, the next footer part is output on the same line
as the previous footer part.
Expressions are always evaluated at the moment the footer has to be

output.
EXAMPLE FOOTER ’’ SKIP 1, @LINE(0) SKIP 1;

9.12.11 HEADER
SYNTAX HEADER [
{<data>
[AT <position> | LEFT | CENTER | RIGHT]
[SKIP <lines>]}[,...]
];
ARGUMENTS <data> An expression defining a part for the
header.
<position> A numeric expression defining the position
of the header part on a line.
<format_specification> A string expression specifying the
appearance of the data part.
<lines> A numeric expression specifying the
number of lines to skip before output the
next header part.
SEMANTICS The HEADER statement specifies the appearance of the header on each
report page.
The HEADER statement overwrites any previous HEADER statement.
One or more header parts can be specified by a HEADER statement.
Each part is separated by a comma. The number of parts is not limited.
A HEADER statement without parameters clear the current HEADER
specification. No header will be output any more.
The header will start on the line specified by the top margin.
The result of the <data> expression is output at the specified line
position using the specified format and a number of lines is skipped.
The <position> is relative to the left margin. If no <position> is
specified, the part will be output to the right of the previous header part
or, if there is no previous header part or if lines were skipped, LEFT is
assumed.
The <format_specification> specifies the appearance of the part. If
omitted, default formatting is used.
When <lines> is equal to 1, the next header part will be output on the
next line. Any larger skip size will insert blank lines in front of the next
header part. If the skip is omitted, the next header part is output on the
same line as the previous header part.

Expressions are always evaluated at the moment the header has to be

output.
NOTES None
EXAMPLE HEADER @CUSTOMER CENTER SKIP1,
@DATE LEFT AS ’Report date DD-MMM-YY’,
@PAGE RIGHT AS ’Page 09’ SKIP1,
LINE(0) LEFT SKIP 2;

9.12.12 IF-THEN-ELSE-ENDIF
SYNTAX IF <condition> [{{AND|OR} <condition>}..]

THEN <statements>
[ELSE <statements>]
ENDIF;
ARGUMENTS <condition> expression relational_operator expression
<statements> a list of any RQL statements
SEMANTICS When the total result of the IF condition is TRUE, the statements
specified between the THEN and ELSE clause are executed. If FALSE,
the statements between the ELSE and END IF clauses are executed
when the ELSE clause is specified.
The expression may be a numeric or string expression but must be of the
same type within a condition. Fields may not be referenced within the
expression. The LIKE operator is allowed.
The evaluation order of the AND/OR conditions may be modified by
enclosing it in parentheses.
NOTES None
EXAMPLE IF @status > 15 THEN
SELECT ...;
ELSE
SELECT ...;
ENDIF;

9.12.13 INCLUDE
SYNTAX INCLUDE {<report_name>} | {FILE <file_name>};

ARGUMENTS <report_name> A string expression containing the name of
the report to be included.
<file_name> A string expression containing the name of
the file to be included.
SEMANTICS The INCLUDE statement specifies a report description to be included
into the current report description as being a part of the current report
description.
The <report_name> specifies the name of a report to be included.
<file_name> is the name of a file containing a report description.
INCLUDE statements may be nested. The nesting limit depends on the
system on which REPORT/FAST is running.
NOTES Reports that have been included are not protected against modifications
via the user interface.
EXAMPLE INCLUDE ’weekly_report’;

9.12.14 LOGIN
SYNTAX LOGIN [<manager_node>:]

<manager_process_name>[,<priority>];
ARGUMENTS <manager_node> The name of the node on which the
REPORT/FAST manager is running.
<manager_process_name> The REPORT/FAST manager’s process
name.
<priority> A numeric expression specifying the
priority.
SEMANTICS The LOGIN statement makes the REPORT/FAST generator known to
the REPORT/FAST manager.
This statement is required in the set-up description to command the
initializing REPORT/FAST generator to log itself in at the manager and
to continue processing in background mode. If the statement is omitted
in the set-up description, the generator will go into interactive mode.
The priority specifies the lowest report priority this generator will
process. If omitted, zero will be used (no priority).
NOTES The LOGIN statement must be the last statement in the set-up
description and it is advised not to use this statement anywhere other
than in a set-up description.
EXAMPLE LOGIN rptman, 4;

9.12.15 LOOP - ENDLOOP
SYNTAX LOOP <statements> ENDLOOP;

ARGUMENTS <statements> Any RQL statement including the LOOP
statement.
SEMANTICS The LOOP statement allows loops within a report description. It is an
unconditional loop. However, in combination with the IF and EXIT
statement, a conditional loop can be constructed.
All the statements specified by the LOOP will be executed continuously
until the loop is exited by the EXIT statement.
NOTES None
EXAMPLE LOOP
SELECT ...;
IF @status > 55 THEN
EXIT;
ENDIF;
ENDLOOP;

9.12.16 OPEN
SYNTAX OPEN <cursor_name>;

ARGUMENTS <cursor_name> The name of the cursor previously declared
by the DECLARE statement.
SEMANTICS Before fetching rows by the FETCH statement, the cursor must be
opened. After the open, the first FETCH statement returns the first row.
Opening a not closed cursor implicitly closes the cursor and re-opens it
positioning the fetch pointer to the first row.
NOTES None
EXAMPLE OPEN @units;

9.12.17 QUIT
SYNTAX QUIT ;
ARGUMENTS None
SEMANTICS The QUIT statement is used to end the current report. It is not required
in report descriptions but required to exit REPORT/FAST while in
interactive mode.
NOTES None
EXAMPLE QUIT;

9.12.18 RECEIVE
SYNTAX RECEIVE [FROM [<node_name>:]<process_name>]

[CODE <message_code>]
[NO] PACKING
[TIMEOUT <time_out>]
[{<variable_name> AS
<format_specification>}[,..]];
ARGUMENTS <node_name> The name of the node on which the process is
active.
<process_name> The name of the process to receive a message
from.
<message_code> A numeric expression defining the message
code of the message to receive.
<time_out> A numeric expression defining the time to wait
before cancelling the receive.
<variable_name> The name of a variable.
<format_specification>A string expression containing an input format
specification.
SEMANTICS The RECEIVE statement enables the receive of a BUS/FAST message.
Both requests and replies are received.
When the RECEIVE statement is encountered, REPORT/FAST waits
until a BUS/FAST message is received. The received data is unpacked
into the specified variables.
The <node_name> and <process_name> specify the sender of the
message. Only messages from this process are accepted by
REPORT/FAST. If omitted, messages from any process are accepted.
The <message_code> specifies the code of the message to receive.
REPORT/FAST will only accept messages with the correct message
code. If omitted, messages with any code are accepted.
If PACKING is specified, the message layout must be according to the
FAST/TOOLS conventions (size, code, data).
The <time_out> specifies the number of seconds REPORT/FAST will
wait before cancelling the receive. The default is 30 seconds.
The received message is unpacked into the specified existing variables
using the specified format.

NOTES A <time_out> specification of 0 seconds specifies a ‘wait forever’. Be

very careful using a ‘wait forever’ because it can block the
REPORT/FAST generator permanently.
EXAMPLE SET @v1 0;
SET @v2 ’’;
RECEIVE FROM my_process NO PACKING @v1 AS ’I4’,
@v2 AS ’A16’;

9.12.19 SELECT
SYNTAX SELECT [DISTINCT] <column_expression>[,..]

[FROM <data_set_spec>[,..]]
[WHERE <condition> [{AND | OR <condition>}..]
[{ORDER BY {<column_reference> |
{field_specification}[,..] [ASC|DESC]} |
{GROUP BY <column_reference>[,..]
[HAVING condition]}];
ARGUMENTS <column_expression> [SET <variable_name>]
<field_group_expression>
[<column_alias>]
<data_set_spec> [<server_node>:]<data_set_name>
[.[<data_node>:]<data_name>][
<data_set_alias>]
<condition> <field_specification>
<relational_operator> <field_expression>
<column_reference> <column_alias> | <column_number>
<variable_name> The name of an existing variable.
<field_group_expression> An expression in which field specifications
and group functions are allowed.
<column_alias> A name of a column to reference columns
defined by the COLUMN or BREAK
statement or a name of a column to
reference alias columns defined by the
SELECT clause.
<column_number> The column in sequence specified by the
SELECT clause.
<server_node> The name of the node on which the process
interfacing between REPORT/FAST and
the data set resides.
<data_set_name> The name of the data set to access.
<data_node> The name of the node on which the data set
is actually located.
<data_name> A string containing the name of the data in
the data set to access.
<data_set_alias> The alias name for the specified data set.

<field_specification> A field specification.

<field_expression> An expression in which field specifications
are allowed.
<variable_name> The name of a user-defined variable.
SEMANTICS The SELECT statement specifies the data to appear in the report.
• SELECT clause:
The select clause specifies the columns to be output and the data in
the columns. If a <variable_name> is specified and no
<column_alias>, the variable will receive the column value and its
value will not be output to the report. However, if a <column_alias>
is specified, the value will also be output to the report. The
<field_group_expression> may contain field specifications and
group functions. However, when a <column_expression> contains
a group function, all other column expressions also require a group
function, unless the GROUP BY clause is specified. It is allowed to
specify an incomplete field specification as field expression.
REPORT/FAST will create columns for all fields belonging to the
incomplete field specification.
The <column_alias> is the name of a column previously defined by
the COLUMN statement. However, when it was not previously
defined, REPORT/FAST creates it temporarily. It will be removed
from the column list when the SELECT statement is completed. A
<column_alias> may only appear once in the SELECT clause and
may be referenced by the GROUP BY or ORDER BY clauses.
When DISTINCT is specified, the first row and the rows different
from the previous row are output to the report.
• FROM clause:
The FROM clause specifies the data sets containing the data for the
fields. It is allowed to specify more than a single data set. However,
when more than one data set is specified, a connection between
these sets must be specified in the WHERE clause. In such a case,
the first specified data set will be the primary one and all other are
related to the primary data set.
The alias can be used as a short cut in field specifications.
Normally a <data_set_name> specification without nodes and
<data_name> is sufficient. In such case, defaults are extracted from
the data dictionary to supply the missing attributes.
The FROM clause is optional. If omitted, REPORT/FAST will
output a single line containing the result of the column expressions.

• WHERE clause:
The WHERE clause specifies connections between data sets and
selections of data from the data sets. The WHERE clause is
required when more than a single data set is specified in the FROM
clause. Connections between data sets must be specified before
other selections. A connection is specified as:
<field_specification> = <field_specification>.
The latter field specification specifies the name of a field in the data
set to be connected. Note that both fields must be of a data set field
type which are connectable. The following connectable types are
available:
Char with char if of the same length;
structured field with structured field if of the same length;
union field with union field if of the same length;
BOOLEAN, SHORT, USHORT, LONG, LONG or UBYTE with
BOOLEAN, SHORT, USHORT, LONG, LONG or UBYTE and
FLOAT or DOUBLE with FLOAT or DOUBLE.
• ORDER BY clause:
The ORDER BY clause specifies how the result must be sorted. It
is followed by either a field_specification or column_reference that
indicates how to sort. The position is a number identifying the
position of the column in the SELECT clause (beginning with 1).
Optionally the ORDER BY clause can be followed by the key
words ASC - indicating ascending order - or DESC - descending
order. If omitted, the ordering is ascending.
• GROUP BY clause:
The GROUP BY clause allows you to group rows in the result and
the HAVING clause lets you apply search conditions to the rows
yielded by the GROUP BY clause.
The HAVING clause is used to restrict the results of the GROUP
BY clause, similar to the way in which the WHERE clause narrows
the focus on the SELECT clause, but it may also contain
aggregates.
When several data sets need to be connected, the connections must
be separated by the AND operator. For example:
SELECTa.field_1, b.field_2, c.field_1
FROM set a, set2 b, set3 c
WHERE a.field_5 = b.field_3 AND
a.field_3 = c.field_5;
Following the connections, selections may be specified. If no

selections are specified all data in the data set will be selected.
NOTES None
EXAMPLE SELECT 12*25;
SELECT field_1 from test
WHERE field_1 > 12 AND field_1 < 14;
SELECT 12*SUM(field_1) FROM test;

9.12.20 SEND
SYNTAX SEND [<node_name>:]<process_name>

[REPLY]
[CODE <message_code>]
[NO] PACKING
[{<data> AS <format_specification>}[,..]];
ARGUMENTS <node_name> The name of the node on which the process
is active.
<process_name> The name of the process to send a message
to.
<message_code> A numeric expression defining the message
code of the message to send.
<data> An expression containing the data to send.
<format_specification> A string expression containing an output
format specification.
SEMANTICS The SEND statement enables the send of a BUS/FAST message.
When the SEND statement is encountered, REPORT/FAST sends the
specified BUS/FAST message and continues processing the report
description.
The <node_name> and <process_name> specify the destination of the
message.
The <message_code> specifies the code of the message to send. If
omitted, the code will be the same as used in a previous send. If there is
no previous send, it will have an arbitrary value.
If PACKING is specified, the message layout will be according to the
FAST/TOOLS conventions (size, code, data). NO PACKING allows
messages with a non-standard layout.
The specified data is packed in the sender buffer using the specified
format. When the packing is completed, the message is sent.
NOTES None
EXAMPLE SEND my_process CODE 12 PACKING
25.3 AS ’F4’, ’test’ AS ’A4’;

9.12.21 SET
SYNTAX SET <variable_name> <value>;

ARGUMENTS <variable_name> The name of a variable to give a value.
<value> An expression containing the value for the variable.
SEMANTICS The SET statement specifies variables to use elsewhere in the report
description.
The <variable_name> is the name of a non-existing or existing variable.
In the latter case the current value of the variable will be overwritten by
the new value. The data type of the variable will become equal to the
data type of the value.
NOTES Some of the pre-defined variables can not be overwritten by the SET
statement.
EXAMPLE SET @v 1;
SET @v @v+1;

9.12.22 SHOW
SYNTAX SHOW [FULL] {BREAKS | COLUMN | CURSOR |

FOOTER | HEADER | RESERVED | RESOURCES
| STAT | VARS | WORKSPACE | *};
ARGUMENTS None
SEMANTICS The SHOW statement shows current defined columns, headers, footers,
etc. More technical information can be shown using STAT (statistics)
and WORKSPACE.
• BREAKS
The BREAKS clause shows all defined breaks (defined by the
BREAK statement). It shows the columns and/or report for which
breaks are defined, including the related calculations and defined
heading.
• COLUMN
The COLUMN clause shows all defined columns (defined by the
COLUMN statement). It shows the position, heading, etc.
• CURSOR
The CURSOR clause shows all declared cursors (declared by the
DECLARE statement). The status (open or closed) of the cursor is
shown, its related SELECT clause and the number of records read
so far.
• FOOTER
The FOOTER clause shows the defined FOOTER (defined by the
FOOTER statement) and its layout.
• HEADER
The HEADER clause shows the defined HEADER (defined by the
HEADER statement) and its layout.
• RESERVED
The RESERVED clause shows all REPORT/FAST reserved
words. When a data set contains a field with a name which is one of
the REPORT/FAST reserved words, the field name must be
specified surrounded by double quotes.
• RESOURCES
The RESOURCES clause shows the resources taken by the
REPORT/FAST generator so far. It includes CPU time and disk
accesses. This clause is not available on all platforms.
• STAT
The STAT clause shows some technical information.
• VARS
The VARS clause shows all defined variables and their value.

• WORKSPACE
The WORKSPACE show the available workspace.
The * shows all. The SHOW statement without the FULL clause shows
global information. Specifying the FULL clause shows detailed
information.
NOTES None
EXAMPLE SHOW VARS;

9.12.23 SPOOL
SYNTAX SPOOL [<file_name>];

ARGUMENTS <file_name> A string expression containing the name of
the file to direct the report result to.
SEMANTICS Using the SPOOL statement, the report output can be copied to any file.
If the specified file exists, it will be overwritten. The specified file is
created when the SPOOL statement is encountered.
NOTES REPORT/FAST has no knowledge about the files created with the
SPOOL statement, which means that they cannot be deleted
automatically.
The maximum file name length used in the SPOOL statement is 79
characters.
A SPOOL statement without an argument closes the current spool file if

any.
EXAMPLE SPOOL ’tls_data:my_file.out’;

Introduction DSS data sets
10 DSS data sets
10.1 Introduction
This chapter explains how DSS data sets can be used in a
REPORT/FAST query. It will explain how queries on the new DSS data
set, differ from those on ISAM data sets.
10.2 What’s the difference between DSS data

sets and ISAM data sets?
The main difference is in the way data is organised in a data set record.
In an ISAM record data is organized in a structured way where record
can be divided in sub records.
field 1
field 2
field 5
field 7 field 8
Figure 10-1 A typical ISAM record
Figure 10-1 shows that a typical ISAM record where fields can be
divided into sub-fields.
Field 1 Field 2 Field 3 Field 4 Field 5
Figure 10-2 A typical DSS dataset
Figure 10-2 shows a DSS record with a flat structure. DSS data sets are
organised in a tabular form where fields don’t have sub -fields.
Reading a record from an ISAM dataset returns a complex data
structure, reading a DSS record returns one dimensional list.
In ISAM dataset a key field can have sub fields that together form the

DSS data sets Configuration for DSS queries
key. In an DSS data set keys are simple one dimensional fields.
All this has consequences for the way REPORT/FAST queries are
organized. It also means you can’t use DSS data sets and ISAM data sets
in the same query. Other important differences are:
• DSS field set don’t use field separators to indicate sub-fields.
• DSS introduces many new data sets that are not available in DSS.
• DSS and ISAM data sets that share the same name can contain
different fields.
10.3 Configuration for DSS queries

REPORT/FAST uses two so-called info-servers to access DSS data sets.
Before you can use DSS data sets in a REPORT/FAST query you must
tell REPORT/FAST to use these info servers instead of the ISAM info
server. The DSS info-server is used by inserting the following line as the
first line of your report:
DICTIONARY rpidis.’tlsdic’
This will tell the report generator to use the DSS info-server. Note that
this is the default data dictionary used by REPORT/FAST so it is not
necessary to supply this line at the start of every report. If you want to
use the old ISAM data dictionary and the data sets as defined by DDL
then you must insert the following line as the first line in your report:
DICTIONARY rpidic.’tlsdic’
10.4 Using DSS queries

The difference in data set record structure between ISAM and DSS data
sets is reflected in the REPORT/FAST queries. The most important
thing too keep in mind is that although ISAM and DSS data set may use
the same names for a data set they often contain different fields. For
example both ISAM and DSS have a data set called item_df that
contains information about items. They both contain item related data
but their field layout is different.
To get information about fields in a DSS data set you can look in their
definition file in the FAST/TOOLS source directory (/tls/src). DSS
definition files can be found by their extension (.dss).

Concealed dataset fields DSS data sets
The DSS data set are implemented as simple 2 dimensional (flat) tables.
This means all fields can be reached directly and don’t have to be
addressed as a sub-field of a composed record. For example, to get to the
field ‘UNIT’ from the ISAM data set ‘UNIT_DF’ you would have to use
the following query.
select unit.unit from unit_df;
Since the field ‘UNIT’ is included in of the record ‘UNIT’ you have to
tell the report generator you want the unit field from the record ‘unit’.
When you use the DSS data sets there are no field records that include
other fields so you can use the query:
select unit from unit_df;
The only time you need to use the dot (.) operator in DSS queries is when
you use fields from different data sets in single query. Example:
SELECT install, unit, unit_df.name

FROM unit_df, status_df
WHERE unit_df.status = status_df.status_number;
Here you have a join of two different data sets. The dot operator is used
the tell the report generator which field to take from which data set.
10.5 Concealed dataset fields

Depending on the FAST/TOOLS configuration some data set fields may
have no function. These fields are then marked as 'Concealed' by DSS.
By default these concealed fields are not available in REPORT/FAST
queries.
If required there fields can be made available by setting the
@CONCEAL variable to 0.

DSS data sets Concealed dataset fields

Draw a graph from historical data
Appendix A:
A.1 Draw a graph from historical data

The following query provides an example of the DRAW function by
obtaining history for two variables and presenting them graphically. The
items to compare are supplied as the first and second parameters to the
report. The units they represent is supplied as the third parameter and
used in the summary at the bottom of the report. Note that parameters
are numbered starting from zero.
SET @first_item @p0;

SET @second_item @p1;
SET @item_val1 0;
SET @item_val2 0;
SET @curr_sample 0;
SET @next_sample 60;
SET @head1 'Legend: 1: ' || @first_item;

SET @head2 ' 2: ' || @second_item;
SET @head3 ' ' || '|' || ' 0% 10% 20% 30% 40%
50% 60% 70% 80% 90% 100% ';
SET @now @date;

SET @max_val 0;
SET @max_val1 0;
SET @max_val2 0;
SET @graph_val '';
COLUMN s_time AS 'hh:mm:ss' HEADING 'Time';

COLUMN val1 AS '999.9' HEADING @head1;
COLUMN val2 AS '999.9' HEADING @head2;
COLUMN graph HEADING @head3;
SELECT SET @max_val1 MAX(item_value)

FROM item_history
WHERE group_name='FIVE_SECONDS' AND
item_name = @first_item AND
sample_time > @now-@next_sample AND interval_time = 5;
SELECT SET @max_val2 MAX(item_value)

FROM item_history
item_name = @second_item AND
sample_time > @now-@next_sample AND interval_time = 5;
IF @max_val1 > @max_val2 THEN

SET @max_val @max_val1;
ELSE
SET @max_val @max_val2;
ENDIF;
REPORT/FAST Language Manual A-1

Examples Draw a graph from historical data
SET @corr 42/@max_val;
SELECT @head1;
SELECT @head2;
SELECT ' ';
SELECT @head3;
LOOP
SELECT SET @curr_sample sample_time, SET @item_val1 item_value
FROM item_history
item_name = @first_item AND
sample_time = @now-@next_sample AND interval_time = 5;
SELECT SET @curr_sample sample_time, SET @item_val2 item_value

FROM item_history
item_name = @second_item AND
sample_time = @now-@next_sample AND interval_time = 5;
SELECT @curr_sample s_time, @item_val1 val1, @item_val2 val2,

DRAW(@item_val1*@corr + 2, '1',
DRAW(@item_val2*@corr + 2, '2', '| . . . . . . . . . . . . . . .
. . . . . . |')) ;
SET @next_sample @next_sample - 5;
IF @next_sample < 0 THEN

EXIT;
ENDIF;
ENDLOOP;
SELECT ' ';
SELECT '100% =', @max_val, @p2;
Below is an example of the generated report:
Legend: 1: INST.UNIT.ITEM_001
2: INST.UNIT.ITEM_005
| 0% 10% 20% 30% 40% 50% 60% 70% 80% 90% 100%
14:39:51 88.0 78.0 | . . . . . . . . . . . . . . . . . . 2 . .1|
14:39:56 1.0 83.0 |1. . . . . . . . . . . . . . . . . . . 2 . |
14:40:01 6.0 88.0 | .1. . . . . . . . . . . . . . . . . . . .2|
14:40:06 11.0 1.0 |2. . 1 . . . . . . . . . . . . . . . . . . |
14:40:11 16.0 6.0 | .2. . 1 . . . . . . . . . . . . . . . . . |
14:40:16 21.0 11.0 | . . 2 . .1. . . . . . . . . . . . . . . . |
14:40:21 26.0 16.0 | . . . 2 . .1. . . . . . . . . . . . . . . |
14:40:26 31.0 21.0 | . . . . .2. .1. . . . . . . . . . . . . . |
14:40:31 36.0 26.0 | . . . . . .2. . 1 . . . . . . . . . . . . |
14:40:36 41.0 31.0 | . . . . . . .2. . 1 . . . . . . . . . . . |
14:40:41 45.0 35.0 | . . . . . . . .2. . 1 . . . . . . . . . . |
14:40:46 51.0 41.0 | . . . . . . . . . 2 . .1. . . . . . . . . |
14:40:51 56.0 46.0 | . . . . . . . . . . 2 . .1. . . . . . . . |
100% = 88 Ticks
A-2 REPORT/FAST Language Manual

Report the current alarms Examples
A.2 Report the current alarms

The following query reports the current alarms:
HEADER 'Report showing the current alarms'

CENTER SKIP 1, @DATE LEFT AS '\Date DD-MMM-YYYY',
@PAGE RIGHT AS 'Page 99' SKIP 1, LINE(0) SKIP 2;
COLUMN time as 'DD-MMM-YY hh:mm:ss';

COLUMN item_name as 'A48';
SELECT alarm_time time, item_name item_name, alarm_text

FROM alarm_current;
Below is an example of the generated report.
Alarm time Item name Alarm text

=============== ============================= ==============
26-OCT-06 15:01:41 INST.UNIT.ITEM_008 low low
26-OCT-06 15:01:42 INST.UNIT.ITEM_005 low
A.3 Building your own queries

All data to be reported is retrieved from data sets specified in the FROM
clause of the SELECT statement. Therefore the layout of the records in
the data sets must be known. This record layout is defined in the DSS
files (Data Set Services) files located on the source folder of the FAST/
TOOLS installation directory. These files have the extension ‘.dss’.
The available data sets can be also be browsed from a drop down menu
by pressing ‘CTRL-<SPACE>’ while in the query window of the report
definition. As well as displaying the allowed keywords and symbols of
the RQL language, it is possible to select ‘Datasets’ from the menu.
After highlighting a dataset in the list the fields belonging to the dataset
can be browsed by selecting ‘Fields of dataset...’ from the menu. This
mechanism avoids having to inspect the DSS files manually when
building RQL queries.
REPORT/FAST Language Manual A-3

Examples Building your own queries
A-4 REPORT/FAST Language Manual

Index
Index
Symbols [ 9-15
] 9-15
!= 3-5, 9-14 _ 3-6
% 3-6 || 9-14
() 9-14
* 6-1, 9-14
*/ 9-64
A
+ 6-1, 9-14 ABS function 6-7, 9-23, 9-55, 9-57
/ 6-1, 9-14 ad hoc query 1-3
/* 9-64 ADD_MONTHS function 6-7, 9-24
< 3-5, 9-14 addition operator 6-1
<= 3-5, 9-14 advance to
<> 3-5, 9-14 next line 9-33
= 3-5, 9-14 next page 9-33
> 3-5, 9-14 alias names 3-10
>= 3-5, 9-14 AND operator 3-6, 5-1, 9-14
@BOTTOM_MARGIN 6-9, 9-4, 9-5 Ann special format 7-2
@CUSTOMER 6-9, 9-5 arguments 1-2
@DATE 6-9, 9-5 arithmetic operations 3-2
@DECIMAL 6-9, 9-5 arithmetic operators 6-1
@DESCRIPTION 6-9, 9-9 array field 9-15
@EXPORT 6-10, 9-5 AS format specification 4-7
@FORMFEED 9-6 ASC 3-8
@GEN_TIME 9-6 ASCII(DELIMITED) 6-10, 9-5
@LEFT_MARGIN 6-9, 9-6, 9-36, 9-41 ASCII_FILE function 9-25
@LINE 9-6 AT format specification 4-7
@NAME 6-9, 9-9 AVG function 6-4, 9-26
@NEXT 9-6
@P0 6-9 B
@P0 to @P7 6-9, 9-9 background generator 1-3
@PAGE 6-9, 9-7 BAND function 9-27
@PAGE_SIZE 6-9, 9-7 basic query elements 3-1
@RIGHT_MARGIN 6-9, 9-7, 9-36, 9- binary representation 7-2
41 BNOT function 9-28
@RQLCOUNT 5-3, 5-5, 9-7 BOR function 9-29
@RQLERROR 5-3, 5-5, 9-7 bottom margin 4-5
@SORTSPACE 6-10, 9-7 BREAK statement 4-8, 9-60
@TIME 9-8 BSHIFT function 9-30
@TOP_MARGIN 6-9, 9-8 BXOR function 9-31
@VERSION 9-8
@WC_ANY 6-11, 9-9 C
@WC_SINGLE 6-11, 9-9 calculations 9-13
@WIDTH 6-9, 9-8, 9-36, 9-41 char field type 9-4
@WORKSPACE 6-10, 9-8 CHAR function 6-7, 9-32
REPORT/FAST Language Manual 1

Index
CHR function 6-7, 9-33 database file 2-2

clause date and time, current 6-3
FROM 3-1 date representation 4-4
GROUP BY 3-8, 9-7 DDL compiler 2-5
HAVING 3-8 DECLARE statement 5-3, 9-65
ORDER BY 3-7 DECODE function 6-6, 9-35
SELECT 3-1 DESC 3-8
SORT BY 9-7 description set-up 1-5
WHERE 3-4 dictionary 2-4
CLOSE statement 5-3, 9-61 default data set block 2-4
column definition 2-5
date 4-3 name 2-4
heading 4-1 name server 2-4
justification 4-4 node location 2-4
position 4-2 record layout 2-4
COLUMN statement 4-1, 9-62, 9-78 DICTIONARY statement 8-1, 9-66
command generation 8-2 DISTINCT 3-3, 6-4
comment statement 9-64 division operator 6-1
communications 7-1 DOUBLE field type 9-4
concatenate operator 6-3 DRAW function 6-7, 9-36
condition duplicate rows, DISTINCT 3-3
IF 5-1
join 3-10 E
conditional execution 5-1 EDIT 1-3
conditional operators 9-14 ELSE 5-1
conditions 3-4 ENDIF 5-1
connecting data sets 3-7 ENDLOOP 5-2
connecting several conditions 3-6 equal to 3-5
constants 3-5 error
conventions 9-1 execute 1-5
conversion to binary representation 7-2 statement 1-5
conversion to integer/real 7-3 error logging device 1-5
COUNT function 6-4, 9-34 errors 9-16
current date and time 6-3 execute errors 1-5
cursors EXIT statement 5-2, 9-67
CLOSE 5-3 expression 3-2
DECLARE 5-3
FETCH 5-3 F
OPEN 5-3
F4 special format 7-2
F8 special format 7-2
D FETCH statement 5-3, 9-7, 9-68
data block identification 2-2 field 2-1
data dictionaries 2-1, 2-4 field specification 3-10
data dictionary ’rptdic’ 8-1 field types
data manipulation 6-3 BOOLEAN 9-4
data set block 2-2 char 9-4
data set definition 2-5 DOUBLE 9-4
data sets 1-1, 2-1 FLOAT 9-4
data types 9-3 LONG 9-4
2 REPORT/FAST Language Manual

Index
SHORT 9-4 SPV_VALUE 6-7

UBYTE 9-4 STDDEV 6-4, 9-51
ULONG 9-4 SUBSTR 9-52
USHORT 9-4 SUM 6-4, 9-53
flag page 4-8 TO_GMT 6-7, 9-54
FLAG PAGE statement 9-69 TO_LCT 6-7, 9-56
FLOAT field type 9-4 UPPER 6-7, 9-58
footer 1-5, 4-6 VARIANCE 6-4, 9-59
FOOTER statement 9-70
format specification 4-3, 9-9 G
AS 4-7 general layout 4-4
AT 4-7 generate commands 8-2
SKIP 4-7 GMT 9-54, 9-56
formatting GPV_QUALITY function 9-37
integer data types 9-10 GPV_STATUS function 6-7, 9-38
real data types 9-11 GPV_VALUE function 6-7, 9-39
string data types 9-12 greater than 3-5
formatting the report 4-1 greater than or equal to 3-5
FROM clause 3-1 GROUP BY clause 3-8, 9-7
functions 3-2, 6-3 group functions 6-4
ABS 6-7, 9-23, 9-55, 9-57
ADD_MONTHS 6-7, 9-24 H
ASCII_FILE 9-25
AVG 6-4, 9-26 HAVING clause 3-8
BAND 9-27 header 1-5, 4-6
header fragment 4-7
BNOT 9-28
BOR 9-29 HEADER statement 9-72
BSHIFT 9-30 heading, column 4-1
BXOR 9-31
CHAR 6-7, 9-32 I
CHR 6-7, 9-33 I1 special format 7-2
COUNT 6-4, 9-34 I2 special format 7-2
DECODE 6-6, 9-35 I4 special format 7-2
DRAW 6-7, 9-36 IF statement 5-1, 9-74
GPV_QUALITY 6-7, 9-37 INCLUDE statement 8-1, 9-75
GPV_STATUS 6-7, 9-38 Including reports 8-1
GPV_VALUE 6-7, 9-39 indexed field 9-15
group 6-4 input formats 7-3
LENGTH 6-6, 9-40 integer 9-3
LINE 6-7, 9-41 interactive mode 8-3
LOGBOOK_TEXT 9-42 interactive session 1-3
LOWER 6-7, 9-43
MAX 6-4, 9-44 J
MIN 6-4, 9-45 joins 3-9
MONTH_DAYS 6-7, 9-46 justification, left/right/centered 4-4
non-group 6-5
NUMBER 6-6, 9-47 K
SPV_QUALITY 6-7, 9-48
key field 2-4
SPV_STATUS 6-7, 9-49, 9-50 KEYWORD 1-2

Index
L concatenate 6-3
conditional 9-14
LCT 9-24, 9-46, 9-54, 9-56 devision 6-1
left margin 4-6 LIKE 3-6, 9-14
LENGTH function 6-5, 9-40 logical 9-14
less than 3-5 multiplication 6-1
less than or equal to 3-5 OR 3-6, 9-15
LIKE operator 3-6, 9-14 relational 3-4
LINE function 6-7, 9-41 substraction 6-1
LOGBOOK_TEXT function 9-42 value 9-14
logging in 8-2 OR operator 3-6, 5-1, 9-15
logical operators 9-14 ORDER BY clause 3-7
LOGIN statement 8-2, 9-76
LOOP statement 5-2, 9-77
LOWER function 6-6, 6-7, 9-43
P
page layouts 1-5
M page size 4-5
page width 4-5
manipulate data 3-2 priority level 8-2
manipulation of data 6-3
margin
bottom 4-5
Q
left 4-6 queries 3-1
right 4-6 query ad hoc 1-3
top 4-5 query language 1-1
MAX function 6-4, 9-44 query result 4-6
message passing facilities 7-1 QUIT statement 1-4, 8-3, 9-79
MIN function 6-4, 9-45
MONTH_DAYS function 6-7, 9-46 R
multi dimensional array field 9-15 real 9-3
multiplication operator 6-1 RECEIVE statement 7-3, 9-80
receiving data 7-3
N record 2-1
naming conventions 9-1 alias field 2-3
narrowing the query 3-4 format 2-3
nesting 5-2 name 2-3
next line 9-33 type 2-3
next page 9-33 value 2-3
non-group function 6-5 record layout 2-3
non-key field 2-4 relational operators 3-4
not equal to 3-5 report description 1-2
NUMBER function 6-6, 9-47 ending 8-3
numeric constant 3-5 REPORT/FAST generator 8-2
REPORT/FAST manager 8-2
O REPORT/FAST Query Language
(RQL) 1-1
OPEN statement 5-3
reserved words 9-2
operator
result table 3-1
addition 6-1
right margin 4-6
AND 3-6, 9-14
row-by-row operation 5-3
arithmetic 6-1
RQL 1-1, 6-1

Index
RQL reference 9-1 LOGIN 8-2, 9-76

RQL statements 1-2 LOOP 5-2, 9-77
rules formatting 9-9 OPEN 5-3, 9-78
QUIT 8-3, 9-79
S RECEIVE 7-3, 9-80
SELECT clause 3-1 SELECT 9-7, 9-82
SELECT statement 9-7, 9-82 SEND 7-1, 9-86
selecting a dictionary 8-1 SET 4-6, 6-8, 6-10, 9-87
SEND statement 7-1, 9-86 SHOW 4-8, 8-3, 9-2, 9-88
sending data 7-1 SPOOL 6-10, 9-90
server 2-2 statements RQL 1-2
SET statement 4-6, 6-8, 6-10, 9-87 STDDEV function 6-4, 9-51
sets data 1-1 string 4-3, 9-3
set-up description 1-5 SUBSTR function 9-52
SHOW statement 4-8, 8-3, 9-2, 9-88 subtraction operator 6-1
showing status 8-3 SUM function 6-4, 9-53
SKIP format specification 4-7
sort T
ASC 3-8 THEN 5-1
DESC 3-8 time representation 4-4
SORT BY clause 9-7 tlsdic 8-1
special formats TO_GMT function 6-7, 9-54
Ann 7-2 TO_LCT function 6-7, 9-56
F4 7-2 top margin 4-5
F8 7-2 type conversion 9-4
I1 7-2
I2 7-2 U
I4 7-2 UPPER expression, example 6-3
SPOOL statement 6-10, 9-90 UPPER function 6-7, 9-58
SPV_QUALITY function 6-7, 9-48
SPV_STATUS function 6-7, 9-49 V
SPV_VALUE function 6-7, 9-50
value operators 9-14
SQL 1-1
variable
statement errors 1-5
@WC_ANY 6-11, 9-9
statements
@WC_SINGLE 6-11, 9-9
BREAK 4-8, 9-60
variables 6-8
CLOSE 5-3, 9-61
@BOTTOM_MARGIN 6-9, 9-4, 9-
COLUMN 4-1, 9-62
5
COMMENT 9-64
@CUSTOMER 6-9, 9-5
comment 9-64
@DATE 6-9, 9-5
DECLARE 5-3, 9-65
@DECIMAL 6-9, 9-5
DICTIONARY 8-1, 9-66
@DESCRIPTION 6-9, 9-9
EXIT 5-2, 9-67
@EXPORT 6-10, 9-5
FETCH 5-3, 9-7, 9-68
@FORMFEED 9-6
FLAG PAGE 9-69
@GEN_TIME 9-6
FOOTER 4-6, 9-70
@LEFT_MARGIN 6-9, 9-6
HEADER 4-6, 9-72
@LINE 9-6
IF 5-1, 9-74
@NAME 6-9, 9-9
INCLUDE 8-1, 9-75
@NEXT 9-6

Index
@P0 to @P7 9-9

@P0-@P7 6-9
@PAGE 6-9, 9-7
@PAGE_SIZE 6-9, 9-7
@RIGHT_MARGIN 6-9, 9-7
@RQLCOUNT 5-3, 5-5, 9-7
@RQLERROR 5-3, 5-5, 9-7
@SORTSPACE 6-10, 9-7
@TIME 9-8
@TOP_MARGIN 6-9, 9-8
@VERSION 9-8
@WIDTH 6-9, 9-8
@WORKSPACE 6-10, 9-8
VARIANCE function 6-4, 9-59
W
WHERE clause 3-4

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Manual TLSCMDX Language
Manual
IM 50D6D00N-E/R10.03

IM 50D6D00N-E/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
0.5 Conventions and Abbreviations .................................0-2
1 General ..................................................................................1-1
1.1 Introduction ...............................................................1-1
1.2 General features of TLSCMDX ................................1-1
1.3 Basic structure of the query language ........................1-1
1.3.1 Commands ................................................................ 1-1
1.3.2 Arguments ................................................................. 1-2
1.3.3 Comment ................................................................... 1-2
1.3.4 Predefined variables .................................................. 1-2
1.3.5 Foreign commands .................................................... 1-3
1.4 Basic mechanisms ......................................................1-3
1.4.1 The query mechanism ............................................... 1-3
1.4.2 The validation mechanism ........................................ 1-4
1.4.3 The value database .................................................... 1-4
1.4.4 The text generation mechanism ................................ 1-5
1.4.5 Flow control primitives. ............................................ 1-5
1.4.6 Variable substitution ................................................. 1-6
1.5 FAST/TOOLS Installation ........................................1-7
1.5.1 Creating the environment and spreading files .......... 1-8
1.5.2 Licensing ................................................................... 1-8
1.5.3 Configuring the tools ................................................ 1-8
1.6 FAST/TOOLS configurator .......................................1-8
2 Reference ...............................................................................2-1
2.1 Introduction ...............................................................2-1
2.2 Commands .................................................................2-1
2.2.1 The assignment command ........................................ 2-2
2.2.2 The check command ................................................. 2-3
2.2.3 The declare command ............................................... 2-6
2.2.4 The exist command ................................................... 2-7
2.2.5 The exit command .................................................... 2-8
2.2.6 The gosub command ................................................. 2-9
2.2.7 The goto command ................................................. 2-10
2.2.8 The conditional if statements .................................. 2-11
2.2.9 BUS/FAST license check ....................................... 2-13
2.2.10 Non BUS/FAST license check. .............................. 2-14
FAST/TOOLS TLSCMDX Language Manual iii

2.2.11 The load command .................................................. 2-15
2.2.12 The on_error command ........................................... 2-16
2.2.13 The on_interrupt command ..................................... 2-17
2.2.14 The return command ............................................... 2-18
2.2.15 The save command .................................................. 2-19
2.2.16 The show command ................................................ 2-20
2.2.17 The subroutine command ........................................ 2-22
2.2.18 The sysid command ................................................ 2-23
2.2.19 The template command ........................................... 2-24
2.2.20 The query command ................................................ 2-25
2.2.21 The verbose command ............................................ 2-27
2.2.22 The xlate command ................................................. 2-28
2.3 Starting TLSCMDX ................................................ 2-29
2.3.1 Implementation of the tls command processor ....... 2-30
Appendix A Examples .................................................................. A-1
A.1 Fragments from bus.qry ........................................... A-1
A.2 Fragments from cre_env.qry .................................... A-5
Appendix B Quick reference .........................................................B-1
iv FAST/TOOLS TLSCMDX Language Manual

Objectives Preface
0 Preface
0.1 Objectives
• To provide application programmers with an overview of the
functionality of the TLSCMDX language.
• To provide experienced users with a reference for the use of the
TLSCMDX commands

This manual is intended for programmers who need to create or modify
FAST/TOOLS installation procedures.

This manual contains 3 chapters and two appendices:
• Chapter 0 (this chapter) is an introduction to this document.
• Chapter 1 can be regarded as an introduction to the TLSCMDX
concepts.
• Chapter 2 is a reference guide for programmers who are already
familiar with the basics of TLSCMDX.
• Appendix A contains some examples of installation scripts. These
can be used as a basis for user scripts.
• Appendix B is a quick reference of TLSCMDX commands.

• FAST/CONVENTIONS Reference Guide.
• FAST/TOOLS Installation Manuals
FAST/TOOLS TLSCMDX Language Manual 0-1


This manual makes use of the following conventions:
CONVENTION MEANING
arguments that need to be passed.
repeated at least once.
... Indicates that not all statements are shown
UPPERCASE Indicate reserved words and predefined
names, e.g. NULL, TRUE,
DUR_NOWAIT.
indicate that the character is to be taken
literally.
<name> Used in format descriptions. <name>
indicates a variable.
<file_name>+ Used in syntax descriptions. One or more
n.u. not used.
output This typesetting is used to indicate output on
a terminal.
input This typesetting is used to indicate input
from the user.
TLSCMDX Tools Commands Interpreter. X means that
TLSCMDX does not need FAST/TOOLS
0-2 FAST/TOOLS TLSCMDX Language Manual





1 General
1.1 Introduction
With tlscmdx it is possible to write configuration procedures which are
almost system independent, called query files. All the things like
questioning and displaying information are the same for each system.
Only where it concerns system specific commands such as copy or
delete for example, some platform dependent commands are needed.
1.2 General features of TLSCMDX

The main functionality of TLSCMDX can be divided into the following
groups:
• Interaction with the user:
- asking questions
- validating the given answers
- supplying help information
- presenting default answers
- remembering and presenting previously given answers as
defaults
• License handling
• Generation of text files.
• Taking care of system dependencies.
1.3 Basic structure of the query language
1.3.1 Commands
It uses UNIX shell like command lines in which a single line is

interpreted as <command> <arg1> <arg2>..., where the separating
character between the command and the arguments is a space. As line
termination character the end of line character ’\n’ is used. To force an
overflow of the command line to the next line, the ’\n’ may be prefixed

General Basic structure of the query language
with a ’\’. This will result in skipping the ’\n’, so that the next line is
logically the same as the previous one.
1.3.2 Arguments
If spaces are to be included within an argument, then the argument must

be surrounded by double quotes (". arg").
1.3.3 Comment
A line is ignored if the first character is an exclamation mark ’!’. The

comment ends when a ’\n’ character is encountered. Within a comment
line continuation by means of the ’\’ character is allowed. To use the ’\’
character within comment is dangerous however because when a
comment line ends with a ’\’ character and the following line is not a
comment line, then the following command line will also be regarded as
an comment line.
1.3.4 Predefined variables
Some variables are predefined and they can always be used. First of all
there are the variables UNIX, FTX, AIX, SYSTEM_V, __NUTC__ and
VMS. There are a few more (OS2 and OS9), but these platforms are not
really supported. If running on UNIX the additional variables FTX or
AIX or __NUTC__ and SYSTEM_V can be defined.
The variables “copy” and “delete” contain the names of the local copy
and delete commands. These variables are handy within a tlscmdx script
to perform system independent copy and delete actions.
The variable QUOTE contains the ‘-sign, which comes in handy if this
character is to be placed inside a variables value, without being
executed.
The variable DQUOTE contains the "-sign.
The NEWLINE variable contains a \n character.
The TIME variable returns the current date and time.
The LEVEL variable contains the current if nesting level. This is mainly
used for test purposes.
Px is the number of arguments passed via the -p switch. P# represents a
parameter value, where # is a number. P0 is the first parameter.

Basic mechanisms General
1.3.5 Foreign commands
If a line starts with “do” it is believed to be a so called foreign command.

This command will be executed using the C primitive
system("command string");. Before the line is passed to the
operating system command processor, possible symbol references are
resolved. For example "do ‘COPY‘ durini.sup ‘TLS_SUP‘" could
be a general purpose copy command, where the definition of the ‘COPY‘
command and the ‘TLS_SUP‘ directory are system dependent.
1.4 Basic mechanisms

The TLSCMDX features mentioned above indicate a number of basic
mechanisms. These mechanisms are:
1 A query mechanism to get values for parameters, license numbers.
etc.
2 A validation mechanism which is capable of screening the values
specified and indicate a possible error made by the user.
3 A database which contains the values entered by the user.
4 A text generation mechanism with which several text files can be
produced dynamically.
5 Flow control primitives with which operating system dependencies
can be resolved.
6 Mechanism for checking en validating license numbers.
7 Variable substitution.
8 Subroutine mechanism.
1.4.1 The query mechanism
The query mechanism basically involves the asking of a question and

collecting an answer. If a question is asked, a default value must be
presented to the user. There must be some relation between the question
to ask, the answer and the place in the database at which the answer is
stored. There must also be some relation between the value specified by
the user and the check to be performed on the value.
For the purpose of relating a question to the actual value and it’s
validation check a symbol name is introduced. This symbol name will
be used as a key into the value database.

General Basic mechanisms
The elements that make up a question are:

• The question itself.
• The default value.
• Symbol name.
1.4.2 The validation mechanism
There are two validation mechanisms. A general purpose one for

validation of data and another one for license validation.
The validation mechanism involves the verification of a value, which is
the result of a question asked to the user. The user can use the default
value which is assumed to be correct, or he can specify a new value
which is assumed to be wrong up to the moment that it has been checked.
The available validation data checks are:
• Checks for alphanumeric values:
- value is alphanumeric
- value only contains a certain set of characters
- value is of a certain length (-range)
- value is member of a certain set of allowed values
• Checks for numeric input:
- value is numeric
- value is within a certain range or ranges
- value is member of a certain set of allowed values
The license checking only specifies a certain type of check that can be
performed on a value.
The way to relate to a value is to specify its symbol name, with which
the corresponding value can be retrieved from the value database for
checking. Furthermore an error message must be issued if the parameter
is qualified as wrong.
The elements that make up a check are:
• Symbol name.
• Check specification.
• Error message.
1.4.3 The value database
The value database is the core mechanism of the functions described

because it is capable of retrieving, modifying and adding a value related

Basic mechanisms General
to a (new) symbol. By implementing the database all specified

parameter values are saved. This is done by saving the database on disk
and reloading it into memory when it is used for instance to retrieve the
last entered values.
The mechanism itself contains a number of functions. These are:
• Load a database from disk to append it to the current one.
• Store the current database on disk.
• Add (or modify) a symbol’s value.
• Retrieve a symbol’s value.
The information needed to perform the functions described above is:
• Database file name.
• Symbol name.
• Symbol type.
• Symbol value.
1.4.4 The text generation mechanism
To be able to generate things like include files, setup files and gen files
It is only necessary to substitute some parameter values within a file at
certain places. This tool will generate files, which is done by substituting
symbols in a template text file by symbol values in an output file, which
is then becomes the actual include, setup or gen file.
The elements needed to specify this operation are:
• Database file name
• Template file name
• Output file name.
Additionally there is a facility to append one or more lines to a file (see
the ‘show’ command). This provides a more flexible means of
generating files.
1.4.5 Flow control primitives.
The mechanism to implement flow control is a C-preprocessor like

facility, which does not act as a real preprocessor but as a dynamic
mechanism imbedded in a read_line function, with which every
command or template file is read. Depending on preprocessor conditions
that were specified, lines are skipped or processed by the evaluator,
which is unaware of the fact that there were lines beginning with

General Basic mechanisms
preprocessor commands. Typical preprocessor commands that are

recognized are:
• if <expression>
• ifdef <symbol>
• ifndef <symbol>
• else
• endif
• subroutine
• endsubroutine
• gosub
• goto
These commands may be nested, except for the subroutine and
endsubroutine commands.
Note: If the template command is used to
generate shell scripts, an extra action is
needed when the shell ’if’ command is used.
Within the show and the template
command the preprocessor can be disabled
on a per line bases by putting a vertical bar
"|" as the first character of a line. This
prevents the preprocessor from
recognizing any if’s, ifdef’s, else’s or
endif’s, while the normal variable
substitution is still performed. The vertical
bar is removed and not shown in the
output.
1.4.6 Variable substitution
As soon as an ’‘’ surrounded string is encountered the characters

between two ‘-signs are treated as a symbol reference. The entire string,
including the ‘-signs is substituted by the symbols value, before it is
even evaluated. This means that even the command itself might be a
symbol reference, containing the actual command. The number of
leading ‘-signs specifies how many times the expression is substituted.
For instance the ‘a‘ is substituted once. The ‘‘a‘ is substituted twice,
etc. With the multiple substitution the result of the former substitution is
taken as a variable name and is substituted by its value again. So with
‘‘a‘ the variable actually contains a variable name. The expression
‘‘a‘ then results in the value of the variable of which the name is

FAST/TOOLS Installation General
specified in the variable a. This mechanism can be compared to the use

of pointers in C.
A variable name can have the following attributes:
• length Returns the length of the string in the symbol.
• [<loc>..<loc>] Where loc is a locator. These can either be
strings or numbers. When strings, the
substring between the two strings is returned.
If numbers, the string starting and ending at
the positions indicated is returned. Both of the
locators are optional. So [..] represents the
entire string, since a left missing locator
resembles the start of the string and a right
missing locator indicates the end of the string.
• <99 A left justified string is returned, which has
the indicated length. Pad character is a space.
• >99 A right justified string is returned, which has
the indicated length. Pad character is a space.
• <9:9 Used for floating point values. A left justified
string is returned, with the specified field
lengths before and after the decimal point
(represented by ‘:’). Pad character is a space.
• >9:9 Used for floating point values. A right
justified string is returned, with the specified
field lengths before and after the decimal
point (represented by ‘:’). Pad character is a
space.
The attributes are appended to the symbol name. For example the
attributes of the symbol file could be accessed by specifying
file.length or file.[1..5] or file.>10. (See also the load
command on how to address symbols in structured symbol tables).
1.5 FAST/TOOLS Installation

TLSCMDX is used within the installation procedures of FAST/TOOLS
on a number of platforms. The following tasks are performed:
• Creating a FAST/TOOLS environment.
• Spreading files to the FAST/TOOLS environment.
• Licensing of the tools.
• Specification of user-dependent parameters (configuration).

General FAST/TOOLS configurator
• Creating setup or .h files.

Refer to the FAST/TOOLS Installation Manuals for more detailed
information on this subject.
1.5.1 Creating the environment and spreading files
A tool (or set of programs) is delivered on a tape or disk. Since most file
systems differ, one has to extract the contents of the medium to an
arbitrary directory. The user is asked where the FAST/TOOLS
environment is created or must be created.Then the files can be spread
over the FAST/TOOLS environment. Spreading means copying files to
specific subdirectories in the FAST/TOOLS environment depending on
the type of files.
1.5.2 Licensing
The user must be able to provide license information. License numbers

must be generated and checked for validity. Any errors must be reported.
1.5.3 Configuring the tools
TLSCMDX provides a platform independent interface for specifying

user-dependent configuration parameters. The position of the FAST/
TOOLS environment and the license information mentioned above are
examples of such parameters. Files containing any configuration
parameters can be generated from templates.
1.6 FAST/TOOLS configurator

The FAST/TOOLS configurator provides a menu driven system for
specifying DURM connections. The tuning of distributed ITEM/FAST
is also done with this feature.
In order to hide system dependencies the FAST/TOOLS configurator is
created using TLSCMDX.

2 Reference
2.1 Introduction
This chapter provides a more precise description of the available
commands. Following this is a description of how to start TLSCMDX.
2.2 Commands
The commands are all arranged in alphabetical order. Every paragraph
is split up into:
• Syntax description.
• Argument description, describing possible switches and argument
values.
• Semantics of the command, which describe the functionality of the
command and their effects and side effects.
• Notes, in which some remarks are made, which are important, but
not directly related to the semantic description of the command.

Reference Commands
2.2.1 The assignment command
Syntax The complete syntax of the command is:
<symbol> := <value>
<symbol> += <value>
<symbol> -= <value>
<symbol> *= <value>
<symbol> /= <value>
<symbol> &= <value>
<symbol> |= <value>
Arguments The function accepts the following argc, argv arguments:
symbol is symbol to assign the value to.

value is the value that is to be assigned.
Semantics The assignment mechanism assigns a value to a symbol. The symbol and
its argument will be copied into the symbol table. The following flavors
are available:
• := is a straight assignment and it only copies the value
• += takes the value of the target variable and adds the value to it.
• -= as += only this subtracts the value from the symbol value.
• *= as += only this multiplies the value.
• /= as += only this divides the symbols value by the value.
• &= bitwise ands the symbol value and the value. If the symbol
contains yes or no then the logical and is performed
• |= bitwise or of the symbol value and the assigned value. If the
symbol contains yes or no a logical or is performed.

Commands Reference
2.2.2 The check command
Syntax The syntax of the check command is specified below:
check [-(r|l<label>)][-n] <check> <message>
Arguments The function accepts the following arguments:
-r Reprompt the question related to the symbol if the

specified check yields a FALSE.
-n Prefix the message with the variable name.
-l<label> Specifies a label to which has to be jumped if the
check yields a FALSE. The -l is to be followed
directly by a label name, including the terminating
label colon (:).
Check The actual check. See also below.
Message Is an error message which is displayed if the check
yields a FALSE result.
Semantics The check command draws some conclusions from the combination of
flags that are specified. The -r and the -l flags are conflicting flags of
which the -l always overrides the -r option. If none of the -r or -l
options is specified the check command returns with a status FALSE if
the check delivers a FALSE, otherwise it returns a TRUE. This status
can then be used by the on_error command.
The grammar for a check expression is the following:

<check> : <symbol> ["characters"] [not] "in" <value list>
;
The "characters in" means that the characters specified in the symbol are
defined within the value list. If only "in" is specified the entire value has
to be a member of the value list.
<symbol> : <name>[.<attribute>]
;
<attribute> : "length"
| "value"
| ">"<number>
| "<"<number>
| "["[<value>]".."["<value>]"]"
;
The symbol is just a name which is known by the database. The attribute
can be a certain aspect of the symbol. Normally the attribute is the value
of the symbol, though the length may also be of interest. Another

Reference Commands
possibility is a substring. The value marking the begin and end of the
substring must be of the same type. This is either a character string or
integer. In case of a character string, the substring beginning with the
specified substring up to the specified endstring is extracted, excluding
the substrings itself. If the begin and end values are integer, then they
represent an offset within the character string. If the begin value is not
specified the substring is taken from the first character up to the end
criteria. If the end value is not specified the substring is taken up to the
end of the character string, so [..] represents the entire string.
<value list> : "("[<value list> ","] <value_item>")"
;
<value_item> : <value>
| <range>
;
<value> : ["’"] <symbol> ["’"]
| ["’"] <integer value> ["’"]
| ["’"] <string value> ["’"]
| ["’"] <boolean value> ["’"]
;
<string value> : <char> <string value>
|
;
<boolean value> : "y"
| "Y"
| "n"
| "N"
;
<range> : <value> ( "-" | "=" ) <value>

;
The value list is built up of one or more value items. These value items
may specify a single value or a value range. The range is specified by
two values separated by a minus sign or an equal sign. If a minus sign is
used the permitted values include the range values. The equal sign
means that the permitted values are within the range specified and do not
include the range values themselves.
The value can be a symbol reference or a constant of type character
string, integer or boolean.
The error message may also contain symbol references, But they are
only recognized if a symbol name is surrounded by ‘-signs. If the value
of the symbol to be checked should be included within the error message,
then a %s should be placed within the error message.
For example: "The value %s is wrong it should be between ‘LOW‘ and
‘HIGH‘",
is an error message which refers to the actual symbol value to be
checked and two other symbols containing the lower and upper
boundary of a range.

Commands Reference
The entire check may look like this:
check INPUT "(‘LOW‘-‘HIGH‘)" \

"The value %s is wrong it should be between ‘LOW‘ and ‘HIGH‘"
Notes Be aware that the value substitution of the LOW and HIGH variables is
merely done by textual substitution before the actual check function is
called. The value of the symbol to be checked is never to be passed in
this way, because of possible reprompting by which the value of the
checked symbol might change.
Another issue to think about is that if there are any spaces inside the
value list then the value list must be surrounded by double quotes (").
This is because of the UNIX like argument parsing and passing. To
surround values with the "’" character is safe, because in that way the
characters: "(", ")", "-", "=" and "," are also legal within a value.

Reference Commands
2.2.3 The declare command
Syntax The complete syntax of the command is
declare <symbol> [volatile | nonvolatile]
Arguments The function accepts the following argc, argv arguments
symbol The name of the symbol to be declared.

volatile The specified symbol will not be saved in the
answer file.
nonvolatile The symbol will be saved in the answer file.
Semantics The declare command assigns the property mentioned (volatile or

nonvolatile) to the symbol. If the symbol doesn’t exist yet, then it is
created as an integer symbol with the value zero.
Notes By setting nonvolatile symbols to volatile, they are not saved in the
database anymore. Typically the parameters P1, P2, P3, etc. and Px are
volatile.

Commands Reference
2.2.4 The exist command
exist [-d|-f] <path> <symbol>
Arguments The function accepts the following arguments

-d Has to be specified when the file to be tested is a
directory.
-f Has to be specified when a file has to be tested.
<path> Path or file name to be tested.
<symbol> Symbol which receives the possible directory name.
Semantics The exist command checks the existence of a file or a directory. A

directory is checked by creating a file in it and then removing it. So when
the command fails it might be the case that the directory exists but the
process is not allowed to access it.
Notes The on_error command can be used in combination with the exist
command to make code flow decisions.

Reference Commands
2.2.5 The exit command
exit [-v][-s] <value>
Arguments The function accepts the following arguments

-v Verbose option. If specified some diagnostic
information is printed out during the execution of the
command.
-s Save option. If specified the current symbol table
will be saved on disk before exiting
value the value that has to be returned to the
environment. The value may be an integer or the
mnemonics BAD_EXIT or GOOD_EXIT which are
operating system independent
Semantics The exit command aborts a currently executing command file with a
given status. This in turn can be interpreted by the OS command file
that invoked the TLSCMDX command processor.
Notes The symbol table is saved to the file specified after the -d flag in the
TLSCMDX command, only if the -s flag is specified.

Commands Reference
2.2.6 The gosub command
gosub <subroutine name>
subroutine name The name of the subroutine that must be

executed.
Semantics The gosub mechanism involves jumping within a command file.

The next command to be executed is the command immediately after the
specified subroutine definition (See the subroutine command). After
the execution of the subroutine, processing continues with the command
just after the gosub that invoked the subroutine execution.
Notes Forward and backward references are supported.

Related commands are subroutine and return.

Reference Commands
2.2.7 The goto command
goto [-v] <label>
-v Verbose option. If specified some diagnostic information

is printed out during the execution of the command.
label The name of the place in the command file where the
next command is to be taken.
Semantics The goto mechanism involves jumping within a command file.

The next command to be executed is the command immediately after the
label definition. The syntax for a label definition is the following:
<label-definition> : <label-name> ":"

;
A label definition may not be followed by another command on the

same line in the command file. Anything put behind a label definition
is comment.
Notes This function provides a backward jump and a forward jump, so a jump
can take place to a random position within the current command file. Be
aware that a label inside the command file is defined by a label name
terminated with a colon, so every time the goto command is called the
label name must also end with a colon.

Commands Reference
2.2.8 The conditional if statements
Syntax The syntax of the dynamic preprocessor commands are:

if <expression>
ifdef <symbol>
ifndef <symbol>
else
endif
Arguments
Syntax The functions accept the following argc, argv arguments:
expression The expression that has to be checked for validity.

symbol The symbol that has to be checked on
occurrence in the symbol table.
Semantics The preprocessor facility is useful for flow control inside a query file and
also when tests are needed to determine the value of, for instance, a
#define constant.
The syntax for an expression is the following:
<expression> :["!"] <boolean value>
|["!"] <operand> <operator> <operand>
;
<operand> :integer
|string
;
<boolean value> : "Y"

| "y"
| "N"
| "n"
;
<operator> :"=="
|"!="
|"<"
|">"
|"<="
|">="
;
The if directive returns TRUE if the expression yields TRUE ifdef

returns TRUE if the symbol specified after ifdef is not defined in the
symbol table.The Ifndef directive returns TRUE if the symbol is
defined in the symbol table, otherwise it returns the complementary
value of the previous if. An endif directive returns the previous level
result if currently at a nested level (nested means level > 0), otherwise
FALSE is returned.
When an expression is prefixed with a "!" character, the inverse of the

Reference Commands
expression will be returned.

The preprocessor command could be used as follow:
if FIRST_DAY == "MON"
#define FIRSTDAY_WEEK 1
else
#define FIRSTDAY_WEEK 0
endif
Notes When the "!" character is used to inverse the return-value of an

expression, be sure that there is at least one space between the "!"
character and the following expression. Be sure also that the
exclamation mark isn’t standing at the first column position on a line,
otherwise it will be interpreted as a comment.

Commands Reference
2.2.9 BUS/FAST license check
Syntax The syntax of the command is specified below:
lic_1 <customer><Name><Number><Type>
<lic # 1><lic # 2><lic # 3>
The arguments to be passed to the lic_1 command have the following

meaning:
customer Customer name.

Name BUS/FAST node name.
Number BUS/FAST node number.
Type License type.
lic # 1 The 1st license number generated.
lic # 2 The 2nd license number generated.
lic # 3 The 3rd license number generated.
The customer name, node name and node number are to be supplied by
the customer. The license type can be either 0 for a run-time license or
1 for a configuration license. The three license numbers are generated by
Yokogawa, who will also need another piece of information, namely the
system number (see also the sysid command).

Reference Commands
2.2.10 Non BUS/FAST license check.
Syntax The syntax of the command is specified below:
lic_2 <lic # 1><lic # 2>
Arguments The arguments to be passed to the lic_2 command have the following
meaning:
lic # 1 The 1st license number generated.

lic # 2 The 2nd license number generated.
Semantics The two license numbers are generated by Yokogawa, who will need
another piece of information, namely is the system number (see also the
sysid command).

Commands Reference
2.2.11 The load command
load [-c] <database>

load <database> into <symbol>

-c Clear option. If specified the current symbol table will
be cleared before loading.
database The file containing the variable-value pairs to load
the symbol-table with.
symbol A symbol to which the entire database is assigned.
The values can then be accessed or modified by
using the <symbol>.name construction, where name
is the actual symbol name as it is retrieved from the
database.
Semantics The load command reads in a symbol table from a file, which is
appended to the current symbol table. If the -c flag is set, the current
symbol table will be cleared before appending the new one.
Notes Note that when the -c flag is set, the current symbol table is lost.
When a database is assigned to a symbol, this symbol is declared volatile
implicitly. This means that the database assigned to this symbol will not
be saved. If declared nonvolatile, the database will be saved to the file
from which it was originally loaded.

Reference Commands
2.2.12 The on_error command
on_error <command>
Arguments The command accepts the following arguments:

command The command that should be executed if one of
the following commands should fail.
Semantics The command specified after the command on_error will be executed
if one of the commands following the on_error should return with
FALSE. Every time a command has finished executing, a
TLS_BOOLEAN value is returned to TLSCMDX. When the returned
value is FALSE then TLSCMDX executes the command specified with
the on_error command.
Notes When a command returns with FALSE, TLSCMDX will execute the
command specified in the most recently defined on_error command.

Commands Reference
2.2.13 The on_interrupt command
on_interrupt <command>

command The command that should be executed if the interrupt
key was pressed (^C on UNIX systems).
Semantics The command specified after the command on_interrupt will be

executed if the interrupt key (likely to be ^C) is pressed. By default the
command is set to the exit command, which will not save the symbol
table. As a side effect any files created by the currently running script
will still exist.
Notes When a TLSCMDX script is interrupted it will complete the current

command. After command completion TLSCMDX will execute the
command specified in the most recently defined on_interrupt
command.

Reference Commands
2.2.14 The return command
return
Arguments The function accepts no arguments:
Semantics The execution of the current subroutine is stopped. Execution is returned

to the place from where the subroutine was called, by means of a gosub.
Notes A return command outside a subroutine is not allowed.

Commands Reference
2.2.15 The save command
save [-c][<database>]

-c Clear option. If specified the current symbol -
table will be cleared after a successful save.
database The file in which the symbol table must be saved.
Semantics The save mechanism involves saving the current symbol table to a
database file. If the file name is specified then the symbol table will be
exported to this file. If the file is not specified then the symbol table is
exported to the database which is specified after the -d flag in
TLSCMDX.
Notes Be aware that the symbol table will be cleared only after a successful
save. To clear the symbol table after an unsuccessful save use the
on_error command.

Reference Commands
2.2.16 The show command
show [-c][-f filename] [-o filename | -a filename]

data
endshow
The endshow must appear at the very first position of the line or at the
same character position as the matching show keyword.
-c Clear option. Clears the screen before the text is

printed out.
-f File option. Allows a file name to be specified.
-o Output file option. The output is redirected in this new
file.
-a Output file option. As with -o, only the output is
appended.
filename The name of the file.
Semantics The show command is able to print out comments, reports or add lines
to a generated file. The text lines that are to be printed may contain
symbol references. A symbol reference is recognized, when the symbol
is surrounded by backquotes. Before a line containing symbol references
is printed, the symbols are replaced by their actual values.
To redirect the output to a file, rather than the screen the -o and -a
switches can be used. The -o creates a new file, thereby destroying the
old one should it exist. The -a option appends the output to an existing
file. These options can be particularly handy when the template
command does not provide a solution or where a template would be too
static. The -c flags cannot be used together with the -o and -a switches.
To end the show command, a statement endshow, beginning at the same
column position where the keyword show starts or at the first position on
a line, has to be used. Everything between the line containing the show
command and the line containing the endshow statement will be printed
out.
Notes The endshow statement must be inserted in the command file at the
beginning of a line or at the same column position where the keyword
show starts.
To prevent any data to be interpreted by the preprocessor as a directive
like if, else, etc., a vertical bar (|) can be put on the first position of the

Commands Reference
data line. This will prevent the preprocessor from recognizing any
ifdef, else, endif, etc. keywords. Variable substitution is still
performed within such a line and the vertical bar is removed from the
beginning of the line so that it does not show up as output.

Reference Commands
2.2.17 The subroutine command
subroutine <subroutine name>

<command>
<command>
endsubroutine
Where the endsubroutine must be either at the very beginning of the

line, or at the same column position as the subroutine keyword.
subroutine name The name of the subroutine to be defined.
Semantics The subroutine mechanism declares and defines a subroutine. All

variable names used are global.
Notes Forward and backward references are supported.

Related commands are gosub and return.

Commands Reference
2.2.18 The sysid command
sysid <customer> <name> <number> <license> <format>
Arguments The function accepts as arguments:
<customer> The license customer name.

<name> The node name of the licensed node
<number> The node number of the licensed node.
<license> The license type. 0 is development license a 1 is end
user.
<format> A printf format with %s resembling the system id.
Semantics Sysid accepts license information and generates the system id, which is
specific for the system with the specified customer, node name, node
number and license type.
Notes It directly prints out the system id number that is specified. It is not
assigned to a variable.

Reference Commands
2.2.19 The template command
template [-s<symbol_table>] <template> <result>

-s Symbol file, containing the variable value pairs.
template A file containing text and symbol references.
result is the resulting file in which the symbols have been
replaced by their actual values retrieved from the
symbol table.
Semantics The template file will be read out sequentially until an EOF is
encountered. If the line just read contains symbol references, then the
symbols will be substituted by their values. The resulting line, obtained
after the symbol substitutions, is written to the result file. If a symbol
table file is specified, the current symbol table will be initially cleared
and loaded with the variable-value pairs specified in the file symbol
table. Flow control commands can also be used in the template (see next
section). The template command can be used to construct .h files or
.sup files, though its usage is certainly not limited to this.
Notes The database to use is specified by the environment in which the routine
runs.
For the programmer’s convenience there are two specially predefined
macro’s: ’NEWLINE’ and ’TIME’ (both in uppercase).
When ’NEWLINE’ is encountered, it is substituted by a ‘\n’ in the text
and ’TIME’ is substituted by the calender day and time.
When if endif constructions are used inside the template, the
keywords if, endif, else, etc. must start at the first position of the line.
This is in contrast with what is allowed inside a query script.
To prevent data from getting interpreted as preprocessor directives, an
escape is available which disables the preprocessor (except for the
variable substitution), is offered. By putting a vertical bar (|) on the first
position of the line, any keyword like if, else, endif, etc. is ignored.

Commands Reference
2.2.20 The query command
query [-h][-q][(i|c|b|x)]<Symbol><Question> [<Default>]

[<help text>
endhelp ]
-h By specifying this parameter, one has to specify a help

text that starts on the first line after the query command.
The help text has to terminated by the command
’endhelp’ which should be entered at the first position of
a line.
-i An integer value must be entered as an answer.
-c A character string is to be entered as an answer.
-b A boolean value either ’y’ or ’n’ is to be entered as an
answer. Uppercase as well as lowercase is accepted.
-x A hexadecimal value in the form 0x... is to be entered as
an answer.
-q This flag only has a meaning if it is combined with the
-c flag.
If -q is specified, blanks are considered to be valid input
characters. If no -q is specified blanks are filtered out.
Symbol The name under which the answer is stored into the
database.
Question The question to be asked
Default The default answer. This default will be used if a null
string is answered while the symbol is not defined yet. If
the symbol is already defined, the actual value of the
symbol will overrule this default.
Semantics The query is asked and the command will wait for an answer which
matches the data type specified. If no data type is specified it assumes
that a character string is to be entered (-c) in which case spaces are not
allowed (so no -q option !). If the answer is provided it is stored in the
database assigned to the symbol name. The query is also stored in the
database assigned to the symbol name prefixed with a ?-mark. If the
answer does not match the requested data type the question is simply
asked again.
Only if the -h flag is specified, is the user able to type question mark
(’?’) to get help from the program. All the text starting at the line after

Reference Commands
the query command is printed, until the command ’endhelp’ is

encountered.
If ?+v is typed, the verbose option is turned on. Conversely, ?-v the
verbose is switched off again. This feature facilitates debugging of
TLSCMDX sources.
Notes In fact the -i, -b, and -x flag perform some basic form of checking.

Commands Reference
2.2.21 The verbose command
[no]verbose
Arguments The function accepts no arguments:
Semantics Verbose turns the verbose option on dynamically (see -v flag). The
noverbose turns it off again.
Notes This function prints out a message indicating that verbose is on/off and
whether verbose was already on/off.

Reference Commands
2.2.22 The xlate command
xlate <variable> [<OS>] -p <prefix> -d <directory> -f <file>

-t <type> -v <version>

Possible OS switch:
• -VMS
For VMS systems.
• -UNIX
For UNIX systems.
• -VOS
For Stratus VOS operating system.
the parts of the file path:
• -p <prefix>
The directory path prefix.
• -d <relative directory path>
The relative directory path in UNIX notation.
• - f <name>
The file name.
• -t <type>
The file type excluding any separator, such as a dot.
• -v <number>
The possible version number.
Semantics Because every OS has its own way of specifying a directory path, some
mechanism must be provided that maps a system independent notation
onto a system dependent notation. Almost every full filename consists
of the following parts:
• Directory path prefix.
Could correspond to the tls_root. This value offers no
specific system independency. It must have the correct
form.
• Directory path relative to the prefix.
Could correspond to tls_data, tls_sup, etc. This offers
system independency. It accepts UNIX like directory
paths, though only relative paths (i.e. not starting with a /
) are accepted.
• Filename part.
Corresponds to the file name like itmcpm. This offers
system independency.

Starting TLSCMDX Reference
• Filename type.
Corresponds to the type like sup, exe, etc. This offers
system independency.
• File version indicator.
Corresponds to a certain version of a file. This is only
supported under the file system of VMS. Under any other
operating system it is ignored, providing system
independency.
Also the command has a switch with which the OS can be
chosen for which the file name path must be generated. By
default this will be the one for the OS on which TLSCMDX is
run.
Notes None.
2.3 Starting TLSCMDX

Several functions have been formulated, which individually provide the
parts of the functionality described in the beginning of this document.
To fulfill all the requirements they are integrated into one tool. This tool
has the capability to use all the functions described in the previous
subsections. The basic idea behind this tool is that it reads in a text file,
which contains directives about what queries should be made, what type
of checking should be performed and which files should be generated.
To be able to do this, such a tool would basically need the following
parameters:
• Name of database file to load.

• Name of text file with directives to interpret.

Reference Starting TLSCMDX
2.3.1 Implementation of the tls command processor
tlscmdx [-s] [-v] [-d<database_file>] <command_filename>

[-p] [arg1] ... [argn]

-s Stepper debugger option.
-v Verbose, prints out trace information, useful for
debugging.
-d Loading and saving the symbols to and from a
symbol table.
database_file
The name of the symbol table file on disk. This file is used
to load the symbol table initially and to save the symbols
afterwards. If not specified the command filename with the
extension ".ans" is used.
command_filename
The name of the file with the commands to interpret, the
default extension is ".qry".
-p Every argument after this switch is passed to the script by
assigning it to variables with names like P1, P2, etc. A
special variable with the name Px contains the number of
arguments that are passed.
Semantics The tlscmdx command starts a program to interpret a FAST/TOOLS

command file. When the command file is specified without an
extension, the tls command processor assumes that the extension is
".qry". The -d flag is optional; when no database file is specified, the
command filename with the extension ".ans" is used. Before the first
command of the command file is to be executed, the symbol table is first
cleared. After that the symbol table is loaded with the variable value
pairs specified in the database file. The syntax of the commands is
specified in the user command reference.
The program reads in a command line until a ‘\n’ is encountered. If the
command line contains symbol references then this symbol is replaced
by its value. When the command specified by the current command line
results in an error and the on_error command has been issued before
the current command line, then the command specified by the on_error
command is the next to be executed. When all the commands of the
command file are executed, the nonvolatile variables within the symbol
table are saved to the file specified by the -d flag. Note that the

Starting TLSCMDX Reference
parameter variables are not saved, since they are implicitly declared as
volatile.
A command file could look like this:
show
BUS/FAST parameter specification
endshow
load os.def
BUS := "March 1990"
VERSION := "4.5 pre-release"
L1:
query -q -c CUSTOMER_NAME "Enter the customer name :"
check -lL1: CUSTOMER_NAME.length in (12=72) \
"Length: %s, must be between 12 and 72"
check -lL1: CUSTOMER_NAME\
characters in "(’a’=’z’, ’A’=’Z’, ’0’=’9’,\
’ ’)"\
"illegal characters in %s, only alfa-numeric
characters and spaces are allowed"
show -c
Customer name : ‘CUSTOMER_NAME‘
endshow
These are the necessary commands within the command file to assign a
value to the symbol CUSTOMER_NAME. The value to be entered by the user
must be a character string ( -c flag ). Within the answer spaces are
allowed ( -q flag). The length of the value entered by the user must be
between 12 and 72 characters, and the value may only contain
alphanumeric characters and spaces. When one of the conditions above
is not satisfied, a jump will take place to the position indicated by L1:.
The label L1: is specified using the -l flags in both the check
commands. When a legal answer is entered, the answer is printed out.
Notes The name of the file which is used to load and save the symbol table
must come directly after the -d flag. No spaces are allowed.

Reference Starting TLSCMDX

Fragments from bus.qry Examples
Appendix A Examples
To ease the development of installation procedures, some fragments of

installation files are supplied here. These files may possibly not reflect
the current situation.
A.1 Fragments from bus.qry

! +--------------------------------------------------------------+
! | * BUS * |
! +--------------------------------------------------------------+
! | Module identification |
! +--------------------------------------------------------------+
!
! Module Name : bus.qry
!
! Version : 1.9
!
! Copyright (c) : Yokogawa System Center Europe B.V.
!
! Author : H.Koekoek
!
! Description : Query file for tool generation
!
!
! +--------------------------------------------------------------+
B := "{ `QUOTE`NODE_NUMBER`QUOTE` , `QUOTE`LIC_1`QUOTE` ,

`QUOTE`LIC_2`QUOTE` }\
, `QUOTE`NEWLINE`QUOTE` `QUOTE`B`QUOTE`"
xlate DUR_GEN_TPL -d ../tpl -f dur_gen -t tpl

do `copy` `DUR_GEN_TPL` dur_gen.tpl
OWN_NODE := "TRUE"
xlate GEN_ANS -d ../sav -f gen -t ans

load `GEN_ANS`
load os.def
ifdef SYSTEM_V
NOHUP := "nohup"
else
NOHUP := " "
endif
nodnum:
NODE_NUMBER := 0
query -i -h NODE_NUMBER "Enter the license node number:"
This number is used to identify the node within the BUS/FAST
FAST/TOOLS TLSCMDX Language Manual Appendix A-1

Examples Fragments from bus.qry
communication network. To communicate with a remote process you

must address the node of that process by its node number. This
number must therefore be unique within the network, and also has
to be in the range 1-254. The number is shown in the DUR display
utility.
endhelp
on_error goto nodnum:
check NODE_NUMBER in (1=254) \
"%s is an invalid node number, it must be in the range 1-254"
on_error goto notloaded:

load `TLS_SAV_FS``/`lic_info`NODE_NUMBER`.ans
goto licinfo:
notloaded:
show
The node number just entered doesn't exist, respecify another !!!!
endshow
goto nodnum:
licinfo:
show
------------------------------------------------------------------
B U S / F A S T L i c e n s e I n f o r m a t i o n
------------------------------------------------------------------
Customer name : `CUSTOMER_NAME`

Node name : `NODE_NAME`
Node number : `NODE_NUMBER`
License type : `LICENSE_TYPE`
endshow
sysid "`CUSTOMER_NAME`" `NODE_NAME` `NODE_NUMBER` 1 \
" System number : %s"
show
------------------------------------------------------------------
endshow
havelic:
query -c -h CONTINUE "Have you already obtained the license numbers"
"y"
If you have already obtained the license numbers from Yokogawa,
you can
answer 'y', otherwise you should enter 'n' and then mail or fax a
completed License Information Form to Yokogawa. The procedure
cannot
continue without the relevant license numbers and so will stop.
endhelp
on_error goto havelic:
check CONTINUE in ('Y','y','N','n') \
"%s is an illegal answer, enter either 'y' or 'n'"
on_error exit -s BAD_EXIT
check CONTINUE in ('Y','y') \
Appendix A-2 FAST/TOOLS TLSCMDX Language Manual

Fragments from bus.qry Examples
"First contact Yokogawa to obtain your system specific license

numbers."
LIC_1 := 0
LIC_2 := 0
LIC_3 := 0
!
! Check to see if the licence numbers are entered before. If this is
! the case use them as defaults
!
on_error goto asklic:
exist -f `TLS_SAV_FS``/`bus_lic`NODE_NUMBER`.ans
load `TLS_SAV_FS``/`bus_lic`NODE_NUMBER`.ans
asklic:
query -i LIC_1 "Enter 1st license number:"
query -i LIC_2 "Enter 2nd license number:"
query -i LIC_3 "Enter 3rd license number:"
on_error goto licinfo:
lic_1 "`CUSTOMER_NAME`" `NODE_NAME` `NODE_NUMBER` 1 `LIC_1` `LIC_2`
`LIC_3`
TLIC1 := `LIC_1`
TLIC2 := `LIC_2`
TLIC3 := `LIC_3`
TNODE := `NODE_NUMBER`
TNAME := `NODE_NAME`
show
endshow
template `TLS_TPL_FS``/`license.tpl `TLS_SAV_FS``/
`bus_lic`NODE_NUMBER`.ans
! ask parameters only once: On the own node
poolkb:
query -i -h POOL_KB "Enter the size of the BUS/FAST pool in
Kbytes" "500"
The pool size is the size of the BUS/FAST common data area. All
dynamic information about inter-process communication, the clock
queue, and inter-node communication, etc., is stored in this pool.
To gauge the total size needed, you can use the rule of thumb that
it takes an average of 8 Kbytes for each attached process. Since
the total number of processes within all FAST/TOOLS products, which
are now available,is around 50, the default value of 500 Kbyte is
a reasonable size. Moreover, because of the dynamic character of
the pool, the chances of this space ever being completely taken up
at any one moment are very small.
endhelp
on_error goto poolkb:
check POOL_KB in (50=) \
"%s is illegal as a BUS/FAST pool size it must be greater than or
equal to 50 Kb"

Examples Fragments from bus.qry
nodequekb:
query -i -h NODE_QUE_KB "Enter the maximum queue size per node in
Kbytes" "50"
This defines the maximum queue size for a node. A good rule of
thumb is to specify this parameter to be about 10% of the size of
the BUS/FAST pool.
endhelp
on_error goto nodequekb:
check NODE_QUE_KB in (2=) \
"%s is illegal as a node queue size it must be greater than or
equal to 2"
shmbuscom:
query -c -h SHM_BUSCOM_ADDRESS \
"Enter the shared BUSCOM address (hex)" "800000"
BUS/FAST contains two shareable images, BUSLIB and BUSCOM, which
are placed at fixed memory addresses. If these addresses are in
conflict with your own software, it is possible to change them. If
you do change them, then the BUSCOM area must be built with a higher
address than the previously defined BUSLIB area, and also the gap
between them must be at least the size of BUSLIB plus connected
libraries (like the VAX C run-time library).
The default gap is (hex) 100000. To prevent paging, it is wise to
put BUSCOM on a page boundary.
endhelp
on_error goto shmbuscom:
check SHM_BUSCOM_ADDRESS characters in ('0'='9','A'='F') \

"Only uppercase characters and digitals allowed"
firstday:
query -c -h FIRST_DAY "Is SUNday or MONday the first day of
the week?" "MON"
This question determines when the week number will be incremented.
If you specify `SUN', it will be incremented at the Saturday-Sunday
transition. If you specify `MON', it will be incremented at the
Sunday-Monday transition.
endhelp
on_error goto firstday:
check FIRST_DAY in ('SUN','MON') \
"Value %s is illegal, specify either SUN or MON in uppercase"
lstname:
query -c -h LST_NAME "Enter LST_NAME " "MET"
LST is an abbreviation for the Local Standard Time. This is the name
of the time zone without daylight saving. The default value is MET
(Middle European Time).
The abbreviation MET is not interpreted, it is only used for
reporting purposes.

Fragments from cre_env.qry Examples
endhelp
on_error goto lstname:
check LST_NAME.length in (0=7)
check LST_NAME characters in "('A'='Z' , 'a'='z')"
do `copy` time_table.sup `TLS_SUP_NODE``/`time_table.sup

do `copy` `TLS_SAV_FS``/`gen.ans `TLS_DAT_NODE``/`bus.new
ifdef UNIX
do chmod 666 `TLS_DAT_NODE``/`bus.new
endif
ifdef UNIX
template `TLS_TPL_FS``/`bus_start.tpl bus_start
template `TLS_TPL_FS``/`bus_stop.tpl bus_stop
do chmod 755 bus_start
do chmod 755 bus_stop
endif
A.2 Fragments from cre_env.qry

! +--------------------------------------------------------------+
! | * GEN *
! +--------------------------------------------------------------+
! | Module identification |
! +--------------------------------------------------------------+
! Module Name : cre_env.qry
!
! Version : 01
!
! Copyright (c) : by Yokogawa System Center Europe B.V., the
! Netherlands
!
! Author : R.Berkel
!
! Description : Query file for the creation of the FAST/TOOLS
! environment on a particular node (including
! logical links)
!
!----------------------------------------------------------------+
xlate DISTRIBUTE_ANS -d ../sav -f distribute -t ans

xlate CRE_ENV_ANS -d ../sav -f cre_env -t ans
load `DISTRIBUTE_ANS`
load `CRE_ENV_ANS`

Examples Fragments from cre_env.qry
!
! TLS_ROOT_PATH indicates the logical name that must be used to
adress the
! FAST/TOOLS environment on every node !!!!!
! (This will be done with logicals on VMS system)
!
askfyspath:
!
FYS_PATH_NODE := " "
ifdef UNIX
TLS_ROOT_LOG_NAME := ""
TLS_DIR := tls/
endif
ifdef VMS
TLS_ROOT_LOG_NAME := tls_root:
TLS_DIR := [.TLS]
endif
query -h -c FYS_PATH_NODE "Enter the FAST/TOOLS root_directory path

on this \
node (full path-name) : " "`DEF_ROOT_NODE`"
The root_directory path is the physical directory path on which the
'`TLS_DIR`' - directory on this node is or has to be installed.
The physical directory can be addressed by using it's logical name
"`TLS_ROOT_LOG_NAME`"
endhelp
on_error goto askfyspath:
check FYS_PATH_NODE characters in "('A'='Z', 'a'='z', \
'0'='9','.','-','_','/','[',']',':','$')" \
"%s is illegal, only alfa-numeric, dots, underscores and
backslashes allowed"
maketls:
do `CREATE_DIR` `TLS_ROOT_NODE`
neededrootpath:
ifdef TLS_ROOT_PATH
if FYS_PATH_NODE == TLS_ROOT_PATH
show
The root_directory path on this node may not be the same as the
logical directory path. Specify an other directory.
endshow
goto askfyspath:
endif
goto checkrootpath:
endif
!
! "Specify the logical directory" this must only be done for UNIX
! systems. On VMS systems, definitions of 'logical names' are made

Fragments from cre_env.qry Examples
! for each node. These logical names must be defined each time the
! node starts up. This is not part of the file system, like on UNIX
! systems!
!
! For both UNIX and VMS systems, node specific directories are
! physically created.
!
on_error goto badroot:

do su - root -c 'rm -f `TLS_ROOT_PATH`/tls; ln -s `TLS_ROOT_NODE`
`TLS_ROOT_PATH`/tls'
answer := yes
declare answer volatile
query -b -h answer "Was the logical directory link created
correctly ?" yes
| If for some reason the creation of the link did not succeed,
then
enter no, otherwise enter yes.
One reason for failure might be the specification of a wrong
super user password.
endhelp
if ! answer
goto askrootpath:
endif
goto createenv:
badroot:
show
Not succeeded to create logical directory link.
endshow
exit -s BAD_EXIT
! Create logical links (common directories)

!
ifdef UNIX
ocheckcom:
on_error goto linkcom:
exist -f `TLS_ROOT_NODE`/com
goto checkupg:
linkcom:
do ln -s `TLS_ROOT_FS`/com `TLS_ROOT_NODE`/com
checkupg:
on_error goto linkupg:
exist -f `TLS_ROOT_NODE`/upg
goto checktpl:
linkupg:
do ln -s `TLS_ROOT_FS`/upg `TLS_ROOT_NODE`/upg

Examples Fragments from cre_env.qry

Quick reference
Appendix B Quick reference
This appendix provides a brief overview of the syntax and arguments of

the available commands. For further information please see the chapter
"Reference".
Startup of the tlscmdx command interpreter:
tlscmdx [-s] [-v] [-d<database_file>] <command_filename>

[-p] [arg1] ... [argn]
Available commands:
<symbol> := <value>
<symbol> += <value>
<symbol> -= <value>
<symbol> *= <value>
<symbol> /= <value>
<symbol> &= <value>
<symbol> |= <value>
check [-(r|l<label>)][-n] <check> <message>
declare <symbol> [volatile | nonvolatile]
exist [-d|-f] <path> <symbol>
exit [-v][-s] <value>
gosub <subroutine name>
goto [-v] <label>
if<expression>
ifdef<symbol>
ifndef<symbol>
else
endif
lic_1 <customer><Name><Number><Type>
<lic # 1><lic # 2><lic # 3>
lic_2 <lic # 1><lic # 2>
FAST/TOOLS TLSCMDX Language Manual Appendix B-1

Quick reference
load [-c] <database>
on_error <command>
on_interrupt <command>
return
save [-c][<database>]
show [-c][-f filename] [-o filename | -a filename]

data
endshow
subroutine <subroutine name>/

<command>
<command>
endsubroutine
sysid <customer> <node name> <node number> <license>
template [-s<symbol_table>] <template> <result>
query[h][q][(i|c|b|x)]<Symbol><Question>[<Default>]
[<help text>
endhelp]
[no]verbose
xlate <variable> [<OS>] -p <prefix>

-d <directory> -f <file>
-t <type> -v <version>
Appendix B-2 FAST/TOOLS TLSCMDX Language Manual

Index
Index
Symbols foreign commands 1-3

FTX 1-2
&= 2-2
*= 2-2
+= 2-2
G
/= 2-2 GOOD_EXIT 2-8
:= 2-2 gosub 1-6, 2-9
-= 2-2 goto 1-6, 2-10
|= 2-2
I
A if 1-6, 2-11
AIX 1-2 ifdef 1-6, 2-11
ans 2-30 ifndef 1-6, 2-11
arguments 1-2
assignment 2-2 L
label 2-10
B LEVEL 1-2
BAD_EXIT 2-8 lic_1 2-13
lic_2 2-14
C load 2-15
check 1-3, 1-4, 2-3
alphanumeric 1-4
M
license 2-13, 2-14 mechanisms 1-3
numeric 1-4
commands 1-1 N
comment 1-2 NEWLINE 1-2, 2-24
nonvolatile 2-6
D
declare 2-6 O
default value 1-4 on_error 2-16
DQUOTE 1-2 on_interrupt 2-17
E P
else 1-6, 2-11 predefined variables 1-2
endif 1-6, 2-11 preprocessor 2-11
endshow 2-20 Px 1-2
endsubroutine 1-6
exist 2-7 Q
exit 2-8 qry 2-30
query 2-25
F query mechanism 1-3
features 1-1 question 1-3
FAST/TOOLS TLSCMDX Language Manual 1

Index
QUOTE 1-2
R
return 2-18
S
save 2-19
show 2-20
starting TLSCMDX 2-29
subroutine 1-6, 2-9, 2-22
symbol 1-3, 1-6, 2-2
sysid 2-23
SYSTEM_V 1-2
T
template 1-5, 2-24
text generation mechanism 1-5
TIME 1-2, 2-24
TLSCMDX 0-2
tlscmdx (command) 2-30
U
UNIX 1-2
V
validation mechanism 1-4
value 2-2
value database 1-4
variable substitution 1-6
verbose 2-27
verification 1-4
VMS 1-2
volatile 2-6
X
xlate 2-28
2 FAST/TOOLS TLSCMDX Language Manual

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction PROCESS/FAST FAST/TOOLS
Manual Java Language Manual
IM50N06N01-01EN/R10.03
YOKOGAWA ELECTRIC CORPORATION IM50N06N01-01EN/R10.03

YOKOGAWA 9-32 Nakacho 2-chome,
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
0 Preface ...................................................................................0-1
0.1 Manual Objectives .....................................................0-1
0.5 Terminology ..............................................................0-2
1 Introduction ..........................................................................1-1
1.1 PROCESS/FAST Java language ...............................1-1
1.2 Using this manual ......................................................1-1
2 Getting started ......................................................................2-1
2.1 Introduction ...............................................................2-1
2.2 Simplest example .......................................................2-1
2.3 Connecting to the world ............................................2-2
2.4 Do something .............................................................2-2
3 Class structure ......................................................................3-1
3.1 Introduction ...............................................................3-1
3.2 Global structure .........................................................3-1
3.3 Class declaration ........................................................3-3
3.3.1 Import statement ....................................................... 3-3
3.3.2 Extends statement ..................................................... 3-4
3.4 Attributes, signals, containments and timer definitions 3-
4
3.5 Object creation and destroyment methods ................3-5
3.6 Object starting and stopping methods .......................3-7
3.7 Trigger processing methods ......................................3-7
3.8 User methods .............................................................3-8
4 Signals ....................................................................................4-1
4.1 Introduction ...............................................................4-1
4.2 Defining signals .........................................................4-1
4.2.1 Signal triggers ........................................................... 4-2
4.3 Attaching items ..........................................................4-3
4.3.1 Attach to an existing item ......................................... 4-3
4.3.2 Create an item and attach to it ................................... 4-4
4.3.3 Putting items is history storage groups ..................... 4-6
4.3.4 Items and points ........................................................ 4-7
4.3.5 Not attached signals .................................................. 4-8
4.4 Handling signal triggers ............................................4-8
4.4.1 The signalEvent() method ......................................... 4-9
4.4.2 Signal listeners .......................................................... 4-9
4.4.3 Trigger value ........................................................... 4-10
4.4.4 Accessing signals .................................................... 4-10
PROCESS/FAST Java Language Manual iii

Table of Contents
4.5 Signal attributes ...................................................... 4-11

4.6 The control item signal ........................................... 4-11
4.7 Arrays of signals ..................................................... 4-12
4.8 Signals and sub-items ............................................. 4-13
4.9 Enterprise classes and objects ................................. 4-13
5 Attributes .............................................................................. 5-1
5.1 Introduction ............................................................... 5-1
5.2 Defining attributes .................................................... 5-1
5.3 Scope ......................................................................... 5-2
5.4 Prompts ..................................................................... 5-2
5.5 Using attributes in the create() method ..................... 5-3
5.6 Accessing attributes .................................................. 5-4
5.7 Arrays of attributes ................................................... 5-4
5.8 Limitations ................................................................ 5-5
6 Timers ................................................................................... 6-1
6.1 Introduction ............................................................... 6-1
6.2 Defining Timers ........................................................ 6-1
6.3 Setting up a timer ...................................................... 6-1
6.4 Handling timer triggers ............................................. 6-2
6.4.1 The timerEvent() method .......................................... 6-2
6.4.2 Timer listeners ........................................................... 6-2
6.5 Accessing timers ....................................................... 6-3
6.6 Arrays of timers ........................................................ 6-3
7 Trigger groups ...................................................................... 7-1
7.1 Introduction ............................................................... 7-1
7.2 Handling trigger group triggers ................................ 7-1
7.2.1 The triggerGroupEvent() method .............................. 7-1
7.3 Accessing trigger groups ........................................... 7-2
7.4 Trigger groups versus Timers ................................... 7-2
8 Containment ......................................................................... 8-1
8.1 Introduction ............................................................... 8-1
8.2 The valve ................................................................... 8-1
8.3 The boiler .................................................................. 8-3
8.3.1 Filtering triggers ........................................................ 8-5
8.3.2 Trigger listeners. ....................................................... 8-6
8.4 The create() and destroy() methods .......................... 8-8
8.5 The start() and stop() methods .................................. 8-9
8.6 The ...Event() methods .............................................. 8-9
8.7 Great news .............................................................. 8-10
9 Inheritance ............................................................................ 9-1
9.1 Introduction ............................................................... 9-1
iv PROCESS/FAST Java Language Manual

Table of Contents
9.2 The boiler with mixer ................................................9-1

9.3 Accessing super definitions .......................................9-2
9.4 Method overriding .....................................................9-3
9.5 Prompts ......................................................................9-3
10 Miscellaneous ......................................................................10-1
10.1 Introduction .............................................................10-1
10.2 Lengthy trigger processing ......................................10-1
10.3 Methods ...................................................................10-2
10.3.1 Adding methods ...................................................... 10-3
10.4 Exception handling ..................................................10-5
10.5 Debugging ...............................................................10-6
10.6 Object statistics ........................................................10-6
11 Reference guide ...................................................................11-1
11.1 Introduction .............................................................11-1
Appendix A:Examples....................................................................A-1
A.1 Introduction ..............................................................A-1
A.2 The valve ..................................................................A-1
A.3 The boiler ..................................................................A-2
A.4 The twin boiler .........................................................A-3
A.5 The mixer boiler .......................................................A-4
A.6 City temperature .......................................................A-4
PROCESS/FAST Java Language Manual v

Table of Contents
vi PROCESS/FAST Java Language Manual

Manual Objectives Preface
0 Preface
0.1 Manual Objectives

• To provide system managers/integrators with an overview of the
functionality of the PROCESS/FAST Java programming language.
The PROCESS/FAST Traditional programming language is
described in the PROCESS/FAST Language Manual.

This manual is intended for system managers/integrators who wish to
write their own application software within their PROCESS/FAST
environment.
The reader is assumed to have knowledge of the FAST/TOOLS
philosophy.
The reader is assumed to have knowledge of the Traditional PROCESS/
FAST programming language. Terms like classes and object are not
covered in this manual.
The reader is assumed to be familiar with the Java programming
language in general and has knowledge about object oriented
programming in Java.

This manual contains 11 chapters and 1 appendices:
• Chapter 1 gives a short introduction to PROCESS/FAST.
• Chapter 2 supplies a simple example to get started.
• Chapter 3 explains the general structure of a class.
• Chapter 4 goes into details on how to use signals.
• Chapter 5 explains how to use attributes.
• Chapter 6 describes the timers.
• Chapter 7 described how to handle triggers from trigger groups.
PROCESS/FAST Java Language Manual 0-1

• Chapter 8 explains how to reuse classes in other classes.

• Chapter 9 explains how to make a specialization of a class.
• Chapter 10 handles miscellaneous items not covered by the
previous chapters.
• Chapter 11 supplies the reference guide.
• Appendix A lists the classes discussed in this manual and some
other examples.

1 USER/FAST User Manual.
2 PROCESS/FAST Language Manual.
0.5 Terminology
The following list contains words that have a special meaning in the
context of PROCESS/FAST.
Activation The process of getting an object to begin executing
its defined actions.
Attribute Characteristics of classes and objects that can
be seen from the outside world.
Class A generic template defining actions and
characteristics representing a particular type
of component within a plant.
Identifier A logical name used to reference data items within
a method.
Method A sequence of actions that is performed when an
object is activated.
Object An entity created from a class that represents a
specific component within a plant.
Trigger A mechanism for indicating to an object that
actions need to be performed.

0-2 PROCESS/FAST Java Language Manual

CONVENTION MEANING
() Parentheses when used in routine syntax indicates

a list of arguments that have to be passed.
<> Angle brackets when used in routine syntax

indicates a program argument.
{} Braces when used in routine syntax indicates a

program comment.

one or more times
... Indicates that not all of the statements are shown.
| Indicates that either the item to the left or to the

right of the bar may be specified



variable.

n.u. not used
output This font is used to indicate output on a terminal
input This font is used to indicate input from the user


PROCESS/FAST Java language Introduction
1 Introduction
For a general introduction to PROCES/FAST and its global

characteristics, you best can read Chapter 1 of the PROCESS/FAST
Language Manual.
1.1 PROCESS/FAST Java language

The PROCESS/FAST Java language provides a framework to program
PROCESS/FAST classes using the wide spread Java programming
language. The functionality of a class written in the Traditional language
can also be realized by writing the class in the Java language. In
addition, the full power of Java can be used to write PROCESS/FAST
classes with extended functionality. Examples of the Java language that
cannot be realized using the Traditional language are:
• Arrays of attributes, signals, and variables can be defined and used.
• Loops can be programmed.
• A class can extend an existing class (inheritance).
• The Java framework can be used, like TCP/IP communication and
many others.
An important additional function is that a defined signal does not need
to be linked to an item as opposite to the Traditional language were the
Signal declarations needs to connect to items. In the Edit Module the
signal attribute Attached can be used to detect whether an item is
attached to a signal.
Note that you cannot include PROCESS/FAST classes written in the

traditional language in classes written in the Java language and visa
versa.
1.2 Using this manual

The manual is divided into a number of chapters explaining the concepts
and usage of the language features. The last chapter contains the
reference guide.

Introduction Using this manual
For creating classes, objects and trigger groups using the Engineering
Module you have to look in the help of the Engineering Module or read
the USER/FAST User Manual.

Introduction Getting started
2 Getting started
2.1 Introduction
In this chapter an introduction is supplied to the PROCESS/FAST Java
language. We will create a simple PROCESS/FAST class using the Java
language.
2.2 Simplest example

Start the Engineering Module and add a class with the name VALVE.
Don’t forget to select Java as the language. In the code tab you can enter
the following code:
import fasttools.processfast.*;
public class VALVE extends ProcessClass {

}
Add the class and open the properties sheet of the class. On the Code tab
click compile.
Congratulations, you succeeded in creating your first PROCESS/FAST
class written in Java.
The code line import fasttools.processfast.* tells the
PROCESS/FAST compiler where it can find the PROCESS/FAST Java
framework. The PROCESS/FAST Java framework supplies the
connection between the class you are writing and the FAST/TOOLS
environment.
The code line public class VALVE extends ProcessClass declares
the name of the class and that the class uses the PROCESS/FAST Java
framework. Note that the name of the class in the declaration must be
exactly the same name as you supplied in the class creation form in the
Engineering Module.
A PROCESS/FAST Java class must extend ProcessClass, which
contains the framework, otherwise you cannot successfully compile it.
You can create objects from this class, but they won’t do anything.

Getting started Connecting to the world
2.3 Connecting to the world

In the next example we will make a connection between the class and the
world. In this case the world is the world of FAST/TOOLS and in special
‘items’.
First create an internal real item with name
ProcessFast.Manual.Items.ValveSetpoint.
Modify the code of the VALVE class to:
Signal sSetPoint = defineDoubleSignal();
public void create() {

attachItemToSignal(sSetPoint,
"ProcessFast.Manual.Items.ValveSetpoint");
}
}
The line Signal sSetPoint = defineDoubleSignal(); defines a

signal. The identifier for this signal is sSetPoint. This line only defines
a signal that can be used throughout the class. It defines a signal with a
double representation.
During creation of an object, the signal has to be connected to an item.
This is done in the create() method. The create method is called by the
framework at the moment an object is created from the class. In this
method you can connect signals to existing items or instruct the
framework to create new items and connect them to the signals.
In this example the statement attachItemToSignal(sSetPoint,
"ProcessFast.Manual.Items.ValveSetpoint") connects the
signal to the existing item with the name
ProcessFast.Manual.Items.ValveSetpoint.
Each object that you create from this class will attach to the same item.
In a subsequent chapter you will see how to instruct the framework to
create items on the fly and attach them to the signals.
2.4 Do something
The class described in the previous section just attaches the defined
signal to an existing item. An object created from the class doesn’t do
anything with the value of the item. In the next example we will change

Do something Getting started
the class in such a way that when you change the value of the item that
a message is printed to the system log with the new value of the item:
Signal sSetPoint = defineIntegerSignal(Signal.Trigger.VALUE);

attachItemToSignal(sSetPoint,
}
public void signalEvent(Signal signal) {

systemMessage("Item: " + signal.getName() +
" New value: " + signal.getValueAsInteger());
}
}
The signal definition

defineIntegerSignal(Signal.Trigger.VALUE) defines a signal
that will trigger the class if the value of the attached item is changed.
When the value of the attached item is changed then the framework calls
the signalEvent() method of the class. The framework passes the
signal identifier, that has the item attached, as an argument to the
method. In this method you can process the value of the item. In this
example we call the systemMessage() method to print the name of the
item and the value of the item that is attached to the signal, to the system
log.
You can try this example by adding an object using this class, activate
the message log and change the value of the item using the Engineering
Module.
Note that, if you change a class that has objects, you have to compile and
reset the class to make the any changed code effective. See the
Engineering Module help or read the USER/FAST User Manuel.

Getting started Do something

Introduction Class structure
3 Class structure
3.1 Introduction
In this chapter we will introduce you to the general structure of a class.
In the previous chapter you tried some simple examples and have seen
already some parts of the class structure.
3.2 Global structure

A class is divided into a number of sections, each having a purpose:
• Class declaration
In this section you declare the class.
• Attributes, signals, containments and timer definitions
In this section you defined the attributes, signals, containments and
timers that you are going to use throughout the class.
• Object creation and destroyment methods
In this section you code a number of methods that are called by the
framework when an object is created from the class and when an
object is deleted from the system. In these section you code how
signals are attached to existing items and how items are to be
created before being attached to signals.
• Object starting and stopping methods
In this section you can code methods that are called when an object
is started and/or stopped. An object is started directly after it is
created and each time the FAST/TOOLS system is started. An
object is stopped each time the FAST/TOOLS system is stopped
and directly before an object is deleted.
• Trigger processing methods
In this section you code methods to be executed when the object
receives a trigger. Examples of triggers are, the value of an item is
changed that is attached to a signal, a trigger group of the object
expires or a timer expires.
• User methods
In this section you can code your own methods to performing
certain tasks. These methods are normally called from one of the
trigger processing methods.

Class structure Global structure
In Java code the global class structure looks like:

// Class declaration
public class CLASS_NAME extends ProcessClass {
// Attributes, signals, containments and timer definitions
Attribute aAttribute = define..();

Signal sSignal = define..();
ProcessClass cContainment = define..();
Timer tTimer = define..();
// Object creation and destroyment methods

}
public void destroy() {

}
// Object starting and stopping methods
public void start() {

}
public void stop() {

}
// Trigger processing methods

}
public void triggerGroupEvent(TriggerGroup triggerGroup) {

}
public void timerEvent(Timer timer) {

}
// User methods
private void xxx(aaa) {

}
private void yyy(bbb) {

}
// Or, for example, an user method that calculates average of a signal
private void addToAverage(Signal signal) {

}

Class declaration Class structure
3.3 Class declaration

You have to enter the class declaration as follows:
<other imports>
public class <class name> extends ProcessClass {
3.3.1 Import statement
You have to add other import statements if you are using classes that are
not part of the PROCESS/FAST framework. The following classes are
part of the PROCESS/FAST framework (which is imported via the
import fasttools.processfast.*; statement):
• ProcessClass
Contains the PROCESS/FAST framework. All PROCESS/FAST
classes must derive from this class using the extends modifier.
• Attribute
Contains the value of an attribute. Attributes must be defined in the
Attributes, signals, containments and timer definitions section of
your class. You can read more about attributes in Chapter 5.
• Signal
Contains the attached item. Signals must be defined in the
your class. You can read more about signals in Chapter 4.
• SignalListener
If the value of an item is changed that is attached to a signal then
the framework will call the signalEvent() method of your class.
The signalEvent() method will be called for all signals you have
defined in your class. In addition, you can add, a so called, trigger
listener to your signal that only will be called if the value of the
attached item of this signal is changed. You can read more about
signal listeners in Section 4.4.
• Timer
Contains the parameters of a timer. Timers must be defined in the
your class. You can read more about timers in Chapter 6.

Class structure Attributes, signals, containments and timer definitions
• TimerListener
If a timer expires then the framework will call the timerEvent()
method of your class. The timerEvent() method will be called
for all expiring timers you have defined in your class. In addition,
you can add, a so called, trigger listener to your timer that only will
be called if this timer expires. You can read more about timer
listeners in Section 6.4.
• TriggerGroup
Contains the definition of a trigger group. You cannot define
trigger groups in your class. Trigger groups are created and
assigned to objects using the Engineering Module. The trigger
group that triggers a class is passed as an argument to the
triggerGroupEvent() method. You can read more about trigger
groups in Chapter 7.
• ObjectStatistics
Contains the statistics of an object like the average method
exceution time, the number of processed triggers and how many
triggers were lost. You can obtain these statistics using the
getStatistics() method in any method within your class except
the create() and destroy() methods. You can read more about
object statistics in Section 10.6.
If you use any other class in your class you must import it with the
import statement. For example if you use ArrayList of the standard
Java framework you must import it with:
import java.util.ArrayList;
The Java framework is known by the PROCESS/FAST framework.

Thus you can use all the functionality supplied by the standard Java
framework in your class.
3.3.2 Extends statement
Your class is declared by:

public class <class name> extends ProcessClass
where you pass for <class name> the name of the PROCESS/FAST
class as entered in the Class definition form of the Engineering Module.
3.4 Attributes, signals, containments and

Object creation and destroyment methods Class structure
timer definitions
You have to define attributes, signals, containments and timers before
any method. Java type modifiers like protected or public are not
allowed with these definitions:
public Signal sMySignal = define...(); // Not allowed
You are also not allowed to define attributes, signals, containments and
timers within methods:
public Signal sMySignal = define...(); // Not allowed
}
3.5 Object creation and destroyment

methods
The method create() is called at the moment you create an object from
your class. It is called by the framework to attach items to the signals
and/or to create items from item templates and attach these to the
signals.
An exiting item is attached to a signal using the method
attachItemToSignal() and you create an item and attach it to a
signal using the method createItemForSignal(). These two methods
are discussed in Chapter 4.
The destroy() method is called when you delete an object from FAST/
TOOLS. You do not need to call methods to detach items from the
signals. The framework takes care of that. In fact there are no methods
available for your purpose in the framework to do so.
You will ask yourself, why is the destroy() method there? Maybe you
have to cleanup things. For example, you put a record in a dataset while
the create() method is called and need to remove this record in the
destroy() method. If the body of the destroy() method is empty you
can leave the whole method away from your class. Thus, when the
framework can’t find the destroy() method in your class it will just
continue with the default actions as mentioned above.
Note: The following paragraph is very important.
If you are not aware of the information
supplied in this note then you may expect
certain behavior which is not true.

Class structure Object creation and destroyment methods
The create() and destroy() methods are called from a different

environment as all others methods in your class including the start()
and stop() methods. With other words, objects are created and
destroyed in a different environment from where objects are started,
handle triggers and are stopped. The first environment is called the
Object creation environment while the latter environment is called the
Object runtime environment.
This means that:
• Signals have only items attached in the runtime environment. Thus
the signal method getValueAsInteger() works only in the
runtime environment.
• The value of attributes is remembered between the creation
environment and runtime environment. Thus, when you give an
attribute a certain value in the create() method, then this value
will be there in the other methods.
• Timer methods can only be called in the runtime environment.
• Any other Java object created in the creation environment will only
exist during the creation and doesn’t exist any more in the runtime
environment.
• A value given to a standard Java primitive like an int or double in
the create() method will not be there in the runtime environment
and in the destroy() method.
Static declarations of objects and primitives like static boolean

myStaticValue; may have different values between the creation and
runtime environment. It is even worse, they may have even different
value between the object created from your class. This, because, an
object that is created from your class will be running in a different
runtime environment than another object that is created from the same
class if these objects have different priorities. The only way to share
information between all objects created from your class is to use an
attribute with a class scope or to use signals that attach to the same item
for all object that are created from your class or to write Java code
outside the FAST/TOOLS environment (see the last paragraph in
Section 10.3).

Object starting and stopping methods Class structure
3.6 Object starting and stopping methods

The methods start() is called when the object is started after creation
or when the FAST/TOOLS system is started. You can program, for
example, certain initialization in this method. The stop() method is
called when FAST/TOOLS stops. It is not guaranteed that the stop
method is called. In cases of a high availability configuration, then the
stop() method is not called when the active server shuts down. The
start() method is always called. You can omit these functions from
your class if you don’t use them. An example of using the start() method
is discussed in SubSection 4.4.2.
3.7 Trigger processing methods

When an object starts then the start() method is called. From that
point no methods are executed until a certain trigger occurs. Triggers
that can occur are:
• The value (or other attribute) of an item attached to signal of your
class is changed. The framework will call the signalEvent()
method and passes the signal of the attached item as an argument to
this method.
It is also possible that you add a trigger listener to the signal that
will be called if the value of the attached item is changed. If you
attach a trigger listener you must do that in the start() method.
• When a trigger group, that is defined for the object, expires then the
triggerGroupEvent() method is called. The trigger group that
expired is passed as an argument to this method.
• When a timer expired then the timerEvent() method is called.
The timer that expired is passed to the timerEvent() method.
When such a trigger occurs then the related trigger methods are not
called immediately. The trigger is queued by the framework and as soon
as possible the related method of your object is called. There can be
some time between the occurrence of the trigger and calling the trigger
method when many trigger occur and need to be processed.
You must make sure that your trigger method return as quick as possible.
Otherwise it will holdup execution of objects that have the same priority.
In Section 10.2 we will see how to handle time consuming processing in
your trigger methods. But for now, never sleep in your trigger method.

Class structure User methods
3.8 User methods

Of course you can add as many user method as required to avoid
duplicated code and to make your code more readable. Normally your
user methods are private to your class:
private void addToAverage(Signal signal) {
// Do something
}
If you are using inheritance or containment you can make your functions
public so that it can be called from the extending class or the containing
class:
public void addToAverage(Signal signal) {
// Do something
}
You can read more about user methods in Section 10.3.

Introduction Signals
4 Signals
4.1 Introduction
In this chapter we will go into more detail in how to define signals, how
to attach existing items to the signals, how to create items from a
template and attach them to signals, how to obtain the values of the item
attributes and how to set new values for the item attributes.
We also will discuss how to use the signalEvent() method and how
to use signal listeners.
4.2 Defining signals

You define signals as following:
Signal sSignal = define...();
sSignal is the identifier for the signal which you use through out your
class. It is advised to start the signal identifier with the lower case letter
s. This way you can easily identify the signal in the class editor while
you are editing the class.
The length of a signal identifier may not exceed the 15 characters.
The value of the connected item is stored by the framework in the signal
in one out of three representations:
• Integer
The value is stored as an integer value having the range of -
2147483648 up to 2147483647.
• Double
The value is stored as a double precision floating point value.
• String
The value is stored as a string. The maximum length of the string is
79 characters.

Signals Defining signals
Normally you define a representation for the signal that matches the
representation of the item you are going to connect to the signal:
Table 1: Advised signal representation
Item representation Signal representation
Boolean Integer
Integer Integer
Real Double
String String
However, if the representation of the signal doesn’t match the

representation of the item then the framework will convert the value to
the correct representation.
For each signal representation you use a different define method:
Table 2: Signal definition methods
Method Description
defineIntegerSignal() Defines a signal with the integer representation
defineDoubleSignal() Defines a signal with the double representation
defineStringSignal() Defines a signal with the string representation
The next example shows the definition of an integer signal:

Signal sMyIntSignal = defineIntegerSignal();
4.2.1 Signal triggers
When you define a signal with one of the methods described in the
previous section then your class will not receive a trigger if the value of
the connected item of the signal is changed. If you want your class to
receive a trigger when the value changes you must pass an argument to
the define...()method that informs the framework that you are
interested in triggers. For example:
Signal sMySignal = defineIntegerSignal(Signal.Trigger.VALUE);
In this example your class will receive a trigger when the value of the
item connected to the signal is changed.

Attaching items Signals
The next table shows the trigger types you can use:
Table 3: Signal trigger types
Trigger Description
Signal.Trigger.VALUE The value of the item is changed
Signal.Trigger.STATUS The status of the item is changed
Signal.Trigger.OPTION The option status of the item is changed
Signal.Trigger.UPDATE The item is updated
Signal.Trigger.FIRST The item is updated the first time after starting
FAST/TOOLS
Signal.Trigger.PIT The value of the items passes the PIT filter of
the item
Signal.Trigger.LIMIT One of the limits of the item is changed
Signal.Trigger.QUALITY The quality of the item is changed
You can combine triggers using a bitwise or. For example:

Signal sMySignal = defineIntegerSignal(Signal.Trigger.VALUE |
Signal.Trigger.STATUS |
Signal.Trigger.OPTION);
In this example the class will be triggered if the value, status or option
status of the connected item is changed.
In Section 4.4 we will see how you can response to signal triggers in
your class.
4.3 Attaching items

To do something with the signals that you have defined, you have to
attach them to existing items or let the framework create items and attach
them.
4.3.1 Attach to an existing item
In the create() method you use the attachItemToSignal() method

to attach an existing item to a defined signal. For example:
attachItemToSignal(sSignal,

Signals Attaching items
In this example the existing item with the name

ProcessFast.Manual.Items.ValveSetpoint is attached to the
signal which identifier name is sSignal.
If the item doesn’t exist then the creation of the object is aborted and any
item that is already created by the framework is deleted from FAST/
TOOLS and all connections already made for the object are removed.
In this case an error box will popup in the Engineering Module.
4.3.2 Create an item and attach to it
In the create() method you use the createItemForSignal()

method to create an item and attach it to the signal. For example:
createItemForSignal(sSignal, "ProcessFast.Manual.ItemTemplates.Setpoint",
"NAME", "ProcessFast.Manual.Items.ValveSetpoint");
In this example the item with the name

ProcessFast.Manual.Items.ValveSetpoint is created using item
ProcessFast.Manual.ItemTemplates.Setpoint as a template and
after creation the item is attached to the signal which identifier name is
sSignal. The framework performs the following steps to do so:
• The definition of the template item is read.
• All fields of the item as listed in the createItemForSignal()
method will be modified to a value as specified (explained further
on).
• The item with the modified field values is inserted into the FAST/
TOOLS system.
• The item is attached to the signal.
If one of these steps fails then creation of the object is aborted and any
item that is already created by the framework is deleted from FAST/
TOOLS and all connections already made for the object are removed.
As listed in the bullet list before, you can change the value of more fields
in the createItemForSignal() method. For example:
"NAME", "ProcessFast.Manual.Items.ValveSetpoint",
"DESCRIPTION", "The setpoint of the valve",
"SCALE_LOW_LIMIT", 0.0,
"SCALE_HIGH_LIMIT", 1.0);
In this example the newly created item will have a description, scale low
limit and scale high limit as listed. Note that the order of fields, with their
value, is not important.

You can use any item field as defined in the ITEM_DF dataset. You can
use Reference search -> Available datasets -> ITEM_DF ->
List field properties in the Engineering Module to get a list of all
the fields of the ITEM_DF that you can update in the
createItemForSignal() method.
You have noticed that for all objects, that you have created from this
class, an attempt is made to create items which will all have the name
ProcessFast.Manual.Items.ValveSetpoint. The framework will
detect that this item already exists and was created before for this class
and will connect this same item to the signal with the identifier sSignal
for all objects. E.g. all objects will be connected to the same item. Of
course you want to create for each object a different item and attach to
it. The next example shows how you can realize this:
"NAME", "ProcessFast.Manual.Items." +
getTag() + "_ValveSetpoint",
In this example the method getTag() is used which returns the tag name
of the object being created. The tag name of the object name is the last
element of the full object name. If the full name of the object is
Section1.Section2.MyObject then getTag() returns MyObject.
Thus the name for the item being created will be
ProcessFast.Manual.Items.MyObjec_ValveSetpoint.
Another example is:
"NAME", getSectionsPath() + ".Items.ValveSetpoint",
In this example the method getSectionsPath() is used which returns

the section path of the object that is being created. Thus if the name for
the object is Section1.Section2.MyObject then the name for the
item will be Section1.Section2.Items.ValveSetpoint.
You must create the section Section1.Section2.Items manually
using the Engineering Module or use the createSection() method to
let the framework create the section. The third option is that the
framework creates the name for the item automatically (see Section 8.7).
Note: The PROCESS/FAST Java framework cannot
undo sections created using the
createSection() method. However, all
sections created automatically by the
framework method createSignalFor() are

Signals Attaching items
deleted automatically. In general using the

createSignalFor() method is preferred and the
use of createSection() should only be used in
special cases.
For all fields in the createItemForSignal() method you can use
similar constructions.
When you delete an object, then the framework will delete all items from
the FAST/TOOLS system that were created by the framework for the
object (unless you checked Leave items: for the object properties
using the Engineering Module).
4.3.3 Putting items is history storage groups
While the framework creates an item using the method

createItemForSignal(), it can also put the item in a maximum of 4
different storage groups. For example:
"NAME", getSectionsPath() + "Items.ValveSetpoint",
"SCALE_HIGH_LIMIT", 1.0,
"GROUP_NAME", "MY_EVENT_GROUP",
"ON_VALUE_CHANGE", true,
"ON_STATUS_CHANGE", true,
"GROUP_NAME", "MY_SCAN_GROUP",
"STORE_VALUE", true);
In this example the item is put in the storage group MY_EVENT_GROUP

which is event based (defined using the Engineering Module). If the
value or status of the item is changed then the value and status of the item
is added to the storage.The item is also put in a second scan based
storage group. At each scan interval of the storage group then the value
is added to the storage.
You can use any item storage field as defined in the ITEM_HIS_DF
dataset. You can use Reference search -> Available datasets -
> ITEM_HIS_DF -> List field properties in the Engineering
Module to get a list of all the fields of ITEM_HIS_DF you can use in the
createItemForSignal() method.
When you delete an object, then the framework will delete all items from
the storage groups to which the items were added to by the framework
for the object.
Note that the order of fields in this case is important:

"GROUP_NAME", "MY_EVENT_GROUP",
"ON_VALUE_CHANGE", true,
"ON_STATUS_CHANGE", true,
ON_VALUE_CHANGE and ON_STATUS_CHANGE are used the first storage

group MY_EVENT_GROUP".
"GROUP_NAME", "MY_SCAN_GROUP",
"STORE_VALUE", true);
STORE_VALUE is used for the second storage group MY_SCAN_GROUP.
4.3.4 Items and points
Of course you also want the createItemForSignal() method to

create items which are connected to equipment via points. There are two
ways for it:
• Use a template item that has a point associated to it. The item to be
created will get the same characteristics as the item with associated
point except the fields you modify with the
createItemForSignal() method,
• Use a template item and a template point. The new item will get the
same characteristics as the template item and the new point will get
the same characteristics as the template point except the fields you
modify with the createItemForSignal() method.
In both cases the framework will first create a point and then an item that
relates to the point.
For example:
createItemForSignal(sSignal, "ProcessFast.Manual.ItemTemplates.Position",
"NAME", getSectionsPath() + ".Items.ValvePosition",
"ITEM’DESCRIPTION", "The position of the valve",
"STATION", "MY_STATION",
"IO_ADDRESS", "RI:12");
First of all notice "ITEM’DESCRIPTION", "The position of the

valve". As soon as you want to create points then the POINT_DF dataset
will also be accessed by the framework. Both ITEM_DF and POINT_DF
have the description field. Thus you have to specify which description
you mean, the description of the item or the description for the point.
You can use both:
"POINT’DESCRIPTION", "The point for position",
Back to the createItemForSignal() example. The template item you

use here is an item related to a point for a modbus station. This example
creates a point, which will get the same name as the item but enclosed
between square brackets, it will be a copy of the point related to the

Signals Handling signal triggers
template item and its station will become MY_STATION and the io
address will become RI:12. Then the item is created that reference the
point just created. Note that the station MY_STATION must already exist
and must be a modbus station.
You can modify also other fields of the point. Note, that these fields
depend on the station type. For modbus stations you can use the fields of
the MODBUS_POINT_DF datasets. If your template point is an OPCDAC
point then you must use the fields of dataset OPCDAC_POINT_DF.
In this example the template item relates to a point by itself. In the next
example you use a template item that has no relation to a point and you
separately specify a template point to be used:
createItemForSignal(sSignal,
"ProcessFast.Manual.ItemTemplates.Position;TEMPLATE_STATION:ANALOG_INPUT",
"NAME", getSectionsPath() + "Items.ValvePosition",
"STATION", "MY_STATION",
Note that the template point TEMPLATE_STATION:ANALOG_INPUT is

separated from the template item
ProcessFast.Manual.ItemTemplates.Position by a ;.
How the point is created and linked to the item is exactly the same as
using the first method.
4.3.5 Not attached signals
In opposite to the Traditional language you do not need to attach an item

to a signal. When, no item is attached, it won’t trigger the class and most
of the methods of the signal will throw an exception. You can use the
signal method isAttached() to detect whether or not an item is
attached to the signal:
if (sSignal.isAttached()) {
// Do something because there is an item attached to the signal.
}
In the Edit Module you can use the Attached attribute of a signal to
detect whether or not an item is attached to the signal.
4.4 Handling signal triggers

If you have specified in the definition of a signal that it should trigger
the class, if an attribute of the attached item is changed, then the

Handling signal triggers Signals
framework will call the signalEvent() method. You can also add a,
so-called, signal listener to the signal.
4.4.1 The signalEvent() method
The signalEvent() method is called if the class receives a trigger for

a signal. The identifier of the signal that is the cause of trigger is passed
as the argument to the method. You can use the equals (==) operator in
the method to detect the signal that caused the trigger if more than one
signal can trigger the class:
Signal sBoilerTemp = defineDoubleSignal(Signal.trigger.VALUE);
Signal sBoilerFlow = defineDoubleSignal(Signal.trigger.VALUE);
...

if (signal == sBoilerTemp) {
// Handle change of boiler temperature
} else if (signal == sBoilerFlow) {
// Handle change of boiler flow
}
}
4.4.2 Signal listeners
In the previous SubSection you saw that the signalEvent() method is

called for triggers on all signals. In the signalEvent() method you
have to detect which signal did cause the trigger and handle accordingly.
Instead of using this method you can add a private signal listener that
will be called only if this signal triggers the class:
Signal sBoilerFlow = defineDoubleSignal(Signal.trigger.VALUE);
...

// We don’t use is
}

sBoilerTemp.addSignalListener(new TempListener());
sBoilerFlow.addSignalListener(new FlowListener());
}
private class TempListener implements SignalListener {
// Handle triggers of sBoilerTemp
}
}
private class FlowListener implements SignalListener {
// Handle triggers of sBoilerFlow
}
}

Signals Handling signal triggers
Normally you add the signal listener to a signal in the start() method
that is called by the framework when the object starts running. You can
use the method removeSignalListener() to remove a listener any
time. The most appropriate place to do so is in the stop() method of the
class. However, this is not required because the framework will remove
any signal listener left over.
It is not allowed to use anonymous signal listeners as demonstrated in
the next example:
sBoilerTemp.addSignalListener(new SignalListener() {
// Handle triggers of sBoilerTemp
}
});
Unfortunately, the framework is not capable to detect such a coding

error at an early stage. You can successfully compile the class and create
an object from it. However the framework will output an error to the
system log when the object is started. For example.
--> From: OPCJEXE00 (Node 220/Task -1) on Mon Feb 18 16:19:23 2013
UMH-I-INFO, (java.lang.NoClassDefFoundError: VALVE$1)
UMH-I-INFO, (Error while running object: Section1.Boiler5.InputValve)
UMH-I-INFO, (At: VALVE:start():21)
When using the signalEvent() method or a signal listener? Normally

you use the signalEvent()method unless you have intentions to use
your class as a containment in another class. We will discuss this in
Chapter 8.
4.4.3 Trigger value
In both the signalEvent() method and signal listeners, the signal

passed to signalEvent()and the signal listener will have the value of
attributes, like value and status, at the moment the value or status of the
connected item was changed.
4.4.4 Accessing signals
In both the signalEvent() method and signal listeners you can access,
besides the trigger signal passed to the method, all other signals you
have defined. For example:
Signal sGasValve = defineDoubleSignal();
...

Signal attributes Signals

if (signal == sBoilerTemp) {
if (signal.getValueAsDouble() > 95.0) {
sGasValve.setValue(0.0)
}
}
}
In this example signalEvent() is called if the temperature in the boiler

changes. If the temperature exceeds the 95.0 degrees celsius then we
shut down the gas valve. Therefore we access the signal sGasValve.
4.5 Signal attributes

An item has many attributes. We can access these item attributes via the
attributes of the associated signal. All of the attributes can be obtained
and a number of them can be set. You can access these attributes using
the methods of the signal. For example:
double mValue = signal.getValueAsDouble();
signal.setValueAndStatus(12.5, Signal.Status.MANUAL);
}
In this example we obtains the value of the signal as a double and we set
a new value and status.
In Chapter 11 of this document you will find all the methods of a signal.
4.6 The control item signal

When you create an object using the Engineering Module you can pass
the name of an existing item as the control item for the object.
Using this control item you can temporary suspend execution of the
object by setting the status of the control item to Blocked. While the
object is suspended, all triggers for the object as ignored.
In your class you can determine whether a control item is attached to
your object:
if (hasControlSignal()) {
Signal mControlSignal = getControlSignal();
mControlSignal.setValue(0.0);
}
In this example hasControlSignal() returns true if there is a control

item defined for the object. If true we set the value of the control item to

Signals Arrays of signals
0.0 by obtaining the signal associated with the control item an calling the
setValue() method of the signal.
4.7 Arrays of signals

You can handle a large number of items by defining an array of signals
and attach items to the elements of this array:
Signal[] sManySignals = defineDoubleSignalArray(10);
In this example we define an array of double signals of 10 elements. If

you want the signals to trigger the class then use:
Signal[] sManySignals = defineDoubleSignalArray(Signal.Trigger.VALUE, 10);
In the create() method you can attach existing items to the signals or
create new items and attach them:
for (int i = 0; i < sManySignals.length; i++) {
createItemForSignal(sManySignals[i],
"ProcessFast.Manual.ItemTemplates.Setpoint",
"NAME", "ProcessFast.Manual.Items.Array_" + i,
// other fields);
}
}
In the next example the value of one of the elements of the signal array
is set:
sManySignals[4].setValue(50);
If you have defined that you are interested in triggers then the signal
element who’s items attribute was changed is passed to the trigger
method:

if (signal == sManySignals[4]) {
// Do something
}
}
In the start() method you can also add a trigger listener to each
element of the signal array:

sManySignals[4].addSignalListener(new TempListener());
}
Note that a class can have a maximum of 4095 signals, including

contained classes and inherited classes (which are discussed in Chapter
8 and Chapter 9).

Signals and sub-items Signals
4.8 Signals and sub-items

You can also attach signals to existing sub-items or create sub-items
from templates and attach a signal to it.
To create a sub-item, the template item must be a sub-item. If you create
a sub-item than its main item must already exist or have been created
prior creation of the sub-item in the create() method.
You can find the fields you can modify in the SUB_ITEM_DF dataset.
4.9 Enterprise classes and objects

For a description of enterprise classes and objects read Section 9.6 and
Subsection 14.3.7 of “PROCESS/FAST Language Manual“. Example 5
supplied in Subsection 14.3.7 will be for a Java class:
createItemForSignal(my_signal, "AREA.PLANT.TEMPLATES.INPUT_INTEGER",
"ITEM’DESCRIPTION", "The level of the tank",
"STATION", "STATION_12",
"IO_ADDRESS", "RI:12",
"ALARMING", true,
"GROUP_NAME", "ITEM_SCAN_GRP",
"STORE_VALUE", true,
"GROUP_NAME", "ITEM_EVENT_GRP",
"CREATE_ITEM", "MASTER_AND_DELEGATE",
"PUT_IN_HISTORY", "MASTER_ONLY",
"ALARM_DETECTION", "DELEGATE_ONLY");

Signals Enterprise classes and objects

Introduction Attributes
5 Attributes
5.1 Introduction
An attribute is a kind of variable that holds a value. The special thing
about an attribute is that you use it to pass a value to an object to be
created. For example, you have defined a valve class and at the moment
you create an object from this class you want to pass it the name of a
station where the point should be created for the valve.
Another usage is that attributes will remember the value between
subsequent FAST/TOOLS starts.
In this chapter you will see how to define attributes and how to use them.
5.2 Defining attributes

You define attributes as following:
Attribute aAttribute = define...();
aAttribute is the identifier for the attribute which you use through out
your class. It is advised to start the attribute identifier with the lower case
letter a. This way you can easily identify the attribute in the class editor
while you are editing the class.
The length of an attribute identifier may not exceed the 15 characters.
The value of an attribute is stored within the attribute and can be one of:
• Integer
The value is stored as an integer value having the range of -
2147483648 up to 2147483647.
• Double
The value is stored as a double precision floating point value.
• String
The value is stored as a string. The maximum length of the string is
255 characters.
Although you specify the representation of the attribute during
definition time, you can put an integer, double or string in any type of
attribute. The framework will convert the value you want to set to the
representation of the attribute.

Attributes Scope
For each attribute representation you use a different define method:

Table 4: Attribute definition methods
Method Description
defineIntegerAttribute() Defines an attribute with the integer representation
defineDoubleAttribute() Defines an attribute with the double representation
defineStringAttribute() Defines an attribute with the string representation
The next example shows the definition of a double attribute:

Attribute sMyAttribute = defineDoubleAttribute(Attribute.Scope.OBJECT);
As you can do with signals, you cannot let a change of the value of an
attribute trigger the class.
5.3 Scope
In the previous example you saw
defineDoubleAttribute(Attribute.Scope.OBJECT). This means
that the attribute will contain a value for each object privately. Thus, the
value of the attribute can be different for each object.
The scope Attribute.Scope.CLASS you use to define an attribute
which value is shared between all objects created from the class. They
all share the same value. You can use a class scope attribute to change
the behavior of all objects created from the class.
5.4 Prompts
As mentioned before you can use attributes to pass information to the
object being created. For this purpose you can define a prompt. A
prompt is a question that will be raised at the moment you create an
object from the class. The answers to the prompts are stored in attributes
and passed to the framework were you can access them in the create()
method. But you must specify that an attribute is intended to receive the
prompt response in its definition:
Attribute aStation = defineStringAttributeForPrompt("Station name:");
In this example the attribute aStation will receive the value of the
response to the prompt Station name:. It will continue to have this

Using attributes in the create() method Attributes
value until the object is deleted or a new value is assigned to the attribute
in your class or via the Engineering Module.
Notice that we didn’t supply a scope in the
defineStringAttributeForPrompt() method. Attributes associated
with prompts will always be of the scope OBJECT.
5.5 Using attributes in the create() method

A very important usage of attributes is that you associate them with
prompts and use them to control how items are created and attached to
signals in the create() method of the class.
For example:
...

if (aStation.getValueAsString().isEmpty()) {
cancel("Please supply a station name");
}
createItemForSignal(sSignal,
"ProcessFast.Manual.ItemTemplates.Position",
"NAME", getSectionsPath() + ".Items.ValvePosition",
"STATION", aStation.getValueAsString(),
}
First of all we obtain the value of the attribute and check whether a
response has been given to the prompt by checking if the string is empty.
If empty we call the cancel() method. The cancel() method will
cancel object creation and outputs the message supplied, to the user of
the Engineering Module. When object creation is cancelled then any
point or item created so far by the framework for the object will be
removed from the system.
You see, that we pass the value of the attribute to set the STATION field
for the point.
In this example we use only one attribute. But, you can use as many
different attributes as required. A maximum of 100 prompts are
available.
The cancel() method we used over here can be used in any other
method of the class. If used else were, it stops further processing of the

Attributes Accessing attributes
trigger and the message supplied will be outputted to the system log. The
framework continues processing of a next trigger.
You can also use the method systemMessage() to sent a message to
the system log, however, systemMessage() doesn’t stop further
processing of the trigger.
In the next example we use an attribute to count how many times the
object has been started:
Attribute aStarted = defineIntegerAttribute(Attribute.Scope.OBJECT);
...

aStarted.setValue(aStarted.getValueAsInteger() + 1);
}
You can use the Engineering Module to see the value of this attribute.
5.6 Accessing attributes

There are a number of methods available you can use to obtain the value
of an attribute and there is one method to set the value of an attribute.
We have seen them being used in the previous examples.
5.7 Arrays of attributes

You can handle a large number of attributes by defining an array of
attributes:
Attribute[] sManyAttrs =
defineStringAttributeArray(Attribute.Scope.OBJECT, 10);
In this example we define an array of attributes with 10 elements.

In the next example the value of one of the elements of the attribute array
is set:
sManyAttrs[4].setValue(50);
Note that a class can have a maximum of 4095 attributes, including

contained classes and inherited classes.

Limitations Attributes
5.8 Limitations
Attributes are meant to pass responses to prompts to the object being
created and to store rarely changing information. For process control
you use points, items and signals.
Setting the value of an attribute in your class is a heavy load compared
to setting the value of a signal. In special, setting the value of a class
scope attribute. Its value has to be stored on disk and be passed to all
runtime environments where the class has objects running.

Attributes Limitations

Introduction Timers
6 Timers
6.1 Introduction
You use a timer to trigger the class again after a certain time. An
example for its usage is that, after switching a valve open or closed you
want to check whether the valve has really opened or closed.
6.2 Defining Timers

You define times as following:
Timer tTimer = defineTimer();
tTimer is the identifier for the time which you use through out your
class. It is advised to start the timer identifier with the lower case letter
t. This way you can easily identify the timers in the class editor while
you are editing the class.
The length of a time identifier may not exceed the 15 characters.
A timer cannot be used in the create() and destroy() methods.
6.3 Setting up a timer

In the previous example you saw how a timer is defined. In a method you
can activate the time in the following way:
tMyTimer.setTime(10);
tMyTimer.start();
In this example we set the timer to 10 seconds and start it. After 10
seconds it will generate a trigger and the framework will call the
timerEvent() method and passes the identifier of the timer that
expired to this method.
Instead of using setTime() and the start() methods you can use:
tMyTimer.start(10);
This example sets the delay to 10 seconds and starts the timer
immediately.

Timers Handling timer triggers
You can set the timer to repeatedly generate triggers:

tMyTimer.setRepeat(true);
tMyTimer.setTime(10);
tMyTimer.start();
You can cancel a timer using the cancel() method of the timer.
Note that the resolution of the timer is one second. This means that when
you start a timer, that the time to the first trigger may take one second
longer than you expect. When set to repeat, then the intervals of the
subsequent triggers correspond with the interval time.
6.4 Handling timer triggers

When a timer expires the framework will call the timerEvent()
method. You can also add a, so-called, timer listener to the timer.
6.4.1 The timerEvent() method
The timerEvent() method is called when a timer expires. The

identifier of the timer that expired is passed as the argument to the
method. You can use the equals (==) operator in the method to detect the
timer that caused the trigger if more than one timer is used:
Timer tValveCheck = defineTimer();
Timer tFlowCheck = defineTimer();
...

if (timer == tValveCheck) {
// Check whether the valve did close or open
} else if (timer == tFlowCheck) {
// Check whether the flow is as expected
}
}
6.4.2 Timer listeners
In the previous sub section you saw that the timerEvent() method is
called for triggers on all timers. In the timerEvent() method you have
to detect which timer expired.
Instead using this method you can add a private timer listener that will
be called only if this timer expires:
Timer tValveCheck = defineTimer();
Timer tFlowCheck = defineTimer();

Accessing timers Timers
...

// We don’t use is
}

tValveCheck.addTimerListener(new ValveListener());
tFlowCheck.addTimerListener(new FlowListener());
}
private class ValveListener implements TimerListener {
// Check whether the valve did close or open
}
}
private class FlowListener implements TimerListener {
// Check whether the flow is as expected
}
}
Normally you add the timer listener to a timer in the start() method
that is called by the framework when the object starts running. You can
use the method removeTimerListener() to remove a listener any
time. The most appropriate place to do so is in the stop() method of the
class. However, this is not required because the framework will remove
any timer listener left over when the object is stopped.
It is not allowed to use anonymous timer listeners as demonstrated in the
next example:
tValveCheck.addTimerListener(new TimerListener() {
// Timer expired
}
});
6.5 Accessing timers

There are a number of methods available you can use to control the
timer. In Chapter 11 you will find a description of the timer methods.
6.6 Arrays of timers

Arrays of timers are not possible.

Timers Arrays of timers

Introduction Trigger groups
7 Trigger groups
7.1 Introduction
Trigger groups cannot be defined in your class. You create them using
the Engineering Module and assign them to your classes or objects.
When a trigger group expires it triggers all the objects of the class or
specific objects. This depends on to which classes and objects you
assigned the trigger group to. See the Engineering Module help on how
to create and use trigger groups or read the USER/FAST User Manual.
7.2 Handling trigger group triggers

When a trigger group expires the framework will call the
triggerGroupEvent() method.
7.2.1 The triggerGroupEvent() method
The triggerGroupEvent() method is called when a trigger group

expires. The framework passes an identifier of a trigger group to this
method. This identifier only exists in the triggerGroupEvent()
method and cannot be access else were except, of course, if it is passed
to a user method.
if (triggerGroup.getName().equals("EACH_MINUTE")) {
// Handled that we are triggered by the
// trigger group with the name EACH_MINUTE
}
}
In this example we use the getName() method of the trigger group to

obtain the name of the trigger group that triggered the object. We can use
the method getInterval() which returns the interval of the trigger
group (in seconds). Note that this method returns specialized values that
indicate special intervals:
if (triggerGroup.getInterval() == TriggerGroup.Interval.ONE_MONTH) {
// Handled that we are triggered by the
// trigger group with an interval of 4 months
}

Trigger groups Accessing trigger groups
A trigger group of type ONCE will trigger the object once at start of the
object. You don’t need to use this type of trigger group because you can
use the start() method of your class.
7.3 Accessing trigger groups

There are a number of methods available you can use to obtain
information about the trigger group that triggered your class. In Chapter
11 you will find a description of the trigger group methods.
7.4 Trigger groups versus Timers

The best practise is that you use trigger groups when your class needs
the be triggered continuously with a certain interval. You use a timer
when you need your class to be triggered after a while after processing
of, for example, a signal trigger.

Introduction Containment
8 Containment
8.1 Introduction
You have a boiler that contains two valves. You can create a single class
that controls the whole boiler. But, you will end up in coding the
behavior of both valves in your boiler. Now we can introduce
containment. You write a single class that controls a single valve. Then
you write the class for your boiler and you include the valve class twice
in your boiler class. Your boiler class will contain two valves. Now you
know where the term containment comes from.
In this chapter we will discuss containment by working out this boiler
example with you.
8.2 The valve

In the next class we control a valve. The goal of this control is to issue
an alarm if the valve doesn’t react in time to an open or close command:
Signal sSetPoint = defineDoubleSignal(Signal.Trigger.VALUE);

Signal sPosition = defineDoubleSignal();

Attribute aRegister = defineStringAttributeForPrompt("Register number:");
Timer tCheckTime = defineTimer();

String mStation = aStation.getValueAsString();
String mRegister = aRegister.getValueAsString();
if (mStation.isEmpty()) {
cancel("Missing station name");
}
if (mRegister.isEmpty()) {
cancel("Missing register number");
}
String mSectionPath = getSectionsPath() + "." + getTag();
createSection(mSectionPath, "The section for the items of the valve",

"", false, true);
createItemForSignal(sSetPoint,
"ProcessFast.Manual.ItemTemplates.RealAnalogOutput",

Containment The valve
"NAME", mSectionPath + ".Setpoint",

"ITEM'DESCRIPTION", "Valve setpoint",
"POINT'DESCRIPTION", "Valve setpoint",
"STATION", mStation,
"IO_ADDRESS", "RO:" + mRegister,
"ALARMING", true,
"ITEM_STAT_1", "FAILED",
"ALARM_STATE_1", "Alarm 1",
"ALARM_TEXT_1", "Valve didn't respond in time");
createItemForSignal(sPosition,
"ProcessFast.Manual.ItemTemplates.RealAnalogInput",
"NAME", mSectionPath + ".Position",
"ITEM'DESCRIPTION", "Valve position",
"POINT'DESCRIPTION", "Valve position",
"IO_ADDRESS", "RI:" + mRegister);
}

tCheckTime.start(60);
}

if (sSetPoint.getValueAsDouble() != sPosition.getValueAsDouble()) {
sSetPoint.setStatusNumber(Signal.Status.FAILED);
}
}
}
Before you can try this example make sure that you create the two
template items
ProcessFast.Manual.ItemTemplates.RealAnalogOutput and
ProcessFast.Manual.ItemTemplates.RealAnalogInput.
Both have a related Modus station point. The first one is connected to a
template Modbus analog output point. The second one is connected to a
template Modbus analog input point.
We create a section to put the items of the valve in with
createSection(). If we create an object with the name
Section1.Section2.ValveObject then we create a section with the
name Section1.Section2.ValveObject and in this section the items
Setpoint and Position will be places. Note that when the object is
deleted that the framework deletes the section we created over here.
You see that in the timerEvent() method we set the status of the
sSetPoint signal to FAILED to indicate failure of the valve. In
createItemForSignal(sSetPoint,...) we switched on alarming
and made the item status FAILED to be an alarm situation.
You can test the class by creating an object from it, change the setpoint
item to a value. After 1 minute an alarm will be raised unless you set the
value of the position item to the same value as the setpoint item within
this minute.
This valve class can be used by you on its own but we will use it in the
boiler class.

The boiler Containment
8.3 The boiler

The purpose of the boiler is to have two valves, one for the water outlet
and one for the gas burner. We want to switch of the gas burner if the
temperature exceeds the 95 degrees celsius:
public class BOILER extends ProcessClass {
Signal sTemperature = defineDoubleSignal(Signal.Trigger.VALUE);

VALVE cWater = (VALVE)defineContainment("VALVE");

VALVE cGas = (VALVE)defineContainment("VALVE");

}
}
String mSectionPath = getSectionsPath() + "." + getTag();
createSection(mSectionPath, "The section for the items of the boiler",

"", false, true);
cWater.aStation.setValue(mStation);
cWater.aRegister.setValue("10" + mRegister);
cGas.aStation.setValue(mStation);
cGas.aRegister.setValue("20" + mRegister);
createItemForSignal(sTemperature,
"NAME", mSectionPath + ".Temperature",
"ITEM'DESCRIPTION", "Boiler temperatur",
"POINT'DESCRIPTION", "Boiler temperatur",
"IO_ADDRESS", "RI:30" + mRegister);
}

if (sTemperature.getValueAsDouble() > 95.0) {
cGas.sSetPoint.setValue(0.0);
}
}
}
See the line VALVE cGas =

(VALVE)defineContainment("VALVE");. Here we include our valve
to be the gas valve to the burner. cGas will become the identifier for this
valve within the boiler class. Note the prefix letter c. This helps us to

Containment The boiler
identify that this identifier is a containment throughout the class code.

The maximum length of a containment identifier is 15 characters.
In standard Java you write such containment as VALVE cGas = new
VALVE();. This won’t work for the PROCESS/FAST Java language
because all kind of information must be extracted by the PROCESS/
FAST compiler to support the Edit Module and the Operator Interface.
A class that is include (the valve in our example) will not receive
answers to the prompts automatically. Actually, the attributes for the
prompts defined in the valve class will become normal attributes as soon
as the class is included. We have to pass values to the valve attributes
within the boiler class:
You can now try to make an object from the boiler class. What happens?
It fails. Why? The framework called de create() method of the valve
for the first contained valve. If we have the object the name
Section1.Section2.Boiler then the items
Section1.Section2.Boiler.Setpoint and
Section1.Section2.Boiler.Position were created. Now the
framework calls the create() method of the valve for the second
contained valve. It tries to create the item with the name
Section1.Section2.Boiler.Setpoint which will fail because is
already exists. Thus, we have to have a way to create different item
names for both containments. We change the valve code a little.
String mSectionPath = getSectionsPath() + "." + getTag() +
"." getContainerIdentifierName();
The method getContainerIdentifierName() returns the name of

the containment identifier if the valve is contained. Thus it returns
cWater for the first contained valve and cGas for the second contained
valve. The items that will be created will get the names:
Section1.Section2.Boiler.cWater.Setpoint
Section1.Section2.Boiler.cWater.Position
Section1.Section2.Boiler.cGas.Setpoint
Section1.Section2.Boiler.cGas.Position
Instead of coding:
String mSectionPath = getSectionsPath() + "." + getTag() +
"." getContainerIdentifierName();
you can use:

String mSectionPath = getFullIdentifierPath(getTag());

The method getFullIdentifierPath() gets the section path of the

object, appends the given argument to it and append the containment
identifier path to it.
You can now create an object from the boiler class. Try to set the gas
valve setpoint to a certain value. What happens? It is immediately set
back to zero. Why? This is because all triggers are passed to the main
class which is in this case the boiler. Thus, when we change the gas
setpoint, then the signalEvent() method of the boiler is called by the
framework and not the signalEvent() method of the gas valve.
We can handle this in two ways, filter on signal triggers or using trigger
listeners.
8.3.1 Filtering triggers
Consider the following code:

if (signal == sTemperature) {
}
} else {
cGas.signalEvent(signal);
cWater.signalEvent(signal);
}
}
If the trigger that we receive is not from a signal of the boiler class we
pass the trigger to the included valve classes. A signal trigger for the gas
valve will also be sent to the water valve. Therefore we must make sure
that we handle only signal triggers in the valve class that are from the
valve class.We have to modify the signalEvent() method of the valve
class as follows:

if (signal == sSetPoint) {
}
}
Now we are sure that we only start the timer if the setpoint of this valve
is changed.
The same story is valid for timers. The boiler class must be extended
with:
cGas.timerEvent(timer);
cWater.timerEvent(timer);
}

Containment The boiler
And the timerEvent() method of the valve class must be changed to:
if (timer == tCheckTime) {
if (sSetPoint.getValueAsDouble() != sPosition.getValueAsDouble()){
}
}
}
Now you can exercise with the object and see whether it works.
8.3.2 Trigger listeners.
The valve class will become as follows.




}
}

"", false, true);
"ALARMING", true,
"NAME", mSectionPath + ".Position",

}

sSetPoint.addSignalListener(new SetPointListener());
tCheckTime.addTimerListener(new ChecTimeListener());
}
private class SetPointListener implements SignalListener {

systemMessage("Signal: " + signal);
}
}
private class ChecTimeListener implements TimerListener {

systemMessage("Timer: " + timer);
}
}
}
}
Because you add a trigger listener to a specific signal or timer, then the
listener will only be called if this specific signal or timer issue a trigger.
In this case we do not need to pass signal and timer triggers to the
included valves:
cGas.start();
cWater.start();
}

}
}
}
In the signalEvent() method of the boiler we only need to handle the

sTemperature signal. We can remove the timerEvent() method
completely. However, we added the start() method that calls the
start() methods of the valves. The framework doesn’t call the
start() or stop() methods of the contained classes by itself. You are
responsible to do so.
If you have intentions to include the boiler class in another class, for
example, a twin boiler, then you better can use also a trigger listener for
the sTemperature signal.
Yes, you can include a class that has containments, in another class, and
again and again:

Containment The create() and destroy() methods
public class TWIN_BOILER extends ProcessClass {

BOILER cPrimary = (BOILER)defineContainment("BOILER");

BOILER cShunt = (BOILER)defineContainment("BOILER");

}
}
cPrimary.aStation.setValue(mStation);
cPrimary.aRegister.setValue("1" + mRegister);
cShunt.aStation.setValue(mStation);
cShunt.aRegister.setValue("2" + mRegister);
}

cPrimary.start();
cShunt.start();
}
8.4 The create() and destroy() methods

The framework first calls the create() method of the main class and
then it automatically calls the create() method of the first
containment, then the create() method of the next containment, etc.
You can change this behavior by calling the create method of a
containment class:
}
}
call(cWater).create();
call(cGas).create();

The start() and stop() methods Containment
createSection(mSectionPath, "The section for the items of the boiler",

"", false, true);
"NAME", mSectionPath + ".Temperature",
}
In this way, you can control the order of item creation. Why not just use
cWater.create()? Because then the framework is not able to detect
that you did call the create() method yourself.
Normally calling call(...).create() is not necessary.
The same rules are applicable for the destroy() method.
8.5 The start() and stop() methods

In opposite to the create() and destroy() methods, you must
explicitly call the start() and stop() methods of the contained
classes. This way you have full control of the order in which you
initialize your object.
8.6 The ...Event() methods

As mentioned before, all trigger received by the class are not
automatically passed to the containment classes. You are responsible to
pass the triggers to the containment classes by calling the ...Event()
methods of the contained classes. Except for the trigger listeners which
you add to specific signals or timers.

Containment Great news
8.7 Great news

In the previous sections we have seen how to create the section path for
the items to be created and how to create the sections for them:

"", false, true);
"POINT'DESCRIPTION", "Valve setpoint");
}
This can also be written as:

"POINT'DESCRIPTION", "Valve setpoint");
}
You notice that we removed the getFullIdentifierPath() and

createSection() methods and that we do not specify a name for the
item to be created in the createItemForSignal() method.
When you do not supply a name for the item to be created then the
framework will create the item name for you and will also create the
required sections for you. The tag for the item name will become the
name of the signal identifier In the above example the tag name for the
item will become sSetPoint.
Because you cannot specify attributes for the sections to be created the
framework will create the sections as you use
createSection(mSectionPath, "", "", false, true).
If you want to have full control on the naming of the items you can
continue to use getFullIdentifierPath() and createSection().
However the framework cannot undo sections created using the
createSection() method, so in general letting the framework create
and destroy sections automatically is preferred.
Note: For sub-items you must specify the name
for the sub-item to be created and the name
field cannot be omitted.

Introduction Inheritance
9 Inheritance
9.1 Introduction
In the previous chapter we have created a boiler that contains two valves.
We coded specific functionality in this boiler. Suppose we need another
boiler that contains a mixer that must be switched on while the burner is
on. We can make a copy of the existing boiler and add the mixer
functionally. This means that we have to maintain two boiler classes.
There is another way. We create a new boiler that extends the
functionality of the existing boiler. The new boiler inherits then the
functionality of the existing boiler. Here the term inheritance comes
from.
9.2 The boiler with mixer

In the next example we create a new boiler type. In our plant we have
standard boilers and we have some boilers that contain a mixer that
should rotate when the heather is switched on, e.g. when the gas valve is
open. Instead of creating this boiler from scratch, we create a new boiler
that extends the functionality of the standard boiler and by this it inherits
the functionality of the standard boiler:
public class BOILER_MIXER extends BOILER {
Signal sMixer = defineDoubleSignal();
super.create();
createItemForSignal(sMixer,
"ITEM'DESCRIPTION", "Boiler mixer",
"POINT'DESCRIPTION", "Boiler mixer",
"IO_ADDRESS", "RO:31" +
aRegister.getValueAsString());
}

if (signal == cGas.sSetPoint) {
sMixer.setValue(1.0);

Inheritance Accessing super definitions
} else {
}
}
super.signalEvent(signal);
}
The code line public class BOILER_MIXER extends BOILER

declares the new boiler and tells that it extends the functionality of the
standard boiler.
Then we use an additional signal to switch on or off the mixer. In the
create() method we create an item for it and attach the signal to the
item. Notice super.create();. We call here the create() method of
the class we are extending which is called in Java terminology, the
super class. Then the create() method will first create all signals
defined in the super class and then the signal in our new boiler. If we
don’t call super.create() then the signals of the super will not be
created.
In the signalEvent() method we check whether the class was
triggered by the setpoint signal of the gas valve. If this is the case, we
switch on or off the mixer depending on whether the gas valve is open
or closed. Also notice that we call here super.signalEvent(signal)
to make sure that any functionality we may have coded in the
signalEvent() method of the super class is executed.
9.3 Accessing super definitions

Within your class that extends another class you can access the
definitions of the super class directly:


...
}

...
sTemperature.setVAlue(10.0);
cWater.sGas.getValueAsDouble();
if (aStation.getValueAsString().equals("FLOW_START)) ...

Method overriding Inheritance
...
}
9.4 Method overriding

As we have seen in the examples you can implement a method in the
extending class that exists in the super class. For example, in the BOILER
class we have the method start(). If we implement this method in the
BOILER_MIXER class the we override the start() method of the
BOILER (the super class).
This means that the framework will call the start() method of the
extending class instead of the start() method of the super class.
You must make sure that you call the start() method of the super class
implicitly. Thus in the BOILER_MIXER:

...
super.start();
...
}
This also the case for the methods: create(), destroy(), stop(),
signalEvent(), timerEvent() and triggerGroupEvent().
9.5 Prompts
Attributes for prompts that you defined in your super class are also valid
for the extending class. When you defined additional attributes for
prompts in your extending class then these are added to those of the
super class:
Attribute aMaxMixSpeed =
defineStringAttributeForPrompt("Maximum mixer speed:");
...
}
We define the attribute for the third prompt. The first two prompts we
have defined in BOILER.

Inheritance Prompts

10 Miscellaneous
10.1 Introduction
In this chapter we will discuss some miscellaneous items that didn’t fit
in the previous chapters.
10.2 Lengthy trigger processing

When an object receives a trigger, then processing of the trigger should
be as short as possible to be enable quickly processing of others triggers
coming in. This can be triggers for the same object or for other objects.
The traditional PROCESS/FAST language is designed in such a way
that it is impossible to code time consuming methods. With the Java
language this is different. You can use loops, you can perform file
access, you can perform inter-process communication, you even can
access web-services on the internet. The processing time needed to
execute these kind of things is often unpredictable and lengthy.
If you do not use priorities and multiple execution environments then an
object that takes a long time to execute holds up execution of all triggers
until this object is ready executing the trigger. Holding up other triggers
may slow down your system and may cause queue overflows and at the
end in an unreliable system.
There are two types of lengthy processing:
• CPU intensive processing, for example doing a lot of calculation
within a big loop. Be very careful with these type of processing
because, CPU intensive processing always influences the whole
system.
• Wait processing in case you wait for, for example, a web-service
request to respond. While waiting, the CPU can perform other
tasks. This kind of processing is not so bad, but you must be
carefully not to holdup other triggers.
How can we avoid that a lengthy trigger processing holds up other
triggers? You use class and/or object priority for this purpose. Each
priority runs in a separate thread (a kind of sub-process). If an object is
busy with the lengthy processing of a trigger then only this thread is hold

Miscellaneous Methods
up. This means that all object that have a different priority will continue
processing triggers. Only objects that have the same priority are hold up.
Thus make sure that important objects which have to response quickly
to triggers, have a different priority than the less important lengthy
objects.
In addition, you also can start-up more than one execution environment,
that is dedicated to processing a certain priority range only. See the
PROCESS/FAST System Integrators Manual for more information on
this subject.
10.3 Methods
In the previous chapters we have seen usage of several methods like
defineIntegerAttribute(), createItemForSignal() etc.
In this section we will touch a number of methods that are very
convenient for you. This list is not intended to be complete. For a full
overview of the methods you must go to Chapter 11.
In addition we will add additional methods that can be used in your
classes.
createSection() enables you to add a section to the FAST/TOOLS
system. You supply the full path of the section to be created, for example
SectionA.SectionB.SectionC. The framework will create any
section in the path you supplied if it doesn’t exist. In addition you have
to supply a description for the section, it’s process areas, whether it is
blocked and whether it is visible for OPC clients. You can only use it in
the create() method of your class. When the object is deleted then the
framework tries to delete all the section you created in the create()
method.
getNode() returns the node number were the object will run (if called
in the create() method) or is running (in a trigger method).
getSections() returns all elements of the section were the object is
located as an array of strings. Thus if the name of the object is
Section1.Section2.Section3.ObjectName then getSections()
returns [0] = Section1, [1] = Section2 and [2] = Section3.
getNow() returns the current time (in GMT) as a double in seconds were
the fractional part has a resolution of milliseconds.

Methods Miscellaneous
toInteger() returns the argument as an integer. If the argument is a

double then the value is rounded to the nearest integer. If the argument
is a string the string is parsed and returned as an integer.
toDouble() returns the argument as a double. If the argument is a
string then the string is parsed and returned as a double.
toString() returns the argument as a string. Optional a format string
can be specified. Use the standard Java documentation to read about
Java format strings.
getContainerIdentifierName() returns the identifier of the
containment where the class is contained. Here some explanation. In the
previous chapters we coded a valve and we contained this valve twice in
the boiler:
If we call getContainerIdentifierName() in the valve class it will

return cWater if this valve is the first containment or it will return cGas
is this valve is the second containment because it exists twice in the
boiler. If the class is not contained then an empty string is returned.
getContainerIdentifierPath() returns the whole containment
path. Thus in the twin boiler example it will return for the first valve in
the first boiler cPrimary.cWater.
getFullIdentifierPath() returns a full containment path of the
class including the section path of the object. It is intended to be used
with the createSection() method to create a section were the items
to be created can be put in. This, in case you are using complex
containment structures like the twin boiler.
10.3.1 Adding methods
Of course you can add your own methods to your classes. For example,
we add the method closeValve() and openValve() to the valve class:
public void closeValve() {
sSetPoint.setValue(0.0);
}
public void openValve() {

}
Then we can change the boiler class to:


Miscellaneous Methods
cGas.closeValve();
}
}
}
Thus we put the logic to close a valve in the valve class and just call the
close() method of the valve in the boiler class. The boiler then doesn’t
need to have knowledge on how to close a valve, it just calls the
close() method of the valve.
We just added a method to a certain class. What to do when we want to
add a general purpose method that we want to call from various classes?
We extend the class from which we extended all our classes up to now.
We create a class with the name BASE_CLASS and it looks like:
public class BASE_CLASS extends ProcessClass {
public double sumOfSignals(Signal[] signals) {

double mSum = 0.0;
for (Signal mSignal : signals) {

if (mSignal.isAttached()) {
mSum += mSignal.getValueAsDouble();
}
}
return mSum;
}
public void myNextMethod() {

}
We added a method that calculates the sum of all signals in an array.

Note that we check whether an item is attached to the signal.
From now on we do not extend our classes from ProcessClass. Now
we extend them all from BASE_CLASS and have the methods we coded
in the base class available in all our classes. For example:
public class MANY_SIGNALS extends BASE_CLASS {
Signal[] sManySignals =
defineDoubleSignalArray(Signal.Trigger.VALUE, 10);

for (int i = 0; i < sManySignals.length; i++) {
createItemForSignal(sManySignals[i],
"ProcessFast.Manual.ItemTemplates.Real",

Exception handling Miscellaneous
"NAME", "ProcessFast.Manual.Items.Array_" + i);

}
}

systemMessage("The sum of all signals is:" +
sumOfSignals(sManySignals));
}
}
Note that each class that you extend from BASE_CLASS will load a copy
of the base class in the runtime environment. Thus you can not use static
declaration of variables in the base class because their values are not
shared between all objects.
If this is an issue you can write you methods using a Java development
environment. Code your methods and other Java classes in there. Gather
them all in a Java jar file and put this jar file on the tls\exe directory.
Using this method you can add functionality that is not restricted by the
PROCESS/FAST framework. One note however, all the classes you
code outside the PROCESS/FAST framework must have a package
name. If such class has no package name the PROCESS/FAST
framework thinks it is part of its framework.
10.4 Exception handling

An exception is an abnormal situation in your code. If such a situation
occurs in the create() method then creation of the object is cancelled
and actions performed so far are rolled back by the framework. If an
exception occurs in trigger method then execution of the method is
canceled and the exception is printed on the system log. Then the
framework continues processing the next trigger. However, you can
intercept exceptions using the standard java mechanism:
double mHighLimit;
try {
mHighLimit = signal.getHighLimit();
} catch (Exception e) {
mHighLimit = 100.0;
}
...
}
In this example we obtain the high limit of a signal. But maybe the signal
doesn’t have a high limit. In this case we catch the exception and assume
a high limit of 100. If we didn’t intercept the exception then all code
after the getHighLimit() is not executed if the item has no high limit.

Miscellaneous Debugging
10.5 Debugging
You will notice that the classes you write often do not do what you
expect them to do. Then debugging comes in. The first step is to switch
on debugging of your object using the Engineering Module. Then test
the object. After testing switch off debugging. This will output tracing
information that was gathered by the execution environment while
debugging was switched on. In this trace list you will find the triggers
that triggered the object and the methods of the framework you called.
If this doesn’t pinpoint the problem then you have to fallback to the good
old days method of putting the systemMessage() method at strategic
positions in your code and follow the output on the system log while you
exercise the object.
Note that you always have to reset the class to let the code take effect,
both on newly created objects and existing objects. Even for a new class,
with no derived objects the class must be reset before adding objects
(compiling alone is not enough), otherwise the code does not take effect!
10.6 Object statistics

You can obtain performance statistics from your object in your object:
ObjectStatistics mStatistics = getStatistics();
systemMessage("The object has processed " +

mStatistics.getProcessedEvents() + " triggers");
There is other information available. See Chapter 11.

Introduction Reference guide
11 Reference guide
11.1 Introduction
The reference guide is supplied as online help for the Engineering
Module. To get the reference press the F1 key while you are in the editor
of a PROCESS/FAST Class properties form in the Engineering Module.

Reference guide Introduction

Introduction
A.1 Introduction
This appendix supplies the classes we used trough out this manual and
some additional examples.
A.2 The valve

This is the valve we used in this document.



}
}
"ALARMING", true,
"ITEM_STAT_1", "FAILED",
}
PROCESS/FAST Java Language Manual A-1

The boiler

sSetPoint.addSignalListener(new SetPointListener());
tCheckTime.addTimerListener(new CheckTimeListener());
}
public void closeValve() {

}
public void openValve() {

}
private class SetPointListener implements SignalListener {

systemMessage("Signal: " + signal);
}
}
private class CheckTimeListener implements TimerListener {

systemMessage("Timer: " + timer);
}
}
}
}
A.3 The boiler

This is the boiler we used in this document.



}
}
A-2 PROCESS/FAST Java Language Manual

The twin boiler
}

cGas.start();
cWater.start();
}

cGas.closeValve();
}
}
}
A.4 The twin boiler

This is the twin boiler we used in this document.
public class TWIN_BOILER extends ProcessClass {

BOILER cPrimary = (BOILER)defineContainment("BOILER");

BOILER cShunt = (BOILER)defineContainment("BOILER");

}
}
cPrimary.aStation.setValue(mStation);
cPrimary.aRegister.setValue("10" + mRegister);
cShunt.aStation.setValue(mStation);
cShunt.aRegister.setValue("20" + mRegister);
}

The mixer boiler

cPrimary.start();
cShunt.start();
}
A.5 The mixer boiler

This is the mixer boiler we used in this document.
Signal sMixer = defineDoubleSignal();

Attribute aMaxMixSpeed =
defineStringAttributeForPrompt("Maximum speed:");
super.create();
createItemForSignal(sMixer,
"ITEM'DESCRIPTION", "Boiler mixer",
"POINT'DESCRIPTION", "Boiler mixer",
"IO_ADDRESS", "RO:31" + aRegister.getValueAsString());

if (signal == cGas.sSetPoint) {
} else {
}
}
}
A.6 City temperature

In this example we show to access a web-service to obtain the
temperature in a city throughout the world.
We use a web-services from openweathermap.org to obtain the
temperature. If you have to access the internet via a proxy server then
you have to uncomment the code in the start() method and specify the
proxy server over there. You have to place the class or object in a trigger
group of, for example, 10 minutes.

City temperature
Note that the processing of a trigger group trigger may take some time
because the internet has to be accessed. Therefore make sure that these
objects run with a different priority as objects created from other classes.
This way you make sure that these city temperature objects do not
holdup execution of more important objects.
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.URL;
public class CITY_TEMP extends ProcessClass {
Signal sTemperature = defineDoubleSignal();
Attribute aCity = defineStringAttributeForPrompt("City name:");

String mCity = aCity.getValueAsString();
if (mCity.isEmpty()) {
cancel("Missing city name");
}
"ProcessFast.Manual.ItemTemplates.Real",
"NAME", getSectionsPath() + "." +
mCity + "_Temp",
"DESCRIPTION", "Temperature of " + mCity);
}
// Sets the proxy server if required

//System.getProperties().put("proxySet", "true");
//System.getProperties().put("proxyHost", "my_proxy_server");
//System.getProperties().put("proxyPort", "8080");
}
// Get the temperature

double mTemperature = 0.0;
try {
URL mUrl =
new URL("http://api.openweathermap.org/data/2.1/find/name?q=" +
aCity.getValueAsString() + ",%20UK&units=metric");
BufferedReader mReader =
new BufferedReader(new InputStreamReader(mUrl.openStream()));
String mInputLine = mReader.readLine();
int mTempPos = mInputLine.indexOf("temp\":") +

"temp\":".length();
int mEndPos = mInputLine.indexOf(",", mTempPos);
mTemperature =
Double.parseDouble(mInputLine.substring(mTempPos, mEndPos));
mReader.close();
}

City temperature
catch (Exception e) {
sTemperature.setStatusNumber(Signal.Status.OFFLINE);
return;
}
sTemperature.setValue(mTemperature);
}
}

Index
A
ALARM_DETECTION 4-13
C
CREATE_ITEM 4-13
D
DELEGATE_ONLY 4-13
E
enterprise class 4-13
enterprise object 4-13
M
MASTER_AND_DELEGATE 4-13
MASTER_ONLY 4-13
P
PUT_IN_HISTORY 4-13
PROCESS/FAST Java Language Manual 1

Index
2 PROCESS/FAST Java Language Manual

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction DATABASE/FAST FAST/TOOLS
Manual Language Manual
IM50F06F00-01EN/R10.03

IM50F06F00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction to DDL ...........................................................1-1
1.1 General .......................................................................1-1
1.2 What are data sets ......................................................1-1
1.2.1 Data sets versus normal data files ........................1-1
1.2.2 How are data sets built-up ..................................1-2
1.3 DDL to define data sets .............................................1-5
1.4 Why generate an include file .....................................1-7
1.5 Why update a data dictionary ....................................1-8
1.6 Why use DDL and the DDL-compiler ......................1-9
1.7 Features of the DDL-compiler ...................................1-9
2 Creation of a DDL-file .........................................................2-1
2.1 Introduction ...............................................................2-1
2.2 General layout of a DDL-file .....................................2-1
2.3 How to specify defined constants ..............................2-2
2.4 How to specify the data set parameters .....................2-3
2.5 How to specify the record layout ...............................2-5
2.6 How to specify the record keys .................................2-9
2.7 How to specify decode information .........................2-10
3 Compilation of a DDL-file ...................................................3-1
3.1 General .......................................................................3-1
3.2 How to run the DDL-compiler ..................................3-1
3.3 How to use command line flags ................................3-2
3.4 How to generate an include file .................................3-2
3.5 How to update a data dictionary ................................3-3
3.6 How to list compiler errors ........................................3-6
3.7 How to suppress error messages ................................3-7
4 The include file ......................................................................4-1
4.1 General .......................................................................4-1
4.2 Defined constants ......................................................4-1
4.3 General data set information ......................................4-1
DATABASE/FAST Language Manual iii

Table of Contents
4.4 Record information ................................................... 4-2

4.5 Key information ........................................................ 4-4
5 The data dictionary .............................................................. 5-1
5.1 General ...................................................................... 5-1
5.2 Records in the set data dictionary file ....................... 5-1
5.3 Records in the field data dictionary file .................... 5-1
5.4 Records in the key data dictionary file ..................... 5-3
5.5 Records in the decode data dictionary file ................ 5-3
6 Reference .............................................................................. 6-1
6.1 Introduction ............................................................... 6-1
6.2 How to read the DDL-syntax description ................. 6-1
6.2.1 General ........................................................... 6-1
6.2.2 Top-down description ....................................... 6-1
6.2.3 Symbols used .................................................. 6-2
6.3 Some frequently used lexicals .................................. 6-3
6.4 General layout of a DDL-file .................................... 6-4
6.5 Defined constant specification .................................. 6-4
6.6 Data set specification ................................................ 6-5
6.7 Record specification .................................................. 6-7
6.7.1 General ........................................................... 6-7
6.7.2 Field declarations ............................................. 6-8
6.7.3 Structure and union declarations ....................... 6-10
6.8 Key specification .................................................... 6-11
6.9 Decode specification ............................................... 6-12
6.10 Usage of the DDL-compiler .................................... 6-13
6.10.1 Running the compiler ..................................... 6-13
6.10.2 Command line flags ........................................ 6-14
6.10.3 Include file flag ............................................. 6-14
6.10.4 Data dictionary flag ........................................ 6-15
6.10.5 Other flags .................................................... 6-18
6.11 Error messages ........................................................ 6-20
Appendix A: An example .............................................................. A-1
A.1 Introduction .............................................................. A-1
A.2 DDL-file ................................................................... A-1
A.3 Include file ............................................................... A-2
A.4 Data dictionary ......................................................... A-4
iv DATABASE/FAST Language Manual

Objectives Preface
0 Preface
0.1 Objectives
This manual describes:
• the syntax of the Data Description Language (DDL),

• the use of the DDL-compiler.
The DDL-compiler is used to generate an include file and/or to update a

data dictionary, using a DDL-source file as input.

The manual is primarily intended for software engineers and application
engineers who want to create DDL-sources and/or want to use the DDL-
compiler.

This manual is structured as follows:
• Chapter 1, Introduction to DDL and the DDL-compiler, is a general

introduction to the functionality of DDL and the features of the
DDL-compiler. It also explains what a ’data set’ is and what it is
used for.
• Chapter 2, Creation of a DDL-file, describes how a DDL-file must

be created. It does not contain the complete syntax description of
DDL. For this refer to chapter ’Reference’.
• Chapter 3, Compilation of a DDL-file, explains how to run the

DDL-compiler in order to generate an include file and/or to update
a data dictionary, using a created DDL-file as source.
DATABASE/FAST Language Manual 0-1

• Chapter 4, The include file, describes the structure of include files

generated by the DDL-compiler.
• Chapter 5, The data dictionary, describes the structure of data

dictionaries that can be created/updated by the DDL-compiler.
• Chapter 6, Reference, contains the complete syntax description of

DDL. The commands and flags for running the DDL-compiler are
also described. Finally, a survey of the DDL-compiler’s error
messages is given.
• Appendix A, An example. To make the properties of DDL and the

DDL-compiler more clear, a complete example is given in this
appendix. The example consists of:
- A DDL-file (compiler input),

- An include file (generated by the DDL-compiler, on the basis of
the DDL-file),
- A data dictionary (created and filled by the DDL-compiler, on
the basis of the DDL-file)

• DATABASE/FAST Programmer’s Guide;
(FAST/CONVENTIONS Reference Guide)
• A reference manual for the ’C’ programming language
• ODBC 2.0 Programmer’s Reference and SDK Guide

CONVENTION MEANING
() Used in routine syntax to indicate a list

of arguments that have to be passed.
[] Indicates that the enclosed item is

optional.
0-2 DATABASE/FAST Language Manual

{ }.. Indicates that the enclosed item may be

... Indicates that not all of the items

are shown.

letters names, e.g. NULL, TRUE, DUR_NOWAIT.

literally.
<name> Used in format descriptions. <name> indicates

a variable.
<file_name>+ Used in syntax descriptions. Exactly one or

more file names may be entered.
n.u. not used

a terminal

the user
DDL DATABASE/FAST Data Description Language
SQL Structured Query Language, according the X/Open

and SQL Access Group SQL CAE specifications
of 1992


General Introduction to DDL
1 Introduction to DDL
1.1 General
This chapter gives an introduction to the Data Description Language
(DDL). DDL has been developed to be able to specify data sets easily
and consistently. With the aid of the DDL-compiler, include files based
on the specified data sets can be generated. In addition, data dictionaries
can be updated with the specified data set description.
This chapter covers the following topics:
• What are data sets

• DDL for defining data sets
• Why an include file has to be generated
• Why a data dictionary needs to be updated
• Why DDL and the DDL-compiler need to be used
• Features of the DDL-compiler
1.2 What are data sets
1.2.1 Data sets versus normal data files
DDL stands for Data Description Language. With this language, the
characteristics of data sets that will be used in a FAST/TOOLS
environment, for example, can be described consistently. Before an
actual description of DDL, a brief explanation of data sets will be given.
data set A data set is a collection of data that can be accessed by FAST/TOOLS
or other applications. It can be a normal database file, e.g. maintained by
DATABASE/FAST. In that case, it is a ’static’ data set, because it is
physically physically stored; the record occurrences are continuously available
stored and filled with data. However, a data set can also be ’dynamic’. In that
case, there is no physical database file containing the records, but each
time a record has to be retrieved, the record data must first be collected
real-time
somewhere. Then the record is filled real time with the values,
whereupon it is available for the requester who wants to retrieve it.

Introduction to DDL What are data sets
Suppose for example that we have a lot of machines in a factory for

which information must be maintained. The record type in a static data
set will contain the information that does not change real time, e.g.
things like production year, color, weight, capacity, etc. The record type
in a dynamic data set will contain real-time information about a
machine, like status (on/off/standby), mode, temperature, oil pressure,
etc.
1.2.2 How are data sets built-up
A data set is a collection of data of the same layout (type). For instance,
it can contain the definitions of all process variables. A single definition
records is called a record. Such an item definition record contains information
like: the name of the process variable, its limits, its alarm parameters,
fields etc. Such an information unit in a record is called a field. A field itself
may contain other fields. For example, the item name field consists of
the installation name, unit name, tag name and sub name. The whole
record itself can also be treated as a field. The features mentioned above
are clarified in figures 1-1 to 1-3:
DATA SET blocks
record 1
record 1
record 1 2
record
record 2
record 2 3
record
record 3
record 3
record n
record n
record n
Fig. 1-1 A data set with its blocks and records
Figure 1-1 shows that a collection of records may occur more than once
in a data set. For example, there can be various instances of process
data set block
variable definitions of different systems in one set. Such an occurrence
or instance is a data set block. In the above example, a data set block
corresponds with a DATABASE/FAST database file and the name of

What are data sets Introduction to DDL
the data set block is the name of the database file. However, as
mentioned already, a data set or a data set block need not necessarily be
a database file.
Often there will only be one data set block, and in many cases the name
of the data set block will have no meaning. A data set block is identified
by:
data set block • The name of the data set.

identification • The name of the node on which the data set block is located.
• The name of the data set block itself. For database files, it is the
name of the database file.
Generally speaking, FAST/TOOLS will access data sets via servers. It

is not necessary for these servers to reside on the same node as the actual
data. For example, the FAST/TOOLS itself runs on node A, the server
runs on node B and the data is available on node C. Furthermore, servers
running on different nodes may have the same name. Physical data files
located on different nodes may also have identical names. For this
reason, a data set block identification includes the server’s node name in
addition to the actual data set name. In addition, it contains the name of
the node on which the actual data is available
record The layout of a record within a data set is shown in figure 1-2.
layout
field 1
field 2
field 5
field 7 field 8
Fig. 1-2 Layout of a record within a data set
The units in a record are fields. A field itself can be divided into other
fields. The record itself is also a field (field 1). A field which itself
contains other fields is called the parent of those other fields. Thus field
6 is the parent of field 7 and 8. A field having a parent is called a child
field.
field Fields have attributes:

attributes
• Name
Each field has a name. Fields may have the same name as long as
they do not have the same parent. Due to the Open DataBase

Introduction to DDL What are data sets
Connectivity (ODBC) component, called ACCESS/FAST, the field

SQL reserved name can not be a reserved Structured Query Language (SQL)
keyword keyword as defined by the X/Open and SQL Access Group SQL
CAE specifications of 1992. Therefore the DDL-compiler
automatically checks if the field name equals such a reserved
keyword. In practise, the name of the record (field 1) is often the
same as the name of the data set.
• Type
The data in a field is stored in a certain representation, the data type.
There are basic data types, like ’integer’ and ’real’. A data type
including more fields is called a structure. The fields included are
the children, while the structure itself is the parent field.
• Format
The format defines the appearance of the data in the field when it is
outputted, e.g. in a report. Structured fields do not have formats.
• An alias field name
The previously mentioned name of the field is a technical name and
in many cases it does not make the purpose of the field clear. A
more user-friendly alias name can be given to the field. Note that
structured fields do not have alias field names.
• Heading
The heading defines the text in the heading for a field, which can be
used e.g. for outputting the field in a report. Structured fields do not
have headings.
• Options
Via the options field it is possible to specify additional sub
attributes for the field in question, like field suppression. These sub
attributes will be discussed more in detail in Chapter 2 of this
document.
In figure 1-3 an example of a record with realistic field names is given.
my_record
status
status
status option
Fig. 1-3 Example of a record with realistic field names
Notice that the name ’status’ is used three times. Only specifying the
name ’status’ does not identify the field. The field name can be made
unique by preceding the field name by its parent’s name until a non-
ambiguous name is created. The three names for the ’status’ fields will

DDL to define data sets Introduction to DDL
become ’my_record.status’, ’status.status’ and ’level.status’. Such an

field unambiguous name is called a field specification.
specification
A data set block can contain many records. In order to decrease the
search time, specific records can be accessed by a key. The key consists
key field of one or more record’s key fields which form (in most cases) a unique
identifier for each record in the data set. Thus suppose that field
’status.status’ in the example above is a key. It is possible to retrieve
specific records by asking:
Give me the records where ’status.status’ is the

alarm ’high’.
If a record has to be found in which a non-key field has a certain value

it is possible to ask:
Give me all records.

I will check all records myself to find those where
’value_1’ is 12.4.
Generally speaking, data set accesses based on keys are much more
efficient than non key-based accesses.
If a field’s value is the same for multiple records, or if the field’s value
decode is taken from a fixed list of given values, then it is usefull to replace the
information
field’s value by an index. In case of such replacements, the field’s values
have to be linked to the indices used; the decode information. It should
be noted that a decoded field can not be part of a key, since it can lead
to non-unique identifiers.
1.3 DDL to define data sets

To describe data sets easily and consistently, DDL has been developed.
With this language the following can be specified:
general • The general information about the data set (its identification), like
data set info data set name, node and name of the server, node and name of the
physical database, etc.
record • The layout of the record type of which the data set will contain
layout occurrences of, in other words the specification of all fields with
their attributes.

Introduction to DDL DDL to define data sets
key • The keys of the record, i.e. their names, the record fields included
arrangement and an indication whether duplicates of the keys are allowed or not.
decode • The field’s decode information; data pairs describing the relation
information between indices used and the fixed field values
When a data set is completely defined in DDL, it can be compiled using

the DDL-compiler, see figure 1-4.
DDL-file
compilation
SDD-file D
a
t
a
FDD-file D
i
DDL- c
DDL-file compiler t
i
o
KDD-file n
a
r
y
DDD-file
include file
Fig 1-4 The DDL-compiler with its input and its outputs
Depending on the flags that will be specified on the command line when
starting-up the compiler, an include file (.h-file) will be generated and/
or a data dictionary will be updated. A more detailed description of the
files that together comprise the data dictionary, will be given in Section
1.5.
In figure 1-5 the relationship between a generated include file, a data

dictionary, one of the FAST/TOOLS (REPORT/FAST) and a random
application program is illustrated. The corresponding explanation is
given in the following two sections.

Why generate an include file Introduction to DDL
(data dictionary)
include file SDD-file
FDD-file
KDD-file
DDD-file
application
programs
REPORT/
FAST
data sets
report
application creation time

run time creation / update
Fig. 1-5 Example of the relationship between include file,

data dictionary and their users
1.4 Why generate an include file

include file An include file generated by the DDL-compiler contains all information
about the data set, as specified in the DDL-source file, however

Introduction to DDL Why update a data dictionary
completely in C-language now. This means that it can be included as

header file in every C-program. In the example of figure 1-5, the file is
used by several application programs. The include file will contain:
• The data set specification; each parameter is represented as a

defined constant.
• The record specification represented as a ’C-structure’.
• The format of the record itself and the formats of the (sub)structures
in case the record contains fields of this type.
• The key specification for the data set; i.e. it can be used directly
when calling ISF-routines (DATABASE/FAST).
This means that REPORT/FAST and the application programs have

knowledge about the layout of the data sets they can retrieve data from.
Note that the layout description in the include file may no longer be
changed. Therefore a new include file has to be generated, whereupon
all programs using that include file must be compiled and linked again.
However, by using a data dictionary, the data set layout can be changed
run time as often as required. The principle is explained in the next
section.
1.5 Why update a data dictionary

As we have said before, in addition to the include file generation, the
data DDL-compiler can also update an existing data dictionary with the data
dictionary specification given in the DDL-file. When the specified data dictionary
does not exist, it will be created automatically, whereupon the data
description is saved in it. The data dictionary that will be updated or
created will always consist of four files:
SDD-file • The Set Data Dictionary file (SDD-file), containing one record for
each data set that is in the dictionary. In this record the set
parameters are saved (set name, etc.).
FDD-file • The Field Data Dictionary file (FDD-file), containing a separate
record with information for each field that is in the record specified
in the DDL-file. Moreover, a separate record exists for each struct
specified in the record of the DDL-file.
KDD-file • The Key Data Dictionary file (KDD-file) containing a separate
record with information for each key that is in the DDL-file.
DDD-file • The Decode Data Dictionary file (DDD-file) containing optional
separate records with decoding information for fields specified in

Why use DDL and the DDL-compiler Introduction to DDL
the DDL file. The decoding information is meant to define the

relation between a binary value in a field and the (explanatory)
plain ASCII text that is related to (the meaning of) this binary value.
The data dictionary files are created, and updated by ISF (DATABASE/
FAST). This means that other applications and FAST/TOOLS (like
REPORT/FAST in the example of figure 1-5) can open them run time,
to obtain information about certain data sets.
Thus when all data set descriptions are stored in a data dictionary, these
descriptions may be changed at any time, with the condition that an
application will always consult that dictionary prior to actually
accessing the data set .
1.6 Why use DDL and the DDL-compiler

The DDL-compiler should be used for the following reasons:
• Applications that need a flexible (i.e. run time, up-to-date) interface
with data sets, will always access the data dictionary to retrieve the
data set descriptions. Examples of such applications are REPORT/
FAST and ACCESS/FAST.
• The description of a new or modified dataset will automatically be
saved in the data dictionary, ready to be used by applications.
• The generated include file can be included in ’C’ source programs.
• If the DDL-compiler is not used, the keys have to be defined by
filling a certain struct with the offset and length of the specified
fields (following DATABASE/FAST). Because this is a rather
complex and time-consuming activity, errors can sneek in if several
structs and unions are used.
The DDL-language is easy to use for software engineers because a great

part of the syntax is ’C-like’. In addition, most of the time another DDL-
file will be available as an example. This manual can then be used as a
reference.
1.7 Features of the DDL-compiler

This section summarizes the main features of the DDL-compiler.

Introduction to DDL Features of the DDL-compiler
• Creation of an include file with the data set characteristics.

• Saving the description of a data set in the data dictionary.
• Dictionary name and include file name (with optional path) to be
specified on the command line; this results in system independence.
• Record specification according to C-syntax.
• The following types are allowed: char, short, ushort, boolean, long,
ulong, float and double.
• The use of struct and unions is possible (there is no limit to the
maximum depth).
• Arrays can be declared up to a maximum of 4 dimensions.
• The boundary of each field and the length of the complete record,
as well as the length of each structure and each union in it, will be
checked (must be a multiple of 4 bytes; long boundary). This is
done to prevent errors during system conversions; see also the
document ’FAST/CONVENTIONS Reference Guide’.
• Keys are simply defined by field names, instead of numbers
indicating offsets and lengths.
• Although there is no maximum limit to the number of keys that are
defined, the file system used might introduce certain constraints.
• A key definition may include a maximum of eight field names.
• Struct names in a key definition do not have to be specified; as long
as the field names are unique within the entire record, only the field
names are appropriate.
• Each field name is checked for being a Sequential Query Language
reserved keyword, conform the X/Open and SQL Access Group
SQL CAE specifications of 1992.
• Replacing repeating field values by an index, and storing the
relation between the indices and field values in a decode table.
• Data sets can be removed from the data dictionary.

Introduction Creation of a DDL-file
2 Creation of a DDL-file
2.1 Introduction
This chapter explains how to create a DDL-file. First of all the general
layout of a DDL-file is described. Then in separate sections the
functional parts in which the DDL-file can be sub divided are described.
Specification of the include file name and the data dictionary name is
explained in the next chapter. The reason is that both parameters have to
be specified on the command line when starting compilation; i.e. they
are not specified in the DDL-file itself.
The effect of the DDL-file contents on the include file to be generated

and the data dictionary to be updated, are described in Chapters 4 and 5
respectively.
The following subjects are covered in this chapter:
• General layout of a DDL-file

• How to specify defined constants
• How to specify the data set parameters
• How to specify the record layout
• How to specify the record keys
• How to specify decode information
• Example of a DDL-file.
2.2 General layout of a DDL-file

A DDL-file is a normal file that can be created with any ordinary system
editor. The general layout of a DDL-file is shown in figure 2-1.

Creation of a DDL-file How to specify defined constants
Defined constants
(optional)
General data set

parameters
Record specification
Key specifications
Decode information
(optional)
Fig. 2-1 General layout of a DDL-file
The parts that together comprise the contents of a DDL-file are:
• A part that specifies defined constants that have to be in the include

file to be generated. This part is optional.
• A part that specifies the general dataset parameters.
• A part that specifies the layout of the record in the dataset.
• A part that specifies the record keys.
• A part that specifies the decode information.
2.3 How to specify defined constants

The define constant specification is used to specify defined constants
(#defines) in the include file (.h file) to be generated. Moreover, when a
certain defined constant is specified in a DDL-file, the constant name
can be used as index in that DDL-file, see also section ’Record
specification’.

How to specify the data set parameters Creation of a DDL-file
A defined constant specification starts with the keyword ’def:’,

’DEF:’, ’define:’ or ’DEFINE:’. Then a name and a numeric value
must follow. The defined constant specification only affects the include
file to be generated by the DDL-compiler. Defined constants specified
here will never affect a data dictionary when it is updated by the DDL-
compiler.
Examples of such defined constant specifications are:
defined def: MAX_INDEX 10

constant DEFINE: Normal_Temperature 20.5
examples
In the include file that will be generated, these specification result in the
following #defines:
#define MAX_INDEX 10
#define Normal_Temperature 20.5
2.4 How to specify the data set parameters

In the data set specification, all general data set parameters have to be
defined.
The set parameters that can be specified are:
survey of • Set name

set This is a unique name within the data dictionary that identifies the
parameters data set. This parameter must always be specified.
• Server node
This is the name of the node on which the server that will handle
the data set is running. This parameter is optional. It can be omitted
in case the server runs on the same node as the application that
wants to access the data set.
• Server name
This is the name of the server that will handle the data set. This
parameter is optional. If it is omitted, the default server name
’DBS_SERVER’ (from ’database’) is filled in by the compiler.
• Data node
This is the name of the node on which the data is actually available,
i.e. from where it must be retrieved by the server. This parameter is
optional. It can be omitted in situations where the node on which
the data is located is the same as the one the server runs on.

Creation of a DDL-file How to specify the data set parameters
• Directory path
This is the number of the directory path as specified in the (FAST/
TOOLS) header file ’tools.h’. The directory is the one that contains
the data base file from where the data must be retrieved. This
parameter is optional. If it is omitted, the compiler fills in the
default directory path number 0, which is the current directory.
• Database file specification
This is the name of the database file (used when the set is actually
a physical file), not always specified in combination with a file
path. This parameter is optional. If it is omitted, the compiler will
make the database file name identical to the data set name, however
the extension ’.dat’ will be added at the end.
• File format mode
For system conversion purposes the include file to be generated
there will contain a file format string. This string is derived from the
record layout and the file format mode specified here. This file
format mode indicates which part of the file format string contains
the real type format and which part of the file format string is
specified in characters (bytes):
- ALL key fields and non-key fields real type format

- KEY key fields only as type format; remaining fields
as characters
- NON all fields as character
This parameter is optional. If it is omitted, the compiler will fill

in the default mode ALL.
A data set specification always starts with one of the equivalent

keywords ’set:’, dataset:’, ’SET:’ or ’DATASET:’. Then the list
of parameters must follow. In this list, each parameter must be separated
with a comma. The set specification is finished with a semi colon (;).
Two examples of a data set parameter specification follow. The

examples show also that comment in a DDL-file can be specified as in
the C-language. However, in DDL, comment may not be written on
more than one line, without using comment symbols ’/*’ and ’*/’ on
each line. It is also required that comment must be the last item on a line;
i.e. it may not be followed by another character string.
set /*-----------------------------------------------------*/
specification /* Data set spec with optional parameters filled in */
example 1 /*-----------------------------------------------------*/
set:auto_set_1, /* set name */

How to specify the record layout Creation of a DDL-file
node_1, /* server node */

auto_server, /* server name */
node_2, /* data node */
3, /* directory path */
"[auto.data]general.dat," /* file spec */
KEY; /* format mode */
set /*-----------------------------------------------------*/
specification /* Data set spec with optional parameters omitted */
example 2 /*-----------------------------------------------------*/
DATASET: auto_set_1,,,,,,;
Each parameter will become a defined constant in the include file to be

generated. Moreover, the ’file format’ that will be specified in the
include file depends on the value of the ’file_fmt_mode’ parameter.
More information about the file format can be found in section ’Record
specification’.
If a data dictionary is updated by the DDL-compiler, a new SDD-record,

containing the specified information will be written into the SDD-file. If
the data dictionary already contains a data set specification with the
same set name, the user is asked for confirmation of updating the
dictionary, see also Chapter ’Compilation of a DDL-file’.
2.5 How to specify the record layout

In the record specification, the layout of the record has to be defined.
The record specification always starts with one of the equivalent

keywords ’rec:’, ’record:’, ’REC:’ or ’RECORD:’. This keyword
must be followed by a unique record name and optionally an alias name.
The layout of the record, i.e. its field description, is enclosed between
accolades and finished with a semi colon. Between those accolades each
field is specified separately, as shown in figure 2-2.

Creation of a DDL-file How to specify the record layout
lay out of sim-

ple record
fields
1
type name ; format alias name header options
Fig. 2-2 Fields within a record specification
Each field starts with a type specification, e.g. ’byte’, ’char’, etc..
These types are equivalent to the C-language types. A type may be
specified either in lower case or upper case.
field type and The type of a field is followed by its name. Each field name must be
name unique within a record. Duplicate names are allowed only if the fields lie
on different levels, i.e. one of two fields is a child in a struct, while the
other field is on the same level as the struct (parent) itself. As mentioned
earlier, the field name may not be a reserved SQL keyword. Using a
reserved SQL keyword as a field name leads, in case of ACCESS/FAST,
to inaccessable tables.
Both the field type and field name will work on the include file to be
generated as well as the data dictionary to be updated.
After the field name, a semi colon must be specified, followed by zero,
one, two, three or four strings, called the ’format’, the ’alias name’, the
’header’, the options of the field respectively. Basically, these fields are
all optional. However if an alias name is specified, the format string
must be specified too. When a header string is specified, both the format
string and the alias name must be there. When the options field is
specified, the format string, the alias name and the header string must be
specified too. The strings only affect the data dictionary and not the
generated include file.

How to specify the record layout Creation of a DDL-file
print The format string can be used to specify the print format of the field,
format used for example when its value must be printed in reports.
alias name The alias name can be used to change the ’technical’ field name to a
more user-friendly name.
column The header can be used when, for example, a column header has to be
header printed above the field’s value in a report.
options field The options field is used to specify additional sub attributes for a field.
The only sub attribute currently defined for a record field is "field
suppression". This sub attribute can be specified by putting the
FIELD_SUP or field_sup keyword between parentheses. The field
suppression attribute will be stored together with the other field
attributes, in the field data dictionary file. The author of the DDL file
will use the field suppression attribute to indicate that the field does not
contain relevant information (e.g. dummy fields in a record to correctly
align fields of the record or dummy fields for spare purposes).
Applications using the data dictionary can e.g. use this field suppression
attribute to determine whether or not to display the field for which the
attribute has been set.
An example of a simple record specification is given below.
example of a /*-----------------------------------------------------*/
record with /* Example of a record with simple field */
simple fields /*-----------------------------------------------------*/
rec: equip_rec "equipment"
{
char field_1[12]; "%12s" "rack" "rack"
char field_2[24]; "%24s" "dev" "device"
int dummy1; "%d" "" "" (field_sup)
};
The example shows a record with two character arrays. Furthermore the
record contains a dummy field with no alias name and no header string
specified. The dummy field has the field suppression attribute active.
Remark: The maximum number of indices for an array used in DDL is 4.
Two more complex field types need some additional remarks. As in the
C-language, one of the field types that may be specified is a structure
(type ’struct’).
An example of a record specification, including a structure field is given

below.

Creation of a DDL-file How to specify the record layout
example of a /*------------------------------------------------------*/
record with /* Example of a record including a structure */
structure /*------------------------------------------------------*/
rec:equip_rec "equipment"
{
char field_1[12]; "%12s" "rack" "rack"
struct field_2 "device"
{
char dev_1[12]; "%12s" "dev" "device name"
long temp; "%d" "" "temperature"
} device;
};
In the example is shown that after the name of a structure, also an alias
name may be specified. The fields of a structure are specified in the same
way as the other (normal) record fields.
nesting of Nesting of structures is allowed; i.e. a structure’s field may also be an-
structures other structure, etc.
One of the other C-like field types that may be specified is a union (type
’union’). An example of a record specification, including a union is
given below.
example of a /*-----------------------------------------------------*/
record with /* Example of a record including a union */
union /*-----------------------------------------------------*/
rec:equip_rec "equipment"
{
char dev[12]; "%12s" "device" "device_name"
union temp
{
long l; "%d" "temp_int" "temperature"
float f; "%f" "temp_real" "temperature"
} temperature;
};
nesting of An alias name after the union name is not allowed. Nesting of unions is
unions possible.
The record information will become part of the include file to be

generated. In this file, the record is present as a normal C-structure. The
strings, as specified after the record fields, will not be present in the
include file.
Within the data dictionary, the information about each record field is
saved in a separate record that will be stored in the field data dictionary
file (FDD-file).

How to specify the record keys Creation of a DDL-file
2.6 How to specify the record keys

The key specification is used to specify the record fields of a data set
which all together define the record’s key. There must always be at least
one key specified. Keys are used as indices to select certain records in a
data set, and in case of ACCESS/FAST to describe relations between
data sets.
key fields The specification consists of a key name (which must be unique), one or
more record fields that form the keys, and a flag (optional). If a key
specification includes more than one field (combined key), those fields
must be separated by a comma.
A flag can be specified for each key. This can be:
key flags • nodup

This means that duplicate keys are not allowed, i.e. each key must
be unique. This flag is also taken as default, if specification in the
DDL-file is omitted.
• dup
This means that duplicate keys are allowed.
• compress
When this flag is specified, redundant key information will be
deleted (see DATABASE/FAST (ISF) documentation for more
information)
The key information will become part of the include file to be generated.
In this file the keys are specified in a #define, being an array of key
descriptions structures. An element of that array can be used directly
when calling ISF-routines (e.g. to open a file, etc.).
Within the data dictionary, the information about each key is saved in a
separate record and will be stored in the key data dictionary file (KDD-
file).
examples of Some examples of key specifications are given below.

key
specifications • Simple key (including one field):
key: rack_key = (field_1) nodup
• Combined key (including more fields):
key: device_key = (field_1, field_2.dev_1) nodup
or
relative and key: device_key = (field_1, dev_1) nodup
absolute keys
If the field is a member of a sub structure, the whole path (structure name

Creation of a DDL-file How to specify decode information
and field name) can be given, where the names are separated by dots.
This way of referencing a member of a structure is identical to the way
this happens in C, and is called a relative key. If the field name is unique
within the entire record, the path is not needed (absolute key). In the case
of two equal field names and where the path is not given in the key, the
compiler will choose the first field name at the lowest nested level!
2.7 How to specify decode information

When designing a record layout for one or other application, it might be
desired to store certain field values in a binary coded way, e.g. repeating
field values in record fields, a list of fixed field values in a record’s field,
etc.. Due to the binary coded, repeating value of the decoded field, the
decoded field can not be used as a key field.
The application accessing the data set in which the records reside, has to
convert the binary coded information to a form readable by an end-user,
when it shows the contents of the records. Also the other way around,
the application has to convert the (plain ASCII) information entered by
an end-user, to its binary equivalent. This can be done in a number of
ways:
• Hard-coded
The application has a "look-up" table to perform the necessary
conversions.
• Additional data set
An additional data set is defined which contains the relation
between binary information and plain ASCII text. The application
accesses this additional data set to perform the necessary
translations.
• By decode information residing in the data dictionary
When specifying the contents of a DDL file, it is optionally possible
to specify so called decode information for simple fields in a record.
This decode information describes the relation between binary
values that may occur in the field and the (explanatory) ASCII text
that is related to the binary value.
A decode specification describes the decode information for one field in

a record. Multiple decode specifications are allowed in a DDL file. A
decode specification always starts with one of the keywords ’DECODE:’
or ’decode:’. This keyword must be followed by a (unambiguous) field
name specification. The field name specification must be followed by a
list of relations. Each relation describing a binary-value/ASCII-text

How to specify decode information Creation of a DDL-file
relation pair.
After the DDL compiler has successfully compiled the DDL file, the
decode information is stored in the Decode Data Dictionary file (DDD-
file).
A simplified example of the use of a decode specification is given

below.
example of /*------------------------------------------------------*/
record with /* Example of a record with decode information */
decode info /*------------------------------------------------------*/
def:MAX_EMP_NAME 20
.....<data set parameters>.....
rec:emp_rec "employee"
{
long emp_nr;
char name[MAX_EMP_NAME];
long function;
long department;
};
.....<record key specification>.....
decode: function { {1,"Junior Engineer"},

{2,"Senior Engineer"},
{3,"Project Manager"}
};
decode: department { {1,"Operations"},
{2,"Research & Development"},
{3,"Services & Support"}
};

Creation of a DDL-file How to specify decode information

General Compilation of a DDL-file
3 Compilation of a DDL-file
3.1 General
This chapter contains a brief explanation of how the DDL-compiler
must be used, how to compile a DDL-file and - depending on what is
desired - how to create an include file and/or update a data dictionary.
Detailed information can be found in chapter ’Reference’.
• How to run the DDL-compiler,

• How to use command line flags,
• How to generate an include file,
• How to update a data dictionary,
• How to list compiler errors.
3.2 How to run the DDL-compiler

To activate the DDL-compiler, the following command must be entered
on the command line:
how to ddl <DDL_file_name>

start-up
The <DDL_file_name> here is the name of the DDL-file to be compiled.
If no file name is specified, the compiler will respond with the
instruction:
Enter file name ddl-source:
If the extension of the <DDL_file_name> is ’.ddl’, it may be omitted.
When the compiler is ready, or the process is terminated in the case of

fatal errors, the result of the compilation is always logged on the screen.
By result is meant the number of compiler errors.
When running the compiler as described above, it will only function as

a ’syntax checker’. For the actual creation of an include file or for
updating a certain data dictionary, a flag must be specified on the
command line when starting up. The same must be done when
information about errors that have occurred is desired. This is explained
in the following sections.

Compilation of a DDL-file How to use command line flags
3.3 How to use command line flags

This section contains a description of the flags that can be specified on
the command line when staring up the compiler. Flags are used to
choose which actions the compiler must take.
Flags are always specified after the <DDL_file_name> on the command

line.
In general:
specification ddl <DDL_file_name> <flag_1> <flag_2> ... <flag_n>

of
flags
The following flags are available:
available • -i to generate an include file

flags • -d to update a data dictionary
• -b to switch off the (TLS_LONG) boundary check
• -l to create a list file containing compilation info
(errors etc.)
• -v to display the same info as in the list file on the screen
• -r to remove an entry from the data dictionary
• -s to create a file containing the compiler’s symbol table
contents
• -q to use quiet mode
All flags are optional, and they may be used in any combination. When
more flags are specified, no special order is required. In the following
subsections each flag is described separately.
3.4 How to generate an include file

To cause the generation of an include file during compilation of a DDL-
file, the ’-i’ flag must be used on the command line.
In general:
generation ddl <DDL_file_name> -i<include_file_name>

of an
include file Specification of the <include_file_name> is optional. If it is
omitted, the name of the generated include file will be equal to the
<DDL_file_name>. The extension of a generated include file name will

How to update a data dictionary Compilation of a DDL-file
always be ’.h’.
Example:
Suppose that on the command line is entered:
ddl test_file.ddl -i
Then an include file will be generated with the name ’test_file.h’.
For details about the include file’s contents, see chapter ’The include
file’
3.5 How to update a data dictionary

Before starting with the explanation of updating the data dictionary, it is
important to know the following rules:
• I Each data set described in a data dictionary must be unique

within that data dictionary.
• II Each record described in a data dictionary must be unique
within that dictionary.
• III A data set described in a data dictionary must contain one
and not more than one record type, that is also described
in the same dictionary.
• IV A record described in a data dictionary must belong to
one and not more than one data set, that is also described
To effect the update of a data dictionary during compilation of a DDL-

file, the ’-d’ flag must be used on the command line.
In general:
update ddl <DDL_file_name> -d<data_dictionary_name>

of a data
dictionary The <data_dictionary_name> must be specified without extension.
The reason is that each data dictionary consists of four logical files and,
depending on the operating system used, each logical file can consist of
one or more physical files. Each logical file will automatically get a
standard extension:
• _s.sdd for the set data dictionary (SDD) file

• _f.fdd for the field data dictionary (FDD) file

Compilation of a DDL-file How to update a data dictionary
• _k.kdd for the key data dictionary (KDD) file

• _d.ddd for the decode data dictionary (DDD) file
Example:
Suppose that the following command line is entered:
ddl test_file.ddl -dtest_dictionary
Then the following logical files will be generated:
• ’test_dictionary_s.sdd’,
• ’test_dictionary_f.fdd’,
• ’test_dictionary_k.kdd’,
• ’test_dictionary_d.ddd’.
new In case the specified data dictionary does not exist, the compiler will
dictionary create the dictionary files and fill these with records containing the data
set information from the DDL-file.
existing When a specified data dictionary already exists, i.e. its dictionary files
dictionary are available, the compiler will open the files to update them.
Depending on the current data dictionary contents and the record and set
name specified in the DDL-file, one of the following situations will
occur:
new set • set name: not yet in dictionary

new record record name: not yet in dictionary
In this case the information from the DDL-file is always added to

the data dictionary.

old record record name: already in dictionary
In this case the dictionary will not be updated, because then there
would be a set without a record (description incompatible with rule
III), or the record would become part of two sets (incompatible with
rule IV).
The compiler will respond with:
Record <record_name> is already used in

another data set. Data dictionary is not
updated!

How to update a data dictionary Compilation of a DDL-file
Remarks:
- Only unique record names and set names
are allowed.
- A record may be part of one data set
only.
old set • set name: already in dictionary

In this case, the compiler will respond with the question:
Data set <data_set_name> already exists

with another record name in data
dictionary.
Modify data dictionary ? [y/n]:
When ’y’ is entered, the dictionary will be updated with the

information from the DDL-file. Meanwhile the description of the
record that was originally coupled to the data set is removed from
the data dictionary, because in the new situation it is no longer
related to a data set (see also rule IV).
When ’n’ is entered, the dictionary will not be updated.

old (equal) record name: already in dictionary, while set reference in
record dictionary is equal to specified set
In this case, the compiler will respond with the question:
Data set <data_set_name> and record

<record_name> already exist in data
dictionary.

information from the DDL-file.

old (different) record name: already in dictionary, but set reference in
record dictionary is not equal to specified set
In this case the dictionary will not be updated, because

then there would be a set without any record (incompatible
with rule III), or the record would become part of two sets

Compilation of a DDL-file How to list compiler errors
(incompatible with rule IV).

updated!!
Remarks:
- Only unique record names and set names are
allowed.
- A record may be part of one data set only.
For details about the contents of the data dictionary files, see Chapter 5.
3.6 How to list compiler errors

Compiler errors are reported by means of error messages. These
messages can be observed using the list flag and/or the verbose flag.
list flag • List flag

When using the list flag a listing file will be created during
compilation. This file contains a ’report’ of the compilation
process; i.e. the source read in and, in the case of compiler errors,
error descriptions are included. The list flag must be entered as
shown below:
ddl <DDL_file_name> -l<listing_file_name>
When the <listing_file_name> is omitted, the compiler will

take a default name, being the <DDL_file_name>. The extension of
a list file name will always be ’.lis’.
verbose • Verbose flag

flag The use of the verbose flag is rather similar to that of the list flag.
It is also used when a ’compilation report’ is desired. However,
when using the verbose flag, the report (error descriptions, etc.), is
represented on the screen, i.e. a list file or similar will not be
created. The verbose flag must be entered as shown below:
ddl <DDL_file_name> -v

How to suppress error messages Compilation of a DDL-file
3.7 How to suppress error messages

It is possible to suppress some of the messages that the DDL compiler
produces. Specifying the quiet mode flag suppresses the following
messages:
• When the DDL compiler does not detect any errors, it normally
reports this fact anyway. In quiet mode, no message is displayed on
success - “no news is good news”!
• The DDL compiler normally asks for confirmation when replacing
a data set in the dictionary that is already there. In quiet mode the
compiler replaces the data set without asking for confirmation.
Quiet mode can be used in combination with other switches and is

specified as follows:
ddl <DDL_file_name> -q

Compilation of a DDL-file How to suppress error messages

General The include file
4 The include file

4.1 General
This chapter includes a brief description of an include file, generated by
the DDL-compiler. This will be done using an example that can be found
in Appendix A:.
In section A.2, a DDL-file example is shown. Section A.3 contains an
include file example; this include file is the result of compilation of the
DDL-file mentioned above.
• Defined constants
• General data set information
• Record information
• Key information
4.2 Defined constants

In the DDL-file, one defined constant specified:
DEF: max_sz 32
In the generated include file it has been translated to the following

#define:
#define max_sz 32
The example shows that both name and value are copied from the DDL
file without changing anything.
4.3 General data set information

The general data set parameters specified in the DDL-file are:
SET: set_name,
serv_node,
serv_name,
data_node,
5,
"datafile.dat",
KEY;

The include file Record information
In the generated include file all of those parameters have been translated
to #defines:
#define SET_NAME_DSET_NM "set_name"
#define SET_NAME_SERV_ND "serv_node"
#define SET_NAME_SERV_NM "serv_name"
#define SET_NAME_DATA_ND "data_node"
#define SET_NAME_PATH_NR 5
#define SET_NAME_FILE_SP "datafile.dat"
#define SET_NAME_FFMT_MD 1
The example shows that all seven parameters are the values of the
#defines now. The names of these #defines are standard names; i.e.
they do not depend on the DDL-file and are the same in each generated
include file.
4.4 Record information

In the DDL-file the following record is specified:
DEF: max_sz 32
RECORD:rec_nm "record_alias"
{
long long_fld; "%d" "long_field" "long"
char strn_fld[max_sz];
"%32s" "string_field""string"
struct struct_nm "struct_alias"

{
ubyte ubyt_fld; "%c" "ubyte_field" "ubyte"
char char_fld; "%c" "char_field" "char"
short shrt_fld; "%d" "short_field" "short"
double dble_fld; "%f" "double_field""double"
} struct_decl;
long dummy; "%d" "" ""
(field_sup)
};
In the generated include file this record has been completely translated

Record information The include file
to a C-structure (struct), see overleaf:
#define max_sz 32
struct rec_nm
{
TLS_LONG long_fld;
char strn_fld[max_sz];
struct struct_nm
{
TLS_UBYTE byt_fld;
char char_fld;
TLS_SHORT shrt_fld;
TLS_DOUBLE dble_fld;
} struct_decl;
TLS_LONG dummy;
};
The following remarks can be made when comparing the specified

DDL- record and the generated C-structure:
• The ’record’ type has been changed into ’struct’.

• All strings (format, alias_name, header and options field), specified
behind the record fields in the DDL-file, are deleted. The specified
strings are used for data dictionary storage only.
• The index ’[max_sz]’ is not changed. This is allowed, because
’max_sz’ is specified as #define in this include file.
In addition to the C-structure, a number of format strings are derived

from the record in the DDL-file. These format strings are included as
#defines in the DDL-file and can be used by applications for system
conversion purposes. The format strings are:
#define STRUCT_NM_FMT "2CSD"

#define REC_NM_FMT "L34CSDL"
#define REC_NM_FFMT "L34CSDL"
The first format string (STRUCT_NM_FMT) is the format of structure

struct_nm.
The second format string (REC_NM_FMT) is the format of the complete

record structure rec_nm.
The third format string (REC_NM_FFMT) is a file format string and can be

The include file Key information
used by applications when calling certain routines of DATABASE/

FAST (ISF-routines). In this example, it coincidentally has the value of
REC_NM_FMT too. The file format string is dependent on the file format
mode, specified in the data set specification of the DDL-file, and will be:
• The same as the format string, where ’ALL’ is specified (or

omitted) as file format mode in the data set specification.
• Different from the format string, where ’KEY’ or ’NON’ is
specified as file format mode in the data set specifications.
- When ’KEY’ is specified, only the fields that are used in a key
specification are formatted, the remaining fields are represented
as characters in the format string.
- When ’NON’ is specified, no field is formatted in
’REC_NM_FFMT’; all fields are represented as characters in this
format string
Because the file format mode is included as a #define

(’SET_NAME_FFMT_MD’) applications using the include file know about
how to interpret the file format string.
4.5 Key information

In the DDL-file, the following keys are specified:
KEY: simp_key = (long_fld) NODUP

KEY: abs_comb_key = (ubyt_fld, shrt_fld) DUP
KEY: rel_comb_key =
(struct_decl.char_fld,struct_decl.dble_fld)DUP
In the generated include file, the key specifications have been translated
to a number of #defines and can be used directly by applications when
calling routines of DATABASE/FAST (ISF-routines). The generated
#defines are listed below:
#define REC_NM_KEYS 3
#define REC_NM_KEYS_DEF struct keydesc

rec_nm_keys[REC_NM_KEYS]
#define REC_NM_KEYS_INI REC_NM_KEYS_DEF = \

{ { ISNODUPS, 1, { 0, 4, 0 } }, \
{ ISDUPS, 2, { { 36, 1, 0 }, \
{ 38, 2, 0 } } }, \
{ ISDUPS, 2, { { 37, 1, 0 }, \
{ 40, 8, 0 } } } }

Key information The include file
#define REC_NM_KEYS_SIMP_KEY 0
#define REC_NM_KEYS_ABS_COMB_KEY 1
#define REC_NM_KEYS_REL_COMB_KEY 2
’REC_NM_KEYS’ specifies the total number of keys for the current record
set. In the current example there are three keys.
’REC_NM_KEYS_DEF’ is an array with ’REC_NM_KEYS’ (3) elements.

Each of the elements is a structure of type ’keydesc’ (key description)
and describes one key.
’REC_NM_KEYS_INI’ is a #define that initializes the key descriptions

array. For each key the following parameters, among others, are
initialized:
• The flag (dup, nodup, etc.)

• The offset, with respect to the beginning of the entire record, of
each record field that participates in the key.
• The length (in characters) of each record field that participates in
the key.
For more information about key descriptions, see ’DATABASE/FAST

Programmer’s Guide’.
The last three #defines, ’REC_NM_KEYS_SIMP_KEY’,

’REC_NM_KEYS_ABS_COMB_KEY’, and
’REC_NM_KEYS_REL_COMB_KEY’, contain a unique sequence number
for each key. This number is used as an index in the key description
array mentioned before.

The include file Key information

General The data dictionary
5 The data dictionary

5.1 General
This chapter includes a brief description of the data dictionary files,
updated by the DDL-compiler.
A data dictionary consists of the following four logical files:
• SDD-file, being the set data dictionary file

• FDD-file, being the field data dictionary file
• KDD-file, being the key data dictionary file
• DDD-file, being the decode data dictionary file
The data dictionary logical files are normal ISF-files and can be
accessed with the ISF-routines as described in the DATABASE/FAST
Programmer’s Guide.
• Records in the set data dictionary file

• Records in the field data dictionary file
• Records in the key data dictionary file
• Records in the decode data dictionary file
5.2 Records in the set data dictionary file

When updating the data dictionary by compilation of a DDL-file, one
record will always be added to the set data dictionary (SDD) logical file.
If the SDD record is already in the data dictionary, it will be updated
with the new set information, as specified in the DDL-file.
An SDD-record consists of a number of fields. These fields are filled

with the set parameter values from the DDL-file.
Note that set parameters, specified as string in the DDL-file, are stored
without the double quotes in the SDD-record.
5.3 Records in the field data dictionary file

The field data dictionary (FDD) logical file, will contain a separate
record for each simple field specified in the record layout of the DDL-
file. Moreover, there will also be such an FDD-record for the DDL-

The data dictionary Records in the field data dictionary file
record itself and also one for each struct specified in DDL.
A FDD-record consists of the following fields, describing a field from

DDL:
• Set name
The name of the set to which the field belongs.
• Record name
The name of the record to which the field belongs.
• Field name
The name of the field as specified in record specification. If an alias
field name is specified for a certain record’s field, then the alias
name is used as the field name in the FDD-record.
• Field identifier
The field identifier is a unique number that identifies the field
within the record.
• Field type
The type of the record’s field as specified in record specification.
Note that the type of ’record’ is converted to ’struct’ here.
• Field length
The field’s length specified in bytes. Note that only simple fields
have a length that is greater than zero.
• Field offset
The field’s offset (in bytes) with respect to the beginning of the
entire record.
• Field level
The field’s level with respect to the record itself (which is level 0).
Thus fields that are not a structure’s field have level 1. Fields that
are a structure’s field have level 2, fields that are structure’s fields
of structures within structures have level 3, etc..
• Previous field identifier
The field’s parent identifier (owner) of the field is indicated.
• Field range
In those cases where the field’s type is an array, the number of
indices is specified here.
• Field format
The print format of the field as specified in a string in the record
specification part of a DDL file.
• Field header
The field’s header that can be used as a column header in a report,
or in an ACCESS/FAST table, specified as a string in the record
specification part of a DDL-file.
• Field options

Records in the key data dictionary file The data dictionary
This field contains the options specified for the field.
5.4 Records in the key data dictionary file

The key data dictionary (KDD) logical file, will contain a record for
each key specified in the DDL-file.
A KDD-record consists of the following fields, to describe a key from

DDL:
• Record name
The name of the record to which a key belongs.
• Key name
The name of a record’s key, as specified in key specification part of
a DDL-file, to the left of the ’=’ symbol.
• Key identifier
A unique number to identify a record’s key.
• Key flag
The flag as specified for a record’s key (nodups, etc.).
• Number of fields
The total number of the record’s fields which form a record’s key.
• Field identifiers
The field identifiers, as specified in the corresponding FDD-record,
of the record’s fields which form a record’s key.
5.5 Records in the decode data dictionary file

The decode data dictionary (DDD) logical file, will contain a record for
each decode relation specified for a field of a data set.
Such a DDD-record consists of the following fields:
• Set name
The name of the data set to which the field belongs.
• Field identifier
A unique number that identifies a field, as specified in the
corresponding FDD-record.
• Binary value
The binary value for which an (explanatory) ASCII text is supplied.
• ASCII value
The ASCII value being related to the binary value.

The data dictionary Records in the decode data dictionary file

6 Reference
6.1 Introduction
This chapter contains information about all aspects of DDL and the
DDL-compiler. It covers:
• How to read the DDL-syntax description,

• Some frequently used lexicals,
• General layout of a DDL-file,
• Defined constant specification,
• Data set specification,
• Record specification,
• Key specification,
• Decode specification,
• Usage of the DDL-compiler,
• Error messages.
6.2 How to read the DDL-syntax description
6.2.1 General
To make the syntax description of DDL that is contained in the

following sections easier to understand, the notation principles used in
these descriptions are briefly explained.
6.2.2 Top-down description
In the explanation of the DDL-syntax description, the top-down

principle is followed. This means that first DDL is assumed to consist of
only a few imaginary language elements. However, in the next step of
the explanation, each of these element consists of other elements or sub-
elements. This conversion from elements to sub-elements will be
repeated, until all sub-elements are items that are actually part of the
language.
A simple example of a top-down description is given overleaf.
person_id : name
address

Reference How to read the DDL-syntax description
city
name : word
address : street
number
city : word
street : word
word : (A,B,C,...,Z) one time

(a,b,c,...,z) n times (with 0<=n<=20)
number : (0,1,2,...,9) n times (with 1<=n<=5)
The example here shows that a person is identified by several words and
a number. A word consists of at least 1, and at most 21 letters, while the
first letter must be upper case and the remaining letters must be lower
case. A number consists of at least 1 and at most 5 digits.
In the example there are no special symbols used to indicate whether an

element is optional, how many times it may be repeated, etc. Such
symbols are described in the next section.
6.2.3 Symbols used
Below is a list of special symbols used in the DDL-syntax description.
| • symbol :|
meaning : indicates one element (to the left of the symbol)
or another element (to the right of the symbol)
to be specified.
example: A|B|C, means one of the characters ’A’, ’B’ or
’C’ must be specified
[] • symbol :[ ]
meaning : indicates that the element included in the
brackets is optional
example : [1|2], means ’1’ or ’2’ may be specified
{ }.. • symbol : { }..
meaning : indicates the element included by the accolades
must be specified one or more times
example : A[{1|2|3|4|5|6|7|8|9|0}..], means that
an ’A’ must be specified, while it may be
<>
followed by zero or more digits
• symbol :< >
meaning : indicates that an element is not a basic

Some frequently used lexicals Reference
element, but a collection of elements or

possibilities.
example : <digit> : 1|2|3|4|5|6|7|8|9|0
’’ • symbol :’ ’
meaning : indicates that the character included by the
quotes is actually part of DDL; i.e. it is not
meant as a special symbol
example : [’[’]key[’]’], means that ’key’ or ’[key]’
must be specified
6.3 Some frequently used lexicals

Prior to the explanation of specifying a data set in DDL with its record
and keys, this section contains a description of some lexicals that are
used quite frequently.
numeric • <numeric_value> : <integer>|<real>

value
examples : 251
38.681
string • <string> : " [{<any character but ’"’>}..] "
examples : "This is a string"

"38ue,dc.3ey$%*& (another string)"
simple_id • <simple_id> : a|b|..|z|A|B|..|Z

[{a|b|..|z|A|B|..|Z|0|1|..9|_}..]
examples : field_1
Main_Area
index • <index> : ’[’<positive_integer>

|<simple_id>’]’
examples : [123]
[index_1]
identifier • <identifier> :<simple_id>[{<index>}..]
examples : item

Reference General layout of a DDL-file
field_1[3][4][2]
Main_Area[section][group]
comment • <comment> :/*[{<any character but ’*/’>}..]*/
examples : /* This is comment */

/* This * is * also * comment */
/* This / is / also / comment */
remark : comment may not be longer than one
line
6.4 General layout of a DDL-file

SYNTAX <DDL_file> : [<defined_constant_spec>]
<data_set_spec>
<record_spec>
<key_spec>
<decode_spec>
SEMANTICS The syntax above covers a complete DDL-file specification. More

details about the elements in it can be found in the following sections.
NOTES • The specifications must be given in the sequence as described

above.
• Only the defined_constant specification is optional.
• It is allowed to add comment through the entire DDL-file. For a
description of comment please refer to section ’Some frequently
used lexicals’.
EXAMPLES An example of a complete DDL-file is given in Appendix A, section

A.2.
6.5 Defined constant specification

SYNTAX <define_constant_spec> :<define_tk>
<constant_name>
<constant_value>
<define_tk> :def:
|define:
|DEF:

Data set specification Reference
|DEFINE:
<constant_name> :<simple_id>
<constant_value> :<numeric_value>
SEMANTICS The defined constant specification is used to specify defined constants

(#define) in the include file (.h file) to be generated. Moreover, once
specified in a DDL-file, a defined constant name may be used as field
index in the record specification of that DDL-file, see also section
’Record specification’.
NOTES The defined constant specification only affects the include file to be
generated. It does not work on any data dictionary.
EXAMPLES • def: MAX_ITEM_COUNT 250
• DEFINE: Normal_Temperature 37.5
6.6 Data set specification

SYNTAX <data_set_spec> :<set_tk>,
[<set_name>],
[<server_node>],
[<server_name>],
[<data_node>],
[<directory_path>],
[<data_file_spec>],
[<file_fmt_mode>];
<set_tk> :set:
|dataset:
|SET:
|DATASET:
<set_name> :<simple_id>
<server_node> :<simple_id>
<server_name> :<simple_id>
<data_node> :<simple_id>
<directory_path> :<(positive)integer_value>

Reference Data set specification
<data_file_spec> :<simple_id>
|<string>
<file_fmt_mode> :ALL
|KEY
|NON
SEMANTICS In the data set specification all general data set parameters are defined.
If this specification is not in the DDL-file, an error will be reported.
The meaning of the parameters is:
• <set_name> is a unique name within the data dictionary that

identifies the data set.
• <server_node> is the location of the server that will handle the
data set.
• <server_name> is the name of the server that will handle the data
set.
• <data_node> is the node on which the data is actually available.
• <directory_path> is the number of the directory path as
specified in the header file ’tools.h’.
• <data_file_spec> is the name of the physical database file (used
when the set is actually a physical file), specified or not in
combination with a directory path.
• <file_fmt_mode> indicates which part of the file format string
contains the actual format:
- ALL : both key fields and non-key fields formatted
- KEY : key fields only; remaining fields as characters
- NON : all fields as characters
NOTES • Only the <set_name> must be specified; the remaining six

parameters are optional. If one of them is omitted, the DDL-
compiler will fill in a default value for it during compilation. The
default values of the optional parameter are:
- <server_node> : "0"
(same node as calling process,
e.g. REPORT/FAST)
- <server_name> : "dbs_server"
- <data_node> : "0"
(same node as server)
- <directory_path> : 0
- <data_file_spec>: "<set_name>.dat"
- <file_fmt_mode> : "ALL"
(value 0, both key and non-key

Record specification Reference
fields formatted in the file

format)
• Each parameter will become a defined constant in the include file

to be generated. Also additional information derived from the set
parameters will be in that include file. For more information about
generating an include file, see also section ’Compilation of a DDL-
file’.
If a data dictionary is updated, a new SDD-record, containing the

specified data set information will be written into the SDD-file. If the
data dictionary already contains a data set specification with the same set
name, the user is asked for confirmation of updating the dictionary, see
also section ’Compilation of a DDL-file’.
EXAMPLES • set: auto_set_1,
node_1,
auto_server,
node_2,
3,
[auto.data]general.dat,
KEY;
• DATASET: auto_set_2,,,,,,;
6.7 Record specification
6.7.1 General
SYNTAX <record_spec> :<record_tk> <simple_id> [<alias_name>]

’{’<field_decl>’}’;
<record_tk> :rec:
|record:
|REC:
|RECORD:
<field_decl> :see subsection ’Field declarations’
<alias_name> :<string>
SEMANTICS • In the record specification, the structure of the record has to be

defined. The record must be specified, otherwise an error will be
generated. Except for the word ’rec:’ the syntax is exactly the

Reference Record specification
same as the variable declaration in the C language. How the fields

(field_decl) have to be specified is explained in subsection
’Field declarations’.
• <alias_name>
This optional string contains an alias for the record name. When it
is specified, this name will be the record name in the data
dictionary; i.e. for the user, the record is accessible by specifying
this name. The alias name does not effect the include file to be
generated.
NOTES • The length of a record must be a multiple of 4 bytes long. The

reason for this is that the field behind the record always lies on the
right boundary and will never cause problems during
communication with other systems.
EXAMPLES • rec: auto_rec "auto"

{
...... (<field_decl>)
};
6.7.2 Field declarations
SYNTAX <field_decl> : {<single_field>}..
<single_field> : <normal_field>
|<struct_union_decl>
<normal_field> : <simple_type_tk>
<identifier>;
[<format>
[<alias_name>
[<column_header>
[<field_options]]]]
<simple_type_tk>
: char|short|ushort|long|ulong|float|
double|boolean
(note: also uppercase is allowed!)
<format> : <string>
<alias_name> : <string>

Record specification Reference
<column_header>: <string>
<field_options>: ’(’<opt_part>[{,<opt_part>}..]’)’
<opt_part> : <field_sup_tk>
<field_sup_tk> : field_sup | FIELD_SUP
<struct_union_decl>
: see next subsection
’Structure and union declarations’
SEMANTICS The field declaration within a record is almost similar to the field
declaration within a structure in the C-language. Fields that are arrays
may have up to four dimensions.
If a <single_field> is a normal field , the following attributes can be

specified behind the semi colon:
• <format>
This string indicates the print format of a single field.
• <alias_name>
This string contains the alias name of a single field. When an alias
name is specified, this name will be the field name in the data
dictionary; i.e. for the user, the field is accessible by specifying this
name.
• <column_header>
This string contains the column header of a single field. It can be
used when generating reports, for example, to name a column with
equivalent fields in it.
• <field_options>
This field is used to specify additional sub attributes for the current
field. The only sub attribute currently defined for a record field is
field suppression.
- The field suppression sub attribute can be used to indicate that
the field does not contain relevant information (e.g. dummy
fields in a record to correctly align fields in the record or dummy
fields for spare purposes). For example, applications using the
data dictionary may use the field suppression sub attribute to
determine whether or not to display the field for which this sub
attribute has been set.
NOTES
• The elements <format>, <user_name>, <column_header> and

Reference Record specification
<field_options> do not affect the include file to be generated.

They will affect the data dictionary only.
• The tokens indicating the field types (<simple_type_tk>) may be
specified in either lower case or upper case.
EXAMPLES • char mark[12]; "%12s" "mark" "mark:"

char reg_num[8]; "%8s" "number" "reg_no:"
long weight; "%5d" "weight" "weight:"
long dummy; "%d" "" ""
(field_sup)
6.7.3 Structure and union declarations
SYNTAX <struct_union_decl> : <struct_union_type>

<simple_id>
[<alias_name>]
’{’<field_decl>’}’;<identifier>
<struct_union_type> :struct|union
<alias_name> : <string>
SEMANTICS • With the <struct_union_decl> it is possible to define structures

and/or unions (like C) within a record. Nesting is allowed, i.e.
within a structure or union a new structure or union can be
specified, because <field_decl> may be a
<struct_union_decl>.
• <alias_name>
This optional string contains an alias for the structure’s name.
When it is specified, the alias name will replace the structure’s
name in the data dictionary; i.e. for the user, the structure is
accessible by specifying the alias name. The alias name does not
affect the include file to be generated.
NOTES • Note that in case of <field_decl> being a <normal_field>, the
field’s identifier may only be followed by the field’s attributes,
see also the previous subsection ’Field declarations’.
• The compiler performs the following checks:
- Whether the size of the structure or union is a multiple of 4 bytes
long.
- Whether the structure or union has to be on a 4 bytes boundary.
Therefore the fields within and after the record are always on the
right boundary and will cause no problems regarding

Key specification Reference
communication with other systems.
EXAMPLES • struct colour

{
long number; "" "col_id" "colour_id"
char name[8]; "%8s" "col_nm" "colour"
long dummy; "" "" ""
(field_sup)
struct attributes
{
long hue; "%d" "" "colour_hue"
long brilance; "%d" "" "colour_bril"
}
}
6.8 Key specification

SYNTAX <key_spec> :{single_key}..
<single_key> :<key_tk>
<simple_id> ’=’
’(’<key_parts>’)’<key_flags>
<key_tk>: :key: | KEY:
<key_parts> :<key_field>[{,<key_field>}..]
<key_field> :<simple_id>[{.<simple_id>}..]
<key_flags> :[nodup|dup][compress]
SEMANTICS This statement is used to specify the record’s keys of a data set. The
specification consists of a key name (which must be unique), one or
more fields that form the keys, and a flag (optional). If a key
specification includes more than one field (combined key), those fields
must be separated by a comma.
For each key a flag can be specified. This can be:
• nodup This means that duplicate keys are not allowed,

i.e. each key must be unique.
• dup This means that duplicate keys are allowed.
• compress When this flag is specified, redundant key information
may be omitted (see ISF-documentation for more
information)

Reference Decode specification
The key information will become part of the include file to be generated.
In this file, the keys are specified in a #define, being an array of key
description structs. An element of that array can be used directly when
calling DATABASE/FAST (ISF-) routines (e.g. to open a file).
Within the data dictionary, the information about each key is saved in a
separate record that will be stored in the key data dictionary (KDD) file.
NOTES If the field is a member of a structure, the whole path (structure name
and field name) can be given, where the different names are separated
by dots. This way of referencing a structure’s member is identical to the
way as is done in C. If the field name is unique within the entire record,
the path is not needed. In case of two identical field names, and where
the path is not given in the key, the compiler will choose the first field
name at the lowest nested level!
EXAMPLES See also the subsections ’Field declarations’ and ’Structure and union
declarations’.
• Simple key (including one field):

key: auto = (reg_num) nodup
• Combined key (including more fields):

key: color = (reg_num, color.name) nodups
or
key: color = (reg_num, name) nodups
6.9 Decode specification

SYNTAX <decode_spec> : {<decode_stmt>}..
<decode_stmt> : <decode_tk> <field_name>

’{’<decode_list>’}’;
<decode_tk> : decode: | DECODE:
<field_name> : <simple_id>[{.<simple_id>}..]
<decode_list> : <decode_elm>[,{<decode_elm>}..]
<decode_elm> : ’{’<integer>,<string>’}’
SEMANTICS
This statement can be used to specify the relations between binary

Usage of the DDL-compiler Reference
values (that might be assigned to the field) and ASCII text strings, for a
certain field in a data set. The decode information is stored in the Decode
Data Dictionary file (DDD-file). The information might be useful for
applications that access data sets which contain one or more fields with
binary coded information, and which want to display this information in
a readable manner to end-users. Also the other way around, if an
application has to convert the ASCII information entered by an end-user
to a binary equivalent, the contents of the DDD-file might be useful.
NOTES • The integer value to be specified for <decode_elm> can be

specified in both decimal and hexadecimal notation.
EXAMPLES • decode: function { {1,"Junior Engineer"},

{2,"Senior Engineer"},
{3,"Project Manager"}
};
• decode: department { {0x0001,"Ops"},
{0x0002,"R & D"},
{0x0003,"Sales"}
};
•
6.10 Usage of the DDL-compiler
6.10.1 Running the compiler
To activate the DDL-compiler, the following command must be entered

on the command line:
how to start ddl <DDL_file_name>
The <DDL_file_name> here is the name of the DDL-file to be compiled.

If no file name is specified, the compiler will respond with the question:
Enter file name ddl-source:
If the extension of the DDL-file is ’.ddl’, it may be omitted.
When the compiler is ready, or the process is terminated due to fatal

errors, the result of the compilation is always logged on the screen. In
this context result means the number of compilation errors.

Reference Usage of the DDL-compiler
a ’syntax checker’. For the actual creation of an include file or for

updating a certain data dictionary, a flag must be specified on the
command line when starting up. The same must be done when
information about errors which have occurred is desired. For this, see
the following subsections.
6.10.2 Command line flags
Flags are used to choose which actions the compiler must take.
Flags are always specified after the <DDL_file_name> on the command

line.
In general:
specification ddl <DDL_file_name> <flag_1> <flag_2> ... <flag_n>

of flags
The following flags are available:
flags • -d to update a data dictionary
• -b to switch off the (TLS_LONG) boundary check
(errors etc.)
• -v to put the same info as in the list file to the screen
• -s to create a file containing the compiler’s symbol table
contents
• -r to remove a data set from the dictionary
All flags are optional, while they may be used in any combination. When
more than one flag is specified, their sequence is random. In the
following subsections each flag is described separately.
6.10.3 Include file flag
To cause the generation of an include file during compilation of a DDL-

file, the ’-i’ flag must be used on the command line.
In general:
generation ddl <DDL_file_name> -i<include_file_name>

of an
include file

Specification of the <include_file_name> is optional. If it is

omitted, the name of the generated include file will be equal to the
<DDL_file_name>. The include file name extension will always be
’.h’.
Examples:
• Suppose that the following is entered the command line:
ddl test_file.ddl -i
Then an include file will be generated with the name
’test_file.h’.
• Suppose that the following is entered the command line:

ddl test_file.ddl -ifile_1.x
Then an include file will be generated with the name
’file_1.h’.
6.10.4 Data dictionary flag
Before starting with the explanation of updating the data dictionary, it is

important to know the following rules:
data
dictionary • I Each data set described in a data dictionary must be unique
rules within that data dictionary.
• II Each record described in a data dictionary must be unique
within that dictionary.
• III A data set described in a data dictionary must contain one
and not more than one record type that is also described
• IV A record described in a data dictionary must belong to
one and not more than one data set that is also described
To cause the update of a data dictionary during compilation of a DDL-

file, the ’-d’ flag must be used on the command line.
In general:

update ddl <DDL_file_name> -d<data_dictionary_name>

of a data
dictionary The <data_dictionary_name> must be specified without any
extension. The reason for this is that every data dictionary consists of
four logical files, each file having a standard extension:
• _s.sdd for the set data dictionary (SDD) file

• _f.fdd for the field data dictionary (FDD) file
• _k.kdd for the key data dictionary (KDD) file
• _d.ddd for the decode data dictionary (DDD) file
Example:
• Suppose the following is entered on the command line:
ddl test_file.ddl -dtest_dictionary
Then the following logical files will be generated:

’test_dictionary_s.sdd’,
’test_dictionary_f.fdd’,
’test_dictionary_k.kdd’,
and ’test_dictionary_d.ddd’.
new Where the specified data dictionary does not exist, the compiler will first
dictionary create the dictionary files, whereupon they are filled with records
containing the data set information from the DDL-file.
existing When a specified data dictionary already exists, i.e. the dictionary files
dictionary are available, the compiler will open the files to update them.
Depending on the current data dictionary contents and the record and set
name specified in the DDL-file, one of the following situations will then
apply:

In this case the information from the DDL-file is always added to

the data dictionary.

old record record name: already in dictionary
In this case the dictionary will not be updated, because then there

would be a set without any record (incompatible with rule III), or

the record would become part of two sets (incompatible with rule
IV).

updated!!
Remarks:
allowed.

new record record nam: not yet in dictionary
In this case the compiler will respond with the question:
Data set <data_set_name> already exists with

another record name in data dictionary.

information from the DDL-file. Meanwhile the description of the
record that was originally coupled to the data set is removed from
the data dictionary, because in the new situation it is not related to
a data set anymore (see also rule IV).

old (equal) record name: already in dictionary, while set reference in
record dictionary is equal to specified set
In this case the compiler will respond with the question:
Data set <data_set_name> and record

<record_name> already exist in data
dictionary.

information from the DDL-file.

old set • set name : already in dictionary

old (different) record name : already in dictionary, but set reference in
record dictionary is not equal to specified set
In this case the dictionary will not be updated, because

then there would be a set without any record (incompatible
with rule III), or the record would become part of two sets
(incompatible with rule IV).

updated!!
Remarks:
allowed.
For details about the contents of the data dictionary files, see Chapter 5.
6.10.5 Other flags
The flags to generate an include file and to update the data dictionary
have one common aspect: they have to be used more or less in order to
run the compiler meaningfully. The intention of the other flags
mentioned at the beginning of this section, is more to get useful
information about the compilation process.
Below a brief description of these flags is given.
boundary • Boundary flag;

flag When using this flag, the compiler does not perform the
(TLS_LONG) boundary check. The boundary flag must be entered
as given below:
ddl <DDL_file_name> -b
list flag • List flag;

When using the list flag a listing file will be created during
compilation. This file contains a ’report’ of the compilation

process; i.e. in the case of compiler errors, error descriptions are

included. The list flag must be entered as given below:
ddl <DDL_file_name> -l[<listing_file_name>]
When the <listing_file_name> is omitted, the compiler will

take a default name, being the <DDL_file_name>. The listing file
name’s extension will always be ’.lis’.
verbose • Verbose flag;

flag The intention of the verbose flag is rather similar to the list flag. It
is also used when a ’compilation report’ is desired. However when
using the verbose flag, the report (error descriptions, etc.), are
represented on the screen. This means that no list file or similar will
be created. The verbose flag must be entered as shown below:
ddl <DDL_file_name> -v
symbol table • Symbol table flag;

flag During the compilation process, the compiler will build a symbol
table. When the source information, read from the DDL-file is
found to be correct (spelling and syntax), the information is
temporarily saved in the symbol table. When the entire DDL-file is
read, the symbol table is complete and is used then to generate an
include file and/or to update a data dictionary, if desired. Finally the
symbol table is deleted, because it is no longer needed.
To be able to evaluate the symbol table’s contents afterwards, the
symbol table flag must be used. This results in a file being created
named ’ddl.sym’ and containing the entire symbol table’s contents.
The symbol table flag must be entered as shown below:
ddl <DDL_file_name> -s
remove • Remove data set flag;

flag This flag is used to remove an existing data set from a data
dictionary. No DDL-file is used as input. The remove data set flag
must be entered as shown below:
ddl <data_set_name> -r -d<data_dictionary_name>

[-v]
No other flags except the verbose flag are allowed in combination

with the remove data set flag.

Reference Error messages
6.11 Error messages

In this section, a survey of the DDL-compiler’s error messages with their
meaning is given. These messages are displayed on the screen, where the
’-v’ flag is used when running the compiler. The error messages are
saved in the list file, where the ’-l’ flag is used. In both cases the error
messages will be positioned in the DDL-source where the error
occurred.
• "’def:’ or ’set:’ expected"

The first keyword in the DDL-file is not one of the above keywords.
• "Identifier expected"
An invalid identifier is specified.
• "Data set name (id) expected"
The first parameter in the data set specification is not a valid data
set name.
• "Server node name (id) expected"
The second parameter in the data set specification is not a valid
server node name.
• "Server name (id) expected"
The third parameter in the data set specification is not a valid server
node name.
• "Data node name (id) expected"
The fourth parameter in the data set specification is not a valid data
node name.
• "Path number (integer) expected"
The fifth parameter in the data set specification is not a valid
directory path number.
• "File specification (string) expected"
The sixth parameter in the data set specification is not a valid file
specification.
• "Format mode expected: ’all’, ’key’ or ’non’"
The seventh parameter in the data set specification is not a valid file
format mode.
• "’rec:’ expected"
The record specification does not start with the right keyword.
• "’key:’ expected"
The key specification does not start with the right keyword.
• "Variable type expected, either in lower case or
upper case"
An invalid variable type is specified.
• "String expected; may be empty"
A string, being any character(s) but starting and ending with a
double quote ("), must be specified.
• "’{’ expected"

Error messages Reference
"’}’ expected"
"’;’ expected"
"’=’ expected"
"’(’ expected"
"’)’ expected"
"’,’ expected"
"’.’ expected"
For all of these messages, the reserved symbols mentioned in the

message must be specified.
• "One of the flags ’dup’, ’nodup’ or ’compress’
expected"
A flag at the end of a key specification is optional, but if specified,
it must be one of the above mentioned ones.
• "Integer or real value expected"
An integer (e.g. 25) or real (e.g. 25.78) value must be specified.
• "Index expected; ’[’<integer>’]’ or
’[’<identifier>’]’"
An index being an integer value between brackets or a previously
specified defined constant name must be specified.
• "’decode:’ expected"
The decode specification does not start with the correct keyword.
• "Field name expected"
The ’decode:’ keyword must be followed by a field name.
• "Integer value expected"
The binary value used in decode specifications must be an integer
value.
• "’field_sup’ expected"
The options part of a field declaration does not contain the
’field_sup’ keyword.
• "Unknown keyword encountered"
The keyword is not recognized by the DDL-compiler.
• "Number of subranges of <output string> exceeds the
limited number"
The number of indices of an array, specified by ’<output
string>’, is greater than 4.
• "<output string 1> has to be on a <output string 2>
bytes boundary"
The field specified by ’<output string 1>’is on an invalid
boundary of ’<output string 2>’ bytes.
• "<output string> already exists"
The name ’<output string>’ is already in use and may not be
specified again at this position.
• "<output string> has to be a multiple of 4 bytes long"
The entire record, field, structure, or union does not start on long
boundary.

Reference Error messages
• "Undefined index name"

The used index name is not specified as a define constant in this
DDL-file.
• "<output string> doesn’t exists"
The field name ’<output string>’ is not specified.
• "Key name <output string> does already exists"
The key name specified with ’<output string>’ is already in use.
• "Dataset <output string> not updated in data
dictionary"
The dataset specified by ’<output string>’, as described in the
DDL-file, is not updated in the data dictionary due to an error.
• "Decode text <output string> is too long"
The length of the string ’<output string>’, used in decode
specifications, exceeds the maximum length allowed.
• "Field <output string> not found in record spec."
A decoded field specified by ’<output string>’ refers to a field
that is not part of the record specification.
• "Decoded field <output string 1> can not be part of
key <output string 2>."
A decoded field, specified by ’<output string 1>’, can not be
part of the key specified by ’<output string 2>’.
• "Fieldname <output string> is a reserved SQL
keyword."
A fieldname, specified by ’<output string>’, can not be a
reserved SQL keyword.
• "Can’t open <output string>"
The file specified by ’<output string>’ cannot be opened.
• "Not enough memory available (alloc)"
The required memory space cannot be allocated.
• "Error"
Default error message, indicating that an unknwon error occured.

Introduction
Appendix A: An example
A.1 Introduction
In this appendix a complete example is given of a DDL-file with its
corresponding include file and data dictionary.
Section A.2 contains the DDL-file example.
Section A.3 contains an example of an include file, being the result of
compilation of the given DDL-file (compiled with the ’-i’ flag).
Section A.4 contains an example of a data dictionary. Here the records
that are in the dictionary as a result of compilation of the given DDL-file
(compiled with ’-d’ flag) are given.
A.2 DDL-file
In this section, an example of a DDL-file is given, including some
comment.
/*---------------------------------------------------*/
/* Example of a DDL-file */
/*---------------------------------------------------*/
/*---------------------------------------------------*/
/* Defined Constants Specification */
/*---------------------------------------------------*/
DEF: max_sz 32
/*---------------------------------------------------*/
/* Data Set Specification */
/*---------------------------------------------------*/
SET: set_name,
serv_node,
serv_name,
data_node,
,
"datafile.dat",
KEY;
/*---------------------------------------------------*/
/* Record Specification */
/*---------------------------------------------------*/
RECORD:rec_nm "record_alias"
{
long long_fld; "%d" "long_field" "long"
char str_fld[max_sz]; "%32s" "string_field" "string"
struct struct_nm "struct_alias"
DATABASE/FAST Language Manual A-1

Include file
{
ubyte ubyt_fld; "%c" "ubyte_field" "ubyte"
ubyte dummy; "" "" ""
(field_sup)
char char_fld; "%c" "char_field" "char"
short shrt_fld; "%d" "short_field" "short"
double dble_fld; "%f" "double_field""double"
} struct_decl;
};
/*---------------------------------------------------*/
/* Key Specification */
/*---------------------------------------------------*/
KEY: simp_key = (long_fld NODUP
KEY: abs_comb_key = (ubyt_fld, shrt_fld) DUP
KEY: rel_comb_key =
(struct_decl.char_fld,
struct_decl.dble_fld)
DUP
/*---------------------------------------------------*/
/* Decode Specification */
/*---------------------------------------------------*/
DECODE: long_field {{1, "First"},
{2,"Second"},
{3,"Third"}};
DECODE: short_field {{50,"Fifty"},
{51,"Fifty one"}};
A.3 Include file

In this section, an example of an include file generated by the DDL-
compiler is given.
A brief explanation of this file can be found in Chapter 4.
#ifndef _EXAMPLE_H
#define _EXAMPLE_H
#ifndef _ISF_H
#include <isf.h>
#endif
#define max_sz 32
#define SET_NAME_DSET_NM "set_name"
#define SET_NAME_SERV_ND "serv_node"
#define SET_NAME_SERV_NM "serv_name"
A-2 DATABASE/FAST Language Manual

Include file
#define SET_NAME_DATA_ND "data_node"
#define SET_NAME_PATH_NR 5
#define SET_NAME_FILE_SP "datafile.dat"
#define SET_NAME_FFMT_MD 1
struct rec_nm
{
TLS_LONG long_fld;
char str_fld[max_sz];
struct struct_nm
{
TLS_UBYTE ubyt_fld;
TLS_UBYTE dummy;
char char_fld;
TLS_SHORT shrt_fld;
TLS_DOUBLE dble_fld;
} struct_decl;
};
#define STRUCT_NM_FMT "2CSD"
#define REC_NM_FMT "L34CSD"
#define REC_NM_FFMT "L34CSD"
#define REC_NM_KEYS 3
#define REC_NM_KEYS_DEF struct keydesc

rec_nm_keys[REC_NM_KEYS]
#define REC_NM_KEYS_INI REC_NM_KEYS_DEF = \

{ { ISNODUPS, 1, { 0, 4, 0 } }, \
{ ISDUPS, 2, { { 36, 1, 0 }, \
{ 38, 2, 0 } } }, \
{ ISDUPS, 2, { { 37, 1, 0 }, \
{ 40, 8, 0 } } } }
#define REC_NM_KEYS_SIMP_KEY 0
#define REC_NM_KEYS_ABS_COMB_KEY 1
#define REC_NM_KEYS_REL_COMB_KEY 2
#endif

Data dictionary
A.4 Data dictionary

In this section, an example is given of data dictionary records that are
created by the DDL-compiler for the several data dictionary files.
Contents of the SDD-file (set data dictionary)
Field name record (n)
set_name SET_NAME
server_node SERV_NODE
server_name SERV_NAME
data_node DATA_NODE
dir_path 5
file_spec datafile.dat
fmt_mode 1

Data dictionary
Field
record (n) record (n + 1) record (n + 2) record (n + 3) record (n + 4) record (n + 5) record (n + 6) record (n + 7) record (n + 8)
name
set_name SET_NAME SET_NAME SET_NAME SET_NAME SET_NAME SET_NAME SET_NAME SET_NAME SET_NAME
rec_name REC_NM REC_NM REC_NM REC_NM REC_NM REC_NM REC_NM REC_NM REC_NM
DATABASE/FAST Language Manual

name RECORD_ LONG_ STRING_ STRUCT_ TLS_UBYTE TLS_UBYTE CHAR_ SHORT_ TLS_DOUBL
ALIAS FIELD FIELD ALIAS _ _ FIELD FIELD E_
FIELD FIELD FIELD
id 0 1 2 3 4 5 6 7 8
type 9 (struct) 4 (long) 0 (char) 9 (struct) 8 (ubyte) 8 (ubyte) 0 (char) 2 (short) 7 (double)
length 0 4 32 0 1 1 1 2 8
offset 0 0 4 36 36 36 37 38 40
level 0 1 1 1 2 2 2 2 2
prev_id 0 0 0 0 3 3 3 3 3
index_1 0 0 32 0 0 0 0 0 0
index_2 0 0 0 0 0 0 0 0 0
index_3 0 0 0 0 0 0 0 0 0
Contents of the FDD-file (field data dictionary)
index_4 0 0 0 0 0 0 0 0 0
format %d %32s %c %c %c %d %f
heading long string ubyte char short double
options 0x0000 0x0000 0x0000 0x0000 0x0000 0x0001 0x0000 0x0000 0x0000
A-5
Data dictionary
Contents of the KDD-file (key data dictionary)
Field name record (n) record (n + 1) record (n + 2)
key_name.rec_name REC_NM REC_NM REC_NM
key_name.name SIMP_KEY ABS_COMB_KEY REL_COMB_KEY
id 0 1 2
flag 2 1 1
parts 1 2 2
field_1 1 4 5
field_2 0 6 7
field_3 0 0 0
field_4 0 0 0
field_5 0 0 0
field_6 0 0 0
field_7 0 0 0
field_8 0 0 0

Data dictionary

Data dictionary

Data dictionary

Data dictionary

Data dictionary

Data dictionary
Contents of the DDD-file (decode data dictionary)
Field name record (n) record (n + 1) record (n + 2) record (n + 3) record (n + 4)
set_name SET_NAME SET_NAME SET_NAME SET_NAME SET_NAME
fld_id 1 1 1 6 6
bin_val 1 2 3 50 51
asc_val First Second Third Fifty Fifty one

Index
Symbols
’dynamic’ data set 1-1
’static’ data set 1-1
A
attributes 1-3
C
child field 1-3
D
Data Description Language 1-1
data set 1-1
data set block 1-2
DDL 1-1
F
FAST/TOOLS servers 1-3
field 1-2
field name 1-3
O
ODBC 1-4
Open DataBase Connectivity 1-3
P
parent field 1-3
physically stored 1-1
Q
quiet mode 3-7
R
real time 1-1
record 1-2
S
Structured Query Language 1-4
DATABASE/FAST Language Manual Index - 1

Index
DATABASE/FAST Language Manual Index - 2

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Manual DSS Language Manual
IM50F06F01-01EN/R10.03

IM50F06F01-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction to DSS-language .............................................1-1
1.1 General .......................................................................1-1
1.2 What are data sets ......................................................1-1
1.3 DSS-language/DSS-compiler ....................................1-3
2 Creation of a DSS-file ...........................................................2-1
2.1 Introduction ...............................................................2-1
2.2 General layout of a DSS-file .....................................2-1
2.3 General syntax rules of DSS-language ......................2-3
2.4 Translations of various properties .............................2-4
2.5 Use of DSS-include files ...........................................2-4
2.6 Definition and use of constants .................................2-5
2.7 Definition and use of macros .....................................2-6
2.8 Definition and use of field templates .........................2-7
2.9 Definition and use of storage nodes ..........................2-9
2.10 Specifying data sets and their properties .................2-10
2.10.1 Data set description ................................................. 2-12
2.10.2 Data file specification ............................................. 2-13
2.10.3 Data access server ................................................... 2-13
2.10.4 Data set operations .................................................. 2-14
2.10.5 Storage nodes .......................................................... 2-15
2.10.6 Hidden property ...................................................... 2-16
2.10.7 concealed property .................................................. 2-16
2.11 Specifying logical fields and their properties ..........2-17
2.12 Specifying normal fields and their properties ..........2-19
2.12.1 Using a field template ............................................. 2-20
2.12.2 Datatype property for a logical field ....................... 2-21
2.12.3 Field description ..................................................... 2-22
2.12.4 Field heading ........................................................... 2-22
2.12.5 Format ..................................................................... 2-23
2.12.6 Transformation information .................................... 2-24
2.12.7 Basic field operations .............................................. 2-25
2.12.8 Range and step information .................................... 2-26
2.12.9 List information ...................................................... 2-27
DATABASE/FAST DSS Language Manual iii

Table of Contents
2.12.10 Required property .................................................... 2-28

2.12.11 Hidden property ...................................................... 2-29
2.12.12 Default value specification ...................................... 2-29
2.12.13 Character restrictions .............................................. 2-31
2.12.14 Character operations ................................................ 2-32
2.12.15 Password encrypted property .................................. 2-33
2.12.16 Maps upon ............................................................... 2-33
2.12.17 Concealed property ................................................. 2-34
2.12.18 Enabled property ..................................................... 2-35
2.12.19 Validate property ..................................................... 2-35
2.12.20 Group property ........................................................ 2-36
2.13 Specifying relational fields and their properties ......2-37
2.14 Specifying compound fields and their properties ....2-39
2.15 Specifying physical fields .......................................2-41
2.15.1 Datatype of physical fields ...................................... 2-42
2.16 Specify indexes and their properties ........................2-43
2.16.1 Index description ..................................................... 2-44
3 Compilation of DSS-files ......................................................3-1
3.1 General ......................................................................3-1
3.2 How to run the DSS-compiler ...................................3-1
3.3 How to use command line flags ................................3-1
3.4 How to generate include files ....................................3-2
3.5 How to create or update a data dictionary .................3-2
3.6 How to list compiler errors ........................................3-3
3.7 How to suppress output to screen ..............................3-3
3.8 How to suppress warnings .........................................3-4
4 The include file .....................................................................4-1
4.1 Introduction ...............................................................4-1
4.2 Other included files ...................................................4-1
4.3 Defined constants ......................................................4-2
4.4 General data set information .....................................4-2
4.5 Record information ....................................................4-3
4.6 Index information ......................................................4-4
5 Reference ...............................................................................5-1
5.1 Introduction ...............................................................5-1
5.2 The DSS-language syntax description .......................5-1
5.2.1 General ...................................................................... 5-1
5.2.2 Symbols used ............................................................ 5-1
5.2.3 The DSS-language syntax ......................................... 5-2
DATABASE/FAST DSS Language Manual iv

Objectives Preface
0 Preface
0.1 Objectives
This manual describes:
• The syntax of the Data Set Services definition Language (DSS-

language),
• The use of the DSS-compiler.
The DSS-compiler is used to create or update a data dictionary and/
or to generate include files, using a dss-source file as input.
Where applicable, this document gives a very brief introduction to DSS

concepts that are closely related to the DSS-language and/or the
functioning of the DSS-compiler. A more detailed description of DSS
concepts can be found in [1]. The reader of this manual is referred to this
document for more detailed information concerning DSS concepts.

The manual is primarily intended for software engineers and application
engineers who want to create DSS-sources and/or want to use the DSS-
compiler.

• Chapter 1, Introduction to DSS-language and the DSS-compiler, is

a general introduction to the functionality of DSS and the features
of the DSS-compiler. It also explains what a ’data set’ is and what
it is used for.
• Chapter 2, Creation of a DSS-file, describes how a DSS-file must

be created. It does not contain the complete syntax description of
DATABASE/FAST DSS Language Manual 0-1

DSS. For this refer to chapter ’Reference’.
• Chapter 3, Compilation of DSS-file, explains how to run the DSS-

compiler in order to generate an include file and/or to update a data
dictionary, using a created DSS-file as source.
• Chapter 4, The include file, describes the structure of include files

generated by the DSS-compiler.
• Chapter 5, The data dictionary, describes the structure of data

dictionaries that can be created/updated by the DSS-compiler.
• Chapter 6, Reference, contains the complete syntax description of

DSS, accompanied by brief explanations and examples. The
commands and flags for running the DSS-compiler are also
described. Finally, a summary of the DSS-compiler’s error
messages is given.
• Appendix A, a complete example. To make the properties of DSS-

language and the DSS-compiler more clear, a complete example is
given in this appendix. The example consists of:
- DSS-files (compiler input),

- Include files generated by the DSS-compiler

1 DATABASE/FAST Programmer’s Guide (Data Set Services part)
2 DATABASE/FAST System Integrator’s Manual
3 REPORT/FAST Lanugage Manual
4 FAST/CONVENTIONS Reference Guide

CONVENTION MEANING

() Used in routine syntax to indicate a list

[] Indicates that the enclosed item is

optional.
{ }.. Indicates that the enclosed item may be

... Indicates that not all of the items

are shown.

letters names, e.g. NULL, TRUE, DUR_NOWAIT.

literally.
<name> Used in format descriptions. <name> indicates

a variable.
<file_name>+ Used in syntax descriptions. Exactly one or

more file names may be entered.
n.u. not used

a terminal

the user
DSS Data Set Services
DSS-language Data Set definition language
SQL Structured Query Language, according to the

X/Open and SQL Access Group SQL
SQL CAE specifications of 1992


General Introduction to DSS-language
1 Introduction to DSS-language
1.1 General
This chapter gives an introduction to the Data Set Services description
language (DSS-language). The DSS-language has been developed to be
able to specify data set properties easily and consistently. When using
DSS, at least a specification of data sets needs to be available. This is
because the data set specification mainly controls the functioning of
DSS.
With the aid of the DSS-compiler, data dictionaries can be created or
updated with the specified data set descriptions. In addition, include files
based on the specified data sets can be generated.
This chapter gives a brief introduction to:
• Data sets
• The DSS-language and DSS-compiler.
1.2 What are data sets

A data set is a model of a collection of data. The "outside world" is given
the illusion of a coherent set of data which is contained by a data set. The
data set contains a collection of records and the records in the data set
are composed of a collection of fields. The figures 1-1 and 1-2 illustrate
this:

Introduction to DSS-language What are data sets
DATA SET
record 1
record 2
record 3
record n
Fig. 1-1 A data set with its records
field 1 field 2 field 3 field 4 field 5
Fig. 1-2 Layout of fields in a data set record
This data set model is the "image" that is created at the logical level and
presented to applications that are using DSS. At the so called "physical"
level there is the real storage and field structure. Both information about
the logical and physical field structure can be specified via the DSS
language. DSS uses this information to access the data in the FAST/
TOOLS system and to present a logical data set model to the application.
At "macro level" a data set consists of the following main components:
• The data contained by the data set.

By definition the data contained by a data set, is modelled as a 2-
dimensional table with fixed length rows and 1 or more records.
In many situations, the data contained by a data set is static
information stored in a database file (e.g. the definition of a process

DSS-language/DSS-compiler Introduction to DSS-language
variable). However the data set data can also comprise "run-time"
data, i.e. data that varies frequently over time (e.g. the value and/or
status of a process variable).
• The collection of data set properties.
The properties of a data set describe the characteristics of the data
set. The properties of a data set are described via the DSS-language
and can be made available to the DSS components via the DSS data
dictionary. Amongst other things the data set characteristics
describe:
- How the data set is known (e.g. its name and description)
- The structure of the data set
- The kind of operations that can be performed on the data set
The following subdivision of data set properties can be made:

- Data set level properties:
Describe properties at data set level (e.g. name of data set, kind
of operations allowed on data set).
- Field level properties
Describe properties at field level (e.g. name of field, type of
field)
- Index level properties
Describe properties of the indices of a data set (e.g. name of the
index, fields of the data set together comprising an index).
1.3 DSS-language/DSS-compiler
The characteristics of a data set can be specified in so called DSS-files.
With aid of the DSS-compiler the data set specification is checked and,
if required, put in the DSS data dictionary. In addition to this, specific
parts of the data set specification will be made available as C-language
constructs, via include files (.dsh files). This process has been depicted
in the figure below.

Introduction to DSS-language DSS-language/DSS-compiler
DSS-files
compilation
DSS-file Data Dictionary
DSS-
DSS-file compiler
include file
DSS-file
include file
include file
The DSS-compiler with input and output

Introduction Creation of a DSS-file
2 Creation of a DSS-file
2.1 Introduction
This chapter explains how to create a DSS-file. First of all the general
layout of a DSS-file is described. Second the separate DSS-language
parts are described and explained with small examples.
The complete syntax of the DSS-language is described in chapter 5. In

this chapter parts of the syntax are described with examples.
The effect of the DSS-file contents on the data dictionary and the include
files, are described in chapter 3 and chapter 4 respectively.
2.2 General layout of a DSS-file

A DSS-file is an ascii-file and can be created with any ordinary system
editor. The general layout of a DSS-file is shown in figure 2-1.
DATA SET SERVICES Language Manual 2-1

Creation of a DSS-file General layout of a DSS-file
Include files (optional)
Defined constants,
macros, field templates,
nodes (optional)
Data set specification
Logical field specifications
Physical field specifications
Index specifications
Extra logical field properties

(optional)
Fig. 2-1 General layout of a DSS-file
Although it is permitted to specify multiple data sets in one DSS-file,

one data set per DSS-file is recommended.
In the DSS-file the following parts can be distinguished:
• Include DSS-file(s) with general definitions of constants, macros,

field templates and/or nodes.
• Specific definitions of constants, macros, field templates and/or
nodes for this DSS-file.
• Data set with its properties.
For a data set:
- Logical fields with their primary properties.
- Physical fields with their name and datatype.
- Indexes with their properties.
- Extra logical field properties.

General syntax rules of DSS-language Creation of a DSS-file
2.3 General syntax rules of DSS-language

The syntax of the DSS-language is of a simple form. A sentence begins
with a ’<’-character, followed by a keyword. The keywords are case
insensitive. Depending on the keyword a value or one or more
subsentences should be specified. The ’>’-character marks the end of the
sentence.
A subsentence is a normal sentence but lies completely within another

sentence or subsentence.
A value can be a numeric value or a character string. The character string

can be enclosed by double quotes ("), but it is not required. The text
within the double-quotes is taken literally. Text is often enclosed by
double quotes when special characters or spaces are used. When a
double quote is used in the text, it should be escaped by supplying an
extra double quote (see the following example).
Comments can be used before, between or after keywords, values,

sentences and subsentences. These comments have C-like formatting (/
* */) or C++-like formatting (//).
Syntax:
/* Comment */
// Comment
<KEYWORD>
<KEYWORD value>
<KEYWORD
subsentences
>
Example:
/*-------------------------------------------+
| This is comment in C-like formatting
+--------------------------------------------*/
// This is comment in C++-like formatting

//
// This is a keyword with a value

<INCLUDE "dss_global.dss">
// This is a sentence with subsentences

<DEFINE_CONSTANT
<LABEL DSS_TAG_NM_SZ>
<VALUE 16>

Creation of a DSS-file Translations of various properties
>
<DEFINE_CONSTANT
<LABEL DSS_INCH_MSG>
<VALUE
<DESCRIPTION "This is the inch-character: "".">
>
>
2.4 Translations of various properties

There are various properties of data sets, logical fields and indexes
where a text can be specified. A translated version of the text can be
specified in the languages English, Dutch, German and French.
The properties where translations can be specified are described below.

In the syntax description the translation is mentioned.
Syntax:
<TRANSLATION
<ENGLISH translated_text>
<NEDERLANDS translated_text>
<DEUTSCH translated_text>
<FRANCAIS translated_text>
>
Example:
<HEADING
<TEXT "Trigger group">
<TRANSLATION
<DEUTSCH "Anloesergruppe">
<FRANCAIS "Groupe de declenchement">
>
>
2.5 Use of DSS-include files

General definitions of constants, macros, field templates and storage
nodes can be gathered into a set of DSS-include files. These include files

Definition and use of constants Creation of a DSS-file
can be included in other DSS-files, so that the definitions can also be

used in other DSS-files.
In a DSS-include file the normal DSS-language syntax can be used. A

DSS-include file also is a normal DSS-file, but is used in an include-
statement.
The filename to include should be specified with extension and without

path specification (the current directory is taken as default).
Syntax:
<INCLUDE filename>
Example:
/*-------------------------------------------+
| External definitions
+--------------------------------------------*/
<INCLUDE "dss_global.inc">
2.6 Definition and use of constants

Instead of specifying a value, a constant can be used so that the values
are not hard coded throughout the DSS-files, but defined only once. A
constant can be used whenever a value should be supplied in a
(sub)sentence.
The definition of the constant must be made known prior to using it. The
constant therefore should be defined in the DSS-file itself or in one of
the DSS-include files. The constant name is case insensitive and should
be unique within all the DSS-files and DSS-include files.
The datatype of the value is checked when it is used.
The constants appear as #define’s in the header files generated by the

DSS-compiler.
Syntax:
<DEFINE_CONSTANT

Creation of a DSS-file Definition and use of macros
<LABEL constant_name>
<VALUE constant_value>
>
<USE_CONSTANT constant_name>
Example:
<DEFINE_CONSTANT
<LABEL DSS_DESCRIPTION_SZ>
<VALUE 80>
>
<DEFINE_FIELD_TEMPLATE
<LABEL tplDESCRIPTION>
<DATATYPE
<MBCHAR
<DIM <USE_CONSTANT DSS_DESCRIPTION_SZ>>
>
>
>
2.7 Definition and use of macros

Instead of having to specify a set of (sub)sentences repeatedly, a macro
can be used so that the same subsentences aren’t hard coded throughout
the DSS-files, but defined only once.
The macro must be made known prior to using it. Therefore the macro
should be defined in the DSS-file itself or in one of the DSS-include
files. The macro is case insensitive and should be unique within all the
DSS-files and DSS-include files.
When a macro is used, the (sub)sentences should have the correct

syntax. The correctness isn’t checked when the macro is defined.
Syntax:
<DEFINE_MACRO
<LABEL macro_name>
<MACROTEXT
{subsentence}
>
>

Definition and use of field templates Creation of a DSS-file
<USE_MACRO macro_name>
Example:
<DEFINE_MACRO
<LABEL PROCESS_AREA>
<MACROTEXT
<RELATES_TO
<DATASET_NAME PROCESS_AREA_DF>
<FIELD_NAME NAME>
>
<DESCRIPTION
<TEXT "Process areas">
>
<FORMAT "%-32s">
>
>
<RELATION_FIELD
<NAME PROCESS_AREA_1>
<USE_MACRO PROCESS_AREA>
>
<RELATION_FIELD
<USE_MACRO PROCESS_AREA>
>
2.8 Definition and use of field templates

When a lot of properties are the same for a number of fields, these
properties can be gathered in a field template. The properties are
specified once and the field template can be used throughout the DSS-
files.
The field template should be made known prior to using it. This can be
done by defining the field template in the DSS-file itself or in one of the
DSS-include files. The field template name is case insensitive and
should be unique within all the DSS-files and DSS-include files.
For the field template the name and the datatype should be specified.
Furthermore a number of properties can be specified. A field template
can be used in a normal logical field. When a field template is used, the
properties of the field template can be overruled by specifying the
property again in the field itself.
For the use of the various properties of a field template see section 2.10.

Creation of a DSS-file Definition and use of field templates
Syntax:
<LABEL field_template_name>
<datatype>
[<field description>]
[<field heading>]
[<format>]
[<transformation>]
[<basic field operations>]
[<range and step information>]
[<list information>]
[<required property>]
[<hidden property>]
[<default value spec>]
[<character restrictions>]
[<character operations>]
[<encrypted property>]
[<concealed expression>]
[<enabled expression>]
[<validate expression>]
[<group value>]
>
<FIELD_TEMPLATE field_template_name>
Example:
/*---------------------------------------------------------------+
| Description field template
+---------------------------------------------------------------*/
<LABEL TplDESCRIPTION>
<DATATYPE
<MBCHAR
<DIM <USE_CONSTANT DSS_DESCRIPTION_SZ>>
>
>
<DESCRIPTION
<TEXT "Description">
>
<HEADING
<TRANSLATION
<DEUTSCH "Beschreibung">
<FRANCAIS "Description">
>
>
<FORMAT "%-80s">
>
<FIELD

Definition and use of storage nodes Creation of a DSS-file
<NAME DESCRIPTION>
<FIELD_TEMPLATE TplDESCRIPTION>
<DESCRIPTION
<TEXT "Description (alarm text)">
>
>
>
2.9 Definition and use of storage nodes

Most of the data sets can be stored on different nodes in a FAST/TOOLS
system. This is called replication of data. In the DSS-language a node
can be referred to by either a node number or a node name.
A node name or node number is linked to a node label. This label is case
insensitive an is used to define the storage node(s) of a data set.
A storage node should made be known prior to using it. This can be done
by defining the storage node in the DSS-file itself or in one of the DSS-
include files.
A priority for the storage nodes can also be specified. When data is read
from the FAST/TOOLS system, the node with the highest priority is
taken first to handle the request. When this node cannot handle the
request the following nodes are taken in decreasing priority. The priority
is a numeric value and can be between 1 and 255. When the priority isn’t
specified, the highest priority, 255, is taken.
The value ’-1’ for node number always refers to the "host node". When
no storage nodes are specified for a data set, the host-node of FAST/
TOOLS is taken as default storage node. See also section 2.10.5 about
the use of storage nodes within a data set.
The first node in the list is the primary node. The data on the other nodes
is always a replica of the data on the primary node. Normally, the host
node (-1) is taken as the primary node for a data set.
Syntax:
<DEFINE_NODE
<LABEL node_label>
<NAME node_name> | <NUMBER node_number>
[<PRIORITY priority>]
>

Creation of a DSS-file Specifying data sets and their properties
<STORAGE
<NODES
{<NODE_NAME node_label>}
>
>
Example:
/*---------------------------------------------------------------+
| Nodes 131 and 132 for storage of the various datasets
+---------------------------------------------------------------*/
<DEFINE_NODE
<LABEL node_131>
<NUMBER 131>
<PRIORITY 255>
>
<DEFINE_NODE
<LABEL node_132>
<NAME NODE_132>
<PRIORITY 255>
>
<DATASET
<NAME INSTALL_DF>
<STORAGE
<NODES
<NODE_NAME node_131>
>
>
>
2.10 Specifying data sets and their properties

Data sets are identified by their name. This name should be unique
within the DSS-files and is case insensitive. It isn’t allowed to use an
SQL keyword for a dataset name. The dataset should have at least one
field and one unique index.
When a data set is specified, the following properties are required:

• The data set name
• At least one logical field
• At least one unique index
When no physical fields are specified in the data set, the logical fields

Specifying data sets and their properties Creation of a DSS-file
map directly to the physical fields.
In the following subsections the properties of a data set are described. In

the section 2.11, section 2.15 and section 2.16 the field, physical field
and index are described.
Syntax:
<DATASET
<NAME dataset_name>
[<data set description>]
{<field definition>}
[{<physical field definition>}]
{<index definition>}
<data file specification>
[<data access server>]
[<basic data set operations>]
[<storage nodes>]
[<hidden property>]
>
Example:
<DATASET
<NAME STATUS_DF>
<DESCRIPTION
<TEXT "Item status definition">
>
<FIELD
<NAME NAME>
<DATATYPE <CHAR <DIM 12>>>
<DESCRIPTION
<TEXT "System text">
>
>
<FIELD
<NAME DESCRIPTION>
>
<PHYSICAL_FIELD
<NAME STATUS_NUMBER>
<DATATYPE <UBYTE>>
>
<INDEX
<NAME NAME>
<FIELD_NAME NAME>
<UNIQUE>
>

<INDEX
<FIELD_NAME STATUS_NUMBER>
<UNIQUE>
>
<DATA_FILE
<NAME "itm_stat.dat">
>
<DATA_ACCESS
<SERVERNAME "dsilib:dsid_sta_df">
>
<STORAGE
<NODES
>
>
>
2.10.1 Data set description
For a data set a description can be specified explaining the use of the data
set. This description can be supplied in the different languages supported
by FAST/TOOLS.
Syntax:
<DESCRIPTION
<TEXT description_text>
[<translations>]
>
Example:
<DATASET
<NAME AUTH_GROUP_DF>
<DESCRIPTION
<TEXT "Authorisation group definition">
<TRANSLATION
<NEDERLANDS "Autorisatie groep">
<DEUTSCH "Autorisation Gruppe">
<FRANCAIS "Autorisation collectif">
>
>

2.10.2 Data file specification
The data of the data set can be stored in a database file. With this
property the name of the database file can be specified. This filename
should be specified including the extension and can include path
information.
Instead of the hard coded path one of the logical path constants can be
specified. These path constants refer to paths defined in FAST/TOOLS.
When no path information is specified, the logical path DATA is used

as default.
Syntax:
<DATA_FILE
<NAME filename>
[<LOGICAL_PATH
<AUX>|<COMMAND>|<DATA>|<DID>|<EXE>|
<HELP>|<HIS>|<INIT>|<LIST>|<SAVE>|
<USER1>
<CREATE>
>]
>
Example:
<DATASET
<NAME ALARM_ASA_DF>
<DATA_FILE
<NAME "alm_asa.dat">
<LOGICAL_PATH <DATA>>
>
>
Normally it is the responsibility of the data access server or associated

physical data source to take of the initial creation of a data file (see
section 2.10.3).The optional "<CREATE>" property can be used to
create the data file for you if it does not exist. This property applies only
to data files that use the default data access server for ISF data files.
2.10.3 Data access server
A data access server maps a specific data set upon the physical
implementation of the data set in the FAST/TOOLS system.

The data access server is a routine within a shared library. Both the data
access server and the shared library should be specified.
The library name should be a library filename without extension. The

library filename can be specified including the path information. The
routine name should be a routine within this library.
Syntax:
<DATA_ACCESS
<SERVERNAME library_name:routine_name>
>
Example:
<DATASET
<NAME INSTALL_DF>
<DATA_ACCESS
<SERVERNAME "/dsilib:dsid_ins_df">
>
>
2.10.4 Data set operations
From a global point of view, the following type of operations can be

distinguished for data sets:
• Synchronous data set operations:
- Read
- Insert
- Update
- Delete
• Asynchronous data set operations:
- Event request at data set level
- Event request at data set record level
- Event request at data set record field level
Not all data sets allow all these kind of operations. For example certain
types of real time data can only be read and can not be manipulated.
It is possible to specify for each individual data set what type of

operations are allowed for that data set. When an attempt is performed
to execute an operation which is not defined for the data set, an error is
given and the action is cancelled.

When no basic operations are specified for a dataset, all operations are
assumed valid for the dataset.
Syntax:
<DATASET_OPERATIONS
{<OPERATION
<SELECT>|<INSERT>|<UPDATE>|<DELETE>|
<EVENT_REQ_DATASET>|<EVENT_REQ_RECORD>|
<EVENT_REQ_FIELD>
>}
>
Example:
<DATASET
<NAME AUDIT_EVENT_CLAS_DF>
<DATASET_OPERATIONS
<OPERATION
<SELECT>
>
<OPERATION
<UPDATE>
>
>
>
2.10.5 Storage nodes
The data contained in a data set can be replicated on different nodes.
The node label specified in the node definition should be used and is
case insensitive. When a storage node is used, it should be already
defined. This can be done by defining the storage node in the DSS-file
itself or in one of the DSS-include files.
When no storage nodes are specified, the host-node handles the request
for the data set.
See also section 2.9 for more information on storage nodes.
Syntax:
<STORAGE
<NODES
{<NODE_NAME node_label>}

>
>
Example:
<DATASET
<NAME SCAN_TYPE_DF>
<STORAGE
<NODES
>
>
>
2.10.6 Hidden property
A data set can be given the property "hidden". At this moment no

specific functionality is linked to this property, but it might be used by
application programs to make specific data sets invisible to the "outside"
world.
Syntax:
<HIDDEN>
Example:
<DATASET
<NAME PROC_AREA_GRP_DF>
<HIDDEN>
>
2.10.7 concealed property
A data set can be given the property concealed. Depending on the FAST/
TOOLS configuration some data sets may have no function, using this
property the DSS-client can "conceal" these datasets for the user.
Which part of a FAST/TOOLS configuration is concealed is defined in

the data set concealed_df. The DSS filter function concealed() can be
used to query this dataset in a filter expression.
The concealed keyword is followed by a DSS filter expression. The filter

expression can only contain the concealed() filter function. If the
expression evaluates to TRUE the dataset is considered concealed.

Specifying logical fields and their properties Creation of a DSS-file
Only one concealed property is allowed per dataset.
This data set property is made available in the DSS-api using the
dss_conc_ds() routine and the DSS_SPROP_CONCEALED_COND.
Syntax:
<concealed "expression">
Example:
<DATASET
<NAME PROC_AREA_GRP_DF>
<CONCEALED "concealed(DISTRIBUTION.FRONT_END) = "TRUE"">
>
2.11 Specifying logical fields and their

properties
The logical fields of a data set together make up the data set record. The
following type of logical fields can be distinguished:
• Normal field
In a normal field data can be stored and retrieved and a number of
properties can be set to restrict the data entered.
• Relational field
A relational field has a relation with another field in another data set
(e.g. item definition having the relational field first-out group
name).
• Compound field
A compound field is a composition of other (normal) fields in the
same data set (e.g. item name being composed of installation, unit,
tag and subtag)
The specification of properties for one field can be separated within a

data set definition. First a set of properties for a field can be specified,
such as fieldname, datatype and description. Later on additional
properties can be specified, like heading, format and default value. The
field to which a property applies is identified by its name. This
mechanism applies to normal, relational and compound fields. The
properties of a field, separated or not, should be defined within the data
set. The properties of a data set cannot be separated.

Creation of a DSS-file Specifying logical fields and their properties
The example below shows that the properties of normal field NAME are
separated.
An overview of the properties that are valid for the logical fields are
described in the section 2.12, section 2.13 and section 2.14. In section
2.12.1 and onwards these properties are described in more detail.
Syntax:
<normal field> |
<relational field> |
<compound field>
Example:
<FIELD
<NAME NAME>
<DESCRIPTION
<TEXT "Name">
>
>
<RELATION_FIELD
<RELATES_TO
<DATASET_NAME PROCESS_AREA_DF>
<FIELD_NAME NAME>
>
<DESCRIPTION
>
<FORMAT "%-32s">
>
<FIELD
<NAME NAME>
<FORMAT "%-32s">
<CHARACTER_OPERATIONS
<CHAR_OPERATION
<TO_UPPER>
>
>
>
<COMPOUND_FIELD
<NAME IDENTIFIER>
<DIM 64>
<SEPARATORS "...">
<FIELD_NAME SUBJECT>
<FIELD_NAME ATTRIBUTE>
<FIELD_NAME ACTION>
<FIELD_NAME SOURCE>
>

Specifying normal fields and their properties Creation of a DSS-file
2.12 Specifying normal fields and their

properties
A normal field can be used to hold data for the data set. The data in the
field can be restricted by specifying a number of properties. The
different properties are described in section 2.12.1 and onwards.
The name of the field should be unique within a data set and is case
insensitive. It isn’t allowed to use an SQL keyword for a field name. It
is not possible to specify a normal field, a relational field and/or a
compound field with the same name.
For this field a datatype or a field template must be specified. When a

field template is used, the properties specified for the field template are
copied to the field. These properties can be overruled by specifying them
again individually for the field itself. See section 2.8 for more
information on field templates.
When a normal field is specified, the following properties are required:

• The field name
• The field template or data type
A normal field can be used in a relational field, a compound field and an

index.
There are restrictions on the datatype when different properties are used.
See the detailed description of the various properties for more
information.
Syntax:
<FIELD
<NAME name>
[<field template used>]
[<datatype>]
[<field heading>]
[<format>]
[<transformation information>]
[<range and step information>]
[<hidden property>]

Creation of a DSS-file Specifying normal fields and their properties
[<default value specification>]

[<maps_upon>]
[<enabled expression>]
[<validate>]
[<group value>]
>
Example:
<FIELD
<NAME NAME>
<DESCRIPTION
<TEXT "The name of the item">
>
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION <NO_DOTS>>
<CHAR_RESTRICTION <NO_SPACES>>
<CHAR_RESTRICTION <ONLY_IDENTIFIER>>
>
<CHAR_OPERATIONS
<CHAR_OPERATION <TO_UPPER>>
>
<MAPS_UPON ITEM_NAME>
>
<FIELD
<NAME VALUE>
<DATATYPE <LONG>>
<RANGE
<LOW 1>
<HIGH 255>
<STEP 1>
>
<DEFAULT_VALUE_SPEC
<VALUE 1>
<INSERT>
>
>
2.12.1 Using a field template
For a description of the field template definition, see section 2.8.
Syntax:
<FIELD_TEMPLATE field_template_name>
Example

<FIELD
<NAME NAME>
<FIELD_TEMPLATE TplInstallation>
<DESCRIPTION
>
>
2.12.2 Datatype property for a logical field
The data in a field should be of a specific data type. The data types
supported by DSS are shown in the syntax below. In addition to the usual
types, some special "FAST/TOOLS data types" have been defined:
• MBCHAR
A multi-byte character string. At this moment FAST/TOOLS does
not provide support for multi-byte character strings, so this data
type is meant to anticipate future developments in this area.
• DATE
To hold an absolute timestamp (expressed in seconds).
• INTERVAL
To hold an interval value (expressed in seconds).
• MEMO
To hold a large amount of ascii-information.
• UNKNOWN
To hold a large amount of binary information.
Syntax:
<DATATYPE
<CHAR <DIM dimension>> |
<SHORT> |
<USHORT> |
<LONG> |
<LONG> |
<FLOAT> |
<DOUBLE> |
<BOOLEAN> |
<BYTE> |
<UBYTE> |
<MBCHAR <DIM dimension>> |
<DATE> |
<INTERVAL> |
<MEMO> |

<UNKNOWN> |
>
Example
<FIELD
<NAME NAME>
<DATATYPE
<CHAR <DIM 16>>
>
>
<FIELD
<NAME FREQUENCY>
<DATATYPE <LONG>>
>
2.12.3 Field description
A field description can be used to explain the use of the field. This
description can be translated into the different languages supported by
FAST/TOOLS.
Syntax:
<DESCRIPTION
[<translations>]
>
Example
<FIELD
<NAME NAME>
<DESCRIPTION
<TEXT "Authorisation action name">
<TRANSLATION
<NEDERLANDS "Autorisatie-actie naam">
<DEUTSCH "Autorisation aktivitat Name">
>
>
>
2.12.4 Field heading
In reports and screens, a text can be shown to label the field. This
heading can also be translated into the different languages supported by

FAST/TOOLS.
Syntax:
<HEADING
<TEXT heading_text>
[<translations>]
>
Example
<FIELD
<NAME ACTIVATION_TIME>
<HEADING
<TEXT "Activation|time">
<TRANSLATION
<DEUTSCH "Aktivierungs-|zeit">
<FRANCAIS "Date|d'activation">
>
>
>
2.12.5 Format
When the value of the field is displayed in a report or on the screen, the
value can be formatted according to the specified format string.
The format string can be a C-like format string, for example "%-32s" or
"%3.5f", a data time format string, like "DD-MM-YYYY hh:mm:ss.pp"
or a REPORT/FAST format string, for example "I2" or
"AAAAAAAAAR".
See the REPORT/FAST Language Manual for the exact format string.
Note that the DSS-compiler doesn’t perform any checks on the format
string specified.
Syntax:
<FORMAT format_string>
Example
<FIELD
<NAME CORRECT_DAYLIGHT>
<FORMAT "%6d">
>
<FIELD
<NAME START_TIME>
<FORMAT "DD-MMM-YY hh:mm:ss">
>

2.12.6 Transformation information
Values of some fields are displayed as text in a report or on screen, but

in reality consist of binary information, a code or a bit-mask, within
FAST/TOOLS. The binary values can be displayed as text by specifying
the transformation information.
The logical field should have the data type CHAR or MBCHAR. By
default the logical field will map on a physical field of data type LONG.
The data type of this physical field can be another data type by explicitly
specifying the type.
The value of the field is restricted to the specified transformation values

and DSS will validate the value of the field against these transformation
values. The transformation values can also be translated to the different
languages supported by FAST/TOOLS.
When transformation information is specified, the list and character

restrictions cannot be specified.
The condition property defines a filter expression that can be evaluated

at runtime by the DSS-client.
Using the DSS_FPROP_TRANSGFORMATION field property. The
DSS-client can then determine whether the transformation entry is valid
for a given data set record.
The example below shows the field ALARM_STATE. The value is stored
physically in a UBYTE-field and can have the values 1, 2, 3 and 4. At
logical level the field ALARM_STATE has the data type CHAR with
dimension 10. The values allowed are “Normal”, “Alarm 1", “Alarm 2",
"Alarm 3".
Syntax:
<TRANSFORMATION
[<physical data type>]
{<ENTRY
<NUMERIC numeric_value>
<STRING string_value>
[<transformation>]
[condition filter_expression]

>}
>
Example
<FIELD
<NAME ALARM_STATE>
<DATA_TYPE <CHAR <DIM 10>>>
<TRANSFORMATION
<DATATYPE
<UBYTE>
>
<ENTRY
<NUMERIC 1>
<STRING "Normal">
>
<ENTRY
<NUMERIC 2>
<STRING "Alarm 1">
>
<ENTRY
<NUMERIC 3>
<STRING "Alarm 2">
>
<ENTRY
<NUMERIC 4>
<STRING "Alarm 3">
>
>
>
2.12.7 Basic field operations
In addition to the operations specified at data set level, the basic

operations can also be specified for the fields separately.
At field level, only the basic operations SELECT and UPDATE can be
specified. When the field operations are omitted, both SELECT and
UPDATE are possible for the field. When a basic field operation is
specified, it should also be specified at data set level, otherwise the
operation will not be allowed for the field.
For example, when operations SELECT, INSERT, UPDATE and

DELETE are specified for the data set and for the field only SELECT
is specified, the data in the field can be retrieved, but it isn’t possible to
modify the value of the field. However when only SELECT is specified
for the data set and for the field SELECT and UPDATE are specified,
still the value of the field cannot be modified, because no data in the data
set can be modified.

Syntax:
<FIELD_OPERATIONS
{<OPERATION
<SELECT> | <UPDATE>
>}
>
Example
<FIELD
<NAME NAME>
<FIELD_OPERATIONS
<OPERATION <SELECT>
<OPERATION <UPDATE>
>
>
<FIELD
<NAME DESCRIPTION>
<FIELD_OPERATIONS
<OPERATION <SELECT>>
>
>
2.12.8 Range and step information
To restrict the possible values for a numeric field or when using the data
type DATE or INTERVAL, the high and low value can be specified.
Furthermore the step can be specified to define an interval. The step
value determines the "granularity" used within the interval when
stepping through the interval.
When a range is required, the low and high value should be specified.
The step and visual change value is optional. The DSS will check the
value of the field against the low, high and step values.
The step value should be greater than or equal to zero and should lie
between the low and high value.
The visual change value can be specified to help the user in selecting a
value for the field. The subsequent values shown to the user have the
interval of the visual change value.
For a field with data type DATE or INTERVAL the low, high, step and
visual change values should be specified in number of seconds since 1-

1-1970 00:00.
The example below shows the field FREQUENCY. The values 0, 2, 4, 6,

8, etc., with a maximum of 999998 are valid for the field. When the user
should select a value, the values 0, 10, 20, 30, etc. with a maximum of
999990 are displayed on the screen to assist the user in selecting a
suitable value.
Syntax:
<RANGE
<LOW numeric_value>
<HIGH numeric_value>
[<STEP numeric_value>]
[<VISUAL_CHANGE numeric_value>]
>
Example
<FIELD
<NAME FREQUENCY>
<DATATYPE <LONG>>
<RANGE
<LOW 0>
<HIGH 999998>
<STEP 2>
<VISUAL_CHANGE 10>
>
>
2.12.9 List information
To restrict the possible values for a string field, a list of possible values
can be specified. The DSS will check the values supplied in the insert or
update against this list of values. The list values can also be translated to
the different languages supported in FAST/TOOLS.
When transformation information is specified for the field, the list

cannot be specified.
The condition property defines a filter expression that can be evaluated

at runtime by the DSS-client. Using the dss_val_list() routine or the
DSS_FPROP_VAL_LIST_COND field property. The DSS-client can
then determine whether the list entry is valid for a given data set record.

Syntax:
<LIST
{<ENTRY
<VALUE string_value>
[<translations>]
[<condition filter_expression]
>}
>
Example
<FIELD
<NAME flags>
<DATATYPE
<CHAR <DIM 20>>
>
<LIST
<ENTRY
<VALUE "Input">
<TRANSLATION
<DEUTSCH "Eingabe">
<FRANCAIS "Saisie">
>
>
<ENTRY
<VALUE "Output">
<TRANSLATION
<DEUTSCH "Ausgabe">
<FRANCAIS "Capacite">
>
>
<ENTRY
<VALUE "Input+Output">
<TRANSLATION
<DEUTSCH "Eingabe+Ausgabe">
<FRANCAIS "Saisie+Capacite">
>
>
>
>
2.12.10 Required property
When it is mandatory that a field value has to be specified during an

insert or update, the required-property can be set. The required-property
can be specified for insert or update or both.
When the required property is set for a field with datatype CHAR or
MBCHAR, the string value specified should have a length greater than

zero.
When neither INSERT or UPDATE is specified, only INSERT will be

required.
Syntax:
<REQUIRED
[{<INSERT> | <UPDATE>}]
>
Example
<FIELD
<NAME STATUS>
<REQUIRED
<INSERT>
<UPDATE>
>
>
2.12.11 Hidden property
A field can be given the property "hidden". At this moment no specific

DSS functionality is linked to this property, but it might be used by
application programs to make specific fields invisible to the "outside"
world.
Syntax:
<HIDDEN>
Example
<FIELD
<NAME DUMMY>
<DATATYPE <USHORT>>
<HIDDEN>
>
2.12.12 Default value specification
When the value of a field is omitted during insert or update, the default
value will be taken for the field. If a default value has not been specified,
the field value will stay empty during insert and will retain its current

value during update.
The default value should be of the same data type as the field itself and
shouldn’t exceed the dimension in case of data type CHAR or
MBCHAR. For a field with data type BOOLEAN, the default values
TRUE and FALSE can be specified. For a field with data type DATE
or INTERVAL the default value should be the number of seconds since
1-1-1970 00:00.
When a transformation or a list value is specified, the default value

should be one of these values. Also the default value should lie within
the range values specified and should correspond with the defined
character restriction and operations.
The basic operations INSERT and/or UPDATE can also be used. The
default value will then apply to the specified operation(s).
Syntax:
<DEFAULT_VALUE_SPEC
<VALUE value>
{<INSERT> | <UPDATE>}
>
Example
<FIELD
<NAME STORAGE>
<DATATYPE <BOOLEAN>>
<DEFAULT_VALUE_SPEC
<VALUE FALSE>
<INSERT>
<UPDATE
>
>
<FIELD
<NAME NUMBER>
<DATATYPE <LONG>>
<DEFAULT_VALUE_SPEC
<VALUE 1>
<INSERT>
<UPDATE>
>
>

2.12.13 Character restrictions
The values for a string field can be restricted. The following character
restrictions can be specified:
• No spaces: the value cannot contain space-characters (’ ’)
• No dots: the value cannot contain periods (’.’)
• Only printables: the value can only contain printable characters,
special characters like backspace, tab or formfeed are not allowed
• Only alphanumerics: only letters, digits, periods (’.’) and commas
(’,’) are allowed
• Only numerics: only digits are allowed
• Only identifier: the string can only be a identifier-name, the name
should begin with a letter and for the rest can contain letters, digits
and underscores (’_’)
Character restrictions can only be used with a logical field of data type
CHAR or MBCHAR. The character restrictions cannot be used together
with transformation information.
Syntax:
<CHAR_RESTRICTIONS
{<CHAR_RESTRICTION
<NO_SPACES> |
<NO_DOTS> |
<ONLY_PRINTABLE> |
<ONLY_ALPHANUMERICS> |
<ONLY_NUMERICS> |
<ONLY_IDENTIFIER>
>}
>
Example
<FIELD
<NAME NAME>
<DATATYPE
<CHAR <DIM 12>>
>
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<ONLY_IDENTIFIER>
>
>
>
<FIELD
<NAME INSTALLATION>
<DATATYPE
<CHAR <DIM 16>>

>
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<NO_SPACES>
>
<CHAR_RESTRICTION
<ONLY_PRINTABLE>
>
<CHAR_RESTRICTION
<NO_DOTS>
>
>
>
2.12.14 Character operations
When a value for a string field is supplied during insert or update, the
value will be stored using the character operations specified. The DSS
will perform the character operations specified before the value is stored
in FAST/TOOLS. The following character operations can be specified:
• To upper: the value is converted to upper case. This operation can
not be specified in combination with To lower
• To lower: the value is converted to lower case. This operation can
not be specified together with To upper
• Remove leading spaces: remove the leading spaces of the value
• Remove trailing spaces: remove the trailing spaces of the value
• Add blanks: pad blank characters to the value
When add blanks is specified without the blank character, space is used
to align the value. When another blank character should be used, it can
be specified explicitly.
The character operations can only be used with a logical field with data
type CHAR or MBCHAR.
Syntax:
<CHAR_OPERATIONS
<CHAR_OPERATION
[[<TO_UPPER> |
<TO_LOWER>] |
<REMOVE_LEADING_SPACES> |
<REMOVE_TRAILING_SPACES> |
<ADD_BLANKS [<BLANK blank_character>]>]
>
>

Example
<FIELD
<NAME INSTALLATION>
<DATATYPE
<CHAR <DIM 32>>
>
<CHAR_OPERATIONS
<CHAR_OPERATION
<TO_UPPER>
>
<CHAR_OPERATION
<REMOVE_LEADING_SPACES>
>
<CHAR_OPERATION
<REMOVE_TRAILING_SPACES>
>
>
>
2.12.15 Password encrypted property
When the encrypted property is set, the value for the field will be
encrypted before the value is stored in the data set.
The encrypted property can only be used with a logical field with data
type CHAR or MBCHAR.
Syntax:
<PASSWORD_ENCRYPTED>
Example
<FIELD
<NAME PASSWORD>
<DATATYPE
<CHAR <DIM 12>>
>
>
2.12.16 Maps upon
The logical field can explicitly be mapped upon a physical field with a
different data type, so that the logical field structure of the data set can
be different from the physical field structure.

The physical field name specified should be defined within the data set,
but can be defined before or after the use in MAPS_UPON.
When no MAPS_UPON is used in the logical field and no physical

fields are specified in the data set, the logical fields will be mapped upon
the physical fields with the same name. The physical field structure will
be the same as the logical field structure, with the same name and data
type, but without the compound fields.
A logical field can be mapped upon only one physical field, but a
physical field can be used in more than one mapping.
Syntax:
<MAPS_UPON physical_field_name>
Example
<FIELD
<NAME NAME>
<MAPS_UPON ATH_GRP_NM>
>
2.12.17 Concealed property
A field can be given the property concealed. Depending on the FAST/

TOOLS configuration some fields may have no function, using this
property the DSS-client can “conceal” these fields for the user.
Which part of a FAST/TOOLS configuration is concealed is defined in

the dataset concealed_df. The DSS filter function concealed() can be
used to query this dataset in a filter expression.
The concealed keyword is followed by a DSS filter expression. The filter

expression can only contain the concealed() filter function. If the
expression evaluates to TRUE the field is considered concealed.
Only one concealed property is allowed per field.
This field property is made available in the DSS-api using the

dss_conc_fld() routine and the DSS_FPROP_CONCEALED_COND.

Syntax:
<CONCEALED "expression">
Example:
<FIELD
<NAME EXAMPLE>
<CONCEALED "concealed(DISTRIBUTION.FRONT_END) = "FALSE"">
>
2.12.18 Enabled property
A field can be given the property enabled. Depending on the FAST/

TOOLS configuration or the value of other fields in the dataset some
fields may have no function, using this property the DSS-client can hide
fields from the user that have no relevance.
The enabled keyword is followed by a DSS filter expression. If the

expression evaluates to TRUE the field is considered enabled.
Only one enable property is allowed per field.

dss_enabled() routine and the DSS_FPROP_ENABLE_COND.
Syntax:
<ENABLED expression>
Example:
<FIELD
<NAME EXAMPLE>
<ENABLED "ITEM_REP = 8 AND concealed(DISTRIBUTION.FRONT_END)=
TRUE"">
2.12.19 Validate property
The validate property is used to validate the value of a field before

inserting it into the dataset. Each validate entry consists of a condition
(DSS filter expression), a message explaining the condition and
optionaly a translation of the message.
Using the message the DSS-client can give some feed-back to the user
explaining why the filed value is not valid.

The validate property is made available in the DSS-api using the

dss_valid () routine and the DSS_FPROP_VALID_CONDITIONS
property.
Syntax:
<FIELD
<VALIDATE
<ENTRY
<VALUE string_value>
<CONDITION filter_expression>
[<TRANSLATIONS>]
>
>
>
Example:
<FIELD
<NAME LOW>
<DATATYPE <DOUBLE>>
<DESCRIPTION
<TEXT "Low limit">
>
<VALIDATE
<ENTRY
<VALUE "LOW LIMITmust be lower then HIGH LIMIT.">
<CONDITION "HIGH_LIMIT >= LOW_LIMIT">
>
>
2.12.20 Group property
A field can be given a group property. This is the group to which the
field belongs. This way application can show fields in a hierarchical
organized way. The group name may contain dots that specify a
hierarchically group path. The value of the GROUP is a string and is
opaque to the DSS-api, It is interpreted by the DSS client.

DSS_FPROP_GROUP that can be retrieve using the dss_prop_fld()
routine.
Syntax:
<FIELD

Specifying relational fields and their properties Creation of a DSS-file
<GROUP string_value>
>
Example:
<FIELD
<GROUP "Lines.Line 1">
>
2.13 Specifying relational fields and their

properties
A relational field is a field which value should exist in a field in another
data set.
The name of the relational field should be unique within a data set and
is case insensitive. It isn’t allowed to use an SQL keyword for a
relational field name.
For a relational field the data set and the field it is related to should be
specified. The datatype of the relational field is the same as the field it is
related to.
In a relation, a so called "via-field" can be specified. The via-field must

be a numerical and logical field. This via-field is useful in situations
where the physical implementation of the relation is performed via
another field than that which the field relates to.
For example the item definition data set, among others, has a relation
with the first-out group data set. What is shown to the user is the name
of a first-out group, the item refers to. However the physical
implementation shows that the relation is implemented by storing a first-
out group ID in the item definition file.
In this case the value of the via-field related to, is stored in the referring
data set. The via field is the name of a field in the data set referred to.
The value of the logical field related to is shown to the user.
The datatype of the physical field is the same as the via-field related to,
when specified. When no via-field is specified the physical datatype of
the relational field is the same as the logical field related to.
When the data is entered for the relational field, the DSS will check if

Creation of a DSS-file Specifying relational fields and their properties
the value exist in the data set related to.
The field related to can not itself be a relational field but can be a normal
field or a compound field.
When the character operations and/or the password encrypted are

specified for the field related to, the properties are also available for the
relational field itself.
When a relational field is specified, the following properties are

required:
• The field name
• The data set and field related to
A relational field can be used in a compound field or in an index. It

cannot be used in another relational field.
For the additional properties field description, field heading, format,

basic field operations, required, hidden and maps upon, see the
corresponding subsections of the section 2.12.
Note: The primary node of the related data set must

be the same as the primary node of the
referencing data set. See also section 2.9.
Syntax:
<RELATION_FIELD
<NAME name>
<RELATES_TO
<DATASET_NAME dataset_name>
<FIELD_NAME field_name>
[<VIA physical_field_name>]
>
[<field heading>]
[<format>]
[<hidden property>]
[<maps_upon>]
>
Example:

Specifying compound fields and their properties Creation of a DSS-file
<RELATION_FIELD
<NAME AOI_1>
<RELATES_TO
<DATASET_NAME ALARM_AOI_DF>
<FIELD_NAME NAME>
<VIA NUMBER>
>
<DESCRIPTION
<TEXT "Area of interest name">
>
<HEADING
<TEXT "Areas of|interest1">
<TRANSLATION
<DEUTSCH "Alarm-|Interessenbereiche1">
<FRANCAIS "Aires d'|interet1">
>
>
<FORMAT "%-16s">
<FIELD_OPERATIONS
<OPERATION <SELECT>>
>
<REQUIRED <INSERT>>
<MAPS_UPON AOI_1>
>
2.14 Specifying compound fields and their

properties
A compound field is a field which value is formatted at run-time from
the values of the fields that make up the compound field. The value of
the separate fields are concatenated using the separator-string between
the field values.
The name of the compound field should be unique within a data set and
is case insensitive. It isn’t allowed to use an SQL keyword for a
compound field name.
The fields which make up the compound field must be defined in the
same data set, but can be specified later on. The compound field itself
always has the character data type.
When a compound field is specified, the following properties are

required:
• The field name
• The dimension of the compound field
• The separator string
• At least one field

Creation of a DSS-file Specifying compound fields and their properties
The separator string will be used to place characters between the values
of the individual fields of the compound field. The first character will be
placed between the first and second value. The second character will be
placed between the second and third value and so on.
When all the characters in the separator string have been used, the last
character of the string will be maintained as separator character. The
following example will explain this behaviour:
A compound field is specified with four fields and the separator string is
",.-". The value for the compound field will be "value1,value2.value3-
value4". When the separator string is ".", the value for the compound
field will be "value1.value2.value3.value4".
A compound field can be used in a relation and an index. It cannot be a

part of another compound field.
For the additional properties field description, field heading, format,

basic field operations, list information, required, hidden, default value,
character restrictions, character operations and encrypted, see the
corresponding subsections of the section 2.12.
Syntax:
<COMPOUND_FIELD
<NAME name>
<DIM number>
<SEPARATORS string>
{<FIELD_NAME field_name>}
[<field heading>]
[<format>]
[<hidden property>]
[<default value specification>]
>
Example:

Specifying physical fields Creation of a DSS-file
<COMPOUND_FIELD
<NAME NAME>
<DIM 48>
<SEPARATORS ".">
<FIELD_NAME INSTALL>
<FIELD_NAME UNIT>
<FIELD_NAME TAG>
<DESCRIPTION
<TEXT "Item name 'install'.'unit'.'tag'">
>
<HEADING
<TEXT "">
<TRANSLATION
<DEUTSCH "">
<FRANCAIS "">
>
>
<FORMAT "%-16s">
>
2.15 Specifying physical fields

Physical fields are part of the physical record structure of the data set.
The physical record structure represent the structure of the data within
FAST/TOOLS and will be used by the DSS to retrieve, insert, update
and delete the data of FAST/TOOLS.
The physical field name is case insensitive and should be unique within
the data set. It isn’t allowed to use an SQL keyword for a physical field
name.
The logical fields can be mapped upon a physical field using

MAPS_UPON, see section 2.12.16 for a more detailed description.
When physical fields are specified for a data set, the order in which they
are specified also defines the physical record structure.
When no physical fields are specified in a data set, the physical record
structure will be the same as the logical field structure, with the same
name and data type, but without the compound fields. The logical fields
will be mapped upon these physical fields.
When a physical field is specified, the following properties are required:

• The physical field name
• The physical data type

Creation of a DSS-file Specifying physical fields
The data types supported for physical fields are described in section
2.15.1.
Syntax:
<PHYSICAL_FIELD
<NAME physical_field_name>
<physical datatype>
>
Example:
<DATASET
<NAME SCAN_TYPE_DF>
<PHYSICAL_FIELD
<NAME TYPE>
<DATATYPE
<CHAR <DIM 16>>
>
>
<PHYSICAL_FIELD
<NAME FREQUENCY>
<DATATYPE <LONG>>
>
>
2.15.1 Datatype of physical fields
The data type of the physical field can only be one of the basic data types
supported by FAST/TOOLS. These data types are a subset of the data
types that can be specified for a logical field.
Syntax:
<DATATYPE
<SHORT> |
<USHORT> |
<LONG> |
<LONG> |
<FLOAT> |
<DOUBLE> |
<BOOLEAN> |
<BYTE> |
<UBYTE>
>

Specify indexes and their properties Creation of a DSS-file
Example:
<PHYSICAL_FIELD
<NAME DESCRIPTION>
<DATATYPE
<CHAR <DIM 80>>
>
>
<PHYSICAL_FIELD
<NAME ATH_GRP_NR>
<DATATYPE <USHORT>>
>
2.16 Specify indexes and their properties

Indexes are used by DSS to enhance the performance of the retrieval of
data.
The index name is case insensitive and should be unique within the data
set. It isn’t allowed to use an SQL keyword for an index name.
For a data set more than one index can be defined. The first index
defined in the data set is the primary index for the data set. For each data
set at least one unique index must be defined.
When an index is specified, the following properties are required:

• The name of the index
• At least one field
A field used in an index should have a physical mapping. When a

compound field is used in an index, the separate fields that make up the
compound field should all have a physical mapping.
Syntax:
<INDEX
<NAME index_name>
[<index description>]
{<FIELD_NAME field_name>}
[<UNIQUE>]
>
Example:

Creation of a DSS-file Specify indexes and their properties
<DATASET
<NAME AUDIT_EVENT_CLASS_DF>
<INDEX
<NAME ECL_NAME>
<DESCRIPTION
<TEXT "Index of dataset audit_event_class_df">
>
<FIELD_NAME SUBJECT>
<FIELD_NAME ATTRIBUTE>
<FIELD_NAME ACTION>
<FIELD_NAME SOURCE>
<UNIQUE>
>
>
2.16.1 Index description
For an index a description can be specified explaining the use of the

index. This description can be translated into the different languages
supported by FAST/TOOLS.
Syntax:
<DESCRIPTION
[<translations>]
>
Example
<INDEX
<NAME ECL_NAME>
<DESCRIPTION
<TEXT "Index of dataset audit_event_class_df">
<TRANSLATION
<NEDERLANDS "Index van dataset audit_event_class_df">
>
>

General Compilation of DSS-files
3 Compilation of DSS-files
3.1 General
This chapter contains a brief explanation of how the DSS-compiler
should be used, how to compile DSS-files and - depending on what is
desired - how to create an include file and/or update a data dictionary.
3.2 How to run the DSS-compiler

To activate the DSS-compiler, the following command should be
entered on the command line:
how to dss
start-up
In the directory where the DSS-compiler is started the DSS-files are
compiled. So all dss-files should be present in this directory. The
extension of the DSS-files should be ’.dss’.
When the compiler is ready, or the process is terminated in the case of

fatal errors, the result of the compilation(any detected compiler errors),
is always logged on the screen.

a ’syntax checker’. The errors found in the DSS-files are reported on the
screen. For the actual creation of an include file or for updating a certain
data dictionary, a flag should be specified on the command line.The
command line flags are explained in the following sections.
3.3 How to use command line flags

This section contains a description of the flags that can be specified on
the command line. Flags are used to choose which actions the compiler
should take.

Compilation of DSS-files How to generate include files
The command line:
specifica- dss <flag_1> <flag_2> ... <flag_n>

tion of
flags The following flags are available:

flags • -d to create or update a data dictionary
• -b to switch off the boundary check
• -q to use quiet mode (suppress screen output)
• -w to suppress warnings
All flags are optional and they may be used in any combination. The
order in which the flags are specified is not important. In the following
subsections each flag is described separately.
3.4 How to generate include files

Include files can be generated by specifying the ’-i’-flag on the
command line.
The command line:
generation dss -i
of
include files The DSS-files are compiled and when no errors are found the include
files are generated. When include files already exist in the directory, the
existing include files are replaced with the new include files. The include
files have the same name as the DSS-files compiled, but with extension
’.dsh’.
For details about the contents of the include files, see Chapter 4.
3.5 How to create or update a data dictionary

The data dictionary can be updated or a new data dictionary can be

How to list compiler errors Compilation of DSS-files
created by specifying the ’-d’-flag on the command line.
The command line:
update dss -d<data_dictionary_name>

of a data
dictionary The data dictionary name is optional. When omitted, the default data
dictionary name ’tlsdic_dss.dic’ will be created or updated and placed in
the directory ’/tls/dat’. When a dictionary name is supplied, it should be
supplied without an extension. It is also allowed to supply an actual or a
relative path. The data dictionary will automatically obtain the extension
’.dic’.
3.6 How to list compiler errors

When the DSS-compiler finds errors in the DSS-files, they are reported
on the screen. The error messages reported to the screen can also be
gathered in a so called list file. The list file can be generated by
specifying the ’-l’-flag on the command line.
The command line:
dss -l<list_file_name>
The list file name is optional. When omitted and no ’-d’-flag is specified,
the default list file name ’tlsdic_dss.lst’ will be created in the directory
of the DSS-files.When the list file name is omitted, but another data
dictionary name is specified, this list file has the same name as the data
dictionary name, but with extension ’.lst’. When the list file name is
specified, it should be specified without an extension. It is also allowed
to use an actual or relative path. When the list file already exists in the
directory, it will be replaced with the new list file
3.7 How to suppress output to screen

It is possible to suppress the messages reported to the screen. This can

Compilation of DSS-files How to suppress warnings
be done by specifying the ’-q’-flag on the command line.
The command line:
dss -q
The error messages of the compiler will not be reported to the screen.
The only message shown will be the number of errors found, if any,
otherwise no output is given at all.
In general this flag will be used together with the ’-l’-flag, so that the
error messages are reported in a list file and not on the screen.
3.8 How to suppress warnings

It is possible to suppress warnings generated by the compiler. The
warnings will not be reported to screen and in the list file.
The command line:
dss -w

Introduction The include file
4 The include file
4.1 Introduction
In this chapter the include files, generated by the DSS-compiler, are
described.
include file Include files generated by the DSS-compiler contain information about
the data set, as specified in the DSS-file, together with the logical and
physical field structure and the index specifications. However this
information is in C-language format so they can be included in C-
programs.
The include files generated by the DSS-compiler have the same name as
the DSS-files, but with extension ’.dsh’. They are placed in the same
directory as the DSS-files. When the include files already exist, they are
replaced with the new include files.
4.2 Other included files

The structure of include-statements in the generated include files are the
same as in the DSS-files. So when a DSS-include file is specified in the
DSS-file, a #include is also created in the include file generated.
Example:
<INCLUDE "dss_global.inc">
will become
#ifndef _DSS_GLOBAL_DSH
#include <dss_global.dsh>
#endif

The include file Defined constants
4.3 Defined constants

In the DSS-file constants can be specified. These constants will become
#define’s in the include file. The #define’s of the constants are placed
in the include file that is derived from the DSS-file.
Example
<DEFINE_CONSTANT
<VALUE 80>
>
will become
#define DSS_DESCRIPTION_SZ 80
4.4 General data set information

Part of the data set information is translated into #define’s. The
following #define’s are generated for the include file:
#define <dataset_name>_DSET_NM "dataset_name"
#define <dataset_name>_PATH_NR 5
#define <dataset_name>_FILE_SP "data_file.dat"
where <dataset_name> will be replaced by the data set name specified.

The file specification and the path number are specified by
<DATA_FILE> in the DSS-file.
Example:
<DATASET
<NAME ALARM_ASA_DF>
<DATA_FILE
<NAME "alm_asa_df.da">
<LOGICAL_PATH <DATA>>
>
>
will become
#define ALARM_ASA_DF_DSET_NM "ALARM_ASA_DF"

#define ALARM_ASA_DF_PATH_NR 5

Record information The include file
#define ALARM_ASA_DF_FILE_SP "alm_asa.dat"
4.5 Record information

The record information of the logical and physical record structures of
the data sets are translated into struct-definitions in the include file. The
following struct-definitions are made:
struct <dataset_name>_p
#define <dataset_name>_FMT_P "format_string"
struct <dataset_name>_l
In addition to the C-structures, a two format strings are generated. These

format strings are #define’s in the include file and can be used by
applications for system conversion purposes. Format strings are only
generated for the physical field structure. For the logical field structure
no format string is generated.
Example:
<DATASET
<NAME ALARM_ASA_DF>
<FIELD
<NAME NAME>
<DATATYPE
<CHAR <DIM 32>>
>
<MAPS_UPON NAME>
>
<FIELD
<NAME DESCRIPTION>
>
<FIELD
<NAME COMPILE>
<DATATYPE <BOOLEAN>>
<MAPS_UPON FLAGS>
>
<PHYSICAL_FIELD
<NAME SEQ_NR>
<DATATYPE <USHORT>>
>
<PHYSICAL_FIELD

The include file Index information
<NAME FLAGS>
<DATATYPE <USHORT>>
>
<PHYSICAL_FIELD
<NAME SRC_FILE>
>
<PHYSICAL_FIELD
<NAME LIST_FILE>
>
<PHYSICAL_FIELD
<NAME PFX_INFO>
>
>
will become
struct alarm_asa_df_p
{
char name[32];
TLS_USHORT seq_nr;
TLS_USHORT flags;
char src_file[80];
char list_file[80];
char pfx_info[884];
};
#define ALARM_ASA_DF_FMT_P"32C2S1044C"
#define ALARM_ASA_DF_FFMT_P"32C2S1044C"
struct alarm_asa_df_l
{
char name[32];
TLS_MBCHAR description[DSS_DESCRIPTION_SZ];
TLS_BOOLEAN compile;
};
4.6 Index information

The index information of the data sets are translated into #define’s for
the indexes and the index fields. This information can be used in calls to
the ISF routins of DATABASE/FAST. The following #define’s are
made:
#define <dataset_name>_KEYS
number_of_indexes
#define <dataset_name>_KEYS_DEF struct keydesc

Index information The include file
#define <dataset_name>_KEYS_INI index_fields
#define <dataset_name>_KEYS_<index_name>
index_number
Example:
<DATASET
<NAME STATUS_DF>
<INDEX
<NAME NAME>
<FIELD_NAME NAME>
<UNIQUE>
>
<INDEX
<FIELD_NAME STATUS_NUMBER>
<UNIQUE>
>
>
will become
#define STATUS_DF_KEYS 2
#define STATUS_DF_KEYS_DEF struct keydesc
status_df_rec_keys[STATUS_DF_KEYS]
#define STATUS_DF_KEYS_INI STATUS_DF_KEYS_DEF = \

{ \
{ ISNODUPS, 1, \
{ \
{ 36, 12, 0 } \
} \
}, \
{ ISNODUPS, 1, \
{ \
{ 0, 1, 0 } \
} \
} \
}
#define STATUS_DF_KEYS_NAME 0
#define STATUS_DF_KEYS_STATUS_NUMBER 1












5 Reference
5.1 Introduction
This chapter contains the formal description of the DSS-language.
5.2 The DSS-language syntax description
5.2.1 General
To make the syntax description of DSS-language easier to understand,

the notation principles used in these descriptions are briefly explained.
5.2.2 Symbols used
Below is a list of special symbols used in the DSS-language syntax

description.
• symbol: BOLD printed elements

meaning: They are part of the DSS-language itself.
example: <REQUIRED>
<INCLUDE filename>
• symbol: italic printed elements
meaning: They are values that should be specified for the
sentence.
example: <NUMERIC numeric value>
<INCLUDE filename>
| • symbol:|
meaning: indicates one element (to the left of the symbol)
or another element (to the right of the symbol)
to be specified.
example: A|B|C, means one of the characters ’A’, ’B’ or
’C’ must be specified
[] • symbol: [ ]
meaning: indicates that the element included in the
brackets is optional

Reference The DSS-language syntax description
example: [1|2], means ’1’ or ’2’ may be specified

{ }.. • symbol: { }..
meaning: indicates the element included by the accolades
should be specified one or more times
example: A[{1|2|3|4|5|6|7|8|9|0}..], means that
an ’A’ must be specified, while it may be
followed by zero or more digits
<> • symbol: < >
meaning: indicates that an element is a sentence of the DSS
-language or it is not a basic element of the DSS-
lanuage, but a collection of subsentences or
elements.
example: <digit> : 1|2|3|4|5|6|7|8|9|0
<include> : <INCLUDE filename>
’’ • symbol: ’ ’
meaning: indicates that the character included by the
quotes is actually part of DSS-language; i.e. it is not
meant as a special symbol
example: [’[’]key[’]’], means that ’key’ or ’[key]’
must be specified
5.2.3 The DSS-language syntax
<syntax>:
[{<include file>}]
[{<define macro>}]
[{<define constant>}]
[{<define field template>}]
[{<define node>}]
{<data set>}
<include file>:
<INCLUDE filename>
<define macro>:
<DEFINE_MACRO
<LABEL macro label name>
<MACROTEXT {<subsentence>}>
>

The DSS-language syntax description Reference
<define constant>:
<DEFINE_CONSTANT
<LABEL constant label name>
<VALUE value>
>
<define field template>:

<LABEL field template label name>
<field_type>
[{optional field properties}]
>
<define node>:
<DEFINE_NODE
<LABEL node label name>
<node_id>
[<PRIORITY priority>]
>
<node_id>:
<NAME nodename> | <NUMBER nodenumber>
<use macro>:
<USE_MACRO macro label name>
<use constant>:
<USE_CONSTANT constant label name>
<data set>:
<DATASET
<NAME name>
[<data set description>]
{<logical field definition>}
{<index definition>}
<data file specification>
[<data access server>]
[<basic data set operations>]
[<storage>]
[<hidden property>]
[{<physical field definition>}]
>

<data set description>:

<description>
<description>
<DESCRIPTION
<TEXT text>
[<language translations>]
>
<language translations>:
<TRANSLATION {<translation>}>
<translation>:
<ENGLISH text> |
<NEDERLANDS text> |
<DEUTSCH text> |
<FRANCAIS text>
<data file specification>:

<DATA_FILE
<filename>
>
<filename>:
<NAME filename>
[<logical pathname>]
<logical pathname>:
<LOGICAL_PATH
<logical path symbol>
>
<logical path symbol>:

<AUX> | <COMMAND> | <DATA> | <DID> | <EXE> |
<HELP> | <HIS> | <INIT> | <LIST> | <SAVE> |
<USER1> | <USER2> | <USER3> | <USER4> |
<USER5>
<data access server>:

<DATA_ACCESS
<SERVERNAME <data access server name>>
>

<data access server name>:

"shared library name:routine name"
<basic data set operations>:

<DATASET_OPERATIONS
{<basic data set operation>}
>
<basic data set operation>:

<OPERATION
<data set operation value>
>
<data set operation value>

<SELECT> | <INSERT> | <UPDATE> | <DELETE> |
<EVENT_REQ_DATASET> | <EVENT_REQ_RECORD> |
<EVENT_REQ_FIELD>
<storage>:
<STORAGE
<node specification>
>
<node specification>:
<NODES
{<node label>}
>
<node label>:
<NODE_NAME node label name>
<hidden property>:
<HIDDEN>
<physical field definition>:

<PHYSICAL_FIELD
<NAME name>
<physical field datatype>
>
<physical field datatype>:

<DATATYPE

<physical datatype>
>
<physical datatype>:
<CHAR <DIM dimension>>|
<SHORT> |
<USHORT> |
<LONG> |
<LONG> |
<FLOAT> |
<DOUBLE> |
<BOOLEAN> |
<BYTE> |
<UBYTE>
<logical field definition>:

<normal field definition> |
<relation field definition> |
<compound field definition
<normal field definition>:

<FIELD
<NAME name>
[<field template used>]
[<field data type>]
[{<optional field properties>}]
>
<field template used>:

<FIELD_TEMPLATE field template label>
<field datatype>:
<DATATYPE
<datatype>
>
<datatype>:
<SHORT> |
<USHORT> |
<LONG> |
<LONG> |
<FLOAT> |

<DOUBLE> |
<BOOLEAN> |
<BYTE> |
<UBYTE> |
<MBCHAR <DIM dimension>> |
<DATE> |
<INTERVAL> |
<MEMO> |
<UNKNOWN>
<optional field properties>:

[<field description>] |
[<heading>] |
[<format>] |
[<transformation>] |
[<basic field operations>]|
[<range and step info>] |
[<list of values>] |
[<required property>] |
[<hidden property>] |
[<default value spec>] |
[<character restrictions>]|
[<character operations>] |
[<encrypted>] |
[<maps upon>]
<relation field definition>:

<RELATION_FIELD
<NAME name>
<relates to>
[{<optional relation field properties>}]
>
<relates to>:
<RELATES_TO
<DATASET_NAME name>
<FIELD_NAME field name>
[<VIA field name>]
>
<optional relation field properties>:

[<heading>] |


[<format>] |
[<maps_upon>]
<compound field definition>:

<COMPOUND_FIELD
<NAME name>
<DIM dimension>
<SEPARATORS text>
{<used field names> }
[{<optional compound field properties>}]
>
<used field names>:

<optional compound field properties>:

[<heading>] |
[<format>] |
[<list of values>] |
[<default value spec>] |
[<character restrictions>]|
[<character operations>] |
[<encrypted>] |
<field description>:
<description>
<heading>:
<HEADING
<TEXT text>
[<language translations>]
>
<format>:

<FORMAT
<format string>
>
<format string>:
<REPORT/FAST format> |
<datetime format> |
<C-like format>
<REPORT/FAST format>:
<Integer format> |
<Real format> |
<String format>
<Integer format>:
[['+'] ['0'] {'9'}] | "I1" | "I2" | "I3" | "I4"
<Real format>:
[['+'] ['0'] [{'9'}] ['.'] [{'9'}] ['E']] |
"F4" | "F8"
<String format>:
[{'A'} ['R' | 'L' | 'C'] [<number>]]
<datetime format> :
[<dateformat>] ['char'] [<timeformat>]
<dateformat>:
[<day>] ['char'] [<month>] ['char'] [<year>]
<day>:
D | DD | DDD | DDDD
<month>:
M | MM | MMM | MMMM
<year>:
YY | YYYY
<timeformat>:
[<hours>] ['char'] [<minutes>] ['char']
[<seconds>] ['char'] [<milliseconds>]
<hours>:
hh

<minutes>:
mm
<seconds>:
ss
<milliseconds>:
ppp
<C-like format>: format in conformance with the

formatting of the printf function of C, like %-
3f or %x
<transformation>:
<TRANSFORMATION
{<transformation entrie>}
[<physical datatype>]
>
<transformation entrie>:
<ENTRY
<NUMERIC numeric value>
<STRING string value>
[<language translation>]
>
<basic field operations>:

<FIELD_OPERATIONS
{<basic field operation>}
>
<basic field operation>:

<OPERATION
<field operation value>
>
<field operation value>:

<SELECT> | <UPDATE>
<range and step info>:

<RANGE
<LOW number>
<HIGH number>
[<STEP number>]
[<VISUAL_CHANGE number>]

>
<list definition>:
<LIST
{<listentry>}
>
<listentry>:
<ENTRY
<listvalue>
>
<listvalue>:
<VALUE string>
[<language translation>]
<required property>:
<REQUIRED
[{<required operations>}]
>
<required operations>:
<INSERT> | <UPDATE>
<hidden property>:
<HIDDEN>
<default value spec>:

<DEFAULT_VALUE_SPEC
<VALUE value>
{<default value operations>}
>
<default value operations>:

<INSERT> | <UPDATE>
<character restrictions>:
<CHAR_RESTRICTIONS
{<character restriction>}
>
<character restriction>:
<CHAR_RESTRICTION

<char_restriction value>
>
<char_restriction value>:
<NO_SPACES> |
<NO_DOTS> |
<ONLY_PRINTABLE> |
<ONLY_ALPHANUMERICS> |
<ONLY_NUMERICS> |
<ONLY_IDENTIFIER>
<character operations>:
<CHAR_OPERATIONS
{<character operation>}
>
<character operation>:
<CHAR_OPERATION
<character operation value>
>
<character operation value>:

<character case operation> |
<character blanks operation>
<character case operation>:

<TO_UPPER> | <TO_LOWER>
<character blanks operation>:

<REMOVE_LEADING_SPACES> |
<REMOVE_TRAILING_SPACES> |
<ADD_BLANKS
[<BLANK char>]
>
<encrypted> :
<maps upon>:
<MAPS_UPON physical field name>
<index definition> :
<INDEX

<NAME name>
{<index field>}
[<index description>]
[<index property>]
>
<index field>:
<index description>:
<description>
<index property>:
<UNIQUE>


Appendix A: An example
A.1 Introduction
In this appendix a complete example is given of DSS-file with its
corresponding include files.
Section A.2 contains the DSS-files.
Section A.3 contains the include files, generated by the DSS-compiler.
A.2 DSS-file
/*---------------------------------------------------------------+
Module Name : dss_global.dss
Description : Global definitions for FAST/TOOLS DSS files
Version :
Copyright (c) : Yokogawa
Author : S. Sietsma
+----------------------------------------------------------------+
| Changes ....
+----------------------------------------------------------------+
|Who When Change What
+----------------------------------------------------------------+
STM Dec-98 Created
External definitions
+---------------------------------------------------------------*/
/*---------------------------------------------------------------+
| Constant definitions
+---------------------------------------------------------------*/
<DEFINE_CONSTANT
<VALUE 80>
>
<DEFINE_CONSTANT
<LABEL DSS_ITEM_NM_SZ>
<VALUE 64>
>
<DEFINE_CONSTANT
<LABEL DSS_INST_NM_SZ>
<VALUE 16>
>
DATA SET SERVICES Language Manual A-1

<DEFINE_CONSTANT
<LABEL DSS_UNIT_NM_SZ>
<VALUE 16>
>
<DEFINE_CONSTANT
<LABEL DSS_TAG_NM_SZ>
<VALUE 16>
>
<DEFINE_CONSTANT
<LABEL DSS_STAG_NM_SZ>
<VALUE 16>
>
<DEFINE_CONSTANT
<LABEL DSS_NODE_NM_SZ>
<VALUE 24>
>
<DEFINE_CONSTANT
<LABEL DSS_CLS_NAME_SZ>
<VALUE 16>
>
<DEFINE_CONSTANT
<LABEL DSS_CLS_DESC_SZ>
<VALUE 80>
>
<DEFINE_CONSTANT
<LABEL DSS_FIL_NAME_SZ>
<VALUE 80>
>
<DEFINE_CONSTANT
<LABEL DSS_QRY_TEXT_SZ>
<VALUE 256>
>
<DEFINE_CONSTANT
<LABEL DSS_TRG_NAME_SZ>
<VALUE 16>
>
<DEFINE_CONSTANT
<LABEL DSS_TRG_DESC_SZ>
<VALUE 64>
>
/*---------------------------------------------------------------+
| Macro definitions
+---------------------------------------------------------------*/
/*---------------------------------------------------------------+
| Template definitions
+---------------------------------------------------------------*/
/*---------------------------------------------------------------+
| Description field
+---------------------------------------------------------------*/
<LABEL tplDESCRIPTION>
<DATATYPE <MBCHAR <DIM <USE_CONSTANT DSS_DESCRIPTION_SZ>>>>
<DESCRIPTION
>
DATA SET SERVICES Language Manual -2

<HEADING
<TRANSLATION
<DEUTSCH "Beschreibung">
<FRANCAIS "Description">
>
>
<FORMAT "%-80s">
>
/*---------------------------------------------------------------+
| Template definition for node-name gebruik ik niet??
+---------------------------------------------------------------*/
<LABEL tplNodeName>
<DATATYPE <CHAR <DIM <USE_CONSTANT DSS_NODE_NM_SZ>>>>
<HEADING
<TEXT "Node name">
>
<FORMAT "%-64s">
>
/*---------------------------------------------------------------+
| Template definition for item-id gebruik ik niet??
+---------------------------------------------------------------*/
<LABEL tplItemIdNode>
<DATATYPE <UBYTE>>
>
<LABEL tplItemIdGroup>
<DATATYPE <UBYTE>>
>
<LABEL tplItemIdNumber>
<DATATYPE <USHORT>>
>
<LABEL tplItemIdSubno>
<DATATYPE <UBYTE>>
>
<LABEL tplItemIdAttno>
<DATATYPE <UBYTE>>
>
<LABEL tplItemIdNu1>
<DATATYPE <UBYTE>>
>
<LABEL tplItemIdNu2>
<DATATYPE <UBYTE>>
>
/*---------------------------------------------------------------+
| Template definition for item-name components
+---------------------------------------------------------------*/
<LABEL tplInstallation>
<DATATYPE <CHAR <DIM <USE_CONSTANT DSS_INST_NM_SZ>>>>
<HEADING
<TEXT "Installation">
>

<FORMAT "%-16s">
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<NO_SPACES>
>
<CHAR_RESTRICTION
<ONLY_PRINTABLE>
>
<CHAR_RESTRICTION
<NO_DOTS>
>
>
<CHAR_OPERATIONS
<CHAR_OPERATION
<TO_UPPER>
>
>
>
<LABEL tplUnit>
<DATATYPE <CHAR <DIM <USE_CONSTANT DSS_UNIT_NM_SZ>>>>
<HEADING
<TEXT "Unit">
>
<FORMAT "%-16s">
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<NO_SPACES>
>
<CHAR_RESTRICTION
<ONLY_PRINTABLE>
>
<CHAR_RESTRICTION
<NO_DOTS>
>
>
<CHAR_OPERATIONS
<CHAR_OPERATION
<TO_UPPER>
>
>
>
<LABEL tplTag>
<DATATYPE <CHAR <DIM <USE_CONSTANT DSS_TAG_NM_SZ>>>>
<HEADING
<TEXT "Tag">
>
<FORMAT "%-16s">
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<NO_SPACES>
>
<CHAR_RESTRICTION
<ONLY_PRINTABLE>
>
<CHAR_RESTRICTION
<NO_DOTS>
>
>
<CHAR_OPERATIONS

<CHAR_OPERATION
<TO_UPPER>
>
>
>
<LABEL tplSubTag>
<DATATYPE <CHAR <DIM <USE_CONSTANT DSS_STAG_NM_SZ>>>>
<HEADING
<TEXT "Subtag">
>
<FORMAT "%-16s">
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<NO_SPACES>
>
<CHAR_RESTRICTION
<ONLY_PRINTABLE>
>
<CHAR_RESTRICTION
<NO_DOTS>
>
>
<CHAR_OPERATIONS
<CHAR_OPERATION
<TO_UPPER>
>
>
>
/*---------------------------------------------------------------+
| Template definition for item-name gebruik ik niet??
+---------------------------------------------------------------*/
<LABEL tplItemName>
<HEADING
<TEXT "Item name">
>
<FORMAT "%-64s">
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<NO_SPACES>
>
<CHAR_RESTRICTION
<ONLY_PRINTABLE>
>
>
<CHAR_OPERATIONS
<CHAR_OPERATION
<TO_UPPER>
>
>
>
/*---------------------------------------------------------------+
| Nodes 131 and 132 for storage of datasets INSTALL_DF
+---------------------------------------------------------------*/
<DEFINE_NODE
<LABEL node_131>
<NUMBER 131>
<PRIORITY 255>

>
<DEFINE_NODE
<LABEL node_132>
<NUMBER 132>
<PRIORITY 255>
>
/*---------------------------------------------------------------+
| Module identification
+----------------------------------------------------------------+
Module Name : user_df
Description : Data Set definition for User data set.
Version :
Author : E. van Norel
+----------------------------------------------------------------+
| Changes ....
+----------------------------------------------------------------+
+----------------------------------------------------------------+
NRL Jan-99 First version documented
+----------------------------------------------------------------+
| External definitions
+---------------------------------------------------------------*/
<INCLUDE "dss_global.dss">
/*---------------------------------------------------------------+
| Template definition for action names
+---------------------------------------------------------------*/
<DEFINE_MACRO
<LABEL PROCESS_AREA_GRP>
<MACROTEXT
<RELATES_TO
<DATASET_NAME PROC_AREA_GRP_DF>
<FIELD_NAME NAME>
<VIA NUMBER>
>
<DESCRIPTION
>
<FORMAT "%-32s">
>
>
/*---------------------------------------------------------------+
| Start of data set definition
+---------------------------------------------------------------*/
<DATASET
<NAME USER_DF>
<DESCRIPTION
<TEXT "User definition">
>
/*---------------------------------------------------------------+
| Data set structure
+---------------------------------------------------------------*/

<FIELD
<NAME NAME>
<DESCRIPTION
<TEXT "Name">
>
>
<FIELD
<NAME DESCRIPTION>
<MAPS_UPON DESCRIPTION>
>
<FIELD
<NAME PASSWORD>
<DESCRIPTION
<TEXT "Password">
>
>
<RELATION_FIELD
<NAME AUTH_GROUP>
<RELATES_TO
<DATASET_NAME AUTH_GROUP_DF>
<FIELD_NAME NAME>
<VIA NUMBER>
>
<DESCRIPTION
<TEXT "Authorisation group">
>
>
<RELATION_FIELD
<NAME ASA>
<RELATES_TO
<DATASET_NAME ALARM_ASA_DF>
<FIELD_NAME NAME>
>
<DESCRIPTION
<TEXT "Alarm selection area">
>
>
<FIELD
<NAME INITIAL_DISPLAY>
<DESCRIPTION
<TEXT "Initial display">
>
>
<RELATION_FIELD
<NAME PROCESS_AREA_GRP_1>
<USE_MACRO PROCESS_AREA_GRP>
>
<RELATION_FIELD
>
<RELATION_FIELD
>
<RELATION_FIELD

>
<RELATION_FIELD
>
/*---------------------------------------------------------------+
| Physical Field info
+---------------------------------------------------------------*/
<PHYSICAL_FIELD
<NAME USER_NAME>
>
<PHYSICAL_FIELD
<NAME DESCRIPTION>
>
<PHYSICAL_FIELD
<NAME PASSWORD>
>
<PHYSICAL_FIELD
>
<PHYSICAL_FIELD
<NAME ASA>
>
<PHYSICAL_FIELD
<NAME ATH_GRP_NR>
<DATATYPE <USHORT>>
>
<PHYSICAL_FIELD
<NAME FILLER>
<DATATYPE <SHORT>>
>
<PHYSICAL_FIELD
<NAME PAG_NR1>
<DATATYPE <LONG>>
>
<PHYSICAL_FIELD
<NAME PAG_NR2>
<DATATYPE <LONG>>
>
<PHYSICAL_FIELD
<NAME PAG_NR3>
<DATATYPE <LONG>>
>
<PHYSICAL_FIELD
<NAME PAG_NR4>
<DATATYPE <LONG>>
>
<PHYSICAL_FIELD
<NAME PAG_NR5>
<DATATYPE <LONG>>
>
<PHYSICAL_FIELD
<NAME PROV_SPARE>
>
<PHYSICAL_FIELD

<NAME CUST_DATA>
>
/*---------------------------------------------------------------+
| Index definition
+---------------------------------------------------------------*/
<INDEX
<NAME NAME>
<FIELD_NAME NAME>
<UNIQUE>
>
/*---------------------------------------------------------------+
| Data access specification
+---------------------------------------------------------------*/
<DATA_FILE
<NAME "dss_user.dat">
>
<DATA_ACCESS
<SERVERNAME "dsilib:dsid_usr_df">
>
/*---------------------------------------------------------------+
| Additional field attributes
+---------------------------------------------------------------*/
<FIELD
<NAME NAME>
<MAPS_UPON USER_NAME>
<FIELD_OPERATIONS
<OPERATION
<SELECT>
>
>
<HEADING
<TEXT "Username">
<TRANSLATION
<DEUTSCH "Bedienername">
<FRANCAIS "Nom d'utilisateur">
>
>
<FORMAT "%-32s">
<REQUIRED
<INSERT>
<UPDATE>
>
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<NO_SPACES>
>
CHAR_RESTRICTION
<NO_DOTS>
>
>
<CHAR_OPERATIONS
<CHAR_OPERATION
<TO_UPPER>
>
>
>
<FIELD

<NAME PASSWORD>
<MAPS_UPON PASSWORD>
<HEADING
<TEXT "Password">
<TRANSLATION
<DEUTSCH "Kennwort">
<FRANCAIS "Mot de passe">
>
>
<FORMAT "%-32s">
<REQUIRED
<INSERT>
<UPDATE>
>
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<NO_SPACES>
>
>
>
<FIELD
<MAPS_UPON INITIAL_DISPLAY>
<HEADING
<TEXT "Initial|Display">
<TRANSLATION
<DEUTSCH "Erste|Anzeige">
<FRANCAIS "Premier synoptique">
>
>
<FORMAT "%-80s">
<CHAR_RESTRICTIONS
<CHAR_RESTRICTION
<NO_SPACES>
>
<CHAR_RESTRICTION
<NO_DOTS>
>
>
<CHAR_OPERATIONS
<CHAR_OPERATION
<TO_UPPER>
>
>
>
<RELATION_FIELD
<MAPS_UPON PAG_NR1>
<HEADING
<TEXT "Process area1">
<TRANSLATION
<DEUTSCH "">
<FRANCAIS "">
>
>
>
<RELATION_FIELD
<MAPS_UPON PAG_NR2>
<HEADING
<TRANSLATION

<DEUTSCH "">
<FRANCAIS "">
>
>
>
<RELATION_FIELD
<MAPS_UPON PAG_NR3>
<HEADING
<TRANSLATION
<DEUTSCH "">
<FRANCAIS "">
>
>
>
<RELATION_FIELD
<MAPS_UPON PAG_NR4>
<HEADING
<TRANSLATION
<DEUTSCH "">
<FRANCAIS "">
>
>
>
<RELATION_FIELD
<MAPS_UPON PAG_NR5>
<HEADING
<TRANSLATION
<DEUTSCH "">
<FRANCAIS "">
>
>
>
<RELATION_FIELD
<NAME AUTH_GROUP>
<MAPS_UPON ATH_GRP_NR>
<HEADING
<TEXT "Authorization">
<TRANSLATION
<DEUTSCH "Autorisation">
<FRANCAIS "Autorisation">
>
>
<REQUIRED
<INSERT>
<UPDATE>
>
>
<RELATION_FIELD
<NAME ASA>
<MAPS_UPON ASA>
<HEADING
<TEXT "Asa">
<TRANSLATION
<DEUTSCH "Asa">
<FRANCAIS "Asa">
>
>

<FORMAT "%-32s">
>
>
A.3 Include file

/*---------------------------------------------------------------+
| * DSS *
+----------------------------------------------------------------+
+----------------------------------------------------------------+
Module Name : dss_global.dsh
Version :
Author : DSS-compiler
+----------------------------------------------------------------+
| Changes ....
+----------------------------------------------------------------+
+----------------------------------------------------------------+
DSS 5-5-1999 Creation
+----------------------------------------------------------------+
| External declarations
+---------------------------------------------------------------*/
#define _DSS_GLOBAL_DSH
#ifndef _ISF_H
#include <isf.h>
#endif
#define DSS_DESCRIPTION_SZ80
#define DSS_ITEM_NM_SZ64
#define DSS_INST_NM_SZ16
#define DSS_UNIT_NM_SZ16
#define DSS_TAG_NM_SZ16
#define DSS_STAG_NM_SZ16
#define DSS_NODE_NM_SZ24
#define DSS_CLS_NAME_SZ16
#define DSS_CLS_DESC_SZ80
#define DSS_FIL_NAME_SZ80
#define DSS_QRY_TEXT_SZ256
#define DSS_TRG_NAME_SZ16
#define DSS_TRG_DESC_SZ64
#endif
/*---------------------------------------------------------------+
| * DSS *
+----------------------------------------------------------------+

+----------------------------------------------------------------+
Module Name : user_df.dsh
Version :
uthor : DSS-compiler
+----------------------------------------------------------------+
| Changes ....
+----------------------------------------------------------------+
+----------------------------------------------------------------+
DSS 19-5-1999 Creation
+----------------------------------------------------------------+
+---------------------------------------------------------------*/
#ifndef _USER_DF_DSH
#define _USER_DF_DSH
#ifndef _ISF_H
#include <isf.h>
#endif
#include <dss_global.dsh>
#endif
#define USER_DF_DSET_NM "USER_DF"

#define USER_DF_PATH_NR 5
#define USER_DF_FILE_SP "dss_user.dat"
/*---------------------------------------------------------------+
| Physical dataset-structure
+---------------------------------------------------------------*/
struct user_df_p
{
char user_name[32];
char description[80];
char password[32];
char initial_display[80];
char asa[16];
TLS_USHORT path_grp_nr;
TLS_SHORT filler;
TLS_LONG pag_nr1;
TLS_LONG pag_nr2;
TLS_LONG pag_nr3;
TLS_LONG pag_nr4;
TLS_LONG pag_nr5;
char prov_spare[100];
char cust_data[100];
};
/*---------------------------------------------------------------+
| Record format description
+---------------------------------------------------------------*/

#define USER_DF_FMT_P "240C2S5L200C"
#define USER_DF_FFMT_P "240C2S5L200C"
/*---------------------------------------------------------------+
| Logical dataset-structure
+---------------------------------------------------------------*/
struct user_df_l
{
char name[32];
TLS_MBCHAR description[80];
char password[32];
char auth_group[32];
char asa[32];
char initial_display[80];
char process_area_grp_1[32];
};
/*---------------------------------------------------------------+
| Indexes
+---------------------------------------------------------------*/
#define USER_DF_KEYS 1
#define USER_DF_KEYS_DEF struct keydesc
user_df_rec_keys[USER_DF_KEYS]
#define USER_DF_KEYS_INI USER_DF_KEYS_DEF = \
{ \
{ ISNODUPS, 1, \
{ \
{ 0, 32, 0 } \
} \
} \
}
#define USER_DF_KEYS_NAME 0
#endif

Index
Index
C field level 1-3

field operations 2-25
CHAR_RESTRICTIONS 2-31, 5-11 field templates 2-2, 2-4, 2-7
character operations 2-32
FIELD_OPERATIONS 2-26, 5-10
character restrictions 2-31
FIELD_TEMPLATE 2-8, 5-6
comments 2-3 fields 1-1
compound field 2-17, 2-19, 2-39
FORMAT 2-23, 5-9
COMPOUND_FIELD 2-40, 5-8 format string 2-23
constants 2-2, 2-5
CREATE property 2-13 H
D HEADING 2-23
HIDDEN 2-16, 2-17, 2-29, 2-35, 2-36,
data access server 2-13 2-37, 5-5, 5-11
data set description 2-12 hidden property 2-16, 2-29, 2-34, 2-35
data set level 1-3
data set operations 2-14
data sets 1-1, 1-2, 2-2, 2-10
I
data types 2-21, 2-37 INCLUDE 2-5
DATA_ACCESS 2-14 include file a-12
DATA_FILE 2-13 include files 1-1, 2-4, 2-5
database file 2-13 INDEX 5-12
DATASET 2-11, 5-3 index 2-10
DATASET_OPERATIONS 2-15, 5-5 index level 1-3
DATATYPE 2-21, 5-5 INTERVAL 2-26, 2-30
DATE 2-26, 2-30
default value 2-29 L
DEFAULT_VALUE_SPEC 5-11 LIST 2-28
DEFINE_CONSTANT 2-5, 5-3 logical field 2-7, 2-10, 2-17, 2-21, 2-24,
DEFINE_FIELD_TEMPLATE 2-8, 5-3 2-31, 2-32, 2-33, 2-37
DEFINE_MACRO 2-6, 5-2 logical structure 1-2, 2-41
DEFINE_NODE 2-9, 5-3 LOGICAL_PATH 2-13, 5-4
DESCRIPTION 2-12, 2-22, 5-4
DSS-compiler 1-3, 2-23, a-1 M
DSS-file 2-1 macros 2-2, 2-6
DSS-files 1-3, 2-5, 2-10, a-1 MAPS_UPON 2-34, 2-41, 5-12
DSS-language 1-1, 2-1, 2-3, 2-9, 5-1 multi-byte character string 2-21
E N
encrypted property 2-33 node label 2-9
NODES 2-15, 5-5
F normal field 2-17, 2-19
field description 2-22
field heading 2-22
DATABASE/FAST DSS Language Manual 1

Index
P
PASSWORD_ENCRYPTED 2-33, 5-
12
physical field 2-10, 2-24, 2-33, 2-41
physical structure 1-2, 2-41
PHYSICAL_FIELD 2-42, 5-5
primary node 2-9, 2-38
PRIORITY 2-9
priority 2-9
properties 1-3, 2-2, 2-7, 2-11, 2-17, 2-
28, 2-29, 2-33, 2-40
R
RANGE 5-10
range 2-26
records 1-1
RELATES_TO 5-7
RELATION_FIELD 2-38
relational field 2-17, 2-19, 2-37
REQUIRED 2-29, 5-11
required property 2-28
S
sentences 2-3, 2-6
separator string 2-40
SERVERNAME 2-14
shared library 2-14
STEP 5-10
step 2-26
STORAGE 2-10, 2-15, 5-5
storage nodes 2-2, 2-9, 2-15
subsentence 2-3
T
TRANSFORMATION 2-24, 5-10
transformation 2-24, 2-27, 2-30
TRANSLATION 2-4, 5-4
translations 2-4
U
UNIQUE 5-13
USE_CONSTANT 2-6, 5-3
USE_MACRO 5-3
V
via-field 2-37
2 DATABASE/FAST DSS Language Manual

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction FAST/TOOLS R10.03 FAST/TOOLS
Manual Terms and Conditions of
Open Source Software
IM 50Z01A01-01E/R10.03

IM 50Z01A01-01E/R10.03
July 2017
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
1 Terms and Conditions of Open Source Software .................1

1.1 Introduction ..................................................................1
1.2 Licenses and applicable programs ................................1
1.2.1 Oracle BCL (Binary Code License) ................1
1.2.2 GNU GPL (GNU General Public License) .....9
1.2.3 GNU LGPL (GNU Lesser Public License
Version 3) 16
1.2.4 Apache Licence 2.0 .......................................19
1.2.5 BSD (Berkeley Software Distribution license) ..
25
1.2.6 MIT
(Massachusetts Institute of Technology License)
26
1.2.7 WTFPL License .............................................27
1.2.8 BOOST Software License .............................27
1.2.9 JDOM License ...............................................28
1.2.10 Eclipse Public License version 1 ...................30
1.2.11 Common Public License version 1 ................35
1.2.12 OpenSSL License ..........................................40
FAST/TOOLS Release Notes iii

Table of Contents
iv FAST/TOOLS Release Notes

Introduction Terms and Conditions of Open Source Software
1 Terms and Conditions of Open

Source Software
1.1 Introduction
FAST/TOOLS contains portions of open source software which are distributed under
specific license agreements. These license agreements and the software to which they apply
is summarized in this document.
1.2 Licenses and applicable programs
1.2.1 Oracle BCL (Binary Code License)
Programs to which this license applies

• J2SE (tm) Runtime (JRE)1.8.0_112-b15
• Javahelp 2.0.05
Oracle Binary Code License Agreement for the Java SE

Platform Products and JavaFX
ORACLE AMERICA, INC. ("ORACLE"), FOR AND ON BEHALF OF ITSELF

AND ITS SUBSIDIARIES AND AFFILIATES UNDER COMMON
CONTROL, IS WILLING TO LICENSE THE SOFTWARE TO YOU ONLY UPON
THE CONDITION THAT YOU ACCEPT ALL OF THE TERMS
CONTAINED IN THIS BINARY CODE LICENSE AGREEMENT AND
SUPPLEMENTAL LICENSE TERMS (COLLECTIVELY "AGREEMENT").
PLEASE READ THE AGREEMENT CAREFULLY. BY SELECTING THE "ACCEPT
LICENSE AGREEMENT" (OR THE EQUIVALENT) BUTTON
AND/OR BY USING THE SOFTWARE YOU ACKNOWLEDGE THAT YOU HAVE READ
THE TERMS AND AGREE TO THEM. IF YOU ARE
AGREEING TO THESE TERMS ON BEHALF OF A COMPANY OR OTHER LEGAL
ENTITY, YOU REPRESENT THAT YOU HAVE THE LEGAL
AUTHORITY TO BIND THE LEGAL ENTITY TO THESE TERMS. IF YOU DO
NOT HAVE SUCH AUTHORITY, OR IF YOU DO NOT WISH TO BE
BOUND BY THE TERMS, THEN SELECT THE "DECLINE LICENSE
AGREEMENT" (OR THE EQUIVALENT) BUTTON AND YOU MUST NOT USE
THE SOFTWARE ON THIS SITE OR ANY OTHER MEDIA ON WHICH THE
FAST/TOOLS T&C of OSS 1

Terms and Conditions of Open Source Software Licenses and applicable programs
SOFTWARE IS CONTAINED.
1. DEFINITIONS. "Software" means the software identified above
in binary form that you selected for download, install or use
(in the version You
selected for download, install or use) from Oracle or its
authorized licensees, any other machine readable materials
(including, but not limited to,
libraries, source files, header files, and data files), any
updates or error corrections provided by Oracle, and any user
manuals, programming guides
and other documentation provided to you by Oracle under this
Agreement. "General Purpose Desktop Computers and Servers"
means computers,
including desktop and laptop computers, or servers, used for
general computing functions under end user control (such as
but not specifically limited
to email, general purpose Internet browsing, and office suite
productivity tools). The use of Software in systems and
solutions that provide dedicated
functionality (other than as mentioned above) or designed for
use in embedded or function-specific software applications,
for example but not limited
to: Software embedded in or bundled with industrial control
systems, wireless mobile telephones, wireless handheld
devices, kiosks, TV/STB, Blu-ray
Disc devices, telematics and network control switching
equipment, printers and storage management systems, and other
related systems are
excluded from this definition and not licensed under this
Agreement. "Programs" means (a) Java technology applets and
applications intended to run
on the Java Platform, Standard Edition platform on Java-
enabled General Purpose Desktop Computers and Servers; and (b)
JavaFX technology
applications intended to run on the JavaFX Runtime on JavaFX-
enabled General Purpose Desktop Computers and Servers.
“Commercial Features”
means those features identified in Table 1-1 (Commercial
Features In Java SE Product Editions) of the Java SE
documentation accessible at
http://www.oracle.com/technetwork/java/javase/documentation/
index.html. “README File” means the README file for the
Software accessible at
index.html.
2. LICENSE TO USE. Subject to the terms and conditions of this
Agreement including, but not limited to, the Java Technology
Restrictions of the
Supplemental License Terms, Oracle grants you a non-exclusive,
non-transferable, limited license without license fees to
reproduce and use
2 FAST/TOOLS T&C of OSS

Licenses and applicable programs Terms and Conditions of Open Source Software
internally the Software complete and unmodified for the sole

purpose of running Programs. THE LICENSE SET FORTH IN THIS
SECTION 2 DOES
NOT EXTEND TO THE COMMERCIAL FEATURES. YOUR RIGHTS AND
OBLIGATIONS RELATED TO THE COMMERCIAL FEATURES ARE AS
SET FORTH IN THE SUPPLEMENTAL TERMS ALONG WITH ADDITIONAL
LICENSES FOR DEVELOPERS AND PUBLISHERS.
3. RESTRICTIONS. Software is copyrighted. Title to Software
and all associated intellectual property rights is retained by
Oracle and/or its licensors.
Unless enforcement is prohibited by applicable law, you may
not modify, decompile, or reverse engineer Software. You
acknowledge that the
Software is developed for general use in a variety of
information management applications; it is not developed or
intended for use in any inherently
dangerous applications, including applications that may create
a risk of personal injury. If you use the Software in dangerous
applications, then you
shall be responsible to take all appropriate fail-safe,
backup, redundancy, and other measures to ensure its safe use.
Oracle disclaims any express or
implied warranty of fitness for such uses. No right, title or
interest in or to any trademark, service mark, logo or trade
name of Oracle or its licensors is
granted under this Agreement. Additional restrictions for
developers and/or publishers licenses are set forth in the
Supplemental License Terms.
4. DISCLAIMER OF WARRANTY. THE SOFTWARE IS PROVIDED "AS IS"
WITHOUT WARRANTY OF ANY KIND. ORACLE FURTHER
DISCLAIMS ALL WARRANTIES, EXPRESS AND IMPLIED, INCLUDING
WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
NONINFRINGEMENT.
5. LIMITATION OF LIABILITY. IN NO EVENT SHALL ORACLE BE LIABLE
FOR ANY INDIRECT, INCIDENTAL, SPECIAL, PUNITIVE OR
CONSEQUENTIAL DAMAGES, OR DAMAGES FOR LOSS OF PROFITS,
REVENUE, DATA OR DATA USE, INCURRED BY YOU OR ANY THIRD
PARTY, WHETHER IN AN ACTION IN CONTRACT OR TORT, EVEN IF ORACLE
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES. ORACLE'S ENTIRE LIABILITY FOR DAMAGES HEREUNDER SHALL
IN NO EVENT EXCEED ONE THOUSAND DOLLARS (U.S.
$1,000).
6. TERMINATION. This Agreement is effective until terminated.
You may terminate this Agreement at any time by destroying all
copies of Software.
This Agreement will terminate immediately without notice from
Oracle if you fail to comply with any provision of this
Agreement. Either party may

terminate this Agreement immediately should any Software

become, or in either party's opinion be likely to become, the
subject of a claim of
infringement of any intellectual property right. Upon
termination, you must destroy all copies of Software.
7. EXPORT REGULATIONS. You agree that U.S. export control laws
and other applicable export and import laws govern your use of
the Software,
including technical data; additional information can be found
on Oracle's Global Trade Compliance web site (http://
www.oracle.com/us/products
/export). You agree that neither the Software nor any direct
product thereof will be exported, directly, or indirectly, in
violation of these laws, or will be
used for any purpose prohibited by these laws including,
without limitation, nuclear, chemical, or biological weapons
proliferation.
8. TRADEMARKS AND LOGOS. You acknowledge and agree as between
you
and Oracle that Oracle owns the ORACLE and JAVA trademarks and
all ORACLE- and JAVA-related trademarks, service marks, logos
and other
brand
designations ("Oracle Marks"), and you agree to comply with
the Third
Party Usage Guidelines for Oracle Trademarks currently located
at
http://www.oracle.com/us/legal/third-party-trademarks/
index.html . Any use you make of the Oracle Marks inures to
Oracle's benefit.
9. U.S. GOVERNMENT LICENSE RIGHTS. If Software is being
acquired by or on behalf of the U.S. Government or by a U.S.
Government prime
contractor or subcontractor (at any tier), then the
Government's rights in Software and accompanying documentation
shall be only those set forth in
this Agreement.
10. GOVERNING LAW. This agreement is governed by the
substantive and procedural laws of California. You and Oracle
agree to submit to the
exclusive jurisdiction of, and venue in, the courts of San
Francisco, or Santa Clara counties in California in any
dispute arising out of or relating to this
agreement.
11. SEVERABILITY. If any provision of this Agreement is held
to be unenforceable, this Agreement will remain in effect with
the provision omitted,
unless omission would frustrate the intent of the parties, in
which case this Agreement will immediately terminate.

12. INTEGRATION. This Agreement is the entire agreement

between you and Oracle relating to its subject matter. It
supersedes all prior or
contemporaneous oral or written communications, proposals,
representations and warranties and prevails over any
conflicting or additional terms of
any quote, order, acknowledgment, or other communication
between the parties relating to its subject matter during the
term of this Agreement. No
modification of this Agreement will be binding, unless in
writing and signed by an authorized representative of each
party.
SUPPLEMENTAL LICENSE TERMS
These Supplemental License Terms add to or modify the terms of
the Binary Code License Agreement. Capitalized terms not
defined in these
Supplemental Terms shall have the same meanings ascribed to
them in the Binary Code License Agreement. These Supplemental
Terms shall
supersede any inconsistent or conflicting terms in the Binary
Code License Agreement, or in any license contained within the
Software.
A. COMMERCIAL FEATURES. You may not use the Commercial
Features for running Programs, Java applets or applications in
your internal
business operations or for any commercial or production
purpose, or for any purpose other than as set forth in Sections
B, C, D and E of these Supplemental Terms. If You want to use
the Commercial Features for any purpose other than as
permitted in this Agreement, You must obtain a
separate license from Oracle.
B. SOFTWARE INTERNAL USE FOR DEVELOPMENT LICENSE GRANT.
Subject to the terms and conditions of this Agreement and
restrictions
and exceptions set forth in the README File incorporated
herein by reference, including, but not limited to the Java
Technology Restrictions of these
Supplemental Terms, Oracle grants you a non-exclusive, non-
transferable, limited license without fees to reproduce
internally and use internally the
Software complete and unmodified for the purpose of designing,
developing, and testing your Programs.
C. LICENSE TO DISTRIBUTE SOFTWARE. Subject to the terms and
conditions of this Agreement and restrictions and exceptions
set forth in the
README File, including, but not limited to the Java Technology
Restrictions and Limitations on Redistribution of these
Supplemental Terms, Oracle
grants you a non-exclusive, non-transferable, limited license
without fees to reproduce and distribute the Software,
provided that (i) you distribute the

Software complete and unmodified and only bundled as part of,

and for the sole purpose of running, your Programs, (ii) the
Programs add significant
and primary functionality to the Software, (iii) you do not
distribute additional software intended to replace any
component(s) of the Software, (iv) you
do not remove or alter any proprietary legends or notices
contained in the Software, (v) you only distribute the
Software subject to a license
agreement that: (a) is a complete, unmodified reproduction of
this Agreement; or (b) protects Oracle's interests consistent
with the terms contained in
this Agreement and that includes the notice set forth in
Section H, and (vi) you agree to defend and indemnify Oracle
and its licensors from and
against any damages, costs, liabilities, settlement amounts
and/or expenses (including attorneys' fees) incurred in
connection with any claim, lawsuit
or action by any third party that arises or results from the
use or distribution of any and all Programs and/or Software.
The license set forth in this
Section C does not extend to the Software identified in Section
G.
D. LICENSE TO DISTRIBUTE REDISTRIBUTABLES. Subject to the
terms and conditions of this Agreement and restrictions and
exceptions set forth
in the README File, including but not limited to the Java
Technology Restrictions and Limitations on Redistribution of
these Supplemental Terms,
Oracle grants you a non-exclusive, non-transferable, limited
license without fees to reproduce and distribute those files
specifically identified as
redistributable in the README File ("Redistributables")
provided that: (i) you distribute the Redistributables
complete and unmodified, and only
bundled as part of Programs, (ii) the Programs add significant
and primary functionality to the Redistributables, (iii) you
do not distribute additional
software intended to supersede any component(s) of the
Redistributables (unless otherwise specified in the applicable
README File), (iv) you do not
remove or alter any proprietary legends or notices contained
in or on the Redistributables, (v) you only distribute the
Redistributables pursuant to a
license agreement that: (a) is a complete, unmodified
reproduction of this Agreement; or (b) protects Oracle's
interests consistent with the terms
contained in the Agreement and includes the notice set forth
in Section H, (vi) you agree to defend and indemnify Oracle
and its licensors from and
against any damages, costs, liabilities, settlement amounts

and/or expenses (including attorneys' fees) incurred in

connection with any claim, lawsuit
or action by any third party that arises or results from the
use or distribution of any and all Programs and/or Software.
The license set forth in this
Section D does not extend to the Software identified in Section
G.
E. DISTRIBUTION BY PUBLISHERS. This section pertains to your
distribution of the JavaTM SE Development Kit Software (“JDK”)
with your printed
book or magazine (as those terms are commonly used in the
industry) relating to Java technology ("Publication"). Subject
to and conditioned upon
your compliance with the restrictions and obligations
contained in the Agreement, Oracle hereby grants to you a non-
exclusive, nontransferable
limited right to reproduce complete and unmodified copies of
the JDK on electronic media (the "Media") for the sole purpose
of inclusion and
distribution with your Publication(s), subject to the
following terms: (i) You may not distribute the JDK on a stand-
alone basis; it must be distributed
with your Publication(s); (ii) You are responsible for
downloading the JDK from the applicable Oracle web site; (iii)
You must refer to the JDK as
JavaTM SE Development Kit; (iv) The JDK must be reproduced in
its entirety and without any modification whatsoever
(including with respect to all
proprietary notices) and distributed with your Publication
subject to a license agreement that is a complete, unmodified
reproduction of this
Agreement; (v) The Media label shall include the following
information: “Copyright [YEAR], Oracle America, Inc. All
rights reserved. Use is subject to
license terms. ORACLE and JAVA trademarks and all ORACLE- and
JAVA-related trademarks, service marks, logos and other brand
designations
are trademarks or registered trademarks of Oracle in the U.S.
and other countries.” [YEAR] is the year of Oracle's release
of the Software; the year
information can typically be found in the Software’s “About”
box or screen. This information must be placed on the Media
label in such a manner as to
only apply to the JDK; (vi) You must clearly identify the JDK
as Oracle's product on the Media holder or Media label, and
you may not state or imply
that Oracle is responsible for any third-party software
contained on the Media; (vii) You may not include any third
party software on the Media which is
intended to be a replacement or substitute for the JDK; (viii)
You agree to defend and indemnify Oracle and its licensors from

and against any

damages, costs, liabilities, settlement amounts and/or
expenses (including attorneys' fees) incurred in connection
with any claim, lawsuit or action by
any third party that arises or results from the use or
distribution of the JDK and/or the Publication; ; and (ix) You
shall provide Oracle with a written
notice for each Publication; such notice shall include the
following information: (1) title of Publication, (2)
author(s), (3) date of Publication, and (4)
ISBN or ISSN numbers. Such notice shall be sent to Oracle
America, Inc., 500 Oracle Parkway, Redwood Shores, California
94065 U.S.A , Attention:
General Counsel.
F. JAVA TECHNOLOGY RESTRICTIONS. You may not create, modify,
or change the behavior of, or authorize your licensees to
create, modify, or
change the behavior of, classes, interfaces, or subpackages
that are in any way identified as "java", "javax", "sun",
“oracle” or similar convention as
specified by Oracle in any naming convention designation.
G. LIMITATIONS ON REDISTRIBUTION. You may not redistribute or
otherwise transfer patches, bug fixes or updates made
available by Oracle
through Oracle Premier Support, including those made available
under Oracle's Java SE Support program.
H. COMMERCIAL FEATURES NOTICE. For purpose of complying with
Supplemental Term Section C.(v)(b) and D.(v)(b), your license
agreement
shall include the following notice, where the notice is
displayed in a manner that anyone using the Software will see
the notice:
Use of the Commercial Features for any commercial or
production purpose requires a separate license from Oracle.
“Commercial Features” means
those features identified Table 1-1 (Commercial Features In
Java SE Product Editions) of the Java SE documentation
accessible at
index.html
I. SOURCE CODE. Software may contain source code that, unless
expressly licensed for other purposes, is provided solely for
reference purposes
pursuant to the terms of this Agreement. Source code may not
be redistributed unless expressly provided for in this
Agreement.
J. THIRD PARTY CODE. Additional copyright notices and license
terms applicable to portions of the Software are set forth in
the
THIRDPARTYLICENSEREADME file accessible at http://

www.oracle.com/technetwork/java/javase/documentation/
index.html. In addition to any terms
and conditions of any third party opensource/freeware license
identified in the THIRDPARTYLICENSEREADME file, the disclaimer
of warranty and
limitation of liability provisions in paragraphs 4 and 5 of
the Binary Code License Agreement shall apply to all Software
in this distribution.
K. TERMINATION FOR INFRINGEMENT. Either party may terminate
this Agreement immediately should any Software become, or in
either party's
opinion be likely to become, the subject of a claim of
infringement of any intellectual property right.
L. INSTALLATION AND AUTO-UPDATE. The Software's installation
and auto-update processes transmit a limited amount of data to
Oracle (or its
service provider) about those specific processes to help
Oracle understand and optimize them. Oracle does not associate
the data with personally
identifiable information. You can find more information about
the data Oracle collects as a result of your Software download
at http://www.oracle.com
/technetwork/java/javase/documentation/index.html.
For inquiries please contact: Oracle America, Inc., 500 Oracle
Parkway,
Redwood Shores, California 94065, USA.
Last updated 02 April 2013
1.2.2 GNU GPL (GNU General Public License)

• Java HotSpot(tm) 64-Bit Server VM 25.112-b15
GNU GENERAL PUBLIC LICENSE

Version 2, June 1991
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
Everyone is permitted to copy and distribute verbatim copies

of this license document, but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General

Public License is intended to guarantee your freedom to share

and change free software--to make sure the software is free
for all its users. This General Public License applies to
most of the Free Software Foundation's software and to any
other program whose authors commit to using it. (Some other
Free Software Foundation software is covered by the GNU
Lesser General Public License instead.) You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom,
not price. Our General Public Licenses are designed to make
sure that you have the freedom to distribute copies of free
software (and charge for this service if you wish), that you
receive source code or can get it if you want it, that you
can change the software or use pieces of it in new free
programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that
forbid anyone to deny you these rights or to ask you to
surrender the rights. These restrictions translate to certain
responsibilities for you if you distribute copies of the
software, or if you modify it.
For example, if you distribute copies of such a program,
whether gratis or for a fee, you must give the recipients all
the rights that you have. You must make sure that they, too,
receive or can get the source code. And you must show them
these terms so they know their rights.
We protect your rights with two steps: (1) copyright the
software, and (2) offer you this license which gives you
legal permission to copy, distribute and/or modify the
software.
Also, for each author's protection and ours, we want to make
certain that everyone understands that there is no warranty
for this free software. If the software is modified by
someone else and passed on, we want its recipients to know
that what they have is not the original, so that any problems
introduced by others will not reflect on the original
authors' reputations.
Finally, any free program is threatened constantly by
software patents. We wish to avoid the danger that
redistributors of a free program will individually obtain
patent licenses, in effect making the program proprietary. To
prevent this, we have made it clear that any patent must be
licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution
and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND

MODIFICATION
0. This License applies to any program or other work which
contains a notice placed by the copyright holder saying it
may be distributed under the terms of this General Public
License. The "Program", below, refers to any such program or
work, and a "work based on the Program" means either the
Program or any derivative work under copyright law: that is
to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into
another language. (Hereinafter, translation is included
without limitation in the term "modification".) Each licensee
is addressed as "you".
Activities other than copying, distribution and modification
are not covered by this License; they are outside its scope.
The act of running the Program is not restricted, and the
output from the Program is covered only if its contents
constitute a work based on the Program (independent of having
been made by running the Program). Whether that is true
depends on what the Program does.
1. You may copy and distribute verbatim copies of the
Program's source code as you receive it, in any medium,
provided that you conspicuously and appropriately publish on
each copy an appropriate copyright notice and disclaimer of
warranty; keep intact all the notices that refer to this
License and to the absence of any warranty; and give any
other recipients of the Program a copy of this License along
with the Program.
You may charge a fee for the physical act of transferring a
copy, and you may at your option offer warranty protection in
exchange for a fee.
2. You may modify your copy or copies of the Program or any
portion of it, thus forming a work based on the Program, and
copy and distribute such modifications or work under the
terms of Section 1 above, provided that you also meet all of
these conditions:
a) You must cause the modified files to carry prominent
notices stating that you changed the files and the date
of any change.
b) You must cause any work that you distribute or

publish, that in whole or in part contains or is derived
from the Program or any part thereof, to be licensed as
a whole at no charge to all third parties under the
terms of this License.

c) If the modified program normally reads commands

interactively when run, you must cause it, when started
running for such interactive use in the most ordinary
way, to print or display an announcement including an
appropriate copyright notice and a notice that there is
no warranty (or else, saying that you provide a
warranty) and that users may redistribute the program
under these conditions, and telling the user how to view
a copy of this License. (Exception: if the Program
itself is interactive but does not normally print such
an announcement, your work based on the Program is not
required to print an announcement.)
These requirements apply to the modified work as a whole. If

identifiable sections of that work are not derived from the
Program, and can be reasonably considered independent and
separate works in themselves, then this License, and its
terms, do not apply to those sections when you distribute
them as separate works. But when you distribute the same
sections as part of a whole which is a work based on the
Program, the distribution of the whole must be on the terms
of this License, whose permissions for other licensees extend
to the entire whole, and thus to each and every part
regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or
contest your rights to work written entirely by you; rather,
the intent is to exercise the right to control the
distribution of derivative or collective works based on the
Program.
In addition, mere aggregation of another work not based on
the Program with the Program (or with a work based on the
Program) on a volume of a storage or distribution medium does
not bring the other work under the scope of this License.
3. You may copy and distribute the Program (or a work based
on it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you
also do one of the following:
a) Accompany it with the complete corresponding
machine-readable source code, which must be distributed
under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
b) Accompany it with a written offer, valid for at least

three years, to give any third party, for a charge no
more than your cost of physically performing source

distribution, a complete machine-readable copy of the

corresponding source code, to be distributed under the
terms of Sections 1 and 2 above on a medium customarily
used for software interchange; or,
c) Accompany it with the information you received as to

the offer to distribute corresponding source code.
(This alternative is allowed only for noncommercial
distribution and only if you received the program in
object code or executable form with such an offer, in
accord with Subsection b above.)
The source code for a work means the preferred form of the
work for making modifications to it. For an executable work,
complete source code means all the source code for all
modules it contains, plus any associated interface definition
files, plus the scripts used to control compilation and
installation of the executable. However, as a special
exception, the source code distributed need not include
anything that is normally distributed (in either source or
binary form) with the major components (compiler, kernel, and
so on) of the operating system on which the executable runs,
unless that component itself accompanies the executable.
If distribution of executable or object code is made by
offering access to copy from a designated place, then
offering equivalent access to copy the source code from the
same place counts as distribution of the source code, even
though third parties are not compelled to copy the source
along with the object code.
4. You may not copy, modify, sublicense, or distribute the
Program except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense or distribute
the Program is void, and will automatically terminate your
rights under this License. However, parties who have received
copies, or rights, from you under this License will not have
their licenses terminated so long as such parties remain in
full compliance.
5. You are not required to accept this License, since you
have not signed it. However, nothing else grants you
permission to modify or distribute the Program or its
derivative works. These actions are prohibited by law if you
do not accept this License. Therefore, by modifying or
distributing the Program (or any work based on the Program),
you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or
modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based
on the Program), the recipient automatically receives a
license from the original licensor to copy, distribute or
modify the Program subject to these terms and conditions. You
may not impose any further restrictions on the recipients'
exercise of the rights granted herein. You are not
responsible for enforcing compliance by third parties to this
License.
7. If, as a consequence of a court judgment or allegation of
patent infringement or for any other reason (not limited to
patent issues), conditions are imposed on you (whether by
court order, agreement or otherwise) that contradict the
conditions of this License, they do not excuse you from the
conditions of this License. If you cannot distribute so as to
satisfy simultaneously your obligations under this License
and any other pertinent obligations, then as a consequence
you may not distribute the Program at all. For example, if a
patent license would not permit royalty-free redistribution
of the Program by all those who receive copies directly or
indirectly through you, then the only way you could satisfy
both it and this License would be to refrain entirely from
distribution of the Program.
If any portion of this section is held invalid or
unenforceable under any particular circumstance, the balance
of the section is intended to apply and the section as a
whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to
infringe any patents or other property right claims or to
contest validity of any such claims; this section has the
sole purpose of protecting the integrity of the free software
distribution system, which is implemented by public license
practices. Many people have made generous contributions to
the wide range of software distributed through that system in
reliance on consistent application of that system; it is up
to the author/donor to decide if he or she is willing to
distribute software through any other system and a licensee
cannot impose that choice.
This section is intended to make thoroughly clear what is
believed to be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is
restricted in certain countries either by patents or by
copyrighted interfaces, the original copyright holder who
places the Program under this License may add an explicit
geographical distribution limitation excluding those
countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License

incorporates the limitation as if written in the body of this

License.
9. The Free Software Foundation may publish revised and/or
new versions of the General Public License from time to time.
Such new versions will be similar in spirit to the present
version, but may differ in detail to address new problems or
concerns.
Each version is given a distinguishing version number. If the
Program specifies a version number of this License which
applies to it and "any later version", you have the option of
following the terms and conditions either of that version or
of any later version published by the Free Software
Foundation. If the Program does not specify a version number
of this License, you may choose any version ever published by
the Free Software Foundation.
10. If you wish to incorporate parts of the Program into
other free programs whose distribution conditions are
different, write to the author to ask for permission. For
software which is copyrighted by the Free Software
Foundation, write to the Free Software Foundation; we
sometimes make exceptions for this. Our decision will be
guided by the two goals of preserving the free status of all
derivatives of our free software and of promoting the sharing
and reuse of software generally.
NO WARRANTY
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS
NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE
COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM
"AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED
TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY
WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED
ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE
PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH

HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF

SUCH DAMAGES.
END OF TERMS AND CONDITIONS
1.2.3 GNU LGPL (GNU Lesser Public License Version 3)
Programs to which this license applies:

• Jexcel 2.6.6
GNU LESSER GENERAL PUBLIC LICENSE

Version 3, 29 June 2007
Copyright © 2007 Free Software Foundation, Inc. <http://
fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
This version of the GNU Lesser General Public License incor-
porates the terms and conditions of version 3 of the GNU Gen-
eral Public License, supplemented by the additional
permissions listed below.
0. Additional Definitions.
As used herein, “this License” refers to version 3 of the GNU
Lesser General Public License, and the “GNU GPL” refers to
version 3 of the GNU General Public License.
“The Library” refers to a covered work governed by this
License, other than an Application or a Combined Work as
defined below.
An “Application” is any work that makes use of an interface
provided by the Library, but which is not otherwise based on
the Library. Defining a subclass of a class defined by the
Library is deemed a mode of using an interface provided by
the Library.
A “Combined Work” is a work produced by combining or linking
an Application with the Library. The particular version of
the Library with which the Combined Work was made is also
called the “Linked Version”.
The “Minimal Corresponding Source” for a Combined Work means
the Corresponding Source for the Combined Work, excluding any
source code for portions of the Combined Work that, consid-
ered in isolation, are based on the Application, and not on
the Linked Version.

The “Corresponding Application Code” for a Combined Work

means the object code and/or source code for the Application,
including any data and utility programs needed for reproduc-
ing the Combined Work from the Application, but excluding the
System Libraries of the Combined Work.
1. Exception to Section 3 of the GNU GPL.
You may convey a covered work under sections 3 and 4 of this
License without being bound by section 3 of the GNU GPL.
2. Conveying Modified Versions.
If you modify a copy of the Library, and, in your modifica-
tions, a facility refers to a function or data to be supplied
by an Application that uses the facility (other than as an
argument passed when the facility is invoked), then you may
convey a copy of the modified version:
• a) under this License, provided that you make a good faith
effort to ensure that, in the event an Application does
not supply the function or data, the facility still oper-
ates, and performs whatever part of its purpose remains
meaningful, or
• b) under the GNU GPL, with none of the additional permis-
sions of this License applicable to that copy.
3. Object Code Incorporating Material from Library Header
Files.
The object code form of an Application may incorporate mate-
rial from a header file that is part of the Library. You may
convey such object code under terms of your choice, provided
that, if the incorporated material is not limited to numeri-
cal parameters, data structure layouts and accessors, or
small macros, inline functions and templates (ten or fewer
lines in length), you do both of the following:
• a) Give prominent notice with each copy of the object code
that the Library is used in it and that the Library and its
use are covered by this License.
• b) Accompany the object code with a copy of the GNU GPL and
this license document.
4. Combined Works.
You may convey a Combined Work under terms of your choice
that, taken together, effectively do not restrict modifica-
tion of the portions of the Library contained in the Combined
Work and reverse engineering for debugging such modifica-
tions, if you also do each of the following:
• a) Give prominent notice with each copy of the Combined
Work that the Library is used in it and that the Library
and its use are covered by this License.
• b) Accompany the Combined Work with a copy of the GNU GPL
and this license document.

• c) For a Combined Work that displays copyright notices

during execution, include the copyright notice for the
Library among these notices, as well as a reference
directing the user to the copies of the GNU GPL and this
license document.
• d) Do one of the following:
–0) Convey the Minimal Corresponding Source under the
terms of this License, and the Corresponding Applica-
tion Code in a form suitable for, and under terms that
permit, the user to recombine or relink the Application
with a modified version of the Linked Version to produce
a modified Combined Work, in the manner specified by
section 6 of the GNU GPL for conveying Corresponding
Source.
–1) Use a suitable shared library mechanism for linking
with the Library. A suitable mechanism is one that (a)
uses at run time a copy of the Library already present
on the user's computer system, and (b) will operate
properly with a modified version of the Library that is
interface-compatible with the Linked Version.
• e) Provide Installation Information, but only if you would
otherwise be required to provide such information under
section 6 of the GNU GPL, and only to the extent that such
information is necessary to install and execute a modified
version of the Combined Work produced by recombining or
relinking the Application with a modified version of the
Linked Version. (If you use option 4d0, the Installation
Information must accompany the Minimal Corresponding
Source and Corresponding Application Code. If you use
option 4d1, you must provide the Installation Information
in the manner specified by section 6 of the GNU GPL for
conveying Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the
Library side by side in a single library together with other
library facilities that are not Applications and are not cov-
ered by this License, and convey such a combined library
under terms of your choice, if you do both of the following:
• a) Accompany the combined library with a copy of the same
work based on the Library, uncombined with any other
library facilities, conveyed under the terms of this
License.
• b) Give prominent notice with the combined library that
part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same
work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new
versions of the GNU Lesser General Public License from time

to time. Such new versions will be similar in spirit to the

present version, but may differ in detail to address new
problems or concerns.
Each version is given a distinguishing version number. If the
Library as you received it specifies that a certain numbered
version of the GNU Lesser General Public License “or any
later version” applies to it, you have the option of follow-
ing the terms and conditions either of that published version
or of any later version published by the Free Software Foun-
dation. If the Library as you received it does not specify a
version number of the GNU Lesser General Public License, you
may choose any version of the GNU Lesser General Public
License ever published by the Free Software Foundation.
If the Library as you received it specifies that a proxy can
decide whether future versions of the GNU Lesser General
Public License shall apply, that proxy's public statement of
acceptance of any version is permanent authorization for you
to choose that version for the Library.
1.2.4 Apache Licence 2.0
• Jetty 9
• Apache commons-logging 1.1.1
• Apache commons-lang 2.3
• Apache commons-httpclient 3.1
• Apache commons-codec 1.3
• Apache commons-cli 1.1
• Apache bsf 2.4.0
• ByteBuffer.js 4.1.0 (https://github.com/dcodeIO/ByteBuffer.js)
• Long.js 2.3.0 (https://www.npmjs.com/package/long)
• Google JSON Simple 1.1.1
(https://code.google.com/p/json-simple/)
• GSON 2.4 (https://github.com/google/gson)
• Google Sfntly (https://code.google.com/p/sfntly/)
• Google Closure Compiler 2.0.26
(https://developers.google.com/closure/)
• sax (https://github.com/ndebeiss/jsXmlSaxParser)
• mbed TLS (https://tls.mbed.org)

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use,

reproduction, and distribution as defined by Sections 1
through 9 of this document.
"Licensor" shall mean the copyright owner or entity

authorized by the copyright owner that is granting the
License.
"Legal Entity" shall mean the union of the acting entity and
all other entities that control, are controlled by, or are
under common control with that entity. For the purposes of
this definition, "control" means (i) the power, direct or
indirect, to cause the direction or management of such
entity, whether by contract or otherwise, or (ii) ownership
of fifty percent (50%) or more of the outstanding shares, or
(iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity

exercising permissions granted by this License.

"Source" form shall mean the preferred form for making

modifications, including but not limited to software source
code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical

transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source

or Object form, made available under the License, as
indicated by a copyright notice that is included in or
attached to the work (an example is provided in the Appendix
below).
"Derivative Works" shall mean any work, whether in Source or

Object form, that is based on (or derived from) the Work and
for which the editorial revisions, annotations, elaborations,
or other modifications represent, as a whole, an original
work of authorship. For the purposes of this License,
Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the
interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including

the original version of the Work and any modifications or
additions to that Work or Derivative Works thereof, that is
intentionally submitted to Licensor for inclusion in the Work
by the copyright owner or by an individual or Legal Entity
authorized to submit on behalf of the copyright owner. For
the purposes of this definition, "submitted" means any form
of electronic, verbal, or written communication sent to the
Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code
control systems, and issue tracking systems that are managed
by, or on behalf of, the Licensor for the purpose of
discussing and improving the Work, but excluding

communication that is conspicuously marked or otherwise

designated in writing by the copyright owner as "Not a
Contribution."
"Contributor" shall mean Licensor and any individual or Legal

Entity on behalf of whom a Contribution has been received by
Licensor and subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and

conditions of this License, each Contributor hereby grants to
You a perpetual, worldwide, non-exclusive, no-charge,
royalty-free, irrevocable copyright license to reproduce,
prepare Derivative Works of, publicly display, publicly
perform, sublicense, and distribute the Work and such
Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and

conditions of this License, each Contributor hereby grants to
You a perpetual, worldwide, non-exclusive, no-charge,
royalty-free, irrevocable (except as stated in this section)
patent license to make, have made, use, offer to sell, sell,
import, and otherwise transfer the Work, where such license
applies only to those patent claims licensable by such
Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their
Contribution(s) with the Work to which such Contribution(s)
was submitted. If You institute patent litigation against any
entity (including a cross-claim or counterclaim in a lawsuit)
alleging that the Work or a Contribution incorporated within
the Work constitutes direct or contributory patent
infringement, then any patent licenses granted to You under
this License for that Work shall terminate as of the date
such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of

the Work or Derivative Works thereof in any medium, with or

without modifications, and in Source or Object form, provided

that You meet the following conditions:
You must give any other recipients of the Work or

Derivative Works a copy of this License; and
You must cause any modified files to carry prominent

notices stating that You changed the files; and
You must retain, in the Source form of any Derivative

Works that You distribute, all copyright, patent, trademark,
and attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
If the Work includes a "NOTICE" text file as part of its

distribution, then any Derivative Works that You distribute
must include a readable copy of the attribution notices
contained within such NOTICE file, excluding those notices
that do not pertain to any part of the Derivative Works, in
at least one of the following places: within a NOTICE text
file distributed as part of the Derivative Works; within the
Source form or documentation, if provided along with the
Derivative Works; or, within a display generated by the
Derivative Works, if and wherever such third-party notices
normally appear. The contents of the NOTICE file are for
informational purposes only and do not modify the License.
You may add Your own attribution notices within Derivative
Works that You distribute, alongside or as an addendum to the
NOTICE text from the Work, provided that such additional
attribution notices cannot be construed as modifying the
License.
You may add Your own copyright statement to Your

modifications and may provide additional or different license
terms and conditions for use, reproduction, or distribution
of Your modifications, or for any such Derivative Works as a
whole, provided Your use, reproduction, and distribution of
the Work otherwise complies with the conditions stated in
this License.

5. Submission of Contributions. Unless You explicitly state

otherwise, any Contribution intentionally submitted for
inclusion in the Work by You to the Licensor shall be under
the terms and conditions of this License, without any
additional terms or conditions. Notwithstanding the above,
nothing herein shall supersede or modify the terms of any
separate license agreement you may have executed with
Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use

the trade names, trademarks, service marks, or product names
of the Licensor, except as required for reasonable and
customary use in describing the origin of the Work and
reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law

or agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
or implied, including, without limitation, any warranties or
conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible
for determining the appropriateness of using or
redistributing the Work and assume any risks associated with
Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal

theory, whether in tort (including negligence), contract, or
otherwise, unless required by applicable law (such as
deliberate and grossly negligent acts) or agreed to in
writing, shall any Contributor be liable to You for damages,
including any direct, indirect, special, incidental, or
consequential damages of any character arising as a result of
this License or out of the use or inability to use the Work
(including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and
all other commercial damages or losses), even if such

Contributor has been advised of the possibility of such

damages.
9. Accepting Warranty or Additional Liability. While

redistributing the Work or Derivative Works thereof, You may
choose to offer, and charge a fee for, acceptance of support,
warranty, indemnity, or other liability obligations and/or
rights consistent with this License. However, in accepting
such obligations, You may act only on Your own behalf and on
Your sole responsibility, not on behalf of any other
Contributor, and only if You agree to indemnify, defend, and
hold each Contributor harmless for any liability incurred by,
or claims asserted against, such Contributor by reason of
your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
1.2.5 BSD (Berkeley Software Distribution license)

• Sprintf-js (https://www.npmjs.com/package/sprintf-js)
• Sprymedia Datatables 1.10.12 (http://datatables.net/)
The 3-Clause BSD License

SPDX short identifier: BSD-3-Clause
Note: This license has also been called the "New BSD License"
or "Modified BSD License". See also the 2-clause BSD License.
Copyright <YEAR> <COPYRIGHT HOLDER>
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:
1. Redistributions of source code must retain the above
copyright notice, this list of conditions and the following
disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials
provided with the distribution.
3. Neither the name of the copyright holder nor the names of

its contributors may be used to endorse or promote products

derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.2.6 MIT
(Massachusetts Institute of Technology License)

• BootStrap 3.3.7 (http://getbootstrap.com/)
• Dygraphs 1.1.1 (http://dygraphs.com/)
• Hammer.js 2.0.8 (http://hammerjs.github.io/)
• JQuery 3.1.1 (https://jquery.org/license/)
• flexdock 0.5.1
• loglevel 1.4.1 (https://www.npmjs.com/package/loglevel)
• hashcode.js 1.0.2 (https://github.com/m3talstorm/hashcode)
• W2ui 1.5.x (http://w2ui.com/web/)
• harmony-collections.js
(https://github.com/Benvie/harmony-collections)
• messageResource.js 1.1
(https://github.com/suhaibkhan/messageResource.js)
• sffjs 1.1 (https://github.com/thorn0/sffjs)
• Normalize.css 3.0.2 (https://necolas.github.io/normalize.css/)
The MIT License

SPDX short identifier: MIT
Copyright <YEAR> <COPYRIGHT HOLDER>

Permission is hereby granted, free of charge, to any person

obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the Software
without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to
whom the Software is furnished to do so, subject to the
following conditions:
The above copyright notice and this permission notice shall
be included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1.2.7 WTFPL License

• nouislider 9.2.0 (https://refreshless.com/nouislider/)
WTFPL-2.0 License
Refer to http://www.wtfpl.net/about/ for full license text.
1.2.8 BOOST Software License

• Boost C++ 1.4.7
Boost Software License

Boost Software License - Version 1.0 - August 17th, 2003
Permission is hereby granted, free of charge, to any person

or organization obtaining a copy of the software and
accompanying documentation covered by this license (the

"Software") to use, reproduce, display, distribute, execute,

and transmit the Software, and to prepare derivative works of
the Software, and to permit third-parties to whom the
Software is furnished to do so, all subject to the following:
The copyright notices in the Software and this entire

statement, including the above license grant, this
restriction and the following disclaimer, must be included in
all copies of the Software, in whole or in part, and all
derivative works of the Software, unless such copies or
derivative works are solely in the form of machine-executable
object code generated by a source language processor.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY

KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE
LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
1.2.9 JDOM License
• JDOM 1.1

JDOM License
Copyright (C) 2000-2012 Jason Hunter & Brett McLaughlin.
All rights reserved.
Redistribution and use in source and binary forms, with or

without modification, are permitted provided that the
following conditions are met:
1. Redistributions of source code must retain the above

copyright notice, this list of conditions, and the following
disclaimer.
2. Redistributions in binary form must reproduce the above

copyright notice, this list of conditions, and the disclaimer
that follows these conditions in the documentation and/or
other materials provided with the distribution.
3. The name "JDOM" must not be used to endorse or promote

products derived from this software without prior written
permission. For written permission, please contact
<request_AT_jdom_DOT_org>.
4. Products derived from this software may not be called

"JDOM", nor may "JDOM" appear in their name, without prior
written permission from the JDOM Project Management
<request_AT_jdom_DOT_org>.
In addition, we request (but do not require) that you include

in the end-user documentation provided with the

redistribution and/or in the software itself an

acknowledgement equivalent to the following:
"This product includes software developed by the JDOM Project

(http://www.jdom.org/)."
Alternatively, the acknowledgment may be graphical using the

logos available at http://www.jdom.org/images/logos.
THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR

IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JDOM
AUTHORS OR THE PROJECT CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT

NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by

many individuals on behalf of the JDOM Project and was
originally created by Jason Hunter <jhunter_AT_jdom_DOT_org>
and Brett McLaughlin <brett_AT_jdom_DOT_org>. For more
information on the JDOM Project, please see <http://
www.jdom.org/>.
1.2.10 Eclipse Public License version 1

• Junit 4.4

Eclipse Public License - v 1.0

THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS
ECLIPSE PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION
OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S
ACCEPTANCE OF THIS AGREEMENT.
1. DEFINITIONS
"Contribution" means:
a) in the case of the initial Contributor, the initial code
and documentation distributed under this Agreement, and
b) in the case of each subsequent Contributor:
i) changes to the Program, and
ii) additions to the Program;
where such changes and/or additions to the Program originate
from and are distributed by that particular Contributor. A
Contribution 'originates' from a Contributor if it was added
to the Program by such Contributor itself or anyone acting on
such Contributor's behalf. Contributions do not include
additions to the Program which: (i) are separate modules of
software distributed in conjunction with the Program under
their own license agreement, and (ii) are not derivative
works of the Program.
"Contributor" means any person or entity that distributes the
Program.
"Licensed Patents" mean patent claims licensable by a
Contributor which are necessarily infringed by the use or
sale of its Contribution alone or when combined with the
Program.
"Program" means the Contributions distributed in accordance
with this Agreement.
"Recipient" means anyone who receives the Program under this
Agreement, including all Contributors.
2. GRANT OF RIGHTS
a) Subject to the terms of this Agreement, each Contributor
hereby grants Recipient a non-exclusive, worldwide, royalty-
free copyright license to reproduce, prepare derivative works
of, publicly display, publicly perform, distribute and
sublicense the Contribution of such Contributor, if any, and
such derivative works, in source code and object code form.
b) Subject to the terms of this Agreement, each Contributor
free patent license under Licensed Patents to make, use,
sell, offer to sell, import and otherwise transfer the
Contribution of such Contributor, if any, in source code and

object code form. This patent license shall apply to the

combination of the Contribution and the Program if, at the
time the Contribution is added by the Contributor, such
addition of the Contribution causes such combination to be
covered by the Licensed Patents. The patent license shall not
apply to any other combinations which include the
Contribution. No hardware per se is licensed hereunder.
c) Recipient understands that although each Contributor
grants the licenses to its Contributions set forth herein, no
assurances are provided by any Contributor that the Program
does not infringe the patent or other intellectual property
rights of any other entity. Each Contributor disclaims any
liability to Recipient for claims brought by any other entity
based on infringement of intellectual property rights or
otherwise. As a condition to exercising the rights and
licenses granted hereunder, each Recipient hereby assumes
sole responsibility to secure any other intellectual property
rights needed, if any. For example, if a third party patent
license is required to allow Recipient to distribute the
Program, it is Recipient's responsibility to acquire that
license before distributing the Program.
d) Each Contributor represents that to its knowledge it has
sufficient copyright rights in its Contribution, if any, to
grant the copyright license set forth in this Agreement.
3. REQUIREMENTS
A Contributor may choose to distribute the Program in object
code form under its own license agreement, provided that:
a) it complies with the terms and conditions of this
Agreement; and
b) its license agreement:
i) effectively disclaims on behalf of all Contributors all
warranties and conditions, express and implied, including
warranties or conditions of title and non-infringement, and
implied warranties or conditions of merchantability and
fitness for a particular purpose;
ii) effectively excludes on behalf of all Contributors all
liability for damages, including direct, indirect, special,
incidental and consequential damages, such as lost profits;
iii) states that any provisions which differ from this
Agreement are offered by that Contributor alone and not by
any other party; and
iv) states that source code for the Program is available from
such Contributor, and informs licensees how to obtain it in a
reasonable manner on or through a medium customarily used for
software exchange.

When the Program is made available in source code form:

a) it must be made available under this Agreement; and
b) a copy of this Agreement must be included with each copy
of the Program.
Contributors may not remove or alter any copyright notices
contained within the Program.
Each Contributor must identify itself as the originator of
its Contribution, if any, in a manner that reasonably allows
subsequent Recipients to identify the originator of the
Contribution.
4. COMMERCIAL DISTRIBUTION
Commercial distributors of software may accept certain
responsibilities with respect to end users, business partners
and the like. While this license is intended to facilitate
the commercial use of the Program, the Contributor who
includes the Program in a commercial product offering should
do so in a manner which does not create potential liability
for other Contributors. Therefore, if a Contributor includes
the Program in a commercial product offering, such
Contributor ("Commercial Contributor") hereby agrees to
defend and indemnify every other Contributor ("Indemnified
Contributor") against any losses, damages and costs
(collectively "Losses") arising from claims, lawsuits and
other legal actions brought by a third party against the
Indemnified Contributor to the extent caused by the acts or
omissions of such Commercial Contributor in connection with
its distribution of the Program in a commercial product
offering. The obligations in this section do not apply to any
claims or Losses relating to any actual or alleged
intellectual property infringement. In order to qualify, an
Indemnified Contributor must: a) promptly notify the
Commercial Contributor in writing of such claim, and b) allow
the Commercial Contributor to control, and cooperate with the
Commercial Contributor in, the defense and any related
settlement negotiations. The Indemnified Contributor may
participate in any such claim at its own expense.
For example, a Contributor might include the Program in a
commercial product offering, Product X. That Contributor is
then a Commercial Contributor. If that Commercial Contributor
then makes performance claims, or offers warranties related
to Product X, those performance claims and warranties are
such Commercial Contributor's responsibility alone. Under
this section, the Commercial Contributor would have to defend
claims against the other Contributors related to those
performance claims and warranties, and if a court requires

any other Contributor to pay any damages as a result, the

Commercial Contributor must pay those damages.
5. NO WARRANTY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM
IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING,
WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE,
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE. Each Recipient is solely responsible for determining
the appropriateness of using and distributing the Program and
assumes all risks associated with its exercise of rights
under this Agreement , including but not limited to the risks
and costs of program errors, compliance with applicable laws,
damage to or loss of data, programs or equipment, and
unavailability or interruption of operations.
6. DISCLAIMER OF LIABILITY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER
RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR
DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS
GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
7. GENERAL
If any provision of this Agreement is invalid or
unenforceable under applicable law, it shall not affect the
validity or enforceability of the remainder of the terms of
this Agreement, and without further action by the parties
hereto, such provision shall be reformed to the minimum
extent necessary to make such provision valid and
enforceable.
If Recipient institutes patent litigation against any entity
(including a cross-claim or counterclaim in a lawsuit)
alleging that the Program itself (excluding combinations of
the Program with other software or hardware) infringes such
Recipient's patent(s), then such Recipient's rights granted
under Section 2(b) shall terminate as of the date such
litigation is filed.
All Recipient's rights under this Agreement shall terminate
if it fails to comply with any of the material terms or
conditions of this Agreement and does not cure such failure
in a reasonable period of time after becoming aware of such
noncompliance. If all Recipient's rights under this Agreement

terminate, Recipient agrees to cease use and distribution of

the Program as soon as reasonably practicable. However,
Recipient's obligations under this Agreement and any licenses
granted by Recipient relating to the Program shall continue
and survive.
Everyone is permitted to copy and distribute copies of this
Agreement, but in order to avoid inconsistency the Agreement
is copyrighted and may only be modified in the following
manner. The Agreement Steward reserves the right to publish
new versions (including revisions) of this Agreement from
time to time. No one other than the Agreement Steward has the
right to modify this Agreement. The Eclipse Foundation is the
initial Agreement Steward. The Eclipse Foundation may assign
the responsibility to serve as the Agreement Steward to a
suitable separate entity. Each new version of the Agreement
will be given a distinguishing version number. The Program
(including Contributions) may always be distributed subject
to the version of the Agreement under which it was received.
In addition, after a new version of the Agreement is
published, Contributor may elect to distribute the Program
(including its Contributions) under the new version. Except
as expressly stated in Sections 2(a) and 2(b) above,
Recipient receives no rights or licenses to the intellectual
property of any Contributor under this Agreement, whether
expressly, by implication, estoppel or otherwise. All rights
in the Program not expressly granted under this Agreement are
reserved.
This Agreement is governed by the laws of the State of New
York and the intellectual property laws of the United States
of America. No party to this Agreement will bring a legal
action under this Agreement more than one year after the
cause of action arose. Each party waives its rights to a jury
trial in any resulting litigation.
1.2.11 Common Public License version 1

• uispec4j 1.5
Common Public License Version 1.0 (CPL)

(NOTE: This license has been superseded by the Eclipse Public

License)
(text)
THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS
COMMON PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR
DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S
ACCEPTANCE OF THIS AGREEMENT.
1. DEFINITIONS
"Contribution" means:
a) in the case of the initial Contributor, the initial code
and documentation distributed under this Agreement, and
b) in the case of each subsequent Contributor:
i) changes to the Program, and
ii) additions to the Program;
where such changes and/or additions to the Program originate
from and are distributed by that particular Contributor. A
Contribution 'originates' from a Contributor if it was added
to the Program by such Contributor itself or anyone acting on
such Contributor's behalf. Contributions do not include
additions to the Program which: (i) are separate modules of
software distributed in conjunction with the Program under
their own license agreement, and (ii) are not derivative
works of the Program.
"Contributor" means any person or entity that distributes the
Program.
"Licensed Patents " mean patent claims licensable by a
Contributor which are necessarily infringed by the use or
sale of its Contribution alone or when combined with the
Program.
"Program" means the Contributions distributed in accordance
with this Agreement.
"Recipient" means anyone who receives the Program under this
Agreement, including all Contributors.
2. GRANT OF RIGHTS
a) Subject to the terms of this Agreement, each Contributor
free copyright license to reproduce, prepare derivative works
of, publicly display, publicly perform, distribute and
sublicense the Contribution of such Contributor, if any, and
such derivative works, in source code and object code form.
b) Subject to the terms of this Agreement, each Contributor
free patent license under Licensed Patents to make, use,
sell, offer to sell, import and otherwise transfer the
Contribution of such Contributor, if any, in source code and
object code form. This patent license shall apply to the
combination of the Contribution and the Program if, at the
time the Contribution is added by the Contributor, such
addition of the Contribution causes such combination to be

covered by the Licensed Patents. The patent license shall not

apply to any other combinations which include the
Contribution. No hardware per se is licensed hereunder.
c) Recipient understands that although each Contributor
grants the licenses to its Contributions set forth herein, no
assurances are provided by any Contributor that the Program
does not infringe the patent or other intellectual property
rights of any other entity. Each Contributor disclaims any
liability to Recipient for claims brought by any other entity
based on infringement of intellectual property rights or
otherwise. As a condition to exercising the rights and
licenses granted hereunder, each Recipient hereby assumes
sole responsibility to secure any other intellectual property
rights needed, if any. For example, if a third party patent
license is required to allow Recipient to distribute the
Program, it is Recipient's responsibility to acquire that
license before distributing the Program.
d) Each Contributor represents that to its knowledge it has
sufficient copyright rights in its Contribution, if any, to
grant the copyright license set forth in this Agreement.
3. REQUIREMENTS
A Contributor may choose to distribute the Program in object
code form under its own license agreement, provided that:
a) it complies with the terms and conditions of this
Agreement; and
b) its license agreement:
i) effectively disclaims on behalf of all Contributors all
warranties and conditions, express and implied, including
warranties or conditions of title and non-infringement, and
implied warranties or conditions of merchantability and
fitness for a particular purpose;
ii) effectively excludes on behalf of all Contributors all
liability for damages, including direct, indirect, special,
incidental and consequential damages, such as lost profits;
iii) states that any provisions which differ from this
Agreement are offered by that Contributor alone and not by
any other party; and
iv) states that source code for the Program is available from
such Contributor, and informs licensees how to obtain it in a
reasonable manner on or through a medium customarily used for
software exchange.
When the Program is made available in source code form:
a) it must be made available under this Agreement; and
b) a copy of this Agreement must be included with each copy
of the Program.
Contributors may not remove or alter any copyright notices
contained within the Program.
Each Contributor must identify itself as the originator of

its Contribution, if any, in a manner that reasonably allows

subsequent Recipients to identify the originator of the
Contribution.
4. COMMERCIAL DISTRIBUTION
Commercial distributors of software may accept certain
responsibilities with respect to end users, business partners
and the like. While this license is intended to facilitate
the commercial use of the Program, the Contributor who
includes the Program in a commercial product offering should
do so in a manner which does not create potential liability
for other Contributors. Therefore, if a Contributor includes
the Program in a commercial product offering, such
Contributor ("Commercial Contributor") hereby agrees to
defend and indemnify every other Contributor ("Indemnified
Contributor") against any losses, damages and costs
(collectively "Losses") arising from claims, lawsuits and
other legal actions brought by a third party against the
Indemnified Contributor to the extent caused by the acts or
omissions of such Commercial Contributor in connection with
its distribution of the Program in a commercial product
offering. The obligations in this section do not apply to any
claims or Losses relating to any actual or alleged
intellectual property infringement. In order to qualify, an
Indemnified Contributor must: a) promptly notify the
Commercial Contributor in writing of such claim, and b) allow
the Commercial Contributor to control, and cooperate with the
Commercial Contributor in, the defense and any related
settlement negotiations. The Indemnified Contributor may
participate in any such claim at its own expense.
For example, a Contributor might include the Program in a
commercial product offering, Product X. That Contributor is
then a Commercial Contributor. If that Commercial Contributor
then makes performance claims, or offers warranties related
to Product X, those performance claims and warranties are
such Commercial Contributor's responsibility alone. Under
this section, the Commercial Contributor would have to defend
claims against the other Contributors related to those
performance claims and warranties, and if a court requires
any other Contributor to pay any damages as a result, the
Commercial Contributor must pay those damages.
5. NO WARRANTY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM
IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR
CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING,
WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE,
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE. Each Recipient is solely responsible for determining
the appropriateness of using and distributing the Program and

assumes all risks associated with its exercise of rights

under this Agreement, including but not limited to the risks
and costs of program errors, compliance with applicable laws,
damage to or loss of data, programs or equipment, and
unavailability or interruption of operations.
6. DISCLAIMER OF LIABILITY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER
RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR
DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS
GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
7. GENERAL
If any provision of this Agreement is invalid or
unenforceable under applicable law, it shall not affect the
validity or enforceability of the remainder of the terms of
this Agreement, and without further action by the parties
hereto, such provision shall be reformed to the minimum
extent necessary to make such provision valid and
enforceable.
If Recipient institutes patent litigation against a
Contributor with respect to a patent applicable to software
(including a cross-claim or counterclaim in a lawsuit), then
any patent licenses granted by that Contributor to such
Recipient under this Agreement shall terminate as of the date
such litigation is filed. In addition, if Recipient
institutes patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the
Program itself (excluding combinations of the Program with
other software or hardware) infringes such Recipient's
patent(s), then such Recipient's rights granted under Section
2(b) shall terminate as of the date such litigation is filed.
All Recipient's rights under this Agreement shall terminate
if it fails to comply with any of the material terms or
conditions of this Agreement and does not cure such failure
in a reasonable period of time after becoming aware of such
noncompliance. If all Recipient's rights under this Agreement
terminate, Recipient agrees to cease use and distribution of
the Program as soon as reasonably practicable. However,
Recipient's obligations under this Agreement and any licenses
granted by Recipient relating to the Program shall continue
and survive.
Everyone is permitted to copy and distribute copies of this
Agreement, but in order to avoid inconsistency the Agreement

is copyrighted and may only be modified in the following

manner. The Agreement Steward reserves the right to publish
new versions (including revisions) of this Agreement from
time to time. No one other than the Agreement Steward has the
right to modify this Agreement. IBM is the initial Agreement
Steward. IBM may assign the responsibility to serve as the
Agreement Steward to a suitable separate entity. Each new
version of the Agreement will be given a distinguishing
version number. The Program (including Contributions) may
always be distributed subject to the version of the Agreement
under which it was received. In addition, after a new version
of the Agreement is published, Contributor may elect to
distribute the Program (including its Contributions) under
the new version. Except as expressly stated in Sections 2(a)
and 2(b) above, Recipient receives no rights or licenses to
the intellectual property of any Contributor under this
Agreement, whether expressly, by implication, estoppel or
otherwise. All rights in the Program not expressly granted
under this Agreement are reserved.
This Agreement is governed by the laws of the State of New
York and the intellectual property laws of the United States
of America. No party to this Agreement will bring a legal
action under this Agreement more than one year after the
cause of action arose. Each party waives its rights to a jury
trial in any resulting litigation.
1.2.12 OpenSSL License

• OpenSSL (http://www.openssl.org/)
OpenSSL License and SSLeay License
LICENSE ISSUES
==============
The OpenSSL toolkit stays under a double license, i.e. both the conditions of
the OpenSSL License and the original SSLeay license apply to the toolkit.
See below for the actual license texts.
OpenSSL License
---------------
/* ====================================================================
* Copyright (c) 1998-2017 The OpenSSL Project. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:

*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. All advertising materials mentioning features or use of this
* software must display the following acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
*
* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be
used to
* endorse or promote products derived from this software without
* prior written permission. For written permission, please contact
* openssl-core@openssl.org.
*
* 5. Products derived from this software may not be called "OpenSSL"
* nor may "OpenSSL" appear in their names without prior written
* permission of the OpenSSL Project.
*
* 6. Redistributions of any form whatsoever must retain the following
* acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit (http://www.openssl.org/)"
*
* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT `ÀS IS'' AND ANY
* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
* ====================================================================
*
* This product includes cryptographic software written by Eric Young
* (eay@cryptsoft.com). This product includes software written by Tim
* Hudson (tjh@cryptsoft.com).
*
*/
Original SSLeay License

-----------------------
/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)

* All rights reserved.
*
* This package is an SSL implementation written
* by Eric Young (eay@cryptsoft.com).
* The implementation was written so as to conform with Netscapes SSL.
*
* This library is free for commercial and non-commercial use as long as
* the following conditions are aheared to. The following conditions
* apply to all code found in this distribution, be it the RC4, RSA,
* lhash, DES, etc., code; not just the SSL code. The SSL documentation
* included with this distribution is covered by the same copyright terms
* except that the holder is Tim Hudson (tjh@cryptsoft.com).
*
* Copyright remains Eric Young's, and as such any Copyright notices in
* the code are not to be removed.
* If this package is used in a product, Eric Young should be given
attribution
* as the author of the parts of the library used.
* This can be in the form of a textual message at program startup or
* in documentation (online or textual) provided with the package.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions

* are met:
* 1. Redistributions of source code must retain the copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. All advertising materials mentioning features or use of this software
* must display the following acknowledgement:
* "This product includes cryptographic software written by
* Eric Young (eay@cryptsoft.com)"
* The word 'cryptographic' can be left out if the rouines from the library
* being used are not cryptographic related :-).
* 4. If you include any Windows specific code (or a derivative thereof)
from
* the apps directory (application code) you must include an
acknowledgement:
* "This product includes software written by Tim Hudson
(tjh@cryptsoft.com)"
*
* THIS SOFTWARE IS PROVIDED BY ERIC YOUNG `ÀS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* The licence and distribution terms for any publically available version or
* derivative of this code cannot be changed. i.e. this code cannot simply be
* copied and put under another distribution licence
* [including the GNU Public Licence.]
*/

End of document


YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction AUDIT/FAST FAST/TOOLS
Manual Programmer’s Guide
IM50H02H00-01EN/R10.03

IM50H02H00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
0.4 Associated documents ...............................................0-2
1 Introduction ..........................................................................1-1
1.1 Interfaces ...................................................................1-1
1.2 Dynamic Data Block (DDB) .....................................1-2
1.2.1 Sequence number ...................................................... 1-2
1.2.2 General info block .................................................... 1-2
1.2.3 Info parts ................................................................... 1-3
2 Notification interface ............................................................2-1
2.1 Introduction ...............................................................2-1
2.2 The interface ..............................................................2-2
2.2.1 Storage process to be addressed ................................ 2-2
2.2.2 Notification modes .................................................... 2-2
2.2.3 Notification options .................................................. 2-3
2.2.4 Notification functions ............................................... 2-4
2.2.5 Event related information ......................................... 2-5
2.2.6 Storage filter indicator .............................................. 2-5
3 Retrieval interface ................................................................3-1
3.1 Introduction ...............................................................3-1
3.2 The interface ..............................................................3-2
3.2.1 Collector process to be addressed ............................. 3-2
3.2.2 Time-out on reply ..................................................... 3-3
3.2.3 Retrieve request parameters block ............................ 3-3
3.2.4 Selection criteria ....................................................... 3-4
3.2.5 Reply ......................................................................... 3-5
4 Distribution interface ...........................................................4-1
4.1 Introduction ...............................................................4-1
4.2 Connecting to AUDIT/FAST ....................................4-2
4.2.1 Process to connect to ................................................. 4-2
4.2.2 Base message id ........................................................ 4-2
4.2.3 Flow control parameters ........................................... 4-3
4.2.4 Information parts ....................................................... 4-4
4.3 Disconnecting from AUDIT/FAST ...........................4-4
4.3.1 Process to disconnect from ....................................... 4-4
AUDIT/FAST Programmer’s Guide iii

Table of Contents
4.3.2 Disconnect options .................................................... 4-5

4.4 Receiving information from AUDIT/FAST ............. 4-5
5 Managing event overviews .................................................. 5-1
5.1 Introduction ............................................................... 5-1
5.2 Overview manager .................................................... 5-1
5.3 Overviews ................................................................. 5-2
6 Reference .............................................................................. 6-1
6.1 General ...................................................................... 6-1
6.2 Conventions .............................................................. 6-1
6.3 Compiling, linking, and running applications ........... 6-2
6.4 Error handling ........................................................... 6-2
6.5 Data Structures .......................................................... 6-3
6.5.1 Introduction ............................................................... 6-3
6.5.2 Event classifier entity table (adt_ece_tb) .................. 6-3
6.5.3 Event classifier entity table pointers (adt_ece_ptr) ... 6-4
6.5.4 Event classifier file entry (adt_ecl) ........................... 6-5
6.5.5 Event classifier code (adt_ecl_code) ......................... 6-5
6.5.6 Event classifier name (adt_ecl_name) ...................... 6-6
6.5.7 General info block (adt_event_gen) .......................... 6-6
6.5.8 Dynamic Data Block (adt_evt) ................................. 6-7
6.5.9 Event key information (adt_evt_key) ....................... 6-9
6.5.10 Flow control data (adt_fc_data) ................................ 6-9
6.5.11 Info parts (adt_info_parts) ...................................... 6-10
6.5.12 Event info part ‘adt_ipev_aif1’ ............................... 6-12
6.5.13 All event info parts (adt_ipev_all) .......................... 6-13
6.5.14 Event info part ‘adt_ipev_ansc’ .............................. 6-13
6.5.15 Event info part ‘adt_ipev_ecls’ ............................... 6-14
6.5.16 Event info part ‘adt_ipev_notm’ ............................. 6-14
6.5.17 Event info part ‘adt_ipev_sbid’ ............................... 6-14
6.5.18 Event info part ‘adt_ipev_onvl’ .............................. 6-15
6.5.19 Event info part ‘adt_ipev_reas’ ............................... 6-15
6.5.20 Event info part ‘adt_ipev_tmus’ ............................. 6-16
6.5.21 Event info part ‘adt_ipev_gdss’ .............................. 6-16
6.5.22 Flow control info part ‘adt_ipfc_lssn’ .................... 6-16
6.5.23 Missing events info part ‘adt_ipms_nrms’ .............. 6-17
6.5.24 Missing events info part ‘adt_ipms_reas’ ............... 6-17
6.5.25 Subject group table (adt_sbg_tb) ............................ 6-18
6.5.26 Overview initialization parameters (adt_ovv_pars) 6-18
6.5.27 Retrieve request parameters block (adt_rev_in) ..... 6-19
6.5.28 Retrieve request line parameters (adt_rev_lin) ....... 6-20
6.5.29 Retrieve reply (adt_rev_out) ................................... 6-21
6.5.30 Selection group file entry (adt_sgp_tot) .................. 6-22
6.5.31 Timestamp (adt_tim_stamp) ................................... 6-23
6.6 Routines and macros ............................................... 6-24
6.6.1 Introduction ............................................................. 6-24
6.6.2 Check selection criteria ........................................... 6-24
iv AUDIT/FAST Programmer’s Guide

Table of Contents
6.6.3 Convert event classifier entities .............................. 6-25

6.6.4 Connect to AUDIT/FAST ....................................... 6-27
6.6.5 Disconnect from AUDIT/FAST ............................. 6-29
6.6.6 Access event classifier entity tables ........................ 6-30
6.6.7 Access to sorted event classifier entity tables ......... 6-31
6.6.8 Load basic set of event classifiers ........................... 6-33
6.6.9 Close event classifier file ........................................ 6-34
6.6.10 Create event classifier file ....................................... 6-35
6.6.11 Delete entry from event classifier file ..................... 6-36
6.6.12 Insert entry in event classifier file ........................... 6-37
6.6.13 Set key for event classifier file ................................ 6-38
6.6.14 Modify entry in event classifier file ........................ 6-39
6.6.15 Open event classifier file ........................................ 6-40
6.6.16 Read entry from event classifier file ....................... 6-41
6.6.17 Perform event notification action ............................ 6-43
6.6.18 Perform event retrieval action ................................. 6-46
6.6.19 Store/retrieve event info parts ................................. 6-49
6.6.20 Store event info parts (macro) ................................. 6-52
6.6.21 Reset and store event info parts (macro) ................. 6-52
6.6.22 Retrieve event info parts (macro) ........................... 6-53
6.6.23 Check if member of basic set of event classifiers ... 6-53
6.6.24 Terminate overview manager ................................. 6-54
6.6.25 Initialize overview manager .................................... 6-55
6.6.26 Browse through overview ....................................... 6-57
6.6.27 Terminate overview ................................................ 6-58
6.6.28 Obtain contents of overview ................................... 6-59
6.6.29 Initialize overview .................................................. 6-61
6.6.30 Get subset of setup file parameters ......................... 6-62
6.6.31 Compile selection expression ................................. 6-64
6.6.32 Close selection group file ........................................ 6-66
6.6.33 Create selection group file ...................................... 6-66
6.6.34 Delete entry from selection group file .................... 6-67
6.6.35 Insert entry in selection group file .......................... 6-68
6.6.36 Lock entry in selection group file ........................... 6-70
6.6.37 Modify entry in selection group file ....................... 6-71
6.6.38 Open selection group file ........................................ 6-72
6.6.39 Read entry from selection group file ...................... 6-73
Appendix A:Example of event notification ..................................A-1
A.1 Introduction ..............................................................A-1
A.2 Example ....................................................................A-1
Appendix B:Example of event retrieval ....................................... B-1
B.1 Introduction .............................................................. B-1
B.2 Example .................................................................... B-1
Appendix C:Distribution interface ...............................................C-1
C.1 Introduction .............................................................. C-1
C.2 Example .................................................................... C-1
AUDIT/FAST Programmer’s Guide v

Table of Contents
Appendix D:Usage of ‘event overview’ routines ......................... D-1

D.1 Introduction .............................................................. D-1
D.2 Example ................................................................... D-1
vi AUDIT/FAST Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives
functionality of AUDIT/FAST from the programmers point of
view.
• To provide experienced users with a reference for the use of several
AUDIT/FAST routines.

This manual is intended for programmers who are familiar with the C
programming language.
The reader of this document is assumed to have a knowledge of the
contents of the following documents (to be read in the indicated order):
• USER/FAST, FAST/TOOLS User Manual (new HMI style),
specifically the part describing the basics of the audit trailing
mechanism from the system managers point of view.
• AUDIT/FAST System Integrator’s Manual.
Furthermore, the reader is assumed to have a knowledge of the contents

of:
• The BUS/FAST message passing facilities.
• The BUS/FAST error logging facility.
• The FAST/CONVENTIONS reference guide volume 1

This manual contains the following chapters:
• Chapter 1 introduces the reader, at a global level, to the main
AUDIT/FAST Programmer’s Guide 0-1

Preface Associated documents
interfaces of AUDIT/FAST.
Furthermore this chapter introduces the reader to the notion
‘Dynamic Data Block’ (DDB) and explains what it is used for.
• Chapter 2 contains a description of the notification interface of
AUDIT/FAST.
• Chapter 3 contains a description of the retrieval interface of
AUDIT/FAST.
• Chapter 4 contains a description of the distribution interface of
AUDIT/FAST.
• Chapter 5 contains a description of a routine set to manage event
overviews.
• Chapter 6 is the reference guide for the AUDIT/FAST routine set.
It contains a description of all data structures and routines that
might be of interest for the application programmer.
• Appendix A contains an example of the usage of the notification
interface.
• Appendix B contains an example of the usage of the retrieval
interface.
• Appendix C contains an example of the usage of the distribution
interface.
• Appendix D contains an example of the usage of the ‘chronological
event overview’ routine set.
0.4 Associated documents

1 FAST/TOOLS User Manual volume 2 (System Management)
This manual provides basic information about the functionality of
AUDIT/FAST.
2 AUDIT/FAST System Integrator’s Manual
This manual provides system integrators with an overview of the
configuration possibilities of AUDIT/FAST.
Furthermore this manual gives a description of the mechanisms that
a system integrator needs to have a knowledge of, to be able to
configure AUDIT/FAST.
3 BUS/FAST Programmer’s Guide, Volumes 1, 2 and 3.
- DUR Programmer’s guide
Provides a description of the standard DUR facilities.
- UMH Programmer’s guide
Provides a description of the standard error logging facilities
which are used.
0-2 AUDIT/FAST Programmer’s Guide

- FSL Programmer’s guide

Provides a description of standard available routines for FAST
software.
4 FAST/CONVENTIONS Reference Guide volume 1.

CONVENTION MEANING
() Parentheses used in routine syntax to
indicate a list of arguments that need to be
passed.
[] Brackets when used in routine syntax
indicates that the enclosed item is optional.
DUR_NOWAIT.
(I) Indicates that the specified parameter is
input.
(M) Indicates that the specified parameter may
have been modified when the routine
returns.
(O) Indicates that the specified parameter is
output.
(R) Indicates that the return value is a routine.
(M)DUR Indicates that the description is valid for
both DUR and MDUR usage.
literally.


n.u. not used.
a terminal.
from the user.

Interfaces Introduction
1 Introduction
1.1 Interfaces
Figure 1-1, depicts from a global point of view, the interfaces of AUDIT/
FAST
A description of the interface with the history manager (history control/
info signals), is beyond the scope of this document. All other interfaces
will be described in the subsequent chapters of this document in the
following order:
history management
notification AUDIT/ retrieval

FAST
distribution
Figure 1-1 The interfaces of AUDIT/FAST
• Notification:
Via this interface, AUDIT/FAST is notified about the occurrence of
events. Furthermore specific information of a previously stored
event, can be modified via this interface.
• Retrieval:
Via this interface, applications are able to retrieve ‘event’ and
‘missing events’ information being stored by AUDIT/FAST.
• Distribution:
Via this interface, ‘event’, ‘missing events’ and ‘flow control’
messages’, can be distributed asynchronously, to other
applications.

Introduction Dynamic Data Block (DDB)
1.2 Dynamic Data Block (DDB)

The mechanism that the notification/distribution/retrieval interfaces
have in common, is the form in which ‘event’, ‘missing events’ and
‘flow control’ information is offered or obtained via these interfaces.
This kind of information is structured in the form of a so called
‘Dynamic Data Block’ (DDB).
A DDB consists of the following basic elements (see Figure 1-2):
• A ‘sequence number’.
• A ‘general info block’.
• A number of ‘info parts’.
sequence nr.
general
info block
info part 1
Dynamic Data Block
info part 2
info part 3
Figure 1-2 Dynamic Data Block
1.2.1 Sequence number
The sequence number is used in the context of the flow control

mechanism (see AUDIT/FAST System Integrator’s Manual) and only
has a meaning for the distribution interface.
1.2.2 General info block
The general info block contains some basic DDB information like
a timestamp, the information type the DDB is related to (one of ‘event’,
‘missing events’ or ‘flow control’ information) and the kind of info parts
being appended to the general info block.

Dynamic Data Block (DDB) Introduction
1.2.3 Info parts
The info parts give additional information type dependent

information, e.g. a “subject identification” in case of the information
type ‘event’. Each information type has its own set of info parts having
a fixed order of appearance in the DDB.
The reference part of this document gives an overview of the info parts
that have been defined for the several information types.
The application interfacing with AUDIT/FAST determines which info

parts it wants to offer (event notification) or wants to receive (event
retrieval, event distribution). Because of this approach, new info parts
can be easily added to the existing set of info parts, without the need to
change or regenerate the application interfacing with AUDIT/FAST.
The info parts are optional ‘information units’, i.e. they need not to be
present in the DDB. However one exception applies to this rule in case
the notification interface is used. In this specific situation the info part
‘event classifier’ needs to be present in the DDB offered to AUDIT/
FAST.

Introduction Dynamic Data Block (DDB)

Introduction Notification interface
2 Notification interface
history management
notificat ion AUDIT/

FAST
retrieval
distribution
2.1 Introduction
Together with ‘retrieval of events’, ‘storage of events’ is one of the
major functions of AUDIT/FAST.
Storage of events that AUDIT/FAST is notified about, is an activity
executed by the AUDIT/FAST storage process. When this process is
notified about the occurrence of an event, it stores information related to
the event in a storage unit (a datafile) of the AUDIT/FAST storage
group.
More information about the storage process and the way in which it
processes event notification actions, can be obtained by consulting the
AUDIT/FAST System Integrator’s Manual.
More information about the kind of event-related-information being
stored by the storage process, can be obtained by consulting the FAST/
TOOLS User Manual volume 2.
In Appendix A of this document, an example is given of a program using
the notification interface of AUDIT/FAST.
The remaining part of this chapter describes how applications should
interface with AUDIT/FAST when they want to notify AUDIT/FAST
about events that they have detected or generated themselves.

Notification interface The interface
2.2 The interface

The interface that applications should use for event notification, is a
routine interface. Once this routine is called and the event classifier of
the event for which this routine is called is active, the routine composes
a BUS/FAST message (event notification message). This message is
sent to the AUDIT/FAST storage process.
The mechanism in the event notification routine that checks whether a
given event classifier is active or not, is called the ‘storage filter’.
The routine that should be called for event notification purposes is:
adt_evt_not().
From a global point of view, an event notification action will look like
this;
...
(event, AUDIT/FAST should be notified about, has
happened)
...
Collect the event related information that must be
stored together with the event.
...
Call adt_evt_not() routine
...
The following subsections introduces some concepts and notions that

are used for the event notification routine.
2.2.1 Storage process to be addressed
When the event notification routine is called, it is possible to specify the

DUR address for the storage process to which the event notification
message should be sent. When this information is not specified, the
routine will assume the process ADTSTO on the same node as where the
application is running.
2.2.2 Notification modes
The event notification routine is able to operate in a number of so called

’notification modes’:

The interface Notification interface
• Direct mode:
In this mode, the routine composes an event notification message
and sends off this message directly (without buffering) to the
storage process.
• Packing mode:
In this mode, the routine composes an event notification message
each time it is called. This message however, is not sent off to the
storage process directly, but buffered internally.
This mode may be useful in situations where a specific action
results in more than one event to be stored. In such a situation,
notification can be done more efficiently by clustering a number of
events into one event notification message.
If the number of events that can be packed in this way is exceeded,
the routine will generate an error. In this situation, the buffered
information is still valid and it is the responsibility of the
application to send off the buffered information by calling the event
notification routine in the so called ‘flush mode’.
The amount of events that can be packed in this mode, is
independent of the amount of info parts being present for the DDB
related to the event.
• Flush mode:
In this mode, the events internally buffered by the event notification
routine, are send off to the storage process.
If an error occurs during this action (e.g. the storage process being
addressed is not active), the internally buffered information is lost.
2.2.3 Notification options
By default, the event notification routine communicates with the storage

process asynchronously, i.e. the event notification routine does not wait
for reply messages. This default behavior has a positive effect on the
performance of an application. On the other hand however, the caller of
the routine is not aware of possible problems that the storage process
may have encountered during the processing of the event notification
message.
As an alternative to this default behavior the following ‘notification
options’ have been defined for the event notification routine:
• Synchronous notification:
By using this option, communication with the storage process is
done synchronously, i.e. the event notification routine waits for the
reply message from the storage process.
This option serves the following purposes:

- By using this option, an application itself is able to detect

whether or not the event is really stored by the storage process.
If the storage process encounters a problem with the
processing of the event notification message and the event
notification routine was not called with the ‘synchronous
notification’ option set, the storage process will log an error
via the UMH standard error logging facilities.
- After the event notification action has successfully been
processed, the storage process returns the DDB as offered to
the event notification routine. The storage process has
completed the DDB in the sense, that it filled up the key
information of the general info block.
This key information might be needed by the application when
the application wants to refer to the same event again (e.g.
modification actions on the contents of the event).
The disadvantage for an application when using this option, is the
degradation of the application’s performance. This is because it has
to wait the entire length of time the storage process needs to process
the event notification message.
The synchronous notification option is only valid in those cases
where the direct mode is selected.
• Multinode confirmation:
By using this option, the application itself is able to detect situations
where the transfer of the event notification message across node
boundaries, fails.
The option is only useful in situations where the node for the
storage process, differs from the node of the application performing
the event notification action.
Be careful; this option only offers the possibility for applications to
detect problems with the transfer (not the processing!) of the event
notification message (e.g. because of a failing DURM connection).
Situations where the storage process fails in processing the event
notification message, will not be detected if only this option is used.
The multinode confirmation option, is only valid in situations
where either the direct or the flush mode is selected.
2.2.4 Notification functions
The event notification routine supports the following so called

’notification functions’:

The interface Notification interface
• Add event:
Add event information. Via this function AUDIT/FAST can be
notified about the occurrence of events.
• Modify event:
Modify event information. This modify action offers the possibility
to change the contents of the ‘modifiable ASCII application info’
field of a previously added event.
2.2.5 Event related information
The actual information that is related to the event must be offered to the
event notification routine in the form of a DDB (Dynamic Data Block,
see Chapter 1).
A more detailed description of the event related information that can be
offered to the event notification routine, can be found in the reference
part of this document.
2.2.6 Storage filter indicator
If the event classifier of an event is not active, the routine will not send
an event notification message to the storage process. In this situation the
event notification routine still returns TRUE. In other words, this
specific situation is not seen as an error situation.
To offer an application the possibility to detect whether or not an event
passes the ‘storage filter’, the event notification routine returns this kind
of information via one of its arguments.


Introduction Retrieval interface
3 Retrieval interface
history management
notification AUDIT/
FAST
retr ieval
distribution
3.1 Introduction
Once event information has been stored, AUDIT/FAST offers the
possibility to retrieve this information via the ‘retrieval’ interface.
Both ‘event’ and ‘missing events’ information can be retrieved via this
interface.
The retrieval action is an activity executed by the AUDIT/FAST
collector process. This process accesses AUDIT/FAST storage group
storage-units (datafiles) to retrieve the required information.
The AUDIT/FAST storage group can be seen as a chain of files,
seamlessly connected to each other. The first element in such a chain
contains the eldest audit trail information available on the system, while
the last element in the chain contains the most recent information.
TOP
STU 1 eldest info
time
STU n most recent info
BOTTOM
Figure 3-1 Graphical representation of AUDIT/FAST storage group

Retrieval interface The interface
More information about the collector process and the way it processes
event retrieval requests, can be obtained by consulting the AUDIT/
FAST System Integrator’s Manual.
In Appendix B of this document, an example is given of a program using
the retrieval interface of AUDIT/FAST.
The remaining part of this chapter describes how applications should
interface with AUDIT/FAST when they want to retrieve information
from AUDIT/FAST.
3.2 The interface

The interface that applications should use for retrieval purposes, is a
routine interface. Once this routine is called, the routine composes a
BUS/FAST message (event retrieval request), sends this message to the
collector process and waits for a reply from the collector process being
addressed.
The routine that should be called for retrieval purposes is:
adt_evt_rtv().
The following subsections will introduce some concepts and notions that
are used for the event retrieval routine.
3.2.1 Collector process to be addressed
When the event retrieval routine is called, it is possible to specify the

DUR address for the collector process to which the event retrieval
request should be sent.
When this information is not specified, the routine will assume it means
that the ADTCOL01 process is running on the same node as the
application.
As described in the AUDIT/FAST System Integrator’s Manual, it is
possible to have several images of one and the same collector executable
active on a node. Although several collector processes might be active
on a node, it is not possible to address each of these collector processes
individually. This is because these collector processes all share the same
receive queue (ADTCOL01) from which the event retrieval requests are
fetched.

The interface Retrieval interface
3.2.2 Time-out on reply
When the event retrieval routine is called, it is possible to specify a time-

out value for the request being issued.
Delayed replies for requests that timed out, are discarded.
3.2.3 Retrieve request parameters block
Some closely related ‘retrieve request’ parameters have been packed

into one parameter block, the so called ‘retrieve request parameters
block’.
This parameter block contains the following information:
• Info part description:
As with the notification interface, the application using this
interface determines the layout of the DDB’s for the information
the application wants to retrieve.
• The number of ‘records’ (DDB’s) to retrieve:
The number of ‘records’ that should be fetched at once, can be
specified in either of two ways:
- Specify the absolute number of ‘records’ to retrieve directly.
- Specify the number of ‘records’ to retrieve indirectly, by
specifying the amount of lines to fill with information.
This option is particular useful in a situation where the event
retrieval request is used to fill up the contents of an overview.
By specifying the amount of lines that should be filled and by
specifying for each information type, the amount of lines being
occupied by one ‘record’ of such an information type, the
collector process is able to determine exactly how many
‘records’ should be returned to the caller of the event retrieval
routine.
• Options:
- TOP:
Return in the reply, via the so called TOP indicator, whether or
not the information returned is the oldest information being
available at the moment the request was processed. This option
only makes sense when a ‘backwards’ read operation is
requested (see option BACK).
The TOP indicator must be interpreted in the context of the
selection criteria possibly specified with the request. In other
words if selection criteria are specified with the request and the
‘TOP’ indicator is set in the reply, the information returned

must be interpreted as: ‘the oldest information available when

the specified selection criteria are applied’.
- BOTTOM:
Return in the reply, via the so called BOTTOM indicator,
whether or not the information returned is the most recent
information available at the moment the request was
processed. By setting this option, the collector process does an
attempt to read an extra record (in addition to the records
requested for), to determine if the ‘bottom’ has been reached.
This indicator must be interpreted in the context of the
selection criteria that may be specified with the request.
- EVENTS:
Return information type ‘event’.
- MISSING EVENTS:
Return information type ‘missing events’.
- INCLUDE:
Return the ‘record’ with the specified keyvalue too
- BACK:
When this option is specified, the retrieve action will start at
the top of the previous storage unit, considering the keyvalue
specified with the request. Via this option backward reading in
the AUDIT/FAST storage group can be achieved.
Considering the keyvalue specified with the event retrieval
request, the retrieve action will start at either one of:
• The top of the storage unit containing the keyvalue
specified with the request. This is only true if the first
record read from this storage unit (considering possibly
specified selection criteria), does not contain this
keyvalue, otherwise the following option applies.
• The top of the non-empty storage unit preceding (is older
than) the storage unit containing the keyvalue specified
with the request.
This option applies if the first record read from the
storage unit, the read action otherwise would have been
started, has a keyvalue equal to the specified keyvalue.
• Keyvalue to start reading from.
3.2.4 Selection criteria
With the event retrieval request it is possible to specify certain selection

criteria. These selection criteria should be seen as the compiled version
of an AUDIT/FAST selection expression.

The interface Retrieval interface
The selection criteria apply to ‘event’ information only. Whether or not

‘missing events’ information is returned with an event retrieval request,
depends only on the ‘MISSING EVENTS’ flag possibly specified in the
retrieve request parameters block (see SubSection 3.2.3).
Selection criteria can be obtained in either of two ways:
• Retrieving this information from the selection group definition file.
The required information is obtained via a routine interface, by
specifying the name of an AUDIT/FAST selection group. The
routine interface will retrieve the selection criteria related to the
specified selection group.
• Retrieving this information directly from the routine responsible
for compiling an AUDIT/FAST selection expression.
As a result of calling this routine, the routine compiles a selection
expression and puts the selection criteria produced, in a buffer
specified by the caller of the routine.
For more details concerning the way selection criteria can be obtained,
please consult the reference section of this document.
3.2.5 Reply
Successful execution of the event retrieval action, places the information

being retrieved, in a buffer supplied by the caller of the event retrieval
routine.
Along with other information, this buffer contains:
• The number of ‘records’ returned.
• A DDB for each ‘record’ returned. Each DDB is preceded by a
standard header (struct fmc_elm), describing the length of each
DDB.
For more details concerning the exact layout of the reply, please consult
the reference section of this document.


Introduction Distribution interface
4 Distribution interface
history control/info
signals
notification AUDIT/ retrieval

FAST
dis tribut ion
4.1 Introduction
When AUDIT/FAST is notified about the occurrence of an event, it is
possible to distribute this event information via so called ‘add event
messages’ to other applications.
In a situation where the contents of a previously stored event is changed,
AUDIT/FAST is able to distribute the changed event information via so
called ‘modify event messages’ to other applications.
Applications being interested in an ‘on-line’ copy of (a changed) event
information are enabled to receive this information via the distribution
interface of AUDIT/FAST. However, before they can receive this
information, they have to connect to AUDIT/FAST.
A connected application not only receives (add/modify) ‘event’
messages, but also ‘missing events’ and ‘flow control’ messages.
In most situations the distribution of information, is executed by the

AUDIT/FAST storage process. In some specific situations however, this
distribution task can be executed by the AUDIT/FAST distributor
process.
More information about the storage and distributor process and the way
in which they distribute ‘event’, ‘missing events’ and ‘flow control’
messages, can be obtained by consulting the AUDIT/FAST System
Integrator’s Manual.

Distribution interface Connecting to AUDIT/FAST
Appendix C of this document, contains a C-code fragment, illustrating

how an application could approach the dispatching of messages
distributed by AUDIT/FAST.
The remaining part of this chapter describes:
• How an application should connect to AUDIT/FAST to receive
information via the distribution interface.
• How an application should disconnect from AUDIT/FAST when it
does not want to receive information from AUDIT/FAST anymore.
• Some aspects of receiving information from AUDIT/FAST via the
distribution interface.
4.2 Connecting to AUDIT/FAST

To connect to AUDIT/FAST an application has to use the interface
routine adt_dst_con() (connect routine). Once this routine is called
successfully, the caller of the routine is connected to either the storage
process or the distributor process, depending on the contents of one of
the arguments passed to this routine.
Some of the concepts and notions that are used in relation to the usage
of this routine, will be introduced in the following subsections.
4.2.1 Process to connect to
When the connect routine is called, it is possible to specify the DUR

address of the process to which the caller of the routine wants to be
connected. When this information is not specified, the routine will
assume the caller of the routine wants to connect to the process
ADTSTO on the local node.
4.2.2 Base message id
When an application has successfully connected to AUDIT/FAST, the

application should be prepared to receive one of the following type of
messages:
• ‘Add event’ message
• ‘Modify event’ message
• ‘Missing events’ message

Connecting to AUDIT/FAST Distribution interface
• ‘Flow control’ message

An explanation for each message type can be found in the AUDIT/FAST
System Integrator’s Manual.
Each of these message types has its own message identification
(message code). This message identification is calculated by adding a
fixed message type dependent offset to a so called base message
identification. The base message identification is application dependent
and should be specified when an application wants to connect to
AUDIT/FAST.
The reference section of this document describes the message type
dependent offsets that have been defined for AUDIT/FAST.
4.2.3 Flow control parameters
When an application connects to the process from which it wants to

receive events (either the storage process or the distributor process), it
has to specify so called flow control parameters.
The process to which the application wants to connect will be called the
event generator.
The flow control parameters specified by the connecting application, are
used to determine:
• How many event generator heartbeat ticks should expire between
the sending of two successive flow control messages to this specific
application.
• How many application heartbeat ticks should expire, after the
receipt of the last flow control message, before the connected
application will assume the connection with the event generator is
lost.
The process to which the application wants to connect, determines how
many heartbeat ticks of respectively the event generator and the
connecting application, correspond with the flow control parameters
specified.
The following example illustrates this:
Suppose the calculated ‘tick values’ are respectively ‘Tgx’ (event
generator ticks for application ‘x’) and ‘Tax’ (‘x’ application ticks).
The event generator will send every ‘Tgx’ event generator ticks, a flow
control message to connected application ‘x’.
On the other hand, the application will expect to receive a flow control
message from the event generator every ‘Tax’ application ticks.

Distribution interface Disconnecting from AUDIT/FAST
As a reply on the connect action, the number of application heartbeat

ticks that correspond with the specified flow control parameters, are
returned to the connecting application.
4.2.4 Information parts
Via the connect routine information-parts argument, the layout of the

DDB’s for the several message types can be specified, as mentioned in
section 4.2.2 .
With the connect action, an application is enabled to specify selection

criteria. These selection criteria will apply to event messages (add/
modify event messages) only. The missing events and flow control
messages will be sent to a connected destination unconditionally.
The way in which these selection criteria can be obtained has been
described in 3.2.4.
4.3 Disconnecting from AUDIT/FAST

If an application being connected to AUDIT/FAST, does not want to
receive information via the distribution interface of AUDIT/FAST
anymore, the application has to disconnect itself from AUDIT/FAST.
For this purpose the application has to use the interface routine
adt_dst_dcon() (disconnect routine).
of this routine, will be introduced in the following subsections.
4.3.1 Process to disconnect from
When the disconnect routine is called, it is possible to specify the DUR

address of the AUDIT/FAST process to disconnect from. When this
information is not specified, the routine assumes, the caller of the routine
wants to disconnect from the process ADTSTO on the local node.

Receiving information from AUDIT/FAST Distribution interface
4.3.2 Disconnect options
With the disconnect action it is possible to specify one or a combination

of the following options:
• Synchronous disconnect:
Wait for the disconnecting process to reply. This option might be
useful in situations where the calling process wants to make sure
that the disconnect action has been successfully executed.
• Empty queue selectively:
Remove all messages being present in the queue of the calling
process and sent by the process being disconnected from.
4.4 Receiving information from AUDIT/FAST

Once an application is connected to AUDIT/FAST, it should be
prepared to receive ‘event’, ‘missing events’ and ‘flow control’
messages.
Each of these type of messages has the form of a DDB (see Chapter 1)
preceded by a standard message header (struct fmc_elm).
The number and kind of info parts being present in the DDB for the
several message types, is determined by the application itself by
specifying these info parts when connecting to AUDIT/FAST.

Distribution interface Receiving information from AUDIT/FAST

Introduction Managing event overviews
5 Managing event overviews
5.1 Introduction
Default functionality delivered with AUDIT/FAST is a (TERMINAL/
FAST) chronological event overview, via which events stored by
AUDIT/FAST can be (selectively) retrieved and inspected.
Currently the chronological event overview has been implemented for a
TERMINAL/FAST environment only.
To enable application programmers to implement these type of
overviews for other environments, AUDIT/FAST has a set of routines
(‘event overview’ routines), which enables application programmers to
do so.
In Appendix D of this document, an example is given of a code fragment
illustrating the usage of these ‘event overview’ routines.
The remaining part of this chapter gives a global description of the
routine set and the notions being used in the context of this routine set.
5.2 Overview manager

A program that is using the event overview routine set to manage a
chronological event overview, is called an ‘overview manager’.
The overview manager must perform the following tasks:
• Creation of an ‘environment’ in which the event overview routines
are able to operate.
Creation of such an ‘environment’ is done by calling the routine
adt_omg_ini(). When this routine is called successfully, the
routine returns a pointer to a so called ‘overview manager context
block’. This pointer must be passed to all other event overview
routines.
• Translation of user input (browse commands) into a call to the
appropriate event overview routine.
The routine that should be called for this purpose is mentioned in
Section 5.3.
• Translation of the internal representation of an event overview,
maintained by the event overview routines, into ‘output actions’ to

Managing event overviews Overviews
the environment specific output device.

The routine that should be called for this purpose is mentioned in
Section 5.3.
• Releasing the overview manager context block when the overview
manager wants to terminate.
Releasing the overview manager context block, is done by calling
the routine adt_omg_exi().
5.3 Overviews
Once an overview manager has been initialized and has created an
overview manager context block, the overview manager is able to
activate the chronological event overviews to be managed.
Each overview to be managed is assigned an ‘overview number’. This
overview number is used for reference purposes and must be unique
within the environment of the overview manager. It is the responsibility
of the overview manager, to assign these overview numbers.
The following actions can be performed at the ‘overview level’:
• Initialization of an overview.
Before any other action can be performed on an overview, the
overview manager has to initialize the overview by calling the
routine adt_ovv_ini().
The overview number, assigned to the overview, must be passed to
this routine, along with other information.
• Process browse action for an overview.
The event that represents a certain browse request issued by a user,
must be translated by the overview manager, in a call to the routine
adt_ovv_brw(). An overview number and the required browse
action must be passed to this routine, along with other information.
• Get contents of an overview.
The contents of an overview can be obtained by the overview
manager by calling the routine adt_ovv_get(). The routine will
return a pointer to a data structure in which for each line in the
overview both binary (if applicable) and ASCII information can be
obtained.
Amongst some other information, the overview number must be
passed to this routine.
• Termination of an overview.
To terminated an overview, the routine adt_ovv_exi() has to be

Overviews Managing event overviews
called. A call to this routine, will release all resources allocated by

a certain overview.

Managing event overviews Overviews

General Reference
6 Reference
6.1 General
This chapter serves as a reference for the AUDIT/FAST macros,
interface routines and related structure definitions. This chapter
describes:
• Conventions
• Compiling, linking, and running applications
• Data structures
• Error handling
• Routines and support functions
6.2 Conventions
All ADT routines have ‘C’-type interfaces. The syntax of all routines as
well as the examples comply with ‘C’ language conventions.
In the routine descriptions, a parameter which is not scalar is declared as
a pointer to that parameter.
Note: Unless otherwise stated, the parameter
itself must also be declared!
All parameters which are passed by reference must be assumed to be
modifiable by the routine to which they are passed.
Most of the ADT routines return a TLS_BOOLEAN as the status
indicator. This is shown in the syntax descriptions as [status=].
Example: the syntax of the routine adt_chkcrit():
[status=] adt_chkcrit(umh_c,....)
TLS_BOOLEAN status; /* TRUE if success */

struct ....; /* .... */
....
Normally this return value will be tested directly rather than being

Reference Compiling, linking, and running applications
if (!adt_chkcrit(....))
{
/* error - use UMH context to log the error(s)*/
}
The type TLS_BOOLEAN is defined in the header file global.h (which
is included in tools.h).
The header file adt.h contains all definitions that might be necessary
when calling ADT routines. For this reason, adt.h must always be
included in any source that refers to ADT routines and/or macros.
The names of macros, routines, data structures, and defined constants
being part of ADT, all start with the three letters ‘adt’.
Note: Do not define a routine or variable name in
your application that starts with these
letters.
6.3 Compiling, linking, and running

applications
In order to use ADT routines in your applications, it is necessary to
ensure that the following is true:
• AUDIT/FAST is installed
• adt.h has been included in the source
• the application will be linked with the BUS and ADT libraries (on
Windows linking with the BUS and AUDIT dll’s)
6.4 Error handling

Most of the ADT routines use the standard FAST/TOOLS error
handling facilities provided by UMH.
Details of the UMH error handling facilities can be found in the BUS/
FAST Programmer’s Guide, part UMH.

Data Structures Reference
6.5 Data Structures
6.5.1 Introduction
This section gives a description of the data structures that are important
for the application programmer. The following applies to this
description:
• All data structures are mentioned in alphabetical order.
• All datastructures can be found in the header file ‘adt.h’ unless
indicated otherwise.
6.5.2 Event classifier entity table (adt_ece_tb)
An event classifier entity table contains the relation between a certain

‘event classifier entity name’ and a certain ‘event classifier entity code’.
For each of the entities ‘subject group action’ and ‘subject group action
source’, such an event classifier entity table exists (see also AUDIT/
FAST System Integrator’s Manual).
For the entity ‘subject group attribute’, a table exists for each ‘subject
group’.
The entity ‘subject group’ uses a different type of table to store the
relation between code and name (Subject group table (adt_sbg_tb)).
This is because the table for the entity ‘subject group’, contains
additional information compared to the other type of tables.
One element of the event classifier entity table is described by the
following datastructure:
struct adt_ece_tb
{
char *name; /* [1] */
TLS_ULONG code; /* [2] */
};
Element description:
1 Pointer to null terminated event classifier entity name.
2 Event classifier entity code.

Reference Data Structures
6.5.3 Event classifier entity table pointers (adt_ece_ptr)
The event classifier entity table pointers describe the start addresses of
the ‘subject group’, ‘subject group action’ and ‘subject group action
source’ entity tables.
A pointer to the ‘subject group attribute’ tables, can be obtained by
accessing the ‘subject group’ table, to which the attributes relate.
The event classifier entity table pointers are described by the following
datastructure:
struct adt_ece_ptr
{
TLS_ULONG nr_sbg; /* [1] */
TLS_ULONG nr_sac; /* [2] */
TLS_ULONG nr_sas; /* [3] */
struct adt_sbg_tb *sbg_nm; /* [4] */
struct adt_sbg_tb *sbg_cd; /* [5] */
struct adt_ece_tb *sac_nm; /* [6] */
struct adt_ece_tb *sac_cd; /* [7] */
struct adt_ece_tb *sas_nm; /* [8] */
struct adt_ece_tb *sas_cd; /* [9] */
};
1 Number of entries in ‘subject group’ event classifier entity table.
2 Number of entries in ‘subject group action’ event classifier entity
table.
3 Number of entries in ‘subject group action source’ event classifier
entity table.
4 Pointer to subject group table sorted on name (see remark below).
5 Pointer to subject group table sorted on code (see remark below).
6 Pointer to subject group action table sorted on name (see remark
below).
7 Pointer to subject group action table sorted on code (see remark
below).
8 Pointer to subject group action source table sorted on name (see
remark below).
9 Pointer to subject group action source table sorted on code (see
remark below).
Use the adt_ece_srt()routine to sort the contents of the event
classifier entity tables on name or code, when obtaining the pointers to
the entity tables.
If the routine adt_ece() is used to obtain these pointers (something

that is not recommended), these pointers point directly to the tables as

defined in the routine adt_ece().
6.5.4 Event classifier file entry (adt_ecl)
An event classifier file entry describes the event classifier entity codes/
names that have been combined, to form an event classifier.
Furthermore, an event classifier file entry describes for each event
classifier:
• Whether the event classifier is active/inactive.
• Whether the event classifier is a member of the so called basic set
of event classifiers.
The event classifier file entry is described by the following datastructure
(datastructure to be found in ‘adt_ecl.h’):
struct adt_ecl
{
struct adt_ecl_code ecl_code; /* [1] */
struct adt_ecl_name ecl_name; /* [2] */
struct adt_ecl_code par_ecl_code; /* [3] */
TLS_LONG flags; /* [4] */
};
1 Event classifier code
2 Event classifier name
3 <Future extension>
4 To flag some special situations. The following flags have been
defined:
- ADT_ECL_FLG_BSET
Event classifier is member of basic set.
- ADT_ECL_FLG_ACTV
Event classifier is active.
6.5.5 Event classifier code (adt_ecl_code)
The event classifier code is a combination of 4 integer values, used to

have a unique internal identification for each event classifier.
The event classifier code is described by the following datastructure

struct adt_ecl_code
{
TLS_ULONG sbj_code; /* [1] */
TLS_ULONG attr_code; /* [2] */
TLS_ULONG action_code; /* [3] */
TLS_ULONG act_src_code; /* [4] */
};
1 Internal code for event classifier entity ‘subject group’.
2 Internal code for event classifier entity ‘subject group attribute’.
3 Internal code for event classifier entity ‘subject group action’.
4 Internal code for event classifier entity ‘subject group action
source’.
6.5.6 Event classifier name (adt_ecl_name)
The event classifier name is a combinations of 4 ‘null terminated’

character strings, used to have a unique external identification for each
event classifier.
The event classifier name is described by the following datastructure
struct adt_ecl_name
{
char sbj_name[ADT_ECL_NAME_SZ]; /* [1] */
char attr_name[ADT_ECL_NAME_SZ]; /* [2] */
char action_name[ADT_ECL_NAME_SZ]; /* [3] */
char act_src_name[ADT_ECL_NAME_SZ]; /* [4] */
};
1 Name of event classifier entity ‘subject group’.
2 Name of event classifier entity ‘subject group attribute’.
3 Name of event classifier entity ‘subject group action’.
4 Name of event classifier entity ‘subject group action source’.
6.5.7 General info block (adt_event_gen)
The general info block is one of the building blocks of the so called
Dynamic Data Block (DDB), see SubSection 6.5.8.
A general info block may be followed by zero or more so called info

parts. Which info parts follow the general info block, is described by the
general info block itself.
The general info block is described by the following datastructure:
struct adt_event_gen
{
struct adt_evt_key evt_key; /* [1] */
struct adt_tim_stamp lm_time; /* [2] */
TLS_USHORT info_type; /* [3] */
TLS_SHORT spare1; /* [4] */
TLS_LONG info_parts; /* [5] */
};
1 Event key information.
2 Timestamp of last modification. This field contains the point of
time at which the last modification action was performed on the
information being represented. Currently this field only applies to
the information type ‘event’.
3 Information type. This field contains a value that describes which
information type the DDB applies.
Possible values for this field are:
- ADT_ITYP_EVNT
For information type ‘event’.
- ADT_ITYP_MSIF
For information type ‘missing events’.
- ADT_ITYP_FLCT
For information type ‘flow control’.
4 <Currently not used>
5 Description of info parts that follow the general info block in the
DDB.
6.5.8 Dynamic Data Block (adt_evt)
A Dynamic Data Block (DDB) is the datastructure that is used to

represent ‘event’, ‘missing events’, and ‘flow control’ information.

The DDB is used when actions are performed via the notification/
distribution/retrieval interfaces of AUDIT/FAST.
sequence nr.
general
info block
info part 1
Dynamic Data Block
info part 2
info part 3
Figure 6-1 Dynamic Data Block
The DDB itself is composed of the following building blocks:

• sequence number
• general info block
• information type dependent info parts
The ‘dynamic part’ of the DDB (the info parts) is described in
SubSection 6.5.11.
The ‘fixed part’ of the dynamic data block (sequence number and
general info block) is described by the following datastructure:
struct adt_evt
{
TLS_ULONG seq_nr; /* [1] */
struct adt_event_gen gen_info; /* [2] */
};
1 Sequence number.
This information is only relevant in case the information
represented by the DDB, is obtained via the distribution interface of
AUDIT/FAST (BUS/FAST messages).
An application wanting to receive information via the distribution
interface, has to connect to AUDIT/FAST. The application itself is
responsible for the detection of missing information (information
that does not arrive for any reason).
To support the implementation of this philosophy, the field
‘sequence number’ contains a number that is incremented by one
each time AUDIT/FAST sends event and missing events messages
to the connected application. In case of flow control messages, the
‘sequence number’ field always contains a zero value.
The numbering for the contents of the ‘sequence number’ field

starts at 1. The value 0 (zero) will never be put in the field, in other
words when an application receives a message with sequence
number MAXUNSIGNEDLONG, the next sequence number (for
an event or missing events message) will be 1.
The application “knows” there is something missing if it does not
detect consecutive numbering in this field.
For more information regarding this mechanism, please consult the
AUDIT/FAST System Integrator’s Manual, subject ‘flow control’.
2 General info block, some basic information for the DDB.
6.5.9 Event key information (adt_evt_key)
All information obtained via the interfaces of AUDIT/FAST (‘event’,

‘missing events’ and ‘flow control’ information) is uniquely identified
by a so called event key.
The event key is described by the following datastructure:
struct adt_evt_key
{
struct adt_tim_stamp evt_stamp; /* [1] */
struct adt_tim_stamp lb_stamp; /* [2] */
};
1 Timestamp.
2 <Future extension, currently filled with null values>.
6.5.10 Flow control data (adt_fc_data)
The flow control data describes the flow control parameters for the flow
control mechanism. The flow control parameters need to be specified
when an application connects to AUDIT/FAST.
The flow control data is described by the following datastructure:

struct adt_fc_data
{
TLS_ULONG tf_req; /* [1] */
TLS_ULONG tf_timo; /* [2] */
TLS_ULONG hbt_s; /* [3] */
TLS_ULONG hbt_r; /* [4] */
};
1 Required flow control interval.
Whether or not the required flow control interval is feasible,
depends on the heartbeat of the process to which an application
wants to connect. If the required flow control interval is less than
the heartbeat of this process, a flow control interval equal to this
heartbeat is assumed.
2 Required timeout on flow control interval.
Via the contents of this field, the connecting application can specify
a timeout value on the receipt of a flow control message. The value
in this field will be used for the calculation of the ‘application ticks’
value that correspond with the required flow control interval.
3 Heartbeat of sending process.
For the connect action, the contents of this field is not important.
The field is present in the flow control data structure because this
structure is also used for internal purposes.
4 Heartbeat of receiving process.
To enable the process to which an application connects, to convert
the required flow control interval and a possibly specified timeout
value, to a number of application heartbeat ticks, the connecting
application has to specify its own heartbeat value.
The value of all parameters, are expressed in seconds.
6.5.11 Info parts (adt_info_parts)
When an application uses the distribution and/or retrieval interface of

AUDIT/FAST, the application has to specify which info parts should be
present in the DDB containing the information obtained via these
interfaces.
The specification of these info parts data can be done via the following
datastructure:

struct adt_info_parts
{
TLS_LONG ev_info_parts; /* [1] */
TLS_LONG lb_info_parts; /* [2] */
TLS_LONG ms_info_parts; /* [3] */
TLS_LONG fc_info_parts; /* [4] */
};
1 Info parts for information type ‘event’.
2 <Future extension, fill with 0 value>.
3 Info parts for information type ‘missing events’.
4 Info parts for information type ‘flow control’.
As can be seen in this datastructure, each information type has its own
set of info parts. The following tables describe for each information
type:
• the info parts that have been defined for the information type.
• the structure definitions being related to these info parts.
• the info part flags being related to these info parts.
Information type: ‘event’:

1 Notification time
2 Event classifier
3 Action and notification source
4 Subject identification
5 Terminal and user identification
6 Old and new value
7 ASCII and modifiable ASCII application information
8 Reason information
9 Generic dataset information
Info Struct Info part

part definition flag
1 adt_ipev_notm ADT_IPEV_NOTM_FLG
2 adt_ipev_ecls ADT_IPEV_ECLS_FLG
3 adt_ipev_ansc ADT_IPEV_ANSC_FLG
4 adt_ipev_sbid ADT_IPEV_SBID_FLG
5 adt_ipev_tmus ADT_IPEV_TMUS_FLG

6 adt_ipev_onvl ADT_IPEV_ONVL_FLG
7 adt_ipev_aif1 ADT_IPEV_AIF1_FLG
8 adt_ipev_reas ADT_IPEV_REAS_FLG
9 adt_ipev_gdss ADT_IPEV_GDSS_FLG
Information type: ‘missing events’:

1 Number of missing events
2 Reason flags

1 adt_ipms_nrms ADT_IPMS_NRMS_FLG
2 adt_ipms_reas ADT_IPMS_REAS_FLG
Information type: ‘flow control’:

1 Last sent sequence number

1 adt_ipfc_lssn ADT_IPFC_LSSN_FLG
6.5.12 Event info part ‘adt_ipev_aif1’
This event info part contains the ASCII and modifiable ASCII
application information fields related to an event.
The info part is described by the following datastructure:
struct adt_ipev_aif1
{
char aainf1[ADT_AAINF1_SZ]; /* [1] */
char m_aainf1[ADT_M_AAINF1_SZ]; /* [2] */
};
1 Null terminated ASCII application information field.
2 Null terminated modifiable ASCII application information field.

6.5.13 All event info parts (adt_ipev_all)
A definition of all currently defined event info parts is given by the ‘all
event info parts’ structure.
Be careful, this structure may be extended in the future!
If the structure is extended, new info parts will be appended to the
current set of info parts.
The set of all currently defined event info parts is described by the
following datastructure:
struct adt_ipev_all
{
struct adt_ipev_notm notm; /* [1] */
struct adt_ipev_ecls ecls; /* [2] */
struct adt_ipev_ansc ansc; /* [3] */
struct adt_ipev_sbid sbid; /* [4] */
struct adt_ipev_tmus tmus; /* [5] */
struct adt_ipev_onvl onvl; /* [6] */
struct adt_ipev_aif1 aif1; /* [7] */
struct adt_ipev_reas reas; /* [8] */
};
1 Notification time.
2 Event classifier.
3 Action/Notification source.
4 Subject identification.
5 Terminal/User identification.
6 Old/New value.
7 ASCII/modifiable ASCII application info.
8 Reason info.
6.5.14 Event info part ‘adt_ipev_ansc’
This event info part contains the DUR addresses for the action and
notification sources related to an event.

struct adt_ipev_ansc
{
struct dur_adr a_src; /* [1] */
struct dur_adr n_src; /* [2] */
};
1 DUR address of the action source.
2 DUR address of the notification source.
6.5.15 Event info part ‘adt_ipev_ecls’
This event info part contains the event classifier code related to an event.
struct adt_ipev_ecls
{
struct adt_ecl_code ecls; /* [1] */
};
1 Event classifier code.
6.5.16 Event info part ‘adt_ipev_notm’
This event info part contains the notification time related to an event.
struct adt_ipev_notm
{
struct ftm_time notm; /* [1] */
};
1 Notification time.
6.5.17 Event info part ‘adt_ipev_sbid’
This event info part contains the subject identification related to an

event.

struct adt_ipev_sbid
{
char sbid[ADT_SBJ_DESC_SZ]; /* [1] */
};
1 Null terminated subject identification name.
6.5.18 Event info part ‘adt_ipev_onvl’
This event info part contains the old and new value for the subject group
attribute related to an event.
struct adt_ipev_onvl
{
char oval[ADT_VAL_SZ]; /* [1] */
char nval[ADT_VAL_SZ]; /* [2] */
};
1 Null terminated description of ‘old value’.
2 Null terminated description of ‘new value’.
6.5.19 Event info part ‘adt_ipev_reas’
This event info part contains the ‘reason info’ related to an event.
struct adt_ipev_reas
{
char reason[ADT_REAS_SZ]; /* [1] */
};
1 Null terminated ‘reason info’.

6.5.20 Event info part ‘adt_ipev_tmus’
This event info part contains the terminal and user name related to an
event.
struct adt_ipev_tmus
{
char term[GIN_TERM_NAM_SIZ]; /* [1] */
char user[GIN_MAX_USER_NAME]; /* [2] */
};
1 Null terminated terminal identification.
2 Null terminated user identification.
6.5.21 Event info part ‘adt_ipev_gdss’
This event info part contains the dataset and field name related to an
event.
struct adt_ipev_gdss
{
char ds_nm[DSS_DS_NM_SZ]; /* [1] */
char fld_nm[DSS_FLD_NM_SZ]; /* [2] */
};
1 Null terminated dataset identification.
2 Null terminated field identification.
6.5.22 Flow control info part ‘adt_ipfc_lssn’
This flow control info part contains information about the ‘last sent
sequence number’.

struct adt_ipfc_lssn
{
TLS_ULONG lssn; /* [1] */
};
1 Last sent sequence number.
6.5.23 Missing events info part ‘adt_ipms_nrms’
This missing events info part contains information about the ‘number of
missing events’.
struct adt_ipms_nrms
{
TLS_ULONG nrms; /* [1] */
};
1 Number of missing events.
6.5.24 Missing events info part ‘adt_ipms_reas’
This missing events info part contains information about the ‘reason of
missing events’.
struct adt_ipms_reas
{
TLS_LONG reas; /* [1] */
};
1 Reason flags.
The following reason flags have been defined:
- ADT_MIS_REAS_UE_SNR
Unexpected sequence number.
- ADT_MIS_REAS_CN_LOS
Connection lost.
- ADT_MIS_REAS_QU_OVF
Queue overflow.

6.5.25 Subject group table (adt_sbg_tb)
The subject group table, contains:

• The relation between a subject group name and a subject group
code.
• The number of attributes related to the subject group.
• A pointer to the related subject group attributes.
One element of the subject group table is described by the following
datastructure:
struct adt_sbg_tb
{
char *name; /* [1] */
TLS_ULONG code; /* [2] */
TLS_ULONG nr_attr; /* [3] */
struct adt_ece_tb *satr; /* [4] */
};
1 Pointer to null terminated subject group name.
2 Internal code for subject group.
3 Number of attributes related to this subject group.
4 Pointer to subject group attributes related to this subject group.
6.5.26 Overview initialization parameters (adt_ovv_pars)
The overview initialization parameters describe the parameters that

describe some characteristics of a chronological event overview.
The parameters are described by the following datastructure:
struct adt_ovv_pars
{
TLS_USHORT lin_tot; /* [1] */
TLS_USHORT nr_char_lin; /* [2] */
TLS_USHORT flags; /* [3] */
TLS_USHORT spare[5]; /* [4] */
char sup_file_name[TLS_FSPEC_SZ]; /* [5] */
char sgp_name[ADT_SGP_NAME_SZ]; /* [6] */
struct fmc_elm *sel_crit; /* [7] */
};
1 Total number of lines for the overview.
2 Number of characters per line for the overview.


5 Setup file related to the overview (file name only, no filepath, no
extension).
6 Selection criteria that should be applied to the contents of the
overview.
7 <Future extension, fill with NULL pointer>.
6.5.27 Retrieve request parameters block (adt_rev_in)
The retrieve request parameters block describes the parameters that need
to be supplied for an event retrieval request.
The retrieve request parameters block are described by the following
datastructure:
struct adt_rev_in
{
struct adt_info_parts info_parts; /* [1] */
TLS_SHORT nr_evt; /* [2] */
TLS_SHORT spare1; /* [3] */
struct adt_rev_lin rev_lin; /* [4] */
TLS_LONG options; /* [5] */
struct adt_evt_key evt_key; /* [6] */
};
1 Description of info parts that should be present in the DDB’s of the
information to retrieve.
2 Number of ‘records’ (events/missing events) to retrieve, expressed
in a direct way.
3 <Future extension, fill with 0 value>
4 Number of ‘records’ (events/missing events) to retrieve, expressed
in an indirect way by specifying:
- The number of lines to fill.
- The number of lines an ‘event’ message will occupy in the
overview.
- The number of lines a ‘missing events’ message will occupy in
the overview.
This information is only used, if the ‘nr_evt’ field contains a zero
value.
5 Retrieve option flags. The following retrieve option flags have been
defined:

- ADT_EVT_RTV_OPT_TOP
Give, if applicable, ‘top indicator’ in reply.
- ADT_EVT_RTV_OPT_BOT
Give, if applicable, ‘bottom indicator’ in reply.
- ADT_EVT_RTV_OPT_REV
Return information of information type ‘event’.
- ADT_EVT_RTV_OPT_RMS
Return information of information type ‘missing events’.
- ADT_EVT_RTV_OPT_INC
If present, returns ‘record’ plus specified keyvalue.
- ADT_EVT_RTV_OPT_BACK
Position at ‘previous’ storage unit (considering the specified
keyvalue), then start reading.
6 Key data to start read operation with.
6.5.28 Retrieve request line parameters (adt_rev_lin)
The retrieve request line parameters describe, indirectly, the number of

‘records’ to fetch with an event retrieval request.
Via the retrieve request line parameters, the number of ‘records’ to fetch
can be expressed by specifying:
• The total number of lines for the overview, to fill with information.
• The number of lines one ‘event’ and one ‘missing events’ message
will occupy in the overview.
The retrieve request line parameters are described by the following
datastructure:
struct adt_rev_lin
{
TLS_USHORT line_to_fill; /* [1] */
TLS_USHORT line_evt; /* [2] */
TLS_USHORT line_mis; /* [3] */
TLS_USHORT spare1[5]; /* [4] */
};
1 Number of lines (of the overview) to fill.
2 Number of lines an ‘event’ message will occupy in the overview.
3 Number of lines a ‘missing events’ message will occupy in the
overview.
4 <Future extension, fill with 0 values>

6.5.29 Retrieve reply (adt_rev_out)
From a global point of view, the retrieve reply describes:

• The number of ‘records’ being returned on a retrieve request.
• The ‘records’ returned on the retrieve request.
The retrieve reply is described by the following datastructure:
struct adt_rev_out
{
TLS_SHORT nr_evt; /* [1] */
TLS_SHORT lines_filled; /* [2] */
TLS_LONG options; /* [3] */
TLS_LONG info[1]; /* [4] */
};
1 Number of ‘records’ being present in the reply.
2 Number of lines in the overview that can be filled with the number
of ‘records’ returned. This information can be supplied only, if the
request contains information about the number of lines that are to
be filled for the overview.
3 Reply option flags. The following reply option flags have been
defined:
The reply contains the eldest information being available at the
moment the request was processed.
The reply contains the most recent information currently
available at the moment the request was processed.
The reply contains at least one event ‘record’.
The reply contains at least one missing events ‘record’.
A ‘record’ with a keyvalue as specified in the request, is also
present in the reply.
Started retrieve action at the top of the ‘previous’ storage unit.
4 Start of ‘records’ retrieved. Each such ‘record’ consists of a DDB
preceded by a standard header. The definition of this header is
given by the structure ‘fmc_elm’.
The ‘size’ field of this header, describes the total amount of bytes
occupied by the header itself (‘size’ and ‘code’ fields) and the size
of the DDB following the header. The code field of the header has

currently no specific meaning.

The next figure (Figure 6-2), gives a graphical representation of the
layout of the retrieve reply.
adt_rev_out fmc_elm adt_evt
nr. of events
nr. of lines filled
size
options code
size body sequence nr.
code general
info block
dynamic data block 1 info part 1
size
info part 2
code
etc.
Figure 6-2 Layout of reply on event retrieval request
6.5.30 Selection group file entry (adt_sgp_tot)
A selection group file entry describes:

• the relation between a selection group and the source and list files
that are related to it.
• whether the selection group is valid (successfully compiled).
• the compiled version of the selection expression that is related to
the selection group.
The selection group file entry is described by the following datastructure
(datastructure to be found in ‘adt_sgp.h’):

struct adt_sgp_tot
{
char sel_grp_name[ADT_SGP_NAME_SZ]; /* [1] */
TLS_USHORT seq_nr; /* [2] */
TLS_SHORT flags; /* [3] */
char src_file[TLS_FSPEC_SZ]; /* [4] */
char list_file[TLS_FSPEC_SZ]; /* [5] */
TLS_UBYTE pfx_info[ADT_TOT_PFX_SZ]; /* [6] */
};
1 Null terminated selection group name.
2 Sequence number of this entry. This information is for internal use
only and has no meaning for the programmer’s interface.
3 To flag some special situations. The following flags have been
defined:
- ADT_SGP_FLG_VALID
The selection expression currently related to this selection
group, has been positively validated (compiled without
errors).
4 Source file name (including filepath and extension). This file
contains the selection expression being related to the selection
group.
5 List file name (including filepath and extension). This file contains
the listing being generated during compilation of the selection
expression, being present in the source file.
6 Start of compiled version of selection expression (the so called
postfix expression).
6.5.31 Timestamp (adt_tim_stamp)
A timestamp for ‘event’, ‘missing events’ and ‘flow control’

information is composed of a number of seconds and milliseconds since
1970 and a sequence number to have a unique timestamp for events
occurring at the “same time”.
The timestamp is described by the following datastructure:

Reference Routines and macros
struct adt_tim_stamp
{
TLS_ULONG sec; /* [1] */
TLS_USHORT msec; /* [2] */
TLS_USHORT seq_nr; /* [3] */
};
1 Number of seconds since 1970.
2 Number of milliseconds (in addition to the contents of the ‘sec’
field).
3 Sequence number, to create a unique timestamp for events
happening at the same point of time.
6.6 Routines and macros
6.6.1 Introduction
In this section the ADT routine and macro set is described.

For each routine a description is given of the following:
• Syntax.
• Parameters.
• Semantics.
• Summary of the most important error codes that may be returned by
it.
• Other ADT routines that are related to it.
The routines and macros are mentioned in alphabetical order.
6.6.2 Check selection criteria
Syntax [status=] adt_chkcrit(umh_c, evt_gen, pfx, match)
Arguments TLS_BOOLEAN status; /* TRUE if success */

struct umh_context *umh_c; /* UMH context block */
struct adt_event_gen *evt_gen;/* Event to check */
struct fmc_elm *pfx; /* Selection criteria */
int *match; /* Match indicator */
Semantics This routine is used to check whether or not an event matches certain
AUDIT/FAST selection criteria.

Routines and macros Reference
Argument umh_c is the pointer to the UMH context obtained via a call
to either the dur_umh_init() or the umh_res_msg() routine.
Argument evt_gen is the pointer to the general info block of the event
that is to be checked against the selection criteria.
Argument pfx is the pointer to the selection criteria to be used for the
check. Selection criteria can be obtained in either of two ways:
• via the selection expression compilation routine adt_pstfix().
• by retrieving the selection criteria from the selection group
definition file via the routine adt_sgp_read().
The selection criteria information obtained in this way, can simply be
cast to the datatype of the argument pfx.
Argument match is the pointer to a variable in which the result of the
selection criteria check is stored. If the event does not match with the
selection criteria specified, this variable will contain the value 0,
otherwise the value 1 will be stored in this variable.
Notes • If the status indicator of the routine returns FALSE, the contents of
the variable the argument match is pointing to, is unpredictable.
Errors • ADTT_E_CHKCRIT
General error, returned in case an internal problem with the routine
occurred. The real cause of the problem is indicated by a deeper
nested error.
• ADTT_E_IT_EVT_ONLY
Function performs operation for information type ‘event’ only.
Related routines • adt_pstfix()

Compile selection expression.
• adt_sgp_read()
Read entry from selection group file.
6.6.3 Convert event classifier entities
Syntax [status=] adt_cnv_ece(umh_c, ecl_code, ecl_name, fnc)

struct adt_ecl_code *ecl_code;/* Code(s) to convert */
struct adt_ecl_name *ecl_name;/* Result of conversion */
int fnc; /* Function */

Semantics This routine is used to convert event classifier entity codes to the
corresponding event classifier entity names and vice versa.
The type of conversion wanted (‘code to name’ or ‘name to code’) can
be indicated via the argument fnc.
It is not necessary to supply all event classifier entity codes/names for a
conversion action. If the caller of the routine is not interested in the
conversion of a certain event classifier entity code or name, the value 0
(for code) or an empty string (for name) can be supplied for the event
classifier entity in question.
It is not possible to convert the ‘subject group attribute’ as a stand-alone
entity. In a situation when a ‘subject group attribute’ needs to be
converted, the ‘subject group code or name’ must also be supplied.
Event classifier entities not being converted, will have a ‘?’ character
(code to name conversion) or 0 value (name to code conversion) in the
result.
Argument ecl_code is a pointer to a piece of memory in which either:
• the event classifier entity codes to convert are stored
• the result of a name to code conversion is stored
Argument ecl_name is a pointer to a piece of memory in which either:
• the event classifier entity names to convert are stored
• the result of a code to name conversion is stored
Argument fnc specifies which type of conversion needs to be
performed. Via this argument one of the following values can be passed
to this routine:
• ADT_CNV_ECE_FNC_TO_NAME
For a conversion from code to name.
• ADT_CNV_ECE_FNC_TO_CODE
For a conversion from name to code.
Notes • The ‘convert event classifier entities’ routine, uses the event
classifier entity tables defined in the routine ‘adt_ece’, to perform
the required conversion actions.
Errors • ADT_E_UNK_SBG_CD
Unknown subject group code encountered (‘<code>’).
• ADT_E_UNK_SAT_CD
Unknown subject group attribute code encountered (‘<code>’).

• ADT_E_UNK_SAC_CD
Unknown subject group action code encountered (‘<code>’).
• ADT_E_UNK_SAS_CD
Unknown subject group action source code encountered
(‘<code>’).
• ADT_E_UNK_SBG_NM
Unknown subject group name encountered (‘<name>’).
• ADT_E_UNK_SAT_NM
Unknown subject group attribute name encountered (‘<name>’).
• ADT_E_UNK_SAC_NM
Unknown subject group action name encountered (‘<name>’).
• ADT_E_UNK_SAS_NM
Unknown subject group action source name encountered
(‘<name>’).
• ADT_E_ECE_SRT
Error occurred during attempt to create the sorted event classifier
entity tables.
Related routines • none
6.6.4 Connect to AUDIT/FAST
Syntax [status=] adt_dst_con(umh_c, proc, timo, bmsg_id, flags,

fc_data, info_parts, sel_crit,
fc_ticks)

struct dur_adr *proc; /* Process addressed */
int timo; /* Timeout on reply */
int bmsg_id; /* Base message id. */
TLS_LONG flags; /* Future extension */
struct adt_fc_data *fc_data; /* Flow control data */
struct adt_info_parts *info_parts;
/* Info parts */
struct fmc_elm *sel_crit; /* Selection criteria */
TLS_ULONG *fc_ticks; /* Flow control ticks */
Semantics This routine is used to connect an application to AUDIT/FAST. Once an
application is connected, the application should be prepared to receive

the message types listed in the table below. This table also lists the
message codes that will be used for a certain type of message.
Message type Message id.
add event base message id. + ADT_OFS_ADD_EVT

modify event base message id. + ADT_OFS_MOD_EVT
missing events base message id. + ADT_OFS_MIS_EVT
flow control base message id. + ADT_OFS_FLW_CTL
Argument proc describes the DUR-address of the AUDIT/FAST
process to which the application wants to connect. If a NULL pointer is
passed for this argument, the application will be connected to the process
ADTSTO on the application’s node.
Argument timo describes the timeout value for the reply on the connect
request. Specifying a zero value, means ‘wait forever’.
Argument bmsg_id describes the base message identification for the
connecting application. All messages sent by AUDIT/FAST to the
application, will have a message code relative to this base message
identification value.
Argument flags is currently not used by the routine. To be upwards
compatible with future releases, it is recommended to pass a 0 value for
this argument.
Argument fc_data describes the flow control parameters the
application wants to use. The fields ‘required flow control interval’,
‘timeout value’ and ‘heartbeat receiver’ are only relevant in this context.
Argument info_parts describes which info parts should be present in
the message types listed in the previous table. From this point of view,
the message types ‘add event message’ and ‘modify event message’, can
be seen as the same type of message (event message), having exactly the
same layout.
Argument sel_crit describes the selection criteria the application
possibly wants to use. These selection criteria apply to ‘event messages’
(add/modify event messages) only.
When an application specifies selection criteria, only ‘event messages’
matching the specified selection criteria will be sent to the connected
application.

If a NULL pointer is passed for this argument, no selection criteria

apply. The layout of the datablock the argument is possibly pointing to,
is hidden for the caller of this routine. The datablock describing the
selection criteria can be obtained in either of two ways:
cast to the datatype of the argument sel_crit.
Via the argument fc_ticks the number of ‘application ticks’ that
correspond with the specified flow control parameters, is returned to the
caller of the routine. The value returned, can be used by the application
to determine how many application ticks should pass, before the
application should expect the next flow control message to arrive.
Each time the flow control message arrives, the application should reset
its own flow control ticks counter. However if the flow control message
does not come in time, the application should assume it has no
connection, with the process it wants to be connected to, anymore.
Notes • none
Errors • ADT_E_CON_ATTEMPT
nested error.
Related routines • adt_pstfix()

Compile selection expression.
• adt_sgp_read()
• adt_dst_dcon()
Disconnect from AUDIT/FAST.
6.6.5 Disconnect from AUDIT/FAST
Syntax [status=] adt_dst_dcon(umh_c, proc, options)

TLS_LONG options; /* Options flags */

Semantics This routine is used to disconnect an application from AUDIT/FAST. It

is the responsibility of the caller of this routine to address the same
process as the process specified for the connect action.
Argument proc describes the DUR-address of the AUDIT/FAST
process from which the application wants to disconnect. If a NULL
pointer is passed for this argument, the process ADTSTO on the
application’s node will be addressed.
Argument options describes several options that can be activated for
the disconnect action. If none of these options should be activated, this
argument should contain the value 0.
The following flags have been defined for this argument:
• ADT_DST_DCON_FLG_SYNC
Do the disconnect action synchronously, in other words wait for the
reply from the process disconnecting from.
• ADT_DST_DCON_FLG_QEMP
Remove those messages from the caller queue that have been sent
by the process being disconnected from.
Notes • none
Errors • ADT_E_DCN_ATTEMPT
nested error.
Related routines • adt_dst_con()

Connect to AUDIT/FAST.
6.6.6 Access event classifier entity tables
Syntax [status=] adt_ece(umh_c, ece_ptr)

struct adt_ece_ptr *ece_ptr; /* Pointers to event
classifier entity
tables */
Semantics This routine is used to obtain the addresses of the original event
classifier entity tables as defined by Yokogawa. These event classifier

entity tables may have been extended by your System Integrator

(therefor the routine is delivered in source).
It is not recommended however, to use the contents of these original
tables directly. It is strongly advised to use the addresses returned by the
routine adt_ece_srt(). This is because:
• the adt_ece_srt() routine performs some elementary checks on
the contents of the original event classifier entity tables, before it
create and returns pointers to its own version of these tables
• the adt_ece_srt() routine creates sorted versions of the several
event classifier entity tables.
Argument ece_ptr is a pointer to a datastructure in which the routine
stores the addresses of the original event classifier entity tables.
Notes • The addresses of the several subject group attribute entity tables can
only be obtained by accessing the table of the related subject group
entity table.
Errors • none
Related routines • adt_ece_srt()

Access to sorted event classifier entity tables.
Related routines 6.6.7 Access to sorted event classifier entity tables
Syntax [status=] adt_ece_srt(umh_c, srt_ece_ptr, options)

struct adt_ece_ptr *srt_ece_ptr;
/* Pointers to sorted
event classifier entity
tables */
TLS_ULONG options; /* Options */
Semantics This routine is used to obtain pointers to checked, normalized and sorted
versions of the event classifier entity tables as defined in the routine
adt_ece(). The following checks/normalization actions are performed
on the contents of the original event classifier entity tables:
• Convert event classifier entity names to uppercase characters.
• Check if length of event classifier entity name is less or equal to
ADT_ECL_NAME_SZ.

• Check if length of event classifier entity name is greater than zero

(no empty string).
• Check if event classifier entity name is unique within the table.
• Check if event classifier entity code is not equal to 0.
• Check if code is unique within the table.
The routine is able to create both a set of event classifier entity tables
sorted on name and a set of event classifier entity tables sorted on code.
Argument srt_ece_ptr is a pointer to a datastructure in which the
adt_ece_srt() routine stores the pointers to the sorted versions of the
event classifier entity tables.
In this datastructure, a set of pointers exists for the event classifier entity
tables sorted on name (‘sbg_nm’, ‘sac_nm’ and ‘sas_nm’), and a set of
pointers exists for the event classifier entity tables sorted on code
(‘sbg_cd’, ‘sac_cd’ and ‘sas_cd’).
Argument options describes the options that can be activated for this
routine.
• ADT_ECE_SRT_FLG_NM
Create event classifier entity tables sorted on name.
• ADT_ECE_SRT_FLG_CD
Create event classifier entity tables sorted on code.
Notes • The addresses of the several ‘subject group attribute’ entity tables
can only be obtained by accessing the table of the related ‘subject
group’ entity table.
Errors • ADT_E_ECE_SRT
nested error.
• ADT_E_NUL_ECE_TAB
Found null pointer for one or more of the event classifier entity
tables.
• ADT_E_ECE_NM_SZ
Maximum allowed length (<max_length>) for event classifier
entity ‘<name>’ exceeded (table type: ‘<event classifier entity table
type>’

• ADT_E_ECE_NM_EMPT
Encountered empty string for event classifier entity (table type:
‘<event classifier entity table type>’
• ADT_E_ECE_NM_NUNQ
Non-unique event classifier entity name encountered (name:
‘<name>’, table type: ‘<event classifier entity table type>’)
• ADT_E_ECE_CD_NULL
Zero value encountered for event classifier entity code related to the
event classifier entity ‘<name>’ (table type: ‘<event classifier
entity table type>’)
Related routines • adt_ece()

Access event classifier entity tables.
6.6.8 Load basic set of event classifiers
Syntax [status=] adt_ecl_bset(umh_c, fp)

struct isf_file_info *fp; /* File pointer */
Semantics This routine is used to load the basic set of event classifiers into the event
classifier file. If a certain event classifier is already present in the event
classifier file, the entry concerned remains untouched (active/not active
indicator is not changed).
Argument fp is the file pointer of the event classifier file.
Notes • none
Errors • Errors returned by routine adt_cnv_ece().

• Errors returned by routine adt_ecl_ins() except for error
ADT_E_ECL_DUP.
Related routines • adt_ecl_clo()

Close event classifier file.
• adt_ecl_crea()
Create event classifier file.

• adt_ecl_del()
Delete entry from event classifier file.
• adt_ecl_ins()
Insert entry in event classifier file.
• adt_ecl_key()
Set key for event classifier file.
• adt_ecl_mod()
Modify entry in event classifier file.
• adt_ecl_ope()
Open event classifier file.
• adt_ecl_read()
Read entry from event classifier file.
• adt_mmb_bset()
Check if member of basic set of event classifiers.
6.6.9 Close event classifier file
Syntax [status=] adt_ecl_clo(umh_c, fp)

Semantics This routine is used to close the event classifier file.

Argument fp is the file pointer for the event classifier file.
Notes • none
Errors • ADT_E_CLO_ECL_FIL
nested error.
Related routines • adt_ecl_bset()

Load basic set of event classifiers.
• adt_ecl_crea()
• adt_ecl_del()

• adt_ecl_ins()
• adt_ecl_key()
• adt_ecl_mod()
• adt_ecl_ope()
• adt_ecl_read()
• adt_mmb_bset()
6.6.10 Create event classifier file
Syntax [status=] adt_ecl_crea(umh_c, node)

int node; /* Node number */
Semantics This routine is used to create the event classifier file on the specified
node. After the file has been created, it is closed immediately.
The name of the event classifier file being created, is determined by the
#define ADT_ECL_FILE_SP.
Argument node is the number of the node on which the file should be
created.
Notes • none
Errors • ADT_E_CRE_ECL_FIL
nested error.

• adt_ecl_clo()

• adt_ecl_del()
• adt_ecl_ins()
• adt_ecl_key()
• adt_ecl_mod()
• adt_ecl_ope()
• adt_ecl_read()
• adt_mmb_bset()
6.6.11 Delete entry from event classifier file
Syntax [status=] adt_ecl_del(umh_c, fp, ecl_rec)

struct adt_ecl *ecl_rec; /* Entry to delete */
Semantics This routine is used to delete an entry from the event classifier file. The
value of the event classifier code determines which entry will be deleted.
Argument ecl_rec is the entry to delete. Only the event classifier code
is relevant information in the context of this routine.
Notes • none
Errors • Errors returned by isf_delete() routine.

• adt_ecl_clo()
• adt_ecl_crea()

• adt_ecl_ins()
• adt_ecl_key()
• adt_ecl_mod()
• adt_ecl_ope()
• adt_ecl_read()
• adt_mmb_bset()
6.6.12 Insert entry in event classifier file
Syntax [status=] adt_ecl_ins(umh_c, fp, ecl_rec)

struct adt_ecl *ecl_rec; /* Entry to insert */
Semantics This routine is used to insert an entry into the event classifier file.
Argument ecl_rec is the entry to insert. Both the event classifier code
and event classifier name field, should contain unique information.
Notes • none
Errors • Errors returned by routine isf_write() except for error

ISF_E_DUPKEY. This error is replaced by ADT_E_ECL_DUP
(see below), to obtain an error text related to event classifiers.
• ADT_E_ECL_DUP
Event classifier already defined.


• adt_ecl_clo()
• adt_ecl_crea()
• adt_ecl_del()
• adt_ecl_key()
• adt_ecl_mod()
• adt_ecl_ope()
• adt_ecl_read()
• adt_mmb_bset()
6.6.13 Set key for event classifier file
Syntax [status=] adt_ecl_key(umh_c, fp, key_nr)

int key_nr; /* Key to set */
Semantics This routine is used to set the key to be used for subsequent read
operations (routine adt_ecl_read()) on the event classifier file.
Two types of key exist for the event classifier file:
• Event classifier name.
• Event classifier code.
Argument key_nr describes the code for the key to be set. This
argument should contain one of the following values:
• ADT_ECL_KEYS_ECL_CODE:
For key event classifier code.
• ADT_ECL_KEYS_ECL_NAME:
For key event classifier name.

Notes • none
Errors • ADT_E_KEY_ECL_FIL
Error occurred during an attempt to set the key for the event
classifier file. The exact cause of the error is indicated by a deeper
nested error.

• adt_ecl_clo()
• adt_ecl_crea()
• adt_ecl_del()
• adt_ecl_ins()
• adt_ecl_mod()
• adt_ecl_ope()
• adt_ecl_read()
• adt_mmb_bset()
6.6.14 Modify entry in event classifier file
Syntax [status=] adt_ecl_mod(umh_c, fp, ecl_rec)

struct adt_ecl *ecl_rec; /* Entry to modify */
Semantics This routine is used to modify an entry in the event classifier file. The
value of the event classifier code, determines which entry will be
modified.

Argument ecl_rec describes the entry to be modified.

Notes • none
Errors • Errors returned by routine isf_rewrite().

• adt_ecl_clo()
• adt_ecl_crea()
• adt_ecl_del()
• adt_ecl_ins()
• adt_ecl_key()
• adt_ecl_ope()
• adt_ecl_read()
• adt_mmb_bset()
6.6.15 Open event classifier file
Syntax [fp =] adt_ecl_ope(umh_c, node, mode, timo)
Arguments struct isf_file_info *fp; /* File pointer */

int mode; /* Open mode */
TLS_ULONG timo; /* Timeout */
Semantics This routine is used to open an event classifier file on a specific node.
Argument node describes the node on which the file must be opened.
Argument mode describes the ‘open mode’. This argument is passed
directly to the isf_uopen() routine. For a description of the possible

‘open modes’ please consult the DATABASE/FAST Programmer’s

Guide.
Argument timo describes the timeout value for the ‘open’ action. This
timeout only applies in case the file is opened on a remote node. The
timeout value must be specified in seconds. A timeout value of zero
means: ‘wait forever’.
Notes • On successful completion, the routine returns a file pointer. If an
error occurs during the open action, the routine returns a NULL
pointer.
Errors • ADT_E_OPE_ECL_FIL
Error occurred during an attempt to open the event classifier file.

• adt_ecl_clo()
• adt_ecl_crea()
• adt_ecl_del()
• adt_ecl_ins()
• adt_ecl_key()
• adt_ecl_mod()
• adt_ecl_read()
• adt_mmb_bset()
6.6.16 Read entry from event classifier file
Syntax [status=] adt_ecl_read(umh_c, fp, ecl_rec, read_mode)

struct adt_ecl *ecl_rec; /* Entry to read or
entry read */
int read_mode; /* Read mode */

Semantics This routine is used to read an entry from the event classifier file.
The key that will be used for the read action, is determined by
information passed to the adt_ecl_key() routine, the last time this
routine was called.
Prior to the call of this routine, argument ecl_rec should describe the
keyvalue to be used for the read operation. The contents of the other
fields in this argument are not important prior to the call of this routine.
After the routine has been successfully called, the argument ecl_rec
contains the entry being read.
The argument read_mode describes the type of read action to be
performed. This argument is passed directly to the isf_read() routine.
For a description of the possible ‘read modes’ please consult the
DATABASE/FAST Programmer’s Guide.
Notes • none
Errors • Errors returned by routine isf_read() except for error

ISF_E_NOREC. This error is replaced by ADT_E_ECL_NO_EXI
(see below), to obtain an error text related to event classifiers.
• ADT_ECL_NO_EXI
Event classifier does not exist.

• adt_ecl_clo()
• adt_ecl_crea()
• adt_ecl_del()
• adt_ecl_ins()
• adt_ecl_key()
• adt_ecl_mod()
• adt_ecl_ope()

• adt_mmb_bset()
6.6.17 Perform event notification action
Syntax [status=]adt_evt_not(umh_c, proc, mode, options,

evt, fnc, passed)

int mode; /* Mode */
TLS_LONG options; /* Options */
struct adt_evt *evt; /* Event info */
int fnc; /* Function */
int *passed; /* Passed indicator */
Semantics This routine is used to notify AUDIT/FAST about the occurrence of an

event. Except for this pure event notification action, it is also possible
via this routine, to modify the contents of a very specific field
(modifiable ASCII application info) of a previously generated event.
Please consult the tutorial in this document (Chapter 2), for a complete
description of some concepts and notions that are used in the context of
the event notification mechanism.
Argument proc describes the DUR address of the process to which the
event information should be sent. If this argument is a NULL pointer,,
the event notification message will be sent to the process ADTSTO on
the application’s node.
The argument mode describes the mode in which the routine should
operate. The following values have been defined for this argument:
• ADT_EVT_NOT_MODE_DIR
Direct mode; the event information is sent directly to the process
being addressed.
• ADT_EVT_NOT_MODE_PCK
Packing mode; the event information is internally buffered in the
routine instead of passed directly to the process being addressed.
• ADT_EVT_NOT_MODE_SPK
Flushing mode; the event information internally buffered in the
routine, is sent off to the process being addressed.

Argument options describes several options that can be activated for

the event notification action. If none of these options must be activated,
the value 0 should be passed for this argument.
• ADT_EVT_NOT_FLG_SYNC
Do the notification action synchronously, i.e. the event notification
routine waits for a reply message from the process being addressed.
• ADT_EVT_NOT_FLG_MNCF
Wait for multi-node confirmation, i.e. wait until a situation has
been achieved where the routine ‘knows’ for sure whether or not
the event notification message has been successfully put in the
queue of the process being addressed.
This option is only useful if the application node calling this routine
and the process node being addressed, differ.
Argument evt describes the event information to be passed to AUDIT/
FAST. The event information is offered to the routine as a DDB.
The following fields of the general info block in this DDB are relevant
for an event notification action:
• evt_key:
It is possible for the application calling the event notification
routine, to ‘time tag’ the event offered to the routine. This option
might be useful in situations where AUDIT/FAST is notified about
a collection of logically related events where each of these events
should be stored having the same timestamp.
In this situation, the fields sec and msec of evt_stamp need to be
filled with a GMT timestamp reflecting the number of seconds and
milliseconds that have elapsed since 1970. The contents of the field
seq_nr is not relevant in this context.
If the application fills the entire field evt_key with zero values,
AUDIT/FAST will use the ‘current time’ to ‘time tag’ the event
offered to the event notification routine.
• info_parts:
This field contains a bit pattern indicating which event info parts
will be present in the remaining part of the DDB.
Remarks:
- All event info parts are optional, except for the info part ‘event
classifier’ which is mandatory. This is because the event
notification routine needs this information for the storage
filter.
- It does not make sense to use the info part ‘notification time’
for event notification purposes. This is because AUDIT/FAST

generates its own event notification timestamp for each event

it is notified about.
- When the info part ‘action and notification source’ is used, it
does not make sense to specify the notification source part.
This is because AUDIT/FAST itself determines which
program called the event notification routine.
The info parts that have been defined for the information type ‘event’,
have been described in SubSection 6.5.11.
Except for the ‘event classifier’ information, all info parts are optional
information units, i.e. it is not absolutely necessary to specify them.
The caller of the routine should indicate to the event notification routine
which info parts will be present in the DDB, by flagging these info_parts
as present/not present in the general info block of the DDB. The flags
that have been defined for this purpose have also been described in
SubSection 6.5.11.
When the routine returns TRUE and a direct, synchronous event
notification action has been performed, the DDB offered to the routine
will contain the timestamp that the storage process used to store the
event. This information might be used when an application wants to
refer to the same event again (e.g. for a modification action on the
event).
The argument fnc describes the so called ‘notification functions’. The
following values have been defined for this argument:
• ADT_EVT_NOT_FNC_ADD
Add event information; if the routine is used to add events to the
current collection of events.
• ADT_EVT_NOT_FNC_MOD
Modify event information; if the routine is used to change the
contents of the ‘modifiable ASCII application information’ field, of
a previously generated (added) event.
Via the argument passed, the event notification routine is able to
indicate whether or not the event offered to the routine, passed the
storage filter. If a value not equal to zero is returned, the event passed
the storage filter. If the value ‘0’ is returned, the event classifier related
to the event was apparently deactivated hence the event did not pass the
storage filter.
Notes • none
Errors • ADT_E_EVT_NOT

occurred in the so called ‘direct mode’.

The real cause of the problem is indicated by a deeper nested error.
• ADT_E_PCK_EVT
occurred in the so called ‘packing mode’.
• ADT_E_SND_PCK_EVT
occurred in the so called ‘flushing mode’.
• ADT_E_MAX_PCK_EVT
Event cluster buffer full. Empty it by sending off the cluster buffer.
• ADT_E_ECL_REQ
Event classifier code is missing. This info is needed for an event
notification action.
• ADT_E_ECL_UNKNOWN
Undefined event classifier encountered (value: <subject code>
<attribute code> <action code> <action source code>)
Related routines • adt_ipev()

Store/retrieve event info parts.
• adt_evt_rtv()
Perform event retrieval action.
6.6.18 Perform event retrieval action
Syntax [status=] adt_evt_rtv(umh_c, proc, timo, rev_in,

sel_crit, rev_out_sz, rev_out)

int timo; /* Timeout on reply */
struct adt_rev_in *rev_in; /* Retrieve parameters */
struct fmc_elm *sel_crit; /* Selection criteria */
int rev_out_sz; /* Size of reply buffer */
struct adt_rev_out *rev_out; /* Reply */
Semantics This routine is used to retrieve information from AUDIT/FAST.

Except for retrieving ‘event’ information, it is also possible to retrieve
‘missing events’ information via this routine. The number of ‘records’
to retrieve at once (via one call) is limited by the value of the #define
ADT_MAX_EVT_TO_REQ.

Please consult the tutorial in this document (Chapter 3), for a complete
description of some concepts and notions that are used in the context of
the event retrieval mechanism.
Argument proc describes the DUR address of the process to which the
event retrieval request should be directed. If a NULL pointer is passed
for this argument, the event retrieval request will be sent to the process
ADTCOL01 on the application’s node.
Argument timo describes the timeout value for the reply on the event
retrieval request. Specifying a zero value, means: ‘wait forever’.
Argument rev_in describes the retrieve request parameters. Via this
argument the caller of the routine specifies:
• The info parts that should be present in the ‘event’ and ‘missing
events’ information. For a description of the flags and structure
being related to the info parts, please consult Section 6.5.
• The number of ‘events’/’missing events’ ‘records’ to retrieve. This
information can be specified in either of two ways:
- Specifying the number of ‘records’ to retrieve directly by
specifying an absolute number of records to be fetched.
- Specifying the number of ‘records’ to retrieve indirectly by
expressing the amount of records to be fetched as:
• The total number of lines to fill with information.
• The number of lines one ‘event’ and one ‘missing events’
message will occupy in the display.
• Certain retrieve options. The following retrieve options have been
defined:
If applicable, set TOP indicator.
If applicable, set BOTTOM indicator.
Return ‘event’ information.
Return ‘missing events’ information.
Also Include in the reply, is the ‘record’ with the specified
keyvalue.
Start retrieve action at the top of the previous storage unit,
considering the keyvalue specified with the request.

• The keyvalue to be used with the request (a timestamp).

Argument sel_crit describes the selection criteria the application
calling this routine, possibly wants to use. These selection criteria apply
to ‘event’ information only. If a NULL pointer is passed for this
argument, no selection criteria apply.
The layout of the datablock that the argument sel_crit is possibly
pointing to, is hidden for the caller of this routine. The datablock
describing the selection criteria can be obtained in either of two ways:
cast to the datatype of the argument sel_crit.
Argument rev_out_sz describes the size of the buffer in which the
reply will be placed.
Argument rev_out is a pointer to a buffer in which the routine will
placed the result of the request. The reply contains the following data:
• The number of ‘records’ (‘event’/’missing events’) returned.
• If ‘lines to fill’ was specified with the request, the amount of lines
that can be filled with the reply data, is returned.
• An options flags word in which a number of situations can be
flagged. Each of these individual situations will only be flagged in
the reply, if the related retrieve option flag, was set in the request.
The following situations (if they occur) will be flagged:
The reply contains the oldest information currently available at
the moment the request was processed.
The reply contains the most recent information currently
available at the moment the request was processed.
The reply contains at least one event ‘record’.
The reply contains at least one missing events ‘record’.
A ‘record’ with a keyvalue as specified in the request, is
present in the reply too.
Started retrieve action at the top of the ‘previous’ storage unit.

• The ‘event’/’missing events’ ‘records’, represented as a DDB.

Each ‘event’/’missing events’ ‘record’ is preceded by a header.
adt_rev_out fmc_elm adt_evt
nr. of events
nr. of lines filled
size
options code
size body sequence nr.
code general
info block
size
info part 2
code
etc. DDB 1
Figure 6-3 Layout of reply on event retrieval request
The definition of this header is given by the structure ‘fmc_elm’.

The ‘size’ field of this header, describes the total amount of bytes
occupied by the header itself (‘size’ and ‘code’ fields) and the DDB
following the header. The code field of the header has currently no
specific meaning.
Notes • none
Errors • ADT_E_RTV_TO_MANY
Retrieve request for too many events at once.
• ADT_E_BUF_TO_SMAL
Reply buffer too small.
Related routines • adt_evt_not()

Perform event notification action.
6.6.19 Store/retrieve event info parts
Syntax [ptr=] adt_ipev(action, ip_code, info_part, ip_flags)

Arguments struct adt_ipev_all *ptr; /* Pointer to info parts*/

int action; /* Action code */
int ip_code; /* Info part code */
void *info_part; /* Info part data */
TLS_LONG *ip_flags; /* Info part flags */
Semantics This routine is used to store event info parts into a temporary store. For
each event info part to be temporarily stored, the routine needs to be
called in the so called ‘add action’ mode. At a later stage, all the event
info parts temporarily stored, can be retrieved at once, by calling the
same routine in the so called ‘retrieve action’ mode.
The routine may be useful for applications performing event notification
actions. In many situations not all information to be stored together with
the event (the contents of the event info parts), can be obtained in the
module performing the event notification action. The information for the
event info parts must also be collected in other modules. To prevent
from using global variables to store this information, this routine can be
called to have a temporary local storage space.
In the module where the actual event notification action has to be done,
all the information being collected can be obtained at once, by calling
the routine for a ‘retrieve action’.
Argument action describes the action the routine should perform. The
following values have been defined for this argument:
• ADT_IPEV_ACT_ADD
‘Add’ function: Add the info part information described by the
argument ip_code and the datastructure the argument info_part
is pointing to.
In the context of this action the argument ip_flags has no
meaning for the routine.
• ADT_IPEV_ACT_ADD_RST
‘Add with reset’ function: As action ADT_IPEV_ACT_ADD, but
before adding information to the temporary store, first flag the
temporary store as ‘empty’.
In the context of this action the argument ip_flags has no
meaning for the routine.
• ADT_IPEV_ACT_RTV
‘Retrieve’ function: Retrieve information currently being stored in
the temporary store.
The info parts flags returned via the ip_flags argument of the
routine, describe which info parts are present/valid in the
datastructure pointed to by the pointer returned by the routine.

In the context of this action, the arguments ip_code and

info_part have no meaning for this routine.
Argument ip_code and info_part respectively describe the code and
the info part information that are related to the event info part being
added. The overview below gives a summary of the codes that need to
be used for the several event info parts. A description of the flags and
datastructures that are related to the several info parts, can be found in
SubSection 6.5.11.
Argument ip_flags describes for a retrieval action, which info parts
are present/valid in the datastructure pointed to by the pointer returned
by the routine. The flags being related to the several info parts, have
been described in SubSection 6.5.11.
Event info part codes

1 Notification time
2 Event classifier
3 Action and notification source
4 Subject identification
5 Terminal and user identification
6 Old and new value
7 ASCII and modifiable ASCII application information
8 Reason information
Info Info part

part code
1 ADT_IPEV_NOTM_CD
2 ADT_IPEV_ECLS_CD
3 ADT_IPEV_ANSC_CD
4 ADT_IPEV_SBID_CD
5 ADT_IPEV_TMUS_CD
6 ADT_IPEV_ONVL_CD
7 ADT_IPEV_AIF1_CD
8 ADT_IPEV_REAS_CD

Notes • On successful completion, the routine returns a pointer to the

temporary store in which the event info parts are stored.
If an error occurs, the routine returns a NULL pointer.
• To make life easier, some macros have been defined for each of the
actions ‘add’, ‘add with reset’ and ‘retrieve’. These macros are
respectively called adt_ipev_add(), adt_ipev_ars() and
adt_ipev_rtv(). For more information about these macros please
consult the relevant subsections.
Errors • none

Related macros • adt_ipev_add()

• adt_ipev_ars()
• adt_ipev_rtv()
6.6.20 Store event info parts (macro)
Syntax (void)adt_ipev_add(ip_code, info_part)
Arguments int ip_code; /* Info part code */

Semantics This macro is used to call the adt_ipev() routine for the so called
‘add’ function of this routine. For more information regarding the
arguments and the usage of this macro, please consult SubSection
6.6.19.
Notes • none
Errors • none

• adt_ipev()
6.6.21 Reset and store event info parts (macro)
Syntax (void)adt_ipev_ars(ip_code, info_part)

Arguments
int ip_code; /* Info part code */


Semantics This macro is used to call the adt_ipev() routine for the so called ‘add
with reset’ function of this routine. For more information regarding the
6.6.19.
Notes • none
Errors • none

• adt_ipev()
6.6.22 Retrieve event info parts (macro)
Syntax [ptr=]adt_ipev_rtv(ip_flags)
Arguments struct adt_ipev_all *ptr /* Pointer to info parts*/

TLS_LONG *ip_flags; /* Info parts flags */
Semantics This macro is used to call the adt_ipev() routine for the so called
‘retrieve’ function of this routine. For more information regarding the
6.6.19.
Notes • none
Errors • none

• adt_ipev()
6.6.23 Check if member of basic set of event classifiers
Syntax [status=] adt_mmb_bset(umh_c, ecl_rec, bset_mmb)

struct adt_ecl *ecl_rec; /* Data to be checked */
int *bset_mmb; /* Member indicator */

Semantics This routine is used to check if a certain event classifier is a member of

the basic set of event classifiers.
Argument ecl_rec points to a datastructure in which the event classifier
to be checked, resides. As well as the name the code of the event
classifier to be checked can be specified.
Argument bset_mmb indicates whether or not the event classifier
offered to the routine, is a member of the basic set of event classifiers.
If the value returned via this argument is 0, the event classifier is not a
member of the basic set. If the value 1 is returned, the event classifier is
indeed a member of the basic set.
Notes • none
Errors • Errors returned by routine adt_cnv_ece().

• adt_ecl_clo()
• adt_ecl_crea()
• adt_ecl_del()
• adt_ecl_ins()
• adt_ecl_key()
• adt_ecl_mod()
• adt_ecl_ope()
• adt_ecl_read()
6.6.24 Terminate overview manager
Syntax (void)adt_omg_exi(umh_c, mc)


void *mc; /* Overview manager
context block */
Semantics This routine is used to terminate the overview manager. All resources
internally claimed by the overview manager and the currently active
(initialized) overviews, will be released after the completion of this call.
Argument mc is a pointer to the overview manager context block. This
pointer can be obtained via a call to the routine adt_omg_ini().
Notes • It is allowed to call this routine without having terminated the
overviews that have been initialized for the overview manager. The
routine will also release all resources of the overviews that have not
been terminated at the moment this routine is called.
Errors • none
Related routines • adt_omg_ini()

Initialize overview manager.
• adt_ovv_brw()
Browse through overview.
• adt_ovv_exi()
Terminate overview.
• adt_ovv_get()
Obtain contents of overview.
• adt_ovv_ini()
Initialize overview.
6.6.25 Initialize overview manager
Syntax [mc=] adt_omg_ini(umh_c, timer_ref, bmsg_id,

sup_file_name, flags)
Arguments void *mc; /* Overview manager

context block */
TLS_LONG timer_ref; /* Timer reference */
int bmsg_id; /* Base message ID */
char *sup_file_name; /* Set-up file name */
int flags; /* Option flags */

Semantics This routine is used to perform the initialization actions for the overview
manager.
Argument timer_ref and bmsg_id are currently not used and are
meant for future extensions. To be upwards compatible with future
releases, please pass a zero value for these arguments.
Argument sup_file_name describes the name of the setup file to be
used for the overview manager. Only the setup file name itself (no
filepath, no extension) should be described by this argument.
The setup file described by this argument, is used as default setup file for
the overviews.
It is allowed to pass a NULL pointer for this argument, in which case the
setup file name “adtovv” is assumed.
Argument flags is currently not used and is meant for future
extensions. To be upwards compatible with future releases, please pass
a zero value for this argument.
Notes • On successful completion the routine returns a void pointer. This

pointer points to a datastructure called the overview manager
context block. This pointer must be passed to all other ‘overview
routines’.
If an error occurred during the initialization action, the routine
returns a NULL pointer.
Errors • ADTO_E_OMG_INI
nested error.
Related routines • adt_omg_exi()

Terminate overview manager.
• adt_ovv_brw()
• adt_ovv_exi()
Terminate overview.
• adt_ovv_get()
• adt_ovv_ini()

6.6.26 Browse through overview
Syntax [status=] adt_ovv_brw(umh_c, mc, ovv_nr, browse_rq,

time, flags)

context block */
int ovv_nr; /* Overview number */
int browse_rq; /* Browse action */
struct ftm_time *time; /* <not used> */
TLS_ULONG flags; /* <not used> */
Semantics This routine is used to perform a browse action on a certain overview.

This routine can only be called for overviews that have been initialized
via a call to the routine adt_ovv_ini().
Argument mc is the pointer to the overview manager context block. This
Argument ovv_nr describes the number of the overview for which the
browse action should be performed. The number to be used for a certain
overview, has been pinned down, after the call to the routine
adt_ovv_ini() has successfully completed.
Argument browse_rq describes the browse action to be performed. The
table below gives the relation between the several browse actions and
the value for the argument browse_rq (browse code).
Browse action Browse code

TOP ADT_OVV_BROWSE_TOP
BOTTOM ADT_OVV_BROWSE_BOT
NEXT-PAGE ADT_OVV_BROWSE_NP
NEXT-LINE ADT_OVV_BROWSE_NL
BACK ADT_OVV_BROWSE_BACK
The arguments time and flags are currently not used and are meant for
future extensions. To be upwards compatible with future releases, please
pass a NULL pointer and a zero value respectively for these arguments.

Notes • none
Errors • ADTO_E_OVV_NOTEXI
Overview does not exist.
• ADTO_E_UNK_BRW_ACT
Unknown browse request specified.
• ADTO_E_NO_EVENTS
No (more) event information available.

• adt_omg_ini()
• adt_ovv_exi()
Terminate overview.
• adt_ovv_get()
• adt_ovv_ini()
6.6.27 Terminate overview
Syntax [status=] adt_ovv_exi(umh_c, mc, ovv_nr)

context block */
int ovv_nr; /* overview number */
Semantics This routine is used to terminate a certain overview. All resources

internally claimed by the overview, will be released after the completion
of this call.
Argument ovv_nr describes the number of the overview to be
terminated.
Notes • none


• adt_omg_ini()
• adt_ovv_brw()
• adt_ovv_get()
• adt_ovv_ini()
6.6.28 Obtain contents of overview
Syntax [ovv=] adt_ovv_get(umh_c, mc, ovv_nr)
Arguments struct adt_ovv_get *ovv; /* Contents description of

overview */
context block */
Semantics This routine is used to obtain the contents of a certain overview. Both
the ASCII representation and the binary representation of the contents of
the overview can be obtained in this way.
Argument ovv_nr describes the number of the overview for which the
caller wants to obtain the contents.
Notes • The routine returns a pointer to a datastructure describing the
contents of the total overview (header lines and dynamic
information). The datastructure has been depicted in Figure 6-4.
For each line in the overview, a pointer to an ASCII text buffer and
a pointer to a DDB are available.
If no information is available for a certain line in the overview
however, the pointer to the ASCII text buffer, points to an empty
buffer (first element of the buffer is a ‘\0’ character) and the pointer

to the DDB contains a NULL pointer.

The pointer to the DDB also contains a NULL pointer for those
lines in the overview that are related to the header lines of the
overview.
• If an error occurs during the ‘overview get’ action, the routine
returns a NULL pointer.
adt_ovv_get adt_ovv_asc adt_ovv_bin adt_evt
........ 1
........ .........
........ null
2
1 .........
......... null
3
2 .........
......... DDB
4 related to
......... event A
3
.........
..
4 .........
......... ....
x
.. .........
......... ....
....
x
......... “First header line\0” 1
“Second header line\0” 2
“First line of event A” 3
“Second line of event A” 4
“First line of event B” 5
“Second line of event B” 6
“............” x
Figure 6-4 Datastructure describing contents of overview

• adt_omg_ini()

• adt_ovv_brw()
• adt_ovv_exi()
Terminate overview.
• adt_ovv_ini()
6.6.29 Initialize overview
Syntax [status=] adt_ovv_ini(umh_c, mc, ini_pars, ovv_nr)

context block */
struct adt_ovv_pars *ini_pars;/* Initialization
parameters */
Semantics This routine is used to perform the initialization actions for an overview.
Each individual overview for a certain overview manager, has its own
overview number. This overview number is used for reference purposes
in calls to other overview manipulation routines.
It is the responsibility of the caller, of this routine, to assign unique
overview numbers for all overviews being activated for a certain
overview manager.
The argument ini_pars describes some overview initialization
parameters like the total number of lines in the overview, the number of
characters per line, possible selection criteria that should be applied to
the contents of the overview etc.
Via this argument it is also possible, to specify the name of the setup file
that is related to the overview. If no setup file is specified, the routine
will take the setup file that was specified during the initialization of the
overview manager.
Argument ovv_nr describes the number the caller of the routine wants
to assign to the overview.
Notes • none

Errors • ADTO_E_OVV_INI
nested error.
• ADTO_E_OVV_ALREXI
Overview already exists.
• ADTO_E_BAD_INI_PAR
Error in overview initialization parameters.
• ADTO_E_NO_DYNAMIC
No room for dynamic information in the overview.
• ADTO_E_EVT_NOT_FIT
The biggest event message will not fit in the overview.

• adt_omg_ini()
• adt_ovv_brw()
• adt_ovv_exi()
Terminate overview.
• adt_ovv_get()
6.6.30 Get subset of setup file parameters
Syntax [param=] adt_params(umh_c, sup_file, param, reinit)
Arguments void *param; /* Parameter value */

char *sup_file; /* Setup file to access */
int param; /* Parameter to obtain */
int reinit; /* Reinit flag */
Semantics This routine is used to obtain certain AUDIT/FAST related parameters

from a setup file. The set of parameters that can be obtained is currently
limited to the node number of the selection group file and the node
number of the event classifier file.

Argument sup_file describes the name of the setup file that should be
accessed to obtain the parameters. Only the name of the setup file (no
filepath, no extension) should be passed via this argument.
If a NULL pointer or an empty string is passed for this argument, the
setup file ‘adtsys.sup’ will be accessed.
Argument param describes the code for the parameter the caller of the
routine wants to obtain the value for. Allowed values for this argument
are:
• ADT_ND_ECL_FILE
For the node number of the event classifier file.
• ADT_ND_SGP_FILE
For the node number of the selection group file.
If the value ‘1’ is passed for the argument reinit, the routine is forced
to access the setup file, each time the routine is called. If a zero value is
passed for this argument, the setup file is only accessed the first time the
routine is called.
The table below gives the relation between the code passed for the
param argument and the type of pointer the return value of the routine (a
void pointer) should be cast to, to access the value of the parameter in
question.
Parameter code Cast return value to:

ADT_ND_ECL_FILE (int *)
ADT_ND_SGP_FILE (int *)
Example: Suppose we want to obtain the node number of the event

classifier file. The following code fragment shows how this can be
accomplished:
....
int ecl_node;
ecl_node = *(int *)adt_params(umh_c,(char *)NULL,

ADT_ND_ECL_FILE,0);
....
Notes • The routine returns a NULL pointer in case an error occurs during
the execution of the routine.
Errors • ADT_E_ILL_ADT_PAR
Illegal AUDIT/FAST parameter specified.

Related routines • none
6.6.31 Compile selection expression
Syntax [status=] adt_pstfix(umh_c, in_file, in_buf, list_file,

out_buf, out_buf_len, pfix_len)

char *in_file; /* Name of input file */
char *in_buf; /* Input buffer */
char *list_file; /* List file name */
TLS_LONG *out_buf; /* Output buffer */
int out_buf_len; /* Size of ‘out_buf’ */
int *pfix_len; /* Number of bytes put in
‘out_buf’ */
Semantics This routine is used to compile an AUDIT/FAST selection expression.

The selection expression can be offered to this routine in either of two
ways:
• Via an ASCII file.
• Via a character buffer.
The routine creates a listing of the selection expression being compiled.
Possible errors in the AUDIT/FAST selection expression, will be
signalled in this listing. The listing can be put in an ASCII file or can be
written to ‘stdout’ directly.
After the selection expression has been successfully compiled, the result
of the compilation (the so called ‘postfix expression’) is put in a buffer
offered by the caller of the routine. The contents of this buffer can be
used e.g. when a ‘event retrieval’ action is performed.
Argument in_file describes the name of the file in which the selection
expression to be compiled, resides. The full file name (including file
path and extension) need to be specified.
If a NULL pointer is specified for this argument, the routine assumes the
selection expression to be compiled is passed via the character buffer
(see description of in_buf argument).
Argument in_buf is a pointer to a character buffer. This character
buffer can be used in case the caller of the routine wants to pass a

selection expression directly, instead of passing it via an ASCII file.

Specifying a NULL pointer for this argument causes the routine to assume that the
selection expression to be compiled will be supplied via an ASCII file.
Argument list_file describes the name of the file in which the
listing, is put. If a NULL pointer is passed for this argument, the listing
is written to ‘stdout’.
Argument out_buf contains a pointer to a buffer in which the routine
puts the result of the compilation. It is not allowed to pass a NULL
pointer for this argument.
Argument out_buf_len describes the size of the buffer pointed to by
the argument out_buf. The size of this buffer must be expressed in a
number of bytes. If the size of the buffer is not large enough to contain
the result of the compilation, the routine returns an error.
Argument pfix_len points to a variable in which the actual length of
the postfix expression, created by this routine, is put. This length is
expressed in a number of bytes.
It is allowed to pass a NULL pointer for this argument.
Notes • If both arguments in_file and in_buf have been specified, the
in_buf argument is used and the in_file argument is neglected.
• If the selection expression compiles well, the routine returns
TRUE. However if the selection expression contains errors, the
routine returns FALSE and the error code
ADTT_E_CMP_NO_SUCC is set in the UMH context block.
Errors • ADTT_E_NO_INPUT
No input source specified for compiler.
• ADTT_E_OPE_INP_FIL
Error during attempt to open the input file.
• ADTT_E_OPE_LIS_FIL
Error during attempt to open the list file.
• ADTT_E_NO_OUT_BUF
No output buffer specified to store the result of the compilation.
• ADTT_E_CMP_NO_SUCC
Number of errors encountered during compilation: <number of
errors>.
Related routines • adt_chkcrit()

Check selection criteria.
• adt_dst_con()
Connect to AUDIT/FAST.

• adt_evt_rtv()
Perform event retrieval action.
6.6.32 Close selection group file
Syntax [status=] adt_sgp_clo(umh_c, fp)

Semantics This routine is used to close the selection group file.

Argument fp is the file pointer of the selection group file.
Notes • none
Errors • ADT_E_CLO_SGP_FIL
nested error.
Related routines • adt_sgp_crea()

Create selection group file.
• adt_sgp_del()
Delete entry from selection group file.
• adt_sgp_ins()
Insert entry in selection group file.
• adt_sgp_lck()
Lock entry in selection group file.
• adt_sgp_mod()
Modify entry in selection group file.
• adt_sgp_ope()
Open selection group file.
• adt_sgp_read()
6.6.33 Create selection group file
Syntax [status=] adt_sgp_crea(umh_c, node)


int node; /* Number of node to create
file on */
Semantics This routine is used to create the selection group file on the specified
node. After the file has been created, it is closed immediately.
The name of the selection group file being created, is determined by the
#define ADT_SGP_FILE_SP.
Argument node is the number of the node on which the file should be
created.
Notes • none
Errors • ADT_E_CRE_SGP_FIL
nested error.
Related routines • adt_sgp_clo()

Close selection group file.
• adt_sgp_del()
• adt_sgp_ins()
• adt_sgp_lck()
• adt_sgp_mod()
• adt_sgp_ope()
• adt_sgp_read()
6.6.34 Delete entry from selection group file
Syntax [status=] adt_sgp_del(umh_c, fp, sgp_rec)



struct adt_sgp_tot *sgp_rec; /* Entry to delete */
Semantics This routine is used to delete an entry from the selection group file. The
contents of the selection group name field, determines which entry will
be deleted.
Argument sgp_rec is the entry to delete. Only the (null terminated)
name of the selection group to delete, is relevant information in the
context of this routine.
Notes • none
Errors • ADT_E_NOREC
Record not found.
• ADT_E_SGP_LCK
This selection group is currently locked by another user.

• adt_sgp_crea()
• adt_sgp_ins()
• adt_sgp_lck()
• adt_sgp_mod()
• adt_sgp_ope()
• adt_sgp_read()
6.6.35 Insert entry in selection group file
Syntax [status=] adt_sgp_ins(umh_c, fp, sgp_rec)


struct adt_sgp_tot *sgp_rec; /* Entry to insert */
Semantics This routine is used to insert an entry into the selection group file.
Argument fp is the file pointer for the selection group file.
Argument sgp_rec is the entry to insert.
The ‘sel_grp_name’ field in the entry to insert, should contain a
selection group name not present in the selection group file yet.
The contents of the ‘seq_nr’ field of the entry to insert, is not relevant
for the insert action.
If the ‘src_file’ field for the entry to be inserted, contains an empty string
(first character contains a ‘\0’ character), the routine will automatically
generate a unique file name for both the source file and the list file
(‘list_file’ field) being related to the selection group. The generated file
names are returned via the datastructure pointed to by the argument
sgp_rec.
The field ‘pfx_info’ contains the postfix expression being related to the
selection group to insert. If no postfix expression is available at the
moment the caller of this routine wants to insert a record, the ’pfx_info’
array should be filled with 0 values. At a later stage, the postfix
information could be related to the selection group, by using the
adt_sgp_mod() routine.
Notes • The names the routine is able to automatically generate for the
source and list files, are preceded by the filepath, ‘FAST/TOOLS
data’ and ‘FAST/TOOLS list’ directory respectively.
• The names of the files the routine is able to automatically generate,
will have a layout conforming to: ‘adtxxxxxxxx.sgs’ and
‘adtxxxxxxxx.sgl’ for the source and list file respectively.
Errors • ADT_E_SGP_DUP
Selection group already defined.

• adt_sgp_crea()
• adt_sgp_del()
• adt_sgp_lck()

• adt_sgp_mod()
• adt_sgp_ope()
• adt_sgp_read()
6.6.36 Lock entry in selection group file
Syntax [status=] adt_sgp_lck(umh_c, fp, sgp_name)

char *sgp_name; /* Selection group to be
locked */
Semantics This routine is used to lock a selection group entry. The kind of locking
being performed is ‘manual record locking’ (see DATABASE/FAST
Programmer’s Guide).
When the ‘adt_sgp_ope’ routine is used to open the selection group file,
the file is automatically opened with the correct mode parameter to
allow manual record locking.
Argument sgp_name describes the name of the selection group to be
locked.
Notes • No separate unlock routine is supplied for the selection group file.
If the records being locked must be unlocked, the ‘isf_release’
routine should be used.
Errors • ADT_E_SGP_NO_EXI
Selection group does not exist
• ADT_E_SGP_LCK
This selection group is currently locked by another user.

• adt_sgp_crea()

• adt_sgp_del()
• adt_sgp_ins()
• adt_sgp_mod()
• adt_sgp_ope()
• adt_sgp_read()
6.6.37 Modify entry in selection group file
Syntax [status=] adt_sgp_mod(umh_c, fp, sgp_rec)

struct adt_sgp_tot *sgp_rec; /* Entry to modify */
Semantics This routine is used to modify an entry in the selection group file. The
contents of the selection group name field, determines which entry will
be modified.
Argument sgp_rec describes the entry to be modified.
Notes • none
Errors • Errors possibly returned by the adt_sgp_del() and

adt_sgp_ins() routines.

• adt_sgp_crea()
• adt_sgp_del()
• adt_sgp_ins()

• adt_sgp_lck()
• adt_sgp_ope()
• adt_sgp_read()
6.6.38 Open selection group file
Syntax [fp=] adt_sgp_ope(umh_c, node, mode, timo)
Arguments struct isf_file_info *fp; /* File pointer */

int mode; /* Open mode */
TLS_ULONG timo; /* Timeout */
Semantics This routine is used to open a selection group file on a specific node.
Argument node describes the node on which the file must be opened.
Argument mode describes the ‘open mode’. This argument is passed
directly to the isf_uopen() routine. For a description of the possible
‘open modes’ please consult the DATABASE/FAST Programmer’s
Guide.
Argument timo describes the timeout value for the ‘open’ action. This
timeout only applies in case the file is opened on a remote node. The
timeout value must be specified in seconds. A timeout value of zero
means ‘wait forever’.
Notes • On successful completion, the routine returns a file pointer. If an
error occurred during the open action, the routine returns a NULL
pointer.
Errors • ADT_E_OPE_SGP_FIL
Error occurred during attempt to open the selection group file.

• adt_sgp_crea()

• adt_sgp_del()
• adt_sgp_ins()
• adt_sgp_lck()
• adt_sgp_mod()
• adt_sgp_read()
6.6.39 Read entry from selection group file
Syntax [status=] adt_sgp_read(umh_c, fp, sgp_rec, read_mode)

struct adt_sgp_tot *sgp_rec; /* Entry to read/
entry read */
int read_mode; /* Read mode */
Semantics This routine is used to read an entry from the selection group file.
By default the routine uses the index ‘selection group name’ for the read
action.
Prior to calling of this routine, the field ‘sel_grp_name’ in the
datastructure that is pointed to by the argument sgp_rec, should be
filled with the value to be used for the read operation.
The contents of the other fields of the datastructure this argument is
pointing to, are not important prior to the call of this routine.
After the routine has been successfully called, the argument ecl_rec
contains the entry being read.
The argument read_mode describes the type of read action to be
performed. Allowed values for this argument are the same as allowed for
the isf_read() routine. For more information, please consult the
Notes • none

Errors • Errors returned by routine isf_read() except for error

ISF_E_NOREC. This error is replaced by ADT_E_SGP_NO_EXI
(see below), to obtain an error text related to selection groups.
• ADT_E_SGP_NO_EXI
Selection group does not exist.

• adt_sgp_crea()
• adt_sgp_del()
• adt_sgp_ins()
• adt_sgp_lck()
• adt_sgp_mod()
• adt_sgp_ope()

Introduction
Appendix A: Example of event no-

tification
A.1 Introduction
This appendix gives a simple (real working) example of the usage of the
‘event notification routine’. The program listed in Section A.2, performs
an event notification action in direct mode.
The event info parts ‘event classifier’ and ‘reason’ are the only info parts
that are part of the DDB offered to the event notification routine.
A.2 Example
/*----------------------------------------------------------------------------+
| |
| ///// ///// ///// ////// / OOOOO OOO OOO O OOOO |
| / / / / / / O O O O O O O |
| /// ///// /// / / O O O O O O OOO |
| / / / / / / O O O O O O O |
| / / / / / / O O O O O O O |
| / / / ///// / / O OOO OOO OOOO OOOO |
| |
+-----------------------------------------------------------------------------+
| * Example * |
+-----------------------------------------------------------------------------+
| Module identification |
+-----------------------------------------------------------------------------+
Module Name : notify.c
Version : 1.0
Copyright (c) : Yokogawa System Center Europe B.V., The Netherlands
Author : S. Sietsma
+-----------------------------------------------------------------------------+
| Changes .... |
+-----------------------------------------------------------------------------+
|Who When Change What |
+-----------------------------------------------------------------------------+
STM Dec-93 e306 First version documented
+-----------------------------------------------------------------------------+
+----------------------------------------------------------------------------*/
#include <adt.h>
struct my_ddb
{
struct adt_evt adt_evt;
AUDIT/FAST Programmer’s Guide A-1

Example
struct adt_ipev_ecls ecls;

struct adt_ipev_reas reas;
};
/*============================================================================+
| Entry point |
+-----------------------------------------------------------------------------+
|
| Description: This program shows the usage of the notification interface.
|
+----------------------------------------------------------------------------*/
main()
{
int passed;
struct dur_context dur_c;
struct umh_context umh_c;
struct my_ddb my_ddb;
/*----------------------------------------------------------------------------+
| Attach to the DUR-common and initialize UMH context block.
+----------------------------------------------------------------------------*/
dur_umh_init (&dur_c,&umh_c,20,100,1000,1000,(char *)NULL);
/*----------------------------------------------------------------------------+
| Fill the DDB with information related to the event.
+----------------------------------------------------------------------------*/
memset((void *)&my_ddb,0,sizeof(struct my_ddb));
my_ddb.adt_evt.gen_info.info_parts = ADT_IPEV_ECLS_FLG | ADT_IPEV_REAS_FLG;
my_ddb.ecls.ecls.sbj_code = ADT_SBG_ITEM;
my_ddb.ecls.ecls.attr_code = ADT_SAT_ITEM_NULL;
my_ddb.ecls.ecls.action_code = ADT_SAC_ACKN;
my_ddb.ecls.ecls.act_src_code = ADT_SAS_OTHS;
strncpy(my_ddb.reas.reason,
“REASON_FIELD_CONTENTS”,
sizeof(my_ddb.reas.reason));
/*----------------------------------------------------------------------------+
| Perform the event notification action.
+----------------------------------------------------------------------------*/
if (!adt_evt_not(&umh_c,(struct dur_adr *)NULL,ADT_EVT_NOT_MODE_DIR,
ADT_EVT_NOT_FLG_SYNC,(struct adt_evt *)&my_ddb,
ADT_EVT_NOT_FNC_ADD,&passed))
{
umh_log_term(&umh_c);
exit(BAD_EXIT);
}
/*----------------------------------------------------------------------------+
| Check if event passed the storage filter.
+----------------------------------------------------------------------------*/
if (!passed)
printf(“The event did not pass the storage filter!\n”);
exit(GOOD_EXIT);
}
A-2 AUDIT/FAST Programmer’s Guide

Introduction
Appendix B: Example of event re-

trieval
B.1 Introduction
This appendix gives a simple (real working) example of the usage of the
‘event retrieval routine’. The program listed in Section B.2, results in the
retrieval of all ‘records’ of information type ‘event’ satisfying the
selection criteria related to a selection group called “SELECT_CRIT”.
The event info parts ‘event classifier’, ‘object identification’ and
‘reason’ are the only info parts that are part of the DDB related to the
event retrieval action.
B.2 Example
/*----------------------------------------------------------------------------+
| |
| / / / / / / O O O O O O O |
| /// ///// /// / / O O O O O O OOO |
| / / / / / / O O O O O O O |
| / / / / / / O O O O O O O |
| |
+-----------------------------------------------------------------------------+
| * Example * |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
Module Name : retrieve.c
Version : 1.0
Author : Allang Weg
+-----------------------------------------------------------------------------+
| Changes .... |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
WEG Dec-93 e306 First version documented
+-----------------------------------------------------------------------------+
+----------------------------------------------------------------------------*/
#include <adt.h>
AUDIT/FAST Programmer’s Guide B-1

Example
struct my_ddb
{
struct adt_evt adt_evt;
struct adt_ipev_sbid sbid;
};
/*----------------------------------------------------------------------------+
| Number of events to retrieve.
+----------------------------------------------------------------------------*/
#define EVENTS_TO_RETRIEVE 10
/*----------------------------------------------------------------------------+
| Determine size of reply buffer (in bytes).
+----------------------------------------------------------------------------*/
#define REPLY_BUFFER_SIZE (sizeof(struct adt_rev_out) - sizeof(TLS_LONG) + \
EVENTS_TO_RETRIEVE * (sizeof(struct fmc_elm) - \
sizeof(TLS_LONG) + sizeof(struct my_ddb)))
#define TIME_FORMAT “DD/MM/YY hh:mm:ss.ppp”
/*============================================================================+
| Entry point |
+-----------------------------------------------------------------------------+
|
| Description: This program shows the usage of the retrieval interface.
|
+----------------------------------------------------------------------------*/
main()
{
int nr;
int req;
char time_buffer[sizeof(TIME_FORMAT) + 1];
TLS_LONG reply_buffer[(REPLY_BUFFER_SIZE + 3)/4];
struct adt_sgp_tot sgp_rec;
struct adt_rev_in rev_in;
struct adt_ecl_name ecl_name;
struct ftm_time ftm_time;
struct isf_file_info *sgp_fp;
struct adt_rev_out *rev_out = (struct adt_rev_out *)reply_buffer;
struct fmc_elm *header;
struct my_ddb *my_ddb;
/*----------------------------------------------------------------------------+
| Attach to the DUR-common and initialize UMH context block.
+----------------------------------------------------------------------------*/
dur_umh_init (&dur_c,&umh_c,20,100,1000,1000,(char *)NULL);
/*----------------------------------------------------------------------------+
| Fill the DDB with information related to the event.
+----------------------------------------------------------------------------*/
memset((void *)&rev_in,0,sizeof(rev_in));
rev_in.info_parts.ev_info_parts = ADT_IPEV_ECLS_FLG |
ADT_IPEV_SBID_FLG |
ADT_IPEV_REAS_FLG;
rev_in.nr_evt = EVENTS_TO_RETRIEVE;
rev_in.options = ADT_EVT_RTV_OPT_REV |
ADT_EVT_RTV_OPT_INC;
/*----------------------------------------------------------------------------+
| Open selection group file.
+----------------------------------------------------------------------------*/
if ((sgp_fp = adt_sgp_ope(&umh_c,0,ISINPUT,0)) ==
(struct isf_file_info *)NULL)
{
B-2 AUDIT/FAST Programmer’s Guide

Example
exit(BAD_EXIT);
}
/*----------------------------------------------------------------------------+
| Read information related to selection group “SELECT_CRIT”.
+----------------------------------------------------------------------------*/
strncpy(sgp_rec.sel_grp_name,”SELECT_CRIT”,sizeof(sgp_rec.sel_grp_name));
if (!adt_sgp_read(&umh_c,sgp_fp,&sgp_rec,ISEQUAL))
{
(void)adt_sgp_clo(&umh_c,sgp_fp);
exit(BAD_EXIT);
}
(void)adt_sgp_clo(&umh_c,sgp_fp);
/*----------------------------------------------------------------------------+
| Check if selection group is considered to be valid.
+----------------------------------------------------------------------------*/
if (!(sgp_rec.flags & ADT_SGP_FLG_VALID))
{
printf(“Selection group used for retrieval action, is not valid!\n”);
printf(“Please (re)compile selection group\n”);
exit(BAD_EXIT);
}
for (req = 0; 1; req++)

{
/*----------------------------------------------------------------------------+
| Perform the information retrieval request.
+----------------------------------------------------------------------------*/
if (!adt_evt_rtv(&umh_c,(struct dur_adr *)NULL,30,&rev_in,
(struct fmc_elm *)sgp_rec.pfx_info,sizeof(reply_buffer),
(struct adt_rev_out *)reply_buffer))
{
exit(BAD_EXIT);
}
/*----------------------------------------------------------------------------+
| Process the reply.
+----------------------------------------------------------------------------*/
if (rev_out->nr_evt == 0)
{
printf(“No information returned anymore\n”);
exit(BAD_EXIT);
}
header = (struct fmc_elm *)rev_out->info;
for (nr = 0; nr < rev_out->nr_evt; nr++)

{
my_ddb = (struct my_ddb *)header->body;
/*----------------------------------------------------------------------------+
| Convert event classifier code to event classifier name.
+----------------------------------------------------------------------------*/
if (!adt_cnv_ece(&umh_c,my_ddb->ecls.ecls,&ecl_name,
ADT_CNV_ECE_FNC_TO_NAME))
{
exit(BAD_EXIT);
}
/*----------------------------------------------------------------------------+
| Convert binary (G.M.T) timestamp to (L.C.T) ASCII timestamp.
+----------------------------------------------------------------------------*/
ftm_time.ftm_sec =
AUDIT/FAST Programmer’s Guide B-3

Example
my_ddb->adt_evt.gen_info.evt_key.evt_stamp.sec;
ftm_time.ftm_usec =
my_ddb->adt_evt.gen_info.evt_key.evt_stamp.msec * 1000;
if (!ftm_c_gmtlct(&ftm_time,&umh_c))
{
exit(BAD_EXIT);
}
(void)ftm_format((TLS_ULONG *)&ftm_time,TIME_FORMAT,time_buffer);
/*----------------------------------------------------------------------------+
| Dump some information to stdout.
+----------------------------------------------------------------------------*/
printf(“Record nr. : %d\n”,(req * EVENTS_TO_RETRIEVE) + nr + 1);
printf(“Timestamp : %s\n”,time_buffer);
printf(“Event classifier: %-15s %-15s\n”,
ecl_name.sbj_name,ecl_name.attr_name);
printf(“ %-15s %-15s\n”,
ecl_name.action_name,ecl_name.act_src_name);
printf(“Object id. : %s\n”,my_ddb->sbid.sbid);
printf(“Reason : %s\n”,my_ddb->reas.reason);
printf(“\n”);
/*----------------------------------------------------------------------------+
| Calculate where possible next header will start.
+----------------------------------------------------------------------------*/
header = (struct fmc_elm *)((char *)header + header->size);
}
/*----------------------------------------------------------------------------+
| Save last key returned for possible next retrieval request.
+----------------------------------------------------------------------------*/
rev_in.evt_key = my_ddb->adt_evt.gen_info.evt_key;
/*----------------------------------------------------------------------------+
| Do not include a record with this key in the next reply again.
+----------------------------------------------------------------------------*/
rev_in.options &= ~ADT_EVT_RTV_OPT_INC;
}
exit(GOOD_EXIT);
}
B-4 AUDIT/FAST Programmer’s Guide

Introduction
Appendix C: Distribution inter-

face
C.1 Introduction
This section illustrates some of the concepts related to the distribution
interface of AUDIT.
The example given here, is simplified in the sense that only the most
relevant code fragments and details are shown.
C.2 Example
/*----------------------------------------------------------------------------+
| |
| / / / / / / O O O O O O O |
| /// ///// /// / / O O O O O O OOO |
| / / / / / / O O O O O O O |
| / / / / / / O O O O O O O |
| |
+-----------------------------------------------------------------------------+
| * Example * |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
Module Name : distribution.c
Version : 1.0
Author : S. Sietsma
+-----------------------------------------------------------------------------+
| Changes .... |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
STM Dec-93 e306 First version documented
+-----------------------------------------------------------------------------+
+----------------------------------------------------------------------------*/
...
#include <adt.h>
....
/*----------------------------------------------------------------------------+
| Some miscellaneous definitions
AUDIT/FAST Programmer’s Guide C-1

Example
+----------------------------------------------------------------------------*/
#define MY_BASE_MSG_ID 293
#define MY_EV_INFO_PARTS (ADT_IPEV_ECLS_FLG | \
ADT_IPEV_REAS_FLG)
#define MY_MS_INFO_PARTS (ADT_IPMS_REAS_FLG)
#define MY_FC_INFO_PARTS (0)
....
/*----------------------------------------------------------------------------+
| Definition Dynamic Data Block event message
+----------------------------------------------------------------------------*/
struct my_ev_ddb
{
struct adt_evt gen_info_block;
};
/*----------------------------------------------------------------------------+
| Definition Dynamic Data Block missing events message
+----------------------------------------------------------------------------*/
struct my_ms_ddb
{
struct adt_ipms_reas reas;
};
/*----------------------------------------------------------------------------+
| Definition Dynamic Data Block flow control message (no info parts)
+----------------------------------------------------------------------------*/
struct my_fc_ddb
{
};
/*============================================================================+
| Entry point |
+-----------------------------------------------------------------------------+
|
| Description: This program fragment shows the usage of the distribution
| interface.
|
+----------------------------------------------------------------------------*/
main()
{
TLS_LONG rcv_buf[1000];
struct fmc_elm *header = (struct fmc_elm *)snd_buf;
TLS_BOOLEAN be_active = TRUE;
struct my_ev_ddb *ev = (struct my_ev_ddb *)header->body;
struct my_ms_ddb *ms = (struct my_ms_ddb *)header->body;
struct my_fc_ddb *fc = (struct my_fc_ddb *)header->body;
struct adt_info_parts my_info_parts;
....
/*----------------------------------------------------------------------------+
| Define which info parts we want to receive for the several information types
+----------------------------------------------------------------------------*/
my_info_parts.ev_info_parts = MY_EV_INFO_PARTS;
my_info_parts.lb_info_parts = 0;
my_info_parts.ms_info_parts = MY_MS_INFO_PARTS;
my_info_parts.fc_info_parts = MY_FC_INFO_PARTS;
/*----------------------------------------------------------------------------+
| Connect to AUDIT/FAST “event generator”.
+----------------------------------------------------------------------------*/
if (!adt_dst_con(..,MY_BASE_MSG_ID,..,&my_info_parts))
{
...
C-2 AUDIT/FAST Programmer’s Guide

Example
while (be_active)
{
/*----------------------------------------------------------------------------+
| Wait for message to arrive.
+----------------------------------------------------------------------------*/
dur_rcv();
...
switch(header->code)
{
/*----------------------------------------------------------------------------+
| Handle (add and modify) ‘event’ message.
+----------------------------------------------------------------------------*/
case (base_msg_id + ADT_OFS_ADD_EVT):
case (base_msg_id + ADT_OFS_MOD_EVT):
event_message(.. ,my_ev, ..);
break;
/*----------------------------------------------------------------------------+
| Handle ‘missing events’ message.
+----------------------------------------------------------------------------*/
case (base_msg_id + ADT_OFS_MIS_EVT):
missing_event_message(.. ,my_ms, ..);
break;
/*----------------------------------------------------------------------------+
| Handle ‘flow control’ message.
+----------------------------------------------------------------------------*/
case (base_msg_id + ADT_OFS_FLW_CTL):
flow_control_message(.. ,my_fc, ..);
break;
/*----------------------------------------------------------------------------+
| Terminate this process.
+----------------------------------------------------------------------------*/
case TLS_UNI_STOP:
....
be_active = FALSE;
continue;
}
....
}
....
/*----------------------------------------------------------------------------+
| Disconnect from AUDIT/FAST. Remove messages being sent by “event generator”
| and still present in the queue of this process.
+----------------------------------------------------------------------------*/
(void)adt_dst_dcon(..,ADT_DST_DCON_FLG_QEMP);
exit(GOOD_EXIT);
}
AUDIT/FAST Programmer’s Guide C-3

Example
C-4 AUDIT/FAST Programmer’s Guide

Introduction
Appendix D: Usage of ‘event over-

view’ routines
D.1 Introduction
This appendix illustrates the usage of the ‘event overview’ routines.
The example given here, is simplified in the sense that only the most
relevant code fragments are shown.
D.2 Example
/*----------------------------------------------------------------------------+
| |
| / / / / / / O O O O O O O |
| /// ///// /// / / O O O O O O OOO |
| / / / / / / O O O O O O O |
| / / / / / / O O O O O O O |
| |
+-----------------------------------------------------------------------------+
| * Example * |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
Module Name : overview.c
Version : 1.0
Author :Ook Allang Weg
+-----------------------------------------------------------------------------+
| Changes .... |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
WEG Dec-93 e306 First version documented
+-----------------------------------------------------------------------------+
+----------------------------------------------------------------------------*/
#include <adt.h>
....
#define OVV_A_NR 1
....
/*============================================================================+
| Entry point |
+-----------------------------------------------------------------------------+
AUDIT/FAST Programmer’s Guide D-1

Example
|
| Description: This program fragment shows the basics of an overview manager.
|
+----------------------------------------------------------------------------*/
entry_point()
{
TLS_BOOLEAN be_active = TRUE;
int browse_cmd;
void *ovv_man;
struct adt_ovv_get *ovv_get;
/* Initialize the overview manager */

if ((ovv_man = adt_omg_ini(..)) == (void *)NULL)
{
/* Error handling */
...
}
/* Initialize the overview */

if (!adt_ovv_ini(..,ovv_man,..,OVV_A_NR))
{
...
}
/* Get the contents of the overview */

if ((ovv_get = adt_ovv_get(..,ovv_man,OVV_A_NR)) == (struct adt_ovv_get *)NULL)
{
...
}
/* Display contents of overview */

...
while(be_active)
{
/* Wait for user-input */
...
/* Some user event has happened, perform the desired action */

switch(event)
{
case BROWSE_CMD_TOP:
case BROWSE_CMD_BOTTOM:
case BROWSE_CMD_NEXT_PAGE:
case BROWSE_CMD_NEXT_LINE:
case BROWSE_CMD_BACK:
/* Convert ‘browse command’ to corresponding ADT_OVV_BROWSE_... value */
browse_cmd = ...
/* Perform browse action */

if (!adt_ovv_brw(..,ovv_man,OVV_A_NR,browse_cmd,..))
{
/* Display error message */
....
break;
}
/* Get the contents of the overview */

if ((ovv_get = adt_ovv_get(..,ovv_man,OVV_A_NR)) ==
(struct adt_ovv_get *)NULL)
{
...
}
D-2 AUDIT/FAST Programmer’s Guide

Example
/* Display contents of overview */

...
break;
/* Handle termination of overview */

case TERMINATION_OF_OVERVIEW
if (!adt_ovv_exi(..,ovv_man,OVV_A_NR))
{
...
}
be_active = FALSE;
break;
...
} /* End ‘switch()’ */
} /* End ‘while()’ */
....
/* Terminate the overview manager */
adt_omg_exi(..,ovv_man);
....
}
AUDIT/FAST Programmer’s Guide D-3

Example
D-4 AUDIT/FAST Programmer’s Guide

Index
Index
A ADT_IPEV_ANSC_CD 6-51
ADT_IPEV_ANSC_FLG 6-11
action source 6-11, 6-13, 6-14, 6-45, ADT_IPEV_ECLS_CD 6-51
6-51 ADT_IPEV_ECLS_FLG 6-11
add event message 4-1, 4-2, 6-28 ADT_IPEV_NOTM_CD 6-51
ADT_AAINF1_SZ 6-12 ADT_IPEV_NOTM_FLG 6-11
ADT_CNV_ECE_FNC_TO_CODE ADT_IPEV_ONVL_CD 6-51
6-26 ADT_IPEV_ONVL_FLG 6-12
ADT_CNV_ECE_FNC_TO_NAME ADT_IPEV_REAS_CD 6-51
6-26 ADT_IPEV_REAS_FLG 6-12
ADT_DST_DCON_FLG_QEMP 6-30 ADT_IPEV_SBID_CD 6-51
ADT_DST_DCON_FLG_SYNC 6-30 ADT_IPEV_SBID_FLG 6-11
ADT_ECE_SRT_FLG_CD 6-32 ADT_IPEV_TMUS_CD 6-51
ADT_ECE_SRT_FLG_NM 6-32 ADT_IPEV_TMUS_FLG 6-11
ADT_ECL_FILE_SP 6-35 ADT_IPFC_LSSN_FLG 6-12
ADT_ECL_FLG_ACTV 6-5 ADT_IPMS_NRMS_FLG 6-12
ADT_ECL_FLG_BSET 6-5 ADT_IPMS_REAS_FLG 6-12
ADT_ECL_KEYS_ECL_CODE 6-38 ADT_ITYP_EVNT 6-7
ADT_ECL_KEYS_ECL_NAME 6-38 ADT_ITYP_FLCT 6-7
ADT_ECL_NAME_SZ 6-6, 6-31 ADT_ITYP_MSIF 6-7
ADT_EVT_NOT_FLG_MNCF 6-44 ADT_M_AAINF1_SZ 6-12
ADT_EVT_NOT_FLG_SYNC 6-44 ADT_MAX_EVT_TO_REQ 6-46
ADT_EVT_NOT_FNC_ADD 6-45 ADT_MIS_REAS_CN_LOS 6-17
ADT_EVT_NOT_FNC_MOD 6-45 ADT_MIS_REAS_QU_OVF 6-17
ADT_EVT_NOT_MODE_DIR 6-43 ADT_MIS_REAS_UE_SNR 6-17
ADT_EVT_NOT_MODE_PCK 6-43 ADT_ND_ECL_FILE 6-63
ADT_EVT_NOT_MODE_SPK 6-43 ADT_ND_SGP_FILE 6-63
ADT_EVT_RTV_OPT_BACK 6-20, ADT_OFS_ADD_EVT 6-28
6-21, 6-47, 6-48 ADT_OFS_FLW_CTL 6-28
ADT_EVT_RTV_OPT_BOT 6-20, ADT_OFS_MIS_EVT 6-28
6-21, 6-47, 6-48 ADT_OFS_MOD_EVT 6-28
ADT_EVT_RTV_OPT_INC 6-20, ADT_OVV_BROWSE_BACK 6-57
6-21, 6-47, 6-48 ADT_OVV_BROWSE_BOT 6-57
ADT_EVT_RTV_OPT_REV 6-20, ADT_OVV_BROWSE_NL 6-57
6-21, 6-47, 6-48 ADT_OVV_BROWSE_NP 6-57
ADT_EVT_RTV_OPT_RMS 6-20, ADT_OVV_BROWSE_TOP 6-57
6-21, 6-47, 6-48 ADT_REAS_SZ 6-15
ADT_EVT_RTV_OPT_TOP 6-20, ADT_SBJ_DESC_SZ 6-15
6-21, 6-47, 6-48 ADT_SGP_FILE_SP 6-67
ADT_IPEV_ACT_ADD 6-50 ADT_SGP_FLG_VALID 6-23
ADT_IPEV_ACT_ADD_RST 6-50 ADT_SGP_NAME_SZ 6-18, 6-23
ADT_IPEV_ACT_RTV 6-50 ADT_TOT_PFX_SZ 6-23
ADT_IPEV_AIF1_CD 6-51 ADT_VAL_SZ 6-15
ADT_IPEV_AIF1_FLG 6-12 ADTCOLxx 3-2, 6-47
AUDIT/FAST Programmer’s Guide 1

Index
ADTSTO 2-2, 4-2, 4-4, 6-28, 6-30, 6-43 disconnect options 4-5, 6-30
ASCII application info 6-11, 6-12, 6-13, disconnecting from AUDIT/FAST 4-2,
6-51 4-4, 6-29
distribution 1-1, 1-2, 1-3, 4-1, 6-8, 6-10,
B C-1
base message id 4-2, 4-3, 6-28 distributor process 4-1, 4-2, 4-3
Dynamic Data Block 1-2, 2-3, 2-4, 2-5,
C 3-3, 3-5, 4-4, 4-5, 6-6, 6-7, 6-10,
6-19, 6-21, 6-44, 6-45, 6-49,
chronological event overview 5-1, 6-18, 6-59, 6-60
6-57, 6-58, 6-59, 6-61, D-1
collector process 3-1, 3-2, 3-3, 3-4
connecting to AUDIT/FAST 4-1, 4-2,
E
4-5, 6-8, 6-9, 6-27 event 6-39
event classifier 2-2, 2-5, 6-5, 6-6, 6-11,
D 6-13, 6-33, 6-44, 6-45, 6-46,
6-51, 6-53
datastructures event classifier entities
adt_ece_ptr 6-4 sorted on code 6-32
adt_ece_tb 6-3
sorted on name 6-32
adt_ecl 6-5 event classifier entity 6-3, 6-4, 6-30,
adt_ecl_code 6-5 6-31
adt_ecl_name 6-6 code of 6-3, 6-5, 6-6, 6-26, 6-32
adt_event_gen 6-6 name of 6-3, 6-5, 6-6, 6-26, 6-31,
adt_evt 6-7 6-32
adt_evt_key 6-9
event classifier file 6-5, 6-33, 6-34,
adt_fc_data 6-9 6-35, 6-36, 6-37, 6-38, 6-39,
adt_info_parts 6-10 6-40, 6-41, 6-42
adt_ipev_aif1 6-12
node number of 6-62, 6-63
adt_ipev_all 6-13
event message 1-1, 4-1, 4-4, 4-5, 6-19,
adt_ipev_ansc 6-13 6-20, 6-28, 6-47
adt_ipev_ecls 6-14
event notification message 2-2, 2-3, 2-4,
adt_ipev_notm 6-14
2-5, 6-43, 6-44
adt_ipev_onvl 6-15
adt_ipev_reas 6-15
adt_ipev_sbid 6-14
F
adt_ipev_tmus 6-16 flow control interval 6-10, 6-28
adt_ipfc_lssn 6-16 flow control message 1-1, 4-1, 4-3, 4-4,
adt_ipms_nrms 6-17 4-5, 6-10, 6-28, 6-29
adt_ipms_reas 6-17 flow control parameters 4-3, 6-9, 6-28,
adt_ovv_pars 6-18 6-29
adt_rev_in 6-19 flow control timeout 6-10
adt_rev_lin 6-20 flushing mode 6-43, 6-46
adt_rev_out 6-21
adt_sbg_tb 6-18 G
adt_sgp_tot 6-22 general info block 1-2, 2-4, 6-6, 6-8,
adt_tim_stamp 6-23 6-9, 6-25, 6-44, 6-45
DDB 1-2, 2-3, 2-4, 2-5, 3-3, 3-5, 4-4,
4-5, 6-6, 6-7, 6-10, 6-19, 6-21, H
6-44, 6-45, 6-49, 6-59, 6-60 heartbeat 4-3, 4-4, 6-10, 6-28
direct mode 2-3, 2-4, 6-43, 6-46
2 AUDIT/FAST Programmer’s Guide

Index
I options 2-3, 6-44

routine 2-3
info parts 1-2, 1-3, 2-3, 4-5, 6-6, 6-7, notification routine 2-2, 2-3, 2-4, 2-5,
6-8, 6-10, 6-19, 6-28, 6-44, 6-43
6-45, 6-47, 6-49, 6-52, 6-53 notification source 6-11, 6-13, 6-14,
adt_ipev_aif1 6-12 6-45, 6-51
adt_ipev_ansc 6-13 notification time 6-11, 6-13, 6-14, 6-44,
adt_ipev_ecls 6-14 6-45, 6-51
adt_ipev_notm 6-14
adt_ipev_onvl 6-15
adt_ipev_reas 6-15
O
adt_ipev_sbid 6-14 old attribute value 6-11, 6-13, 6-15,
adt_ipev_tmus 6-16 6-51
adt_ipfc_lssn 6-16 overview manager 5-1, 6-54, 6-55
adt_ipms_nrms 6-17 overview number 5-2, 6-57, 6-58, 6-59,
adt_ipms_reas 6-17 6-61
for information type ’event’ 6-11,
6-13 P
for information type ’flow control’ packing mode 2-3, 6-43, 6-46
6-12 process
for information type ’missing ADTCOLxx 3-2, 6-47
events’ 6-12 ADTSTO 2-2, 4-2, 4-4, 6-28, 6-30,
information type 1-2, 1-3, 3-3, 6-7, 6-8, 6-43
6-11
event 1-3, 3-4, 6-7, 6-11, 6-20, 6-25, R
6-45 reason info 6-11, 6-13, 6-15, 6-51
flow control 6-7, 6-11, 6-12 retrieval 1-1, 1-2, 1-3, 2-1, 3-1, 6-8,
missing events 3-4, 6-7, 6-11, 6-12, 6-10, 6-19, 6-20, 6-22, 6-46,
6-20 6-64, B-1
options 3-3, 6-19, 6-47
M selection criteria 3-4, 6-48
macros retrieve request parameters block 3-3,
adt_ipev_add() 6-52 6-19
adt_ipev_ars() 6-52 routines
adt_ipev_rtv() 6-52, 6-53 adt_chkcrit() 6-24
missing events message 1-1, 4-1, 4-2, adt_cnv_ece() 6-25
4-4, 4-5, 6-19, 6-20, 6-28, 6-47 adt_dst_con() 4-2, 6-27
modifiable ASCII application info 2-5, adt_dst_dcon() 4-4, 6-29
6-11, 6-12, 6-13, 6-43, 6-45, adt_ece() 6-4, 6-5, 6-30, 6-31
6-51 adt_ece_srt() 6-31, 6-32
modify event message 4-1, 4-2, 6-28 adt_ecl_bset() 6-33
adt_ecl_clo() 6-34
N adt_ecl_crea() 6-35
new attribute value 6-11, 6-13, 6-15, adt_ecl_del() 6-36
6-51 adt_ecl_ins() 6-37
notification 1-1, 1-2, 1-3, 2-1, 6-8, 6-43, adt_ecl_key() 6-38, 6-42
6-50, A-1 adt_ecl_mod() 6-39
functions 2-4, 6-45 adt_ecl_ope() 6-40
mode 2-2, 6-43 adt_ecl_read() 6-38, 6-41
adt_evt_not() 2-2, 6-43
AUDIT/FAST Programmer’s Guide 3

Index
adt_evt_rtv() 3-2, 6-46 subject identification 1-3, 6-11, 6-13,

adt_ipev() 6-49, 6-52, 6-53 6-14, 6-15, 6-51
adt_mmb_bset() 6-53
adt_omg_exi() 5-2, 6-54 T
adt_omg_ini() 5-1, 6-55, 6-57, 6-58, terminal identification 6-11, 6-13, 6-16,
6-59, 6-61 6-51
adt_ovv_brw() 5-2, 6-57
adt_ovv_exi() 5-2, 6-58 U
adt_ovv_get() 5-2, 6-59
user identification 6-11, 6-13, 6-16,
adt_ovv_ini() 5-2, 6-57, 6-61
6-51
adt_params() 6-62
adt_pstfix() 6-25, 6-29, 6-48, 6-64
adt_sgp_clo() 6-66
adt_sgp_crea() 6-66
adt_sgp_del() 6-67, 6-71
adt_sgp_ins() 6-68, 6-71
adt_sgp_lck() 6-70
adt_sgp_mod() 6-69, 6-71
adt_sgp_ope() 6-72
adt_sgp_read() 6-25, 6-29, 6-48,
6-73
S
selection criteria 3-3, 3-4, 4-4, 6-19,
6-24, 6-25, 6-28, 6-29, 6-48,
6-61
selection expression 3-4, 3-5
selection group 3-5, 6-22, 6-23, 6-68,
6-69, 6-70, 6-71, 6-73
selection group file 3-5, 6-22, 6-25,
6-29, 6-48, 6-62, 6-63, 6-66,
6-67, 6-68, 6-70, 6-71, 6-72,
6-73
sequence number 6-8
for DDB 1-2, 6-8
for timestamp 6-23, 6-24
last sent 6-12, 6-16, 6-17
unexpected 6-17
setup file 6-19, 6-56, 6-61, 6-62, 6-63
setup file parameters 6-62
storage filter 2-2, 2-5, 6-44, 6-45
storage process 2-1, 2-2, 2-3, 2-4, 2-5,
4-1, 4-2, 4-3, 6-45
subject group 6-3, 6-4, 6-6, 6-18, 6-26,
6-32
subject group action 6-3, 6-4, 6-6
subject group action source 6-3, 6-4, 6-6
subject group attribute 6-3, 6-4, 6-6,
6-18, 6-26, 6-32
4 AUDIT/FAST Programmer’s Guide

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction BUS/FAST FAST/TOOLS
Manual DUR Programmer’s Guide
IM50E02E00-01EN/R10.03

IM50E02E00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ....................................................................................0-1
0.1 Objectives ...................................................................0-1
0.2 Intended Audience ......................................................0-1
0.3 Structure of this Document .........................................0-1
0.4 Associated Documents ...............................................0-2
0.5 Conventions and Abbreviations ..................................0-2
1 Introduction ...........................................................................1-1
1.1 Development Considerations ......................................1-1
1.1.1 Possible solutions for concurrent
programming ..................................................1-1
1.1.2 Shared variables .............................................1-2
1.1.3 Message passing ............................................1-2
1.1.4 Choosing a solution .......................................1-2
1.2 Functionality of DUR .................................................1-3
1.2.1 Message passing in DUR ...............................1-3
1.2.2 Event mechanism ...........................................1-5
1.2.3 Debugging facilities .......................................1-6
2 The Dynamic User Region ....................................................2-1
2.1 Using the Dynamic User Region ................................2-1
2.2 The Common Area (BUSCOM) .................................2-1
2.3 Multi-processor Aspects .............................................2-3
3 Message Passing .....................................................................3-1
3.1 Mechanism ..................................................................3-1
3.2 A Send/Receive Session .............................................3-4
3.3 Send Options ...............................................................3-7
3.3.1 Choosing the desired routine .........................3-7
3.3.2 The send-parameter buffer .............................3-7
3.3.4 Change the message size ...............................3-9
3.3.6 How to use the reply required flag ..............3-10
3.3.7 Assigning priority to a message ...................3-10
3.3.8 Change the sender address (alias) ................3-11
3.3.9 Wait for multi-node confirmation ................3-12
3.3.10 Use of queue filling percentage ...................3-13
3.3.11 Use of multi-node time out ..........................3-13
3.3.12 Use of task number ......................................3-14
3.3.13 Sending to redundant node ..........................3-14
3.4 Receive Options ........................................................3-15
DUR Programmer’s Guide iii

Table of Contents
3.4.1 Choosing the desired routine ....................... 3-15

3.4.2 The receive-parameter buffer ...................... 3-15
3.4.3 Define the message buffer ........................... 3-16
3.4.4 Examine the send parameters ...................... 3-17
3.4.5 Specifying the synchronization option ........ 3-18
3.4.6 Read messages from other queues (alias) ... 3-19
3.4.7 Specify a previously created selection
buffer ........................................................... 3-20
3.5 Miscellaneous Routines ........................................... 3-21
3.5.1 Summary of miscellaneous routines ........... 3-21
3.5.2 Routines for initialization ............................ 3-21
3.5.3 Routines to delete messages ........................ 3-22
3.5.4 Routines to create a selection buffer ........... 3-22
3.5.5 Routine for queue-size inquiry .................... 3-25
3.5.6 Routine to cancel pending wait-for-events . 3-26
3.5.7 Routines to obtain node information ........... 3-26
3.5.8 Routine to obtain a one-second time-stamp 3-27
3.5.9 Routine to obtain the own process address . 3-27
3.5.11 Test if a process has been restarted recently 3-28
3.5.12 Detect overflow situations in your
own queue ................................................... 3-29
3.5.13 Routine to test if BUSCOM is locked ......... 3-31
3.5.14 Routine to test if a common is locked ......... 3-31
3.5.15 Routines to exit asynchronous .................... 3-32
3.5.16 Snapshot routine .......................................... 3-32
4 Event Mechanism .................................................................. 4-1
4.1 Principle ..................................................................... 4-1
4.2 Obtain an Event Flag ................................................. 4-3
4.3 Attach and Detach ...................................................... 4-4
4.4 Wait for Events .......................................................... 4-5
4.5 Generate Events ......................................................... 4-6
4.6 Reset Event Flags ....................................................... 4-6
4.7 Using Event Flags for Timing Purposes .................... 4-7
5 Communication Status Monitoring ..................................... 5-1
5.1 Introduction ................................................................ 5-1
5.2 The Mechanism .......................................................... 5-2
5.3 What Information Can be Obtained? ......................... 5-3
5.3.1 Specials for redundant host ........................... 5-5
6 Clock Queue Mechanism ...................................................... 6-1
6.1 Message Generation on Request ................................ 6-1
6.1.1 Introduction ................................................... 6-1
6.1.2 Send messages regularly ............................... 6-2
iv DUR Programmer’s Guide

Table of Contents
6.1.3 Send one message at a specific time ..............6-3

6.1.4 Cancel clock queue requests for messages ....6-3
6.2 Event Generation on Request .....................................6-4
6.2.1 Introduction ...................................................6-4
6.2.2 Generate events at regular intervals ...............6-4
6.2.4 Cancel clock queue requests for events .........6-5
7 Display Utilities ......................................................................7-1
7.1 Functionality ...............................................................7-1
7.2 How to Use the DUR Display Utility .........................7-1
7.3 Options .......................................................................7-2
7.3.1 Analyze messages in a queue (A O) ..............7-2
7.3.2 Log contents of messages being transferred
(A L or I I I) ...................................................7-2
7.3.3 Redirect messages to other destinations
(I I I ) ..............................................................7-3
7.3.4 Generate messages (G) ..................................7-3
7.3.5 Block queues (I B) .........................................7-4
7.3.6 Flush queues (I F) ..........................................7-4
7.3.7 Unlock common data area BUSCOM
(I R U) ............................................................7-4
7.3.8 Loading the time table in BUSCOM
(I R D) ............................................................7-4
8 Reference guide to DUR routines .........................................8-1
8.1 Conventions ................................................................8-1
8.2 Compiling, Linking and Running Programs ..............8-2
8.3 Error Handling ............................................................8-2
8.3.1 How is UMH integrated? ...............................8-3
8.4 Data Structures ...........................................................8-4
8.4.1 Address buffer ...............................................8-4
8.4.2 DUR context ..................................................8-5
8.4.3 Send parameter buffer ....................................8-5
8.4.4 Receive parameter buffer ...............................8-6
8.4.5 Node information buffer ................................8-7
8.4.6 Event block ....................................................8-7
8.4.7 Clock-queue message ....................................8-7
8.4.8 Communication status message .....................8-8
8.4.9 Overflow indication message ........................8-8
8.4.10 User attachment message ...............................8-8
8.4.11 Snap information ...........................................8-8
8.5 Routines ....................................................................8-10
8.5.1 Compare Two Addresses .............................8-11
8.5.2 Fill Defaults of Address Struct ....................8-12
8.5.3 Initialize Address Buffer ..............................8-13
DUR Programmer’s Guide v

Table of Contents
8.5.4 Obtain Own Process Address ...................... 8-14

8.5.5 Test Whether a Common Area is Locked ... 8-15
8.5.6 Request Program to Exit ............................. 8-16
8.5.7 Attach to (M)DUR ...................................... 8-17
8.5.8 Check attached to (M)DUR ........................ 8-19
8.5.9 Obtain Process Identification number ......... 8-20
8.5.10 Attach to (M)DUR common memory ......... 8-21
8.5.11 Overflow-Detection Request ...................... 8-22
8.5.12 Cancel User Attachment updates ................ 8-23
8.5.13 Cancel Wait-for-Message / Queue-size ...... 8-24
8.5.14 Cancel Clock-Queue Requests for Events .. 8-25
8.5.15 Cancel Clock Queue Requests
for Messages ............................................... 8-26
8.5.16 Put Request to Clock Queue for an Event ... 8-27
8.5.17 Put Request to Clock Queue for a Message 8-28
8.5.18 Convert logical address ............................... 8-30
8.5.19 Convert Node Name to Node Number ........ 8-31
8.5.20 Cancel Request for Message on Channel
Status Change .............................................. 8-32
8.5.21 Cancel a Request for a Message on Node
Status Change .............................................. 8-33
8.5.22 Request a Message on
Channel Status Change ............................... 8-34
8.5.23 Request a Message on Node Status Change 8-36
8.5.24 Delete Messages From a Queue .................. 8-38
8.5.25 Delete Reply Messages from a Queue ........ 8-39
8.5.26 Delete Request Messages From a Queue .... 8-40
8.5.27 Detach from DUR ....................................... 8-41
8.5.28 Attach to an Event Flag ............................... 8-42
8.5.29 Cancel Timer Event flag ............................. 8-43
8.5.30 Detach From an Event flag ......................... 8-44
8.5.31 Fix an Event Flag so That it Survives a
Process Stop ................................................ 8-45
8.5.32 Generate an Event ....................................... 8-46
8.5.33 Use Event Flag as Timer ............................. 8-47
8.5.34 Obtain the First Event Flag ......................... 8-48
8.5.35 Obtain Multiple Event Flags ....................... 8-49
8.5.36 Reset an Event Flag ..................................... 8-50
8.5.37 Test State of an Event Flag ........................ 8-51
8.5.38 Release a Previously Fixed Event Flag ....... 8-52
8.5.39 Wait for a Single Event ............................... 8-53
8.5.40 Wait for Multiple Events ............................. 8-54
8.5.41 Get Own Node Number ............................. 8-57
8.5.42 Get queue size ............................................. 8-58
vi DUR Programmer’s Guide

Table of Contents
8.5.43 Get variable ..................................................8-59

8.5.44 Get Node Information ..................................8-60
8.5.45 Modify queue size .......................................8-61
8.5.46 Wait for Queue Size .....................................8-62
8.5.47 Receive any Message ...................................8-65
8.5.48 Initialize Receive Parameter Buffer .............8-67
8.5.49 Receive Reply Message ...............................8-69
8.5.50 Receive Request-Message ...........................8-71
8.5.51 Request an Overflow Indication for
Own Queue ..................................................8-73
8.5.52 Request a User Attachment .........................8-74
8.5.53 Select Messages by Sender Reference .........8-75
8.5.54 Select Messages by Expedite Status ............8-76
8.5.55 Select Messages by Message-id ...................8-77
8.5.56 Select Messages by Reply Status .................8-79
8.5.57 Select Messages by Task Number ...............8-80
8.5.58 Set variable ..................................................8-82
8.5.59 Exit when a SIGINT or SIGHUP Signal
is Received ...................................................8-83
8.5.60 Snap information in the common area .........8-84
8.5.61 Send Request Message ................................8-86
8.5.62 Initialize Send Parameter Buffer .................8-88
8.5.63 Send and Receive Message ..........................8-89
8.5.64 Send Reply Message ....................................8-91
8.5.65 Get a One-second Time-stamp ....................8-92
8.5.66 Test Whether BUSCOM is Locked .............8-92
8.5.67 Attach to DUR and Initialize UMH .............8-93
Appendix A:Using (M)DUR on UNIX systems .............................A-1
A.1 Compiling, Linking and Running
(M)DUR Programs ....................................................A-1
A.2 Process Names ...........................................................A-1
A.3 Event Mechanism ......................................................A-1
Appendix B:Using (M)DUR on Windows systems ....................... B-1
B.1 Compiling, Linking and Running
(M)DUR Programs .................................................... B-1
B.2 Process Names ........................................................... B-1
B.3 Event Mechanism ...................................................... B-1
DUR Programmer’s Guide vii

Table of Contents
viii DUR Programmer’s Guide

Preface Objectives
0 Preface
0.1 Objectives
The manual has the following objectives:
functionality of the message passing mechanism Dynamic User
Region (DUR).
• To provide experienced users with a reference for the use of DUR.

language. The reader is assumed to have knowledge of the Unsolicited
Message Handler (UMH) (see Section 0.4 - Associated Documents).

This manual contains 8 chapters and a number of appendices. Chapters
1 to 7 can be regarded as a tutorial for all mechanisms covered by DUR,
in particular message passing and event mechanism. Chapter 8 is a
reference guide for programmers who are already familiar with DUR.
• Chapter 1 introduces the reader to the DUR concept.
• Chapter 2 describes the common memory area used by DUR.
• Chapter 3 describes the message passing mechanism and
summarizes all the available options.
• Chapter 4 describes the event mechanism and summarizes the
options available.
• Chapter 5 describes the clock queue mechanism. This chapter
requires knowledge of both the message passing mechanism and
event mechanism.
• Chapter 6 describes the Communication Status Monitoring
mechanism. This chapter requires knowledge of both the message
passing mechanism and the clock queue mechanism.
• Chapter 7 describes the DUR display utility, providing on-line
facilities for manipulating message transfer.
DUR Programmer’s Guide 0-1

Associated Documents Preface

handling are described. Routine syntax is summarized in
alphabetical order.

1 FAST/TOOLS Installation Manual
This manual provides the information necessary to install
BUS/FAST on your system.
2 UMH Programmer’s Guide, BUS/FAST Vol. 2
This provides a description of the standard error logging facilities
which are used by the DUR functions.
3 FAST/SUPPORT Library (FSL) Programmer’s Guide, BUS/FAST
Vol. 3.
This contains a description of standard routines available. Some of
these are referred to in this manual (e.g. conversion routines).

CONVENTION MEANING
() Parentheses when used in routine syntax to
passed.
[] Brackets indicate that the enclosed item is
optional.
DUR_NOWAIT.

input.
0-2 DUR Programmer’s Guide


returns.
CONVENTION MEANING
output.
literally.
n.u. not used.
a terminal.
from the user.
&& Same as logical AND function
|| Same as logical OR function.
a==b True if a equals b.
a!=b True if a does not equal b.


Introduction Development Considerations
1 Introduction
1.1 Development Considerations

A typical characteristic of a real-time system is the fact that it supports
synchronization between a directly linked environment and the
application functions related to that environment.
In most cases, this implies that, for industrial real-time control systems,
application functions are executed on a time scale of milliseconds.
Generally speaking, slower application functions also reside in the
system, to serve relatively slow peripherals, for example.
As a typical example, consider a simple alarm logger that scans its input
signals at 10 millisecond intervals while printing change-of-state texts
on a hard-copy device. In most cases the software function printing
change-of-state texts will run in a much slower cycle than the function
scanning the input signals.
The execution of multiple or concurrent software processes is an
inevitable consequence of every non-trivial real-time system. The
management of such processes is sufficiently handled by any
multi-programming (or multi-tasking) operating system as long as these
are completely isolated from each other. If, however, communication
and/or synchronization is required between the processes, most
operating systems fail to support adequate functionality.
1.1.1 Possible solutions for concurrent

programming
Basically there are two methods which might solve the problems of
concurrent programming techniques:
• Solutions based on the shared usage of a memory section
• Solutions based on the exchange of data in the form of messages.
The first principle is known as the ‘shared variable’ concept, the latter
as the ‘message passing’ concept.

Development Considerations Introduction
1.1.2 Shared variables

Sharing a memory section between multiple concurrently executing
processes is the most primitive form of communication and/or
synchronization solutions. Communication is established by a process
reading data from the shared memory which is written there by one or
more processes running in parallel.
Several concepts are used for synchronization. The simplest one of these
is the ‘busy waiting’ mechanism: a process periodically checks whether
a shared variable satisfies the synchronization condition. Higher
abstractions for synchronization are ‘semaphores’, ‘critical regions’ and
‘monitors’.
An advantage of the shared variable concept is the low overhead which
is involved in the basic mechanism. A disadvantage is the fact that it is
difficult to implement in a distributed environment, especially where
physically shared memory is not possible.
1.1.3 Message passing

The message passing mechanism supports both communication and
synchronization via the exchange of messages. An important difference
with the shared variable concept lies in the fact that reading is
destructive: once a message has been read by its receiver, it no longer
exists in the system.
This is also the basis for synchronization, since receiving processes are
unable to read a message until the sending process has written (or, more
precisely, generated) one. Further refinements of this basic
synchronization method can be added on both the send and receive side,
allowing, for example, a receiving process to wait for the arrival of any
message (or a particular message).
One of the advantages of the message passing concept is that it can be
used on both non-distributed and distributed systems; it is even possible
to mask the differences between the two alternatives.
1.1.4 Choosing a solution

Concurrent programming is a central theme in many of the
developments in recent years. Modern programming languages such as
ADA and MODULA-2 incorporate many of these concepts. The idea
behind such languages is that it is a better way of supporting concurrent
programming within the machine-independent language, than simply
relying on (often machine-dependent) operating systems. Making

Introduction Functionality of DUR
practical use of these programming languages was - and still is - not

Feasibility feasible for many system integrators, the main problems being the
restricted availability of production-quality compilers and the lack of
sufficiently trained software engineers.
As an alternative, message passing may be implemented as a set of
subroutines. In this way, the same functionality is available on different
systems. The DUR package is such an implementation. The set of
routines comprising the functionality of DUR has been written in C
because of the availability of C-compilers on most computers. At the
moment only C-type interfaces are supported.
1.2 Functionality of DUR

The functionality of DUR can be divided into four main parts:
• Message passing
• Event generation
• Clock queue mechanism
• Debugging facilities
1.2.1 Message passing in DUR

Basically, the message passing mechanism provides the means to
transfer messages between various processes. The transfer is performed
at high speed in a defined and traceable way providing a number of
synchronization possibilities and various send and receive options.
The following principles underlie the requirements of the message
passing mechanism.
Send/Receive 1 Asynchronous send/receive mechanism.
Mechanism In a real-time environment, processes cannot afford to wait for
other processes when messages have to be transferred. The send
and receive action must be performed asynchronously from one
another. This means that messages have to be buffered and a
reliable mechanism to coordinate the send and receive action.
DUR provides the means for both synchronous and asynchronous
message transfer between processes.
2 Communication between processes in different nodes.
Processes must be able to communicate both with processes in their
own node and in other nodes. Multi-node DUR (MDUR for short)
provides the same functionality for inter-node communication as
DUR does for processes in a single node.

Functionality of DUR Introduction
Debugging 3 Simple debugging of the message transfer.

Especially in a real-time environment, it is often difficult to monitor
and interpret message transfer between processes.
(M)DUR provides utilities to redirect, ‘snatch’ and generate
messages via the terminal. These utilities provide a powerful tool
for debugging purposes.
The basic mechanism for message passing within DUR is the support of
a SEND and RECEIVE operation. These operations are available in a
wide variety of synchronization options.
Other functions are available for operations of a ‘housekeeping’ nature.
Send options
Messages may be of variable length. However, when a user-definable
limit is exceeded, the message will automatically be divided into smaller
units. In this way, the usage of the common data area of DUR
(BUSCOM) is spread more evenly over time.
The SEND operation supports a wide range of options, including:
• Specification of message priority
• Synchronization options, such as
- Synchronous or asynchronous
- Wait until the receiver queue is shorter than a
specified length.
1 Attaching a message identification number to the message, which
may be used by the receiver to selectively fetch a message from its
queue.
Receive options
The receiver of a message stream has a choice of options for controlling
the reception.
One option is for a filter to be specified on several message attributes to
limit the number of acceptable messages. The filter may be given as a
combination of sender name, message reference number or task number.
Messages whose attributes do not satisfy the filter requirements are left
in the receiver queue. Of the messages that do match the filter
requirements, the first one (which is typically the least recent message
with the highest priority) is retrieved from the queue and made available
to the receiver.

Introduction Functionality of DUR
For situations in which no message may be retrieved from the queue,

either because the queue is empty or because no message satisfies the
filter requirements, the receiver may specify one of two synchronization
options.
• In asynchronous receive-mode, a status parameter is returned to the
receiver indicating the non-availability of an (appropriate)
message.
• In synchronous receive-mode, DUR will stop the receiver until an
appropriate message can be retrieved from the queue. The waiting
time may be limited by the addition of a time-out parameter with
the RECEIVE operation.
Multi-node support
The multi-node variant of DUR (called MDUR) allows message passing
between processes within different computers. To that effect, a
communication line must be available between those nodes. For the
DUR user, the multi-node aspect is only visible in the form of a CPU
identification (node number) which is part of the process identification
of sender or destination.
1.2.2 Event mechanism

The event mechanism supported by (M)DUR has two major application
areas:
• Synchronization of processes
• Simultaneous waiting for various events
Event Flags Events are represented by global event flags. (M)DUR enables
processes to set flags (to generate events) and to wait for event flags to
be set (to wait for events).
Synchronization of processes can be realized by forcing a process to
wait for a particular event. The process will then only continue when the
event is generated.
(M)DUR allows a process to wait for two or more events
simultaneously. Suppose, for instance, that a process has performed an
I/O request, and has sent a message to another process. Now it wants to
wait either for a reply message or for an acknowledgment of the I/O. The
event mechanism provides the means to do so.

Functionality of DUR Introduction
1.2.3 Debugging facilities

An interactive debugging process is available for use on a VDU. The
major function of the utility is the display of the actual state of the shared
memory area (BUSCOM). It shows information on message queues,
waiting tasks (with the reasons for waiting) and the remaining free space
in a queue.
Other functions include:

• Interactive inspection of incoming messages before delivery to the
destination.
• Interactive generation of DUR messages.
• Setting up of path interception blocks, to print the contents of
messages going from a specified sender to a specified destination.
• Setting up of queue re-direction.

The Dynamic User Region Using the Dynamic User Region
2 The Dynamic User Region
2.1 Using the Dynamic User Region

The Dynamic User Region (DUR) provides a number of routines
covering the functionality of message passing and event generation. In
the following chapters, the message passing and event mechanism are
described separately. Each of these subjects consists of a subset of the
available routines and therefore can be regarded as independent of one
another.
In addition to these routines, the Dynamic User Region consists of a
Temporary common memory area which is used both for message passing and event
Storage generation. The area is used for temporarily storing information about
events, processes, interfaces to other nodes, messages etc.
This area is kept transparent to the user and only internal routines access
this area directly. The programmer can only access this area using the
routines provided. An explanation of these routines is given in the
following sections.
2.2 The Common Area (BUSCOM)

The common memory area used by DUR is part of a generally used
common area: BUSCOM. In this common area, relevant data about
processes that use DUR facilities are stored. This information is
essential for DUR. The only processes that are able to participate in
DUR actions are those whose information is present in the common area.
In addition to the storage of process context, BUSCOM is used to
temporarily store messages that need to be transferred from one process
to another. Furthermore, this area contains all internal DUR information
necessary to coordinate both message passing and event generation.
As mentioned earlier, the common area is kept transparent to the
Attaching to programmer and one of the actions the programmer has to take in
BUSCOM connection with BUSCOM is to ’attach’ his process to BUSCOM, i.e. to
put process information into the common area.
The following routines are available to do this:
dur_att() (Attach to DUR)_
dur_umh_init (Attach to DUR and initialize UMH)

The Common Area (BUSCOM) The Dynamic User Region
Process A
Context Buffer
Context Buffer
dur_att()
dur_umh_init()
COMMON
DATA ProcessContext
Process Context
AREA
dur_att () (Attach to DUR)

dur_umh_init () (Attach to Dur and initialize UMH)
Fig. 2-1
The attach routines pass a name as argument. This name will be used in
(M)DUR to refer to this process and is not necessarily the same as the
name by which the process is known to the system. Not specifying a
name will mean that (M)DUR will take the name by which the process
is known to the system.
To reduce the amount of overhead in BUSCOM, we strongly advise
removing the process information from BUSCOM when the process has
Detaching finished using the DUR facilities (e.g. when the process is terminated).
from DUR This is called ’detaching’ from DUR and is done with the routine:
dur_det() (DUR detach)
In addition to the attach routine there is one other routine which is
required to enable DUR to be used. DUR itself (i.e. the internal DUR
routines) uses the standard error handling facility, the Unsolicited
Message Handler (UMH). This means that all processes that make use
of DUR routines must be adapted for use with UMH prior to attaching
to DUR.
Each process has to call the following UMH routine:
umh_res_msg() (Initialize UMH)
Once your program is attached to BUSCOM and has been adapted for
UMH, it will be able to use any of the DUR routines.

The Dynamic User Region Multi-processor Aspects
For the programmer’s convenience, a routine has been provided which

combines the two routines mentioned previously:
umh_res_msg() and dur_att().
Hence, it attaches to BUSCOM as well as adapting for UMH usage
dur_umh_init()
The advantage of this routine is that it results in a reduction in both the
total number of routines necessary and the number of arguments to be
passed.
Normally speaking, this routine will be the one to use. In some
situations, however, it is better use the two routines separately instead
(see dur_umh_init() description).
For detailed information of the error handling, please refer to the UMH
Programmer’s Guide.
2.3 Multi-processor Aspects

Mul- Multi-processor DUR (MDUR) is an optional version of DUR that
ti-Proces- allows messages to be passed to processes which are physically located
sor DUR in other processors (nodes). It also supports the generation of events in
other processors.
In practice, the user will perceive very little difference between the use
of DUR and MDUR, since all routines are identical. The major
difference is the destination address, in which the node number must be
specifically added.
Inter-node communication is performed as follows:
When a message is sent from a sender process to a destination which is
located in another node, a MDUR process takes care of the inter-node
communication. It sends the message to an identical process in the other
node. The latter receives the message and puts it in the requested queue.

Multi-processor Aspects The Dynamic User Region
Node1 Node2
Sender Destination
queue queue
DURM_1 DURM_1
MDUR queue MDUR queue
Transparent
Fig. 2-2 Inter-node communication
The inter-process (inter-node) communication is taken care of by

internal MDUR routines that are transparent to the user. The application
processes communicate only with DUR, while MDUR takes care of the
interface between the nodes.
System In the case of systems that are of a different make or family, it might be
Conversion necessary to convert the messages from one system format to another. In
some systems, for example, the sequence of bytes in a long integer are
swapped. MDUR will not take care of this conversion. This is because
MDUR has no knowledge about the layout of the message. The
conversion must therefore be done in the application. The FAST Support
Library (FSL) provides functions do this conversion.
In this document the abbreviation (M)DUR will be used to indicate that
the description is valid for both DUR and MDUR.

Message Passing Mechanism
3 Message Passing
3.1 Mechanism
The fundamental mechanism for message passing in (M)DUR can be
best explained with the aid of an example.
Suppose two processes, A and B, want to communicate with one
another. Both processes are attached to DUR. As mentioned in the
previous chapter, messages are stored temporarily in the common data
area BUSCOM, i.e. messages are queued for each receiving process.
Figures 3-1 and 3-2 show the two elementary send/receive mechanisms
provided by DUR.
PROCESS A PROCESS B
send receive send receive
parameter parameter parameter parameter
buffer buffer buffer buffer

message message message message
dur_snd() dur_rcv_req()
COMMON queue A
DATA
AREA queue B
dur_snd () (send request message)

dur_rcv_req () (receive request message)
Fig. 3-1 Sending a notification

In the example above, Process A requests Process B to perform a certain
task. In other words, a message is transferred from Process A to Process
B.

Mechanism Message Passing
The significant aspect of this example is that Process A does not expect
Request a message back. We call this message ’a request without a reply being
required’.
The basic mechanism can be divided into two phases:
1 Process A sends the request using the following routine:
dur_snd() (DUR send ’request’ message)
This results in the message being transferred from the buffer of
process A to the queue of process B. In addition to the message,
parameters are also transferred (see example in 2 below). Now
process A is ready and continues with other tasks.
2 Process B, being a serving process, expects requests from other
processes. It therefore continuously waits for messages in its queue,
which is done with routine:
dur_rcv_req() (DUR receive requests)
If a message is present, the routine performs a destructive read, i.e.
the message and parameters are transferred to the buffers of process
B and are removed from the queue. Now the message transfer is
complete.
In the second example, Process A requires information from Process B.
This is the most commonly used message transfer in (M)DUR. The
Reply message sent from process A to B is said to be a request with a reply
required.
As shown in the figures, sending a message not only means that the
actual message is transferred, but also that additional information is
present in a parameter buffer. This additional information consists of
message context (message-id, for example) and flags (reply required
flag, for example).
This send/receive mechanism can be divided into six phases:
1 Prior to calling routine dur_snd() process A has set the ’reply
required’ flag in the send parameter buffer. With dur_snd() the
message is queued for process B together with the additional
information (the reply required flag).
2 Process A starts waiting for the reply with routine dur_rcv_rep().
3 Process B performs a (destructive) read with dur_rcv_req(), i.e. the
message is passed to the buffer of process B and is removed from
its queue. The additional information is passed to the parameter
buffer.
4 Process B detects the ’reply required’ flag being TRUE and puts the
required message in the send buffer.

Message Passing Mechanism
5 Now process B returns this information with routine dur_snd_rep().

6 Finally process A reads this reply from the queue with
dur_rcv_rep().
Note that in the example above, process A did not explicitly state its
address. This (sender) address is added to the message automatically.
PROCESS A PROCESS B
parameter parameter parameter parameter

message message message message
dur_snd() dur_rcv_rep() dur_snd_rep() dur_rcv_req()
COMMON queue A
DATA
AREA queue B
dur_snd () (send request message)

dur_rcv_rep () (receive reply message)
dur_snd_rep () (send reply message)
dur_rcv_req () (receive request message)
Fig. 3-2 Send/reply mechanism
As shown above, it depends on the kind of message which of the routines

are used for sending or receiving the message:
• Requests are sent with routine dur_snd().
• Routine dur_rcv_req() only reads requests from the queue. Reply
messages are ignored (left in the queue).
• Replies are sent with routine dur_snd_rep().
• Routine dur_rcv_rep() only reads reply messages from the queue.
Request messages are ignored (left in the queue).

A Send/Receive Session Message Passing
Synchronous and In figure 3-2 process B waits for requests with only dur_rcv_req().
Asynchronous Evidently process B does not expect (or does not want) to receive
Modes replies.
On the other side process A waits for replies only with dur_rcv_rep().
Even when another process sends a request message, it is ignored by that
process. Process A remains waiting for the reply.
The mechanism described above is called ’synchronous’ mode: process
A actually waits for the reply.
In the ’asynchronous’ mode (one of the receive options) process A can
poll the queue at regular intervals to check if replies have been received
or use the event flag mechanism to signal that a message has been
received
3.2 A Send/Receive Session

The send/receive session that is discussed in this section deals with
typical send and receive options. A detailed description of the more
sophisticated options is given in subsequent sections. This send/receive
session resembles the mechanism as shown in figure 3-2 of the previous
section: the request/reply mechanism.
Before any of the (M)DUR facilities can be used the process has to be
attached to DUR. Furthermore, (M)DUR expects the programs to log the
errors via the standard error handling facility (Unsolicited Message
Handler UMH). Finally, prior to terminating a process, it should be
detached from DUR.
Therefore a typical program that wants to communicate with (M)DUR
contains the following two standard routines:
dur_umh_init()(Attach to the common area and
initialize buffers for the UMH)
dur_det() (Detach from the common area)
Send As mentioned before, in addition to the message, extra information is
Parameters also transferred. This information must be present in a ’parameter
buffer’, which not only contains the destination address, but also
message context (message size, message-id, etc.), flags (reply required,
for example) and implicitly added information (sender address, for
example).
Destination This parameter buffer must be filled prior to calling the send routine. It
Address is obligatory to enter the destination (receiver) address. Note that all
elements of the parameter buffer are directly accessible thereby making

Message Passing A Send/Receive Session
it possible to directly enter an address in the buffer. However, it is

recommended to use the following routine which requires the address to
be passed as argument:
dur_adr_ini() (Initialize address buffer)
The reason for this is that this routine converts the address to the
required standard format. The result is stored in a buffer, which should
be used to fill the parameter buffer (see figure overleaf).
The remaining part of the parameter buffer also has to be initialized
before sending a message. This part contains message context, flags and
send options. In order to set the buffer to a typical (normally used) state,
a routine is available:
Initialize dur_snd_ini() (Initialize send parameter buffer)
This routine stores default values in the parameter buffer for flags and
options.
After initializing the parameter buffer message transfer is possible with
one of the following routines:
dur_snd() (send request message)
dur_snd_rep() (send reply message)
Receive The receiving process also has a parameter buffer. However, in contrast
Parameters to the send parameter buffer (input only) the receive-parameter buffer is
used both for input (the receive options) and output (the received
message-parameters). Before receiving messages, the input part has to
be initialized. In analogy with the sender side, the following routine sets
the parameters to a typical (normally used) state:

A Send/Receive Session Message Passing
dur_adr_ini()
temporary
Temporary
defaults
address
Address
buffer
Buffer
defaults
dur_snd_ini() send receive

send
send send
parameter parameter
parameter parameter dur_rcv_ini()
buffer buffer
buffer buffer
destination
rcv address
address
receive
send receive
send options
options options
options
Fig. 3-3 Initialization

The following example shows a typical program body of a send/receive
program, in which the program requires a message from another process
and waits for the reply. This example should be regarded as an
illustration, to give an idea of a send/receive session. Detailed
explanation is given in the subsequent paragraphs.
Examples
Process A (requester)
dur_umh_init(); /* initialize UMH error buffers and
attach to DUR */
dur_adr_ini() /* specify destination: process B*/
dur_snd_ini(); /* initialize send options */
dur_rcv_ini(); /* initialize receive parameters */
dur_par_snd.reply_required=TRUE
/* set flag reply-required */
dur_snd(); /* send request to process B */
...
dur_rcv_rep(); /* wait for reply message */
...
dur_det(); /* detach from DUR */

Message Passing Send Options
Process B (server)
dur_umh_init(); /* initialize UMH error buffers and
attach to DUR */
dur_rcv_ini(); /* initialize receive parameters */
dur_par_snd.rcv_adr=dur_par_rcv.snd_adr
/* specify the destination
(process A) */
dur_rcv_req(); /* wait for request messages. */
... /* Flag ’reply required’ detected
Fill message-and parameter buf*/
dur_snd_ini(); /* initialize send parameters */
dur_snd_rep(); /* send reply back to process A */
...
dur_det(); /* detach from DUR */
An extensive listing of this example, complete with error handling

routines, can be found in Appendix A.
3.3 Send Options

Selecting an option to specify the send-action that suits your specific
needs is done by:
• Choosing the desired routine
• Specifying the desired option in the parameter buffer.
3.3.1 Choosing the desired routine

Two send routines are available:
dur_snd() (DUR send)
dur_snd_rep() (DUR send reply)
The dur_snd() routine is typically used to transfer request messages,
notifications, or messages which are not replies.
Routine dur_snd_rep() on the other hand, is used purely for sending
reply messages.
3.3.2 The send-parameter buffer

The send-parameter buffer (dur_par_snd) is used to store the following
information:
• Destination specification
- Destination (receiver) address
• Parameters to be sent to the destination transparently.
- Message identification

Send Options Message Passing
- Reply required flag

- Message priority
- Alias sender name
- Alias system type
• Multi node confirmation
- Synchronization mode
The parameter buffer is of the following type:
struct dur_par_snd
{
char *msg_buf_pnt; /*(I) message to be sent*/
int msg_size; /*(I) message size in bytes*/
short msg_id; /*(I) message id*/
struct dur_adr rcv_adr; /*(I) destination address*/
struct dur_adr alias_adr; /*(I) alias sender address*/
TLS_BOOLEAN expedite; /*(I) message priority*/
TLS_BOOLEAN reply_required; /*(I) reply required flag*/
int system_type; /*(I) alias system format type*/
int sync_type; /*(I) multi-node sync and
queue filling percent.*/
int time_out; /*(I) multi-node timeout*/
};
Where (I) signifies input.

Default A routine is available to set the send options to a default state i.e. the one
Settings that is normally used:
dur_snd_ini() (Initialize dur_par_snd)
The following sections give the defaults for each option after being
initialized with this routine.
Where applicable, reference is made to the members of the struct as
described above.
3.3.3 Specify the destination address

The destination (receiver) address consists of 3 elements:
• Node number
• Process name (max 12 characters ASCII)
• Task number
Buffers containing process addresses must be of the following type:

struct dur_adr
For filling address buffers, it is recommended to use the following
routine (which requires the address to be passed as argument)
dur_adr_ini()

Other When the destination is physically located in the same node, it is not
Node necessary to specify the actual node_nr. Specifying 0 for node_nr means
’own node’.
The task number will only be specified when you have subtasks running
in one process. The task number then identifies the task that is
responsible for sending the message. This enables the main process to
return reply messages to the correct task. When there is only one task per
process (i.e. a normal situation) this number should be 0.
As stated earlier, the destination address must be present in the
parameter buffer dur_par_snd. Therefore, when you want to change the
destination, you must pass the desired (new) destination address into the
parameter buffer.
This is done by accessing member rcv_adr of the parameter buffer, as
shown in the following example:
dur_adr_ini(&dur_par_snd.rcv_adr,0,"SLAVE",0);
3.3.4 Change the message size

The value of ’msg_size’ (in bytes) is not only transferred to the
receive-parameter buffer, but is also used by (M)DUR. The actual
transfer will be exactly this size. When the specified size is smaller than
the buffer size, only part of the buffer is transferred. If a number of
buffers are concatenated to one message (cluster) the total message size
must be given. Note that the FSL library provides routines to cluster
messages. The message size may be any value. When a zero size is
specified, only the context present in the parameter buffer (e.g.
message-id) is transferred.
The message size should be equal to or smaller than the size of the
message buffer of the destination. If the message is too long to fit into
the buffer, the receiving process only gets part of the message, with an
error indicating that it was too long.
When the size is greater than the empty space in the receiver queue, an
error message is returned to the sending process.
For inter-node communication, the maximum message size is limited to
a size of 50 Kbytes (typical). This is the size of the internal MDUR
queue for inter-node communication. This size can be changed at
MDUR generation time.
The message size can be specified as a parameter in the initialization
routine dur_snd_ini().

3.3.5 How to use the message-id

When sending a message, it is possible to give it an identification
number. This number is passed to the parameter buffer of the destination
(receiving process).
The message-id is free to use, (M)DUR does not perform any check on
this number.
The message-id is often used as identification of the message type, rather
than of the message itself: the message type indicates to the receiving
process what action it has to perform and what message it has to send
back.
The initialization routine dur_snd_ini() results in:
dur_par_snd.msg_id = 0
3.3.6 How to use the reply required flag

Sending a message with the ’reply required’ flag being TRUE, obliges
the receiving process to return a reply. It goes without saying that the
sender has to receive this reply.
The flag is transferred to the parameter buffer of the receiving process.
This process has to test the flag to find out if a reply is required. The
initialization routine dur_snd_ini() results in:
dur_par_snd.reply_required = FALSE
3.3.7 Assigning priority to a message

You can assign your message two priorities:
• Normal
• Expedite
Expedite messages always have priority over the normal messages.

When the receiving process waits for messages, (M)DUR first scans the
queue for expedited messages.
It should be noted that when the receiver is waiting for replies only, no
request messages are read from the queue, not even when they have
expedite priority.
When the receiver waits for ’any’ message (M)DUR scans the queue in
the following sequence:

1 Expedite reply messages

2 Expedite request messages
3 Normal reply messages
4 Normal request messages
After initialization the expedite flag is set to:

dur_par_snd.expedite=FALSE
3.3.8 Change the sender address (alias)

Normally you do not have to bother about the sender address as it is
automatically added to the message by (M)DUR.
However, (M)DUR does allow you to change the sender address: the
receiving process then ’thinks’ it receives the message from another
process. This is a powerful feature, especially for debugging and test
purposes.
When you want to change the sender address, you will have to fill the
alias buffer in the appropriate way. This buffer is of the type:
struct dur_adr
We recommend the use of dur_adr_ini() to fill this buffer. You must
always fill in the alias information always either explicitly or using
dur_snd_ini() (even when you do not use the alias feature).
The reason is that (M)DUR uses this information in the following way:
Each time you send a message, the alias information is checked against
the default information in BUSCOM.
First the alias node-number is checked. If this number is 0, the default
node-number is taken. Otherwise, the alias node-number is taken.
Subsequently, the alias name is checked. If the name consists of spaces,
the default process name is taken. Else the alias name is taken.
Finally the task number is checked. If the number is 0, the default task
number is taken from the dur_context. If not, the alias task number is
used.
After initialization with dur_snd_ini(), the alias address is set to:
dur_par_snd.alias_adr.node=0;(default node)
dur_par_snd.alias_adr.name=" ";(default process)
dur_par_snd.alias_adr.task=0;(default task)

Alias A problem may be encountered with inter-node communication. As

System Type mentioned in Chapter 2, a conversion of the message contents may be
necessary when a message crosses node boundaries. The FSL library
provides functions to overcome this problem.
(M)DUR automatically adds the system type of the sender to the
message. As a result, the receiver always ’knows’ the format of the
message and how to convert it. But what happens when you have
specified an alias address that is located in another node? In this case,
the receiver will mistakenly take the sender system type for conversion.
That is why the alias system type can be specified also. Note that for
communication between processes in the same node this member does
not have to be specified.
After initialization with routine dur_snd_ini():
dur_par_snd.system_type=0; (own system_type)
3.3.9 Wait for multi-node confirmation

When you send messages to other nodes, you can choose from one of
two send modes:
• Wait until the process in the other node has received the message.
When the message is received by MDUR in the destination node,
the message must be put in the queue of the destination process.
Once this has happened, the node returns a confirmation (see Fig.
3-4).
Node1 Node2
1
Sender Destination
queue
7
(confirmation)
5
6
DURM_1 DURM_1
2
3
queue 4
queue
Fig. 3-4 Multi-node confirmation

• Note that this does not mean that the destination process in the other
queue has actually read the message from the queue already - the
message is merely queued.
Where no confirmation is returned (e.g. the connection with the
node went down) an error will be returned. MDUR takes care of the
time-out: the routine always returns, either successful, or with an
error status.
• Do not wait for confirmation.
The routine returns immediately.
Note that in this mode, the errors coming from the other node (e.g.
destination process unknown) are not returned to your process!
Change the send mode as follows:

dur_par_snd.sync_type = DUR_SYNC_WAIT or
dur_par_snd.sync_type = DUR_SYNC_NOWAIT
Using the initialization routine dur_snd_ini() results in:
dur_par_snd.sync_type = DUR_SYNC_WAIT
3.3.10 Use of queue filling percentage

In the high part of the parameter sync_type a queue filling percentage
can be specified. If, for example 20 is specified, the receiver queue will
not be filled more than 20% by the message sent. If the message will not
fit in the receiver queue, the sender will get the error
DUR_E_QUE_LIM and the receiver will not be notified for queue
overflow. However, in case the message to be stored itself is bigger than
20% of the receiver queue and the receiver queue is empty, the message
will be put in the receiver queue without error. (This last action is always
true, even if the message is bigger than 100% of the receiver queue).
The queue filling percentage can be specified as follows:
dur_par_snd.sync_type |= (<queue filling perc.> *
DUR_SYNC_QLIM_BASE) & DUR_SYNC_QLIM_FIELD;
3.3.11 Use of multi-node time out

The time_out parameter will only be used when a multi-node message
with confirmation is used. In this case during the specified time the
process will wait for confirmation. If this confirmation does not come in
time, the error DUR_F_POS_LOST will be returned and the message
will be internally handled as a non confirmation message.

3.3.12 Use of task number

The dur_adr struct contains a task number as its third element. This
number is meant to be used if multi tasking within one process is
performed.
A process can specify its active task by storing the task number in
the’task’ element of the dur context. If done so, messages sent will
automatically get that task number as part of the originator address. A
receiver process will normally copy the originator address to its reply
destination address (including the task number element) and the multi
tasking process will receive the task number back in the rcv_task
element of the receive parameters. It can use that number for dispatching
the reply to the correct task.
The task number can also be used for synchronizing a send/receive
session. However, when process A logs into process B for example,
process B will normally store the address of the caller in an internal list.
When process A continues with a request with another synchronize
(=task) number, process B will see it as a different caller. To avoid these
problems the task number values are divided into the following ranges:
>= +1 Task number within a process.
0 Default task number, will become -1.
-1 Main task number.
<= -2 Task number is split in 6 (LSB) bits task number and 10
(MSB) bits synchronize number.
This synchronize number must be <= -2 to be assure that
the whole task number is <= -2.
The routine dur_adr_cmp() will detect such synchronization numbers
and will not include them in the compare.
The routine dur_snd_rcv() uses the synchronize feature as default.
3.3.13 Sending to redundant node

When a redundant node pair is configured, both nodes have the same
node number. It is possible to connect these two nodes with an MDUR
connection, however, sending messages to the remote node number will
always direct the message to the own node. By specifying node number
-2 in de dur address, a message will be directed to the remote node with
the same node number. On receive of the message, the remote node will
see node number -2 in the sender address.

Message Passing Receive Options
3.4 Receive Options

For the receive action, you can select an option that best suits your
application. Selecting an option can be done by:
• Choosing the desired routine.
• Specifying the desired options in the ’parameter buffer’.
• Using a ’selection buffer’.
These options are described in the coming sections.
3.4.1 Choosing the desired routine

Three routines are available:
• dur_rcv()DUR receive)
• dur_rcv_req()(DUR receive request)
• dur_rcv_rep()(DUR receive reply)
Routine dur_rcv_req() only reads request messages from the queue.
These are messages that are not requested by the process (notifications,
for example). Replies are ignored and these messages remain in the
queue.
Routine dur_rcv_rep() only reads reply messages from the
queue,-requests are ignored.
Routine dur_rcv() reads messages from the queue irrespective of
whether the message is a reply or a request. In one of the arguments, an
indication of whether the message was a reply or a request is returned.
Each of the routines takes into account the existence and priority of a
selection buffer. If expedited messages are present in the queue, the
routine first takes these out. If a selection buffer was specified, only the
messages meeting the filter requirements are read. Other messages are
ignored but not deleted (see Miscellaneous Functions).
3.4.2 The receive-parameter buffer

As stated earlier, the receive-parameter buffer is used for both input and
output. The parameter buffer can be used to:
• Specify the message buffer (input)
- buffer to receive the message in
- size of this buffer
• Specify the synchronization option (input).
- wait method
- event generation
• Specify the ’alias receiver name’ (input).

Receive Options Message Passing
• Specify a previously created selection buffer (input).

• Examine the send-parameters (output).
- sender address
- message id
- message size
- destination task number
- expedite flag
• reply required flag
• system type
The receive-parameter buffer is of the type as shown below:

struct dur_par_rcv
{
char *msg_buf_pnt; /* (I)message buffer*/
int msg_buf_size; /* (I)buffer size in bytes*/
int msg_size; /* (O)size in bytes*/
TLS_SHORT msg_id; /* (O)message id*/
struct dur_adr snd_adr;/* (O)sender id*/
struct dur_adr alias_adr;/*(I)alias receiver id*/
TLS_SHORT rcv_task; /* (O)destination task
number*/
TLS_BOOLEAN expedite;/* (O)expedite flag*/
TLS_BOOLEAN reply_required;/*(O)reply required flag*/
int system_type; /* (O)system format type*/
int sync_type; /* (I)wait method to use*/
int time_out; /* (I)time-out value*/
struct dur_evt_blk *event_block_pnt;
/* (I)pointer to event blk*/
struct dur_sel_blk *select_buf_pnt;
/* (I)pointer to selection
buffer*/
};
A routine is available to set the receive options to a typical (normally

used) state:
dur_rcv_ini() (Initialize dur_par_rcv)
In the following sections, the defaults after initialization are mentioned
for each option and where applicable, reference is made to the members
of the struct as described above.
3.4.3 Define the message buffer

The receiver of the message must have a buffer which is prepared to
receive messages. The size of this buffer must be equal to or greater than
the longest message to be expected.

In addition to the size of the message, the message layout (datastructure)

must also be take into account. This layout, however, is not always
known beforehand. A convention should be made between the sender
and the receiver in order to ’understand’ messages from each other. This
convention is typically laid down in the message-id. The destination
process prepares a buffer without a specific structure. After it has
received the message, the message-id is interpreted. Depending on the
message-id, the receiver converts the message using a cast expression,
such as shown here:
#define MAX_RCV 1024
#define EXAMPLE_ID 10
struct example *example_ptr;
TLS_LONG inbuf[MAX_RCV/sizeof(TLS_LONG)];
...
if (dur_par_rcv.msg_id==EXAMPLE_ID)
example_ptr = (struct example*)inbuf;
...
Note that the receiver buffer has been declared to be an array of LONGs.
TLS_LONG is specially defined to be 32-bit in each system (see FAST
Support Library). Declaring the array of LONGs is done for reasons of
portability. When you transfer a TLS_LONG, make sure that the
receiver is also able to retrieve the TLS_LONG from the message. In
other words, be sure that the TLS_LONG is received on a TLS_LONG
boundary.
3.4.4 Examine the send parameters

The send parameters are transferred transparently to the
receiver-parameter buffer.
Member msg_size gives the size as specified by the sending process.
(M)DUR transfers a message of exactly this size. If the receive buffer is
smaller than the message size, the message will be truncated and an error
will be returned as soon as the receiver has read the message from the
queue.
The use of the message-id depends on the conventions agreed upon by
the programmers of the different processes.
The sender-id gives the address (node, name and task number) of the
originating process.
The receiver task number indicates which task in the process the
message is meant for (used in the case of multi-tasking in a process
only).

The expedite flag indicates whether or not the message has a high
priority. If the expedite flag is TRUE, it could mean that older messages
(not of the expedite type) than the one just received are still in the queue.
The ’reply required’ indicates whether or not the sender expects a reply
message and should not be confused with ’the message is a reply’
indication. The latter is indicated implicitly by the routine you use.
Routine dur_rcv_rep() only returns reply messages. Routine
dur_rcv_req() only returns request messages.
Routine dur_rcv() returns both, with an indication if the message was a
reply or not. This indication is returned in one of the arguments which
has been passed to the routine.
The last send parameter is system_type. As mentioned in section ’Send
Options’ the system type is merely a number specifying the system type
on which the sender resides.
Programmers have to take care of format conversions of messages
themselves when messages are transferred to other system types.
Conversion routines are available in the FAST/SUPPORT Library.
3.4.5 Specifying the synchronization option

The receiving process has two synchronization options available:
• Synchronous mode (sync_type = DUR_SYNC_WAIT)
• Asynchronous mode (sync_type = DUR_SYNC_NOWAIT)
Actually this option is only significant when no (appropriate) message

is found in the queue. If a message is present, that message will always
be returned immediately, independent of the sync_type.
Three members of the parameter buffer dur_par_rcv are used to indicate
these options:
• dur_par_rcv.time_out
• *dur_par_rcv.event_block_pnt
• dur_par_rcv.sync_type
Synchronous mode
Wait There are two synchronous mode options:
Mode
1 Wait for message with or without time-out
When you wait for a message, the process continues waiting until a
correct message is received. This option requires the time-out value
to be filled in the parameter buffer. This value is specified in

seconds, specifying 0 means no time-out (wait forever).

Event 2 Generate an event when a message of the specified type arrives
Mode (*dur_par_rcv.event_block_pnt!=NULL)
If you want an event to be generated when a message has arrived,
you have to insert *event_block_pnt into the parameter buffer.
When the message is not in the queue, the routine returns
immediately with a warning that no message was found. At the
moment that a message is queued, (M)DUR checks to see whether
the message meets the filter requirements. If so, (M)DUR generates
the event (the event-flag is set).
Although this mode is asynchronous with regard to the (M)DUR
mechanism (the routine returns when no message is found), the use
of this mode is often synchronous.
Eventually the process will start waiting for this event, together
with one or more other events.
The event mechanism is explained in detail in chapter 4.
The synchronous mode is indicated by:
dur_par_rcv.sync_type=DUR_SYNC_WAIT.
Asynchronous mode
Queue Receiving in an asynchronous mode means polling the queue at regular
Polling predefined intervals. If this option is selected, the routine will always
return immediately. If a message is found, it will be returned. If not, an
error is returned. This option merely requires the sync_type to be set to
DUR_SYNC_NOWAIT.
After initializing the parameter buffer with routine dur_rcv_ini():
dur_par_rcv.sync_type = DUR_SYNC_WAIT
*dur_par_rcv.event_block_pnt = NULL (no event block given).
dur_par_rcv.time_out = 0.
This results in the synchronous mode: wait for message without

time-out.
3.4.6 Read messages from other queues (alias)

(M)DUR allows a process to specify another receiver name (an alias).
This alias only affects the receiving routines. DUR will treat the process
as though its name was the alias, resulting in DUR transferring messages

from the alias queue to your process.

You may specify the name of any process attached to DUR and read
messages from its queue as if they were your own.
Great care should be taken when using this feature. The message you
read will never arrive at its destination, unless you return the message
again. In that case the message should be returned to the original queue
sent with an ’alias sender name’ being the original sender.
It is not allowed to specify a process to be the alias when that process is
physically located in another node. Currently only process names known
to DUR in your own node may be used as an alias.
The alias receiver address is of type:
struct dur_adr
You must fill in the alias information, either explicitly or with
dur_rcv_ini() (even when you do not use this alias feature). The reason
is the same as for the sender alias: (M)DUR always takes the alias into
account. When the alias contains ’default’ information, the actual
address is taken. Note that the task number has no significant meaning.
After initialization with dur_rcv_ini, the alias address is set to:
dur_par_rcv.alias_adr.node = 0; (default node)
dur_par_rcv.alias_adr.name = ""(default process)
dur_par_rcv.alias_adr.task = 0; (not significant).
3.4.7 Specify a previously created selection

buffer
A selection buffer can be regarded as a filter. Only messages matching
the selection criteria are read from the queue.
In the parameter buffer you specify which selection buffer is currently
active, by specifying the pointer to that buffer. When you specify NULL,
(M)DUR ignores all selection buffers.
After initialization with dur_rcv_ini():
dur_par_rcv.select_buf_pnt = NULL (no selection
buffer)
For a description of how a selection buffer is created see the following
section - ’Miscellaneous Routines’.

Message Passing Miscellaneous Routines
3.5 Miscellaneous Routines
3.5.1 Summary of miscellaneous routines

Twelve categories of miscellaneous routines are provided:
• Routines for initialization
• Routines to delete messages
• Routines to create a selection buffer
• A routine for queue-size inquiry
• A routine to cancel pending wait-for-events
• Routines to obtain node information
• A routine to obtain a one second time-stamp
• A routine to obtain the own process-address
• A routine to fill the defaults of an address
• A routine to test if a process has been restarted recently
• Routines to detect overflow situations in your own queue
• A routine to test if BUSCOM is locked
• A routine to take snapshots from the common area for monitoring
purposes
3.5.2 Routines for initialization

(M)DUR provides three routines for initialization purposes:
dur_adr_ini() (Initialize address buffers)
dur_snd_ini() (Initialize send-parameter buffer)
dur_rcv_ini() (Initialize receive-parameter buffer)
For advice on how to use these routines, see the previous section.
In all routines where addresses are required (e.g. destination address,
alias address, etc.) it is recommended to use the routine:
dur_adr_ini()
The main advantages of this routine are:
• It converts the name to upper case
• When necessary, it limits the length of the process name to
12 characters.
• When necessary, it increases the length of the name with spaces up
to 12 characters
The name size is typically 12 characters but this size may differ for some
networks (depending on DUR generation).

Miscellaneous Routines Message Passing
In the send-parameter buffer and receive-parameter buffer you specify

the send and receive options respectively. Generally speaking, however,
special options are rarely used.
Routines are provided for initializing these buffers to a default state, in
which most of the options are set to a typical (normally used) state.
Initialization of dur_par_rcv and dur_par_snd is done with the following
routines respectively:
dur_rcv_ini()
dur_snd_ini()
The default state is found in the descriptions in the previous section. A

summary of all defaults can be found in the routine description of
dur_snd_ini() and dur_rcv_ini() in the last chapter.
3.5.3 Routines to delete messages

The following routines are available for deleting messages from a queue.
dur_del_req() (delete request messages)
dur_del_rep()(delete reply messages)
dur_del()(delete both request and reply messages)
The messages are deleted selectively, which means that only the
messages that meet the selection criteria of the selection buffer are
deleted. All other messages are ignored and will therefore remain in the
queue.
When calling the routine, an argument must be passed (max_delete) to
specify the number of messages that have to be deleted. When this
number is greater than the number of messages in the queue, only the
queued messages are deleted and the routine returns: it is not possible to
wait until the requested number has been reached.
3.5.4 Routines to create a selection buffer

One of the receive options is to take the existence of a selection buffer
into account. A selection buffer can be regarded as a filter since only
messages meeting the selection criteria are read. All other messages
remain in the queue. The ’delete message’ facility also checks whether
or not a selection buffer exists.
The messages can be filtered according to the following attributes:
• Sender address
• Message-id

• Receiver task-number
Routines are available for creating a filter that satisfies logical

expressions. These expressions consist of the attributes as operand,
combined with the following relations:
• DUR_EQ(Equal)
• DUR_NE(Not Equal)
• DUR_LT(Less Than)
• DUR_GT(Greater Than)
• DUR_LE(Less Than or Equal)
• DUR_GE(Greater Than or Equal)
Filter expressions can be logically extended to larger expressions with

the following operators:
• DUR_FIRST (Indicates first element of selection buffer)
• DUR_AND (Logical AND function)
• DUR_OR (Logical OR function)
The selection buffer is created using the following routines.

• dur_sel_adr()(select sender address as filter)
• dur_sel_msg()(select message-id as filter)
• dur_sel_tsk()(select receiver task-number as filter)
Every time one of the routines is called, a new entry in the selection
buffer is created. By choosing the routine, you specify the attribute you
want to select on.
With the arguments you can pass:
• The relation with the attribute (e.g. DUR_EQ),
• The operation you want to be performed with the previous entry
(e.g. DUR_AND)
• The evaluation level of the operation (similar to the use of
parentheses in mathematical expressions)
The priority of the levels is ascending, i.e. level 0 has a higher
priority than level 1. Operations with level 0 are evaluated first,
followed by operations with level 1, and so on.
The example overleaf illustrates the creation of a selection buffer.
Example
Suppose you only want to receive the following messages:
• Messages coming from process A, having message-id 63
OR

• Messages coming from process B, having a message-id < 12
The expression can be written as follows:

(Sender=A AND msg-id=63)OR(Sender=B AND msg-id <12)
0 1 0
The two expressions within the brackets must be evaluated first. Both
AND operations have the same level: they may be evaluated
simultaneously. Therefore these operations are given the level 0.
Afterwards the OR operation must be evaluated. This operation is given
level 1.
Creating a selection buffer is done by reading the expression from left to
right and translating it into terms of (M)DUR.
Note that the first entry (sender=A) cannot be given an operation with
the previous entry. Therefore the operation DUR_FIRST must be given,
indicating the first entry.
Hereafter a summary is given of the routines that have to be called,
together with the arguments for each routine. For detailed information
of the routines reference should be made to Chapter 6.
First element
Routine to use : dur_sel_adr()
Operation with previous element: DUR_FIRST
Level of operation : Not significant
Relation : DUR_EQ
Operand : process A
Second element
Routine to use : dur_sel_msg()
Operation with previous element: DUR_AND
Level of operation : 0
Relation : DUR_EQ
Operand : 63
Third element
Routine to use : dur_sel_adr()
Operation with previous element: DUR_OR
Relation : DUR_EQ
Operand : process B

Fourth element
Routine to use : dur_sel_msg()
Operation with previous element: DUR_AND
Relation : DUR_LT
Operand : 12
An extensive listing of this example is included in Appendix A.
3.5.5 Routine for queue-size inquiry

For some application purposes it might be desirable to wait for the queue
size (number of queued messages or percentage) to drop below a certain
value before sending messages to that process.
In other situations one might want to wait for the local queue-size to
grow above a certain value before reading the messages from the queue.
The following routine provides this possibility:
dur_que_size() (wait for queue size)
This routine can be used in several modes. One of the arguments passed
with this routine is the wait_type. You can select one of the following
wait_types:
• DUR_WAIT_NOT
Return the actual queue size (number of
messages in the queue).
• DUR_WAIT_PRC_NOT
Return the actual queue size as a percentage (0-100%).
• DUR_WAIT_LOW
Wait until the queue drops below the specified number
of messages.
• DUR_WAIT_PRC_LOW
Wait until the queue drops below the specified percentage.
• DUR_WAIT_HIGH
Wait until the queue-size grows above the specified
number of messages.
• DUR_WAIT_PRC_HIGH
Wait until the queue-size grows above the specified percentage
number of messages.
• DUR_WAIT_LOW_EVENT
Generates an event when the queue drops below the
specified number of messages.

• DUR_WAIT_PRC_LOW_EVENT
Generates an event when the queue drops below the specified
percentage.
• DUR_WAIT_HIGH_EVENT
Generate an event when the queue-size has grown above
the specified number of messages.
• DUR_WAIT_HIGH_PRC_EVENT
Generate an event when the queue-size has grown above the
specified percentage.
You can wait for a certain queue-size for any queue, including your own
or the queue of a process in another node.
As an example, consider the following situation:
Two processes perform the same function. One is primary, the other is
secondary. When the primary becomes ’overloaded’, the secondary
starts assisting the master. In order to realize this, the secondary checks
the queue-size of the primary. The secondary will only start assisting and
reading the messages from the primary-queue (with a receiver
alias-name) when the size grows above a certain limit.
3.5.6 Routine to cancel pending wait-for-events

Using receive routines or using the queue-size inquiry routine, you may
have specified certain events. (M)DUR will continuously search for a
certain condition to become true. (M)DUR is said to be
waiting-for-events. It can occur that even though these events have not
been generated yet, you do not want to wait for them anymore. In that
case, you can cancel these pending wait-for-events using routine
dur_can_wts()
All active wait-for-events for the calling process are cancelled, except
for those in another node. Note that it is not possible to specify one
specific event and that when you detach from DUR, all pending
wait-for-events are cancelled automatically.
3.5.7 Routines to obtain node information

Three routines are available to obtain node information:
dur_get_node()(obtain own node number)
dur_inf_node()(obtain node name and communication
status with that node)
dur_cnv_node()(convert node name to node number)

Routine dur_inf_node() returns a status, just as the majority of the other

routines do. Routines dur_get_node() and dur_cnv_node() do not return
a status. Both routines return the node number.
Routine dur_get_node() returns the number of your own node.
Using dur_inf_node() you can obtain additional information about a
node, such as the status of the communication with that node (good or
bad) and the node name in ASCII (24 characters max).
When you have the node name, but not the node number, use routine
dur_cnv_node(), which converts name to number.
3.5.8 Routine to obtain a one-second time-stamp

The routine used to obtain the GMT time in seconds since 1 Jan 1970
00:00 hour is:
dur_time_sec()
It is advised to use this routine where time-stamps are required with no
more than 1 or 2 second resolution.
This routine does not perform a system call to obtain the time in seconds,
but uses internal (M)DUR information. Depending on the (M)DUR
generation, this value is updated on a 1 or 2 second interval basis by an
internal (M)DUR process. You can check which interval cycle is used
with the DUR Display Utility (DUR MO).
3.5.9 Routine to obtain the own process address

In some situations it is absolutely essential to know the address of your
own process. As an example, suppose your process requests another
process to send data. The request explicitly specifies the process to
which the information should be sent. That process may either be your
own process or another one. But how do you obtain the address of your
own process? The following routine is provided for this:
dur_adr_own()
This routine fills an address struct that you pass as argument with your
own node number, process name and current task number.
3.5.10 Routines to compare and complete dur addresses

A routine is provided which compares two DUR addresses:
dur_adr_cmp()

This routine returns TRUE if the addresses are identical and FALSE if
not. However, situations may occur in which one of the addresses
contains a full address specification, while the other contains defaults
(e.g. in order to make the program independent of the node in which it
runs). In these situations, dur_adr_cmp() will return FALSE.
EXAMPLE:
Suppose the node on which the program runs is node 4. The two
addresses are:
struct dur_adr address_1
{
0, /* default node*/
PROCESS_A/* process name*/
-1 /* main task*/
};
struct dur_adr address_2

{
4, /* node number*/
PROCESS_A,/* process name*/
-1 /* main task*/
};
These addresses are the same, but comparison of these will not result in
a match. In order to fill in the defaults of an address struct, use routine
dur_adr_def()
After calling this routine with address_1 as argument, both addresses
will be identical.
3.5.11 Test if a process has been restarted recently

You might find yourself in a situation in which you want to know
whether a specific process is ’still’ present or has re-appeared. It might
be necessary to perform certain actions in the latter case. Consider, for
example, a database management process that locks and unlocks files. A
certain process has a number of files locked and crashes. The same
process is restarted again and tries to open those files again. The
database manager will not approve since the files are still locked. This
causes a so-called ’deadly embrace’ situation.
Using a special routine, the database manager is now able to establish
whether that process was restarted or not and will unlock all files that
were owned by the ’old’ process. How is this distinction achieved?

Each time a process is attached to BUSCOM, it obtains a sequence

number. This sequence number is unique since it is incremented each
time a new process attaches. Existing numbers are never used more than
once. This number can be obtained by using routine:
dur_att_cnt()
If the number, the so called ’attach count’, is different when you call the
routine after a certain period of time, you know that the process has been
restarted in that period.
It is also possible to obtain the ’attach count’ of a process running on
another node. However care must be taken that his routine call is not
made to often for processes running on another node. This is because
calling the routine for a ’remote process’ puts a relatively high stress on
the DURM connections.
3.5.12 Detect overflow situations in your

own queue
Attaching to BUSCOM requires a queue size to be specified. This size
must be carefully chosen so that it will be large enough to handle worst
case situations. As worst case situations are hard to predict, it may occur
that the queue will be too small. In that case messages that do not fit in
the queue are lost (the sender obtains an error message indicating a
queue overflow). Normally, however, the receiving process will never
know that this situation has occurred. In order to detect this situation you
can request an overflow indication. The mechanism is as follows:

Overflow detected:
queue is blocked
Max queue size Queue is unblocked
Block limit (%)
Queue Time
Size Queue blocked
Filled Blocked
Empty space
QUEUE
Normal message Overflow message
Fig. 3-5 Overflow Detection
In the Fig. 3-5 a process has requested an overflow indication from

DUR.
Now suppose that the queue starts growing and that the queue becomes
completely full. All new messages sent to process A will be rejected. As
soon as the queue becomes shorter again an extra message will be added
- the overflow indication. Sooner or later the process will read that
message and detect the overflow situation. But what happens when the
overflow situation continues to exist for a longer period of time? Then
numerous overflow messages will be put in the queue: when the queue
becomes shorter, the overflow message is entered, a new message
arrives but does not fit, resulting in another overflow situation. If space
allows, a new overflow message will be entered, and so on. In order to
avoid such undesirable situations, it is possible to block the queue
temporarily. You do this by specifying a ’block value’ expressed as a
percentage. The queue will remain blocked until this percentage of the
queue is reached. From that moment on new messages can enter the
queue. As a result, the overflow message will always be followed by a
number of ’real’ messages.
The routine to request this indication is
dur_req_ovf()

One of the parameters that this routine expects is the message-id. This
message-id will be used in the overflow message, allowing you to
distinguish overflow messages from other messages. Another parameter
is the restart value between 0 and 100. This value expresses the size in
percentage terms. When you are no longer interested in overflow
messages, the request can be canceled with routine:
dur_can_ovf().
Note: Do not confuse the notion ’blocked’ with the one used in
DUR display. In the case described above, messages will
not be put in the blocked queue but will be rejected
completely.
3.5.13 Routine to test if BUSCOM is locked

Normally speaking, locking BUSCOM is completely covered by the
DUR routines. You will never need to bother about this locking
mechanism. There is, however, one exception - the interrupt routine.
Such a routine will not be handled properly by the normal locking
mechanism since there is always the possibility of an interrupt occurring
when BUSCOM is locked. This problem can only be solved in the
interrupt routine itself. Therefore a special routine is available that
allows you to check if BUSCOM is locked or not. Suppose, for example,
that a process allows a Ctrl-C command to abort it. As a result of this
command an interrupt routine is entered. When this Ctrl-C is not
handled properly, it is possible that the process will be aborted, leaving
BUSCOM locked. That will cause the whole system to hang. Typically,
such a situation is handled as follows: when the interrupt routine is
entered, the lock is tested. If BUSCOM appears to be locked, the routine
is exited directly. To the user it will appear as though the Ctrl-C was not
seen. Normally this will never be a problem, as BUSCOM is locked only
in very small, distinct, time segments. The chances that BUSCOM will
be locked are very low.
The routine is:
dur_tst_lock().
3.5.14 Routine to test if a common is locked

BUS/FAST maintains locks to other common areas besides BUSCOM.
Examples of these commons are the DATABASE/FAST and
ITEM/FAST common. Normally speaking, locking an common area is
completely covered by the DUR routines. You will never need to bother
about this locking mechanism. There is, however, one exception - the

interrupt routine. Such a routine will not be handled properly by the

normal locking mechanism since there is always the possibility of an
interrupt occurring when a common area is locked.
The routine dur_any_lock() tests whether or not the process has one
of the common areas locked.
The routine dur_tst_lock() tests whether or not BUSCOM is locked.
3.5.15 Routines to exit asynchronous

Sometime an interactive process is aborted by the user (he types Ctrl-C)
or a process is aborted by a signal request (for example SIGHUP). These
events are handled asynchronous. A common area may be locked when
the event is handled. Exiting the process at that moment causes common
areas to be locked forever. In such case you must use the routine
dur_ask_exit() to exit the process. When the process has no common
area locked, this routine causes to exit the process immediately. When
the a common area is locked, the process continues and exits when it has
unlocked the common area.
The routine dur_sig_exit() makes your life easier. It sets up a signal
routine, during initialization of your process, which is called when the
program receives SIGINT or a SIGHUP signal. The signal routine called
dur_ask_exit() for you.
3.5.16 Snapshot routine

To build a monitor process, information can be extracted from the
common area like:
• General information like node name and number.
• List of all queues and their characteristics and performance.
• List of all know nodes and their characteristics.
• List of the locking performance.
You use the routine dur_snap() to obtain a snapshot and you use the
same routine to browse through the snap result to extract the information
required.

Event Mechanism Principle
4 Event Mechanism
4.1 Principle
The event mechanism in (M)DUR makes it possible to synchronize
processes running concurrently, or to wait simultaneously for a number
of events to occur.
Event Flags The mechanism is based on the use of global event flags.
An event flag represents an event. A process can wait for an event to
occur, by waiting for a particular event flag to be set. Another process
’generates’ the event by setting the corresponding event flag.
The advantages of using the event mechanism are twofold:
1 System events can be mixed with (M)DUR events. On some
systems, for example, it is possible to wait for (M)DUR messages
and asynchronous I/O simultaneously.
2 Event flags are allocated centrally by (M)DUR. This stops events
being allocated twice by mistake.
Figure 4-1 shows which actions have to be taken to realize
synchronization between two processes. Suppose process A waits for an
event to occur and generation of that event is done by process B.

Principle Event Mechanism
PROCESS A PROCESS B
parameter event block event block parameter
4 dur_evt_att()
1 dur_evt_obt()
2 dur_snd()
5 dur_evt_wait() 3 dur_rcv()
7 dur_evt_rst() 6 dur_evt_gen()
COMMON event context

DATA
AREA
queue B
Fig. 4-1 Event mechanism
1 Process A indicates to (M)DUR that it wants to use (obtain) an

event flag. DUR finds a free flag and returns an ’event block’ to
process A. This event block contains all information necessary to
identify the event flag. Obtaining the event flag is done with
dur_evt_obt().
2 Process A passes the event block with dur_snd() to the other
process to make the existence of the event flag known to process B.
3 Process B receives the event block with dur_rcv().
4 Now Process B makes itself known to the event flag by ’attaching’
to this particular flag with dur_evt_att().
5 Meanwhile, Process A has started waiting for the event to occur
with dur_evt_wait(). Waiting for an event means that the process
becomes inactive until the event occurs.
6 At the appropriate time, Process B generates the event by setting the
flag with dur_evt_gen().
7 As a result, Process A continues and resets the flag with
dur_evt_rst() in order to enable subsequent events to occur.
Note that steps 5 through 7 may be repeated and that step 6 may be
performed before step 5.

Event Mechanism Obtain an Event Flag
A process that has obtained the event flag is called the owner of the flag.
(M)DUR allows one process to wait for more than one event
simultaneously.
(M)DUR allows more than one process to generate the same event. This
means that more than one process may attach to the same event flag. The
event block must then be passed to each of them.
Moreover, (M)DUR allows more than one process to wait for the same
event to occur.
Note: The latter might introduce complications in the
application program. In that case, which of the waiting
processes will receive the event first is not defined. In
addition, whether or not the remaining processes will
be activated after the flag has been reset has not been
defined.
With the multiprocessor option (MDUR), it is possible to set event flags
in other nodes. This allows processes to be synchronized beyond the
physical processor boundaries.
The only consequence for the programmer is that the event block has to
be sent to the process in the other node. The event block automatically
contains the node information.
Note that it is not possible to be the owner of an event flag in another
node, i.e. it is not possible to wait for an event whose event flag is
physically located in another processor.
There are some parameters that depend on the system in which (M)DUR
is implemented. An example of system-dependent parameters is the
maximum number of events (flags) that can be used (see appendices).
4.2 Obtain an Event Flag

When a process wants to wait for a particular event to occur it has to
obtain an event flag representing that event. The process is said to be ’the
owner’ of that flag.
You do not have to specify which flag you want since (M)DUR
automatically allocates a free flag. Two routines are available:
• dur_evt_obt()
• dur_evt_orl()
Always use routine dur_evt_obt to obtain the first event flag.

Attach and Detach Event Mechanism
Use dur_evt_orl (DUR event flag obtain related) for the remaining event
flags only when more than one event is required. The reason that another
routine has to be used is due to implementation constraints. A process
can only wait for ’related’ flags simultaneously. Using this routine you
indicate to DUR that another event flag has been obtained already. DUR
takes care of finding a related flag (see Section: Wait For Events).
When the routine returns, the calling process receives an event block.
This event block contains all information necessary to identify that
particular event flag. You must pass that event block to each process that
may generate the event.
4.3 Attach and Detach

When you want a process to generate an event that other processes are
waiting for, you must attach the process to the particular event flag first
using routine:
dur_evt_att()
Only routines that are attached to (M)DUR are allowed to attach to an
event flag. Before a process can attach, it must receive an event block
from the owner of the flag. When this is a process which is physically
located in another processor, the event block contains the correct node
number.
Once attached, the process is able to set that particular event flag to
generate the corresponding events. When a process is owner of the flag
it does not need to attach. This is done implicitly when the flag is
obtained.
Detaching from the flag is done with routine:
dur_evt_det()
When the process detaches from (M)DUR it is automatically detached
from the event flags as well. Note that owners of a flag also have to
detach explicitly.
Detaching is done in order to release flags again. Only a limited number
of event flags are available per system (see appendices). A flag will only
be released after all processes have been detached from that flag.

Event Mechanism Wait for Events
4.4 Wait for Events

When a process waits for an event, it remains inactive until that event
occurs. A process can wait for one single event or for multiple events
simultaneously. Furthermore a timer may be used for time-out purposes.
The routines available are:
dur_evt_wait()
dur_evt_wor()
You can use the routine dur_evt_wait (DUR event wait) when the
process must wait for one single event only.
The routine dur_evt_wor (DUR event wait for logical OR) can be used
to wait for a number of related events simultaneously. The routine
returns as soon as one of the event flags is set (logical OR of all flags).
Additionally you can use routine dur_evt_wor for time-out purposes. In
that case you must obtain and attach an event flag, which will be used as
a timer. The timer is started with a value in seconds, that you pass as
argument. When the timer expires your time-out event is generated.
A typical use is as follows:
Suppose process A reads a file when it receives an event. This file
contains information to be processed. Process B reads commands from
the terminal. Each time a command is entered, process B enters the
command in the file and generates an event for process A. This might be
implemented with the program body as depicted below:
------------------- Process A ------------------------
dur_att();
...
dur_evt_obt();/* flag is also reset*/
...
dur_snd();/* send event flag to B*/
...
while (1)
{
while (file not empty)
{
dur_evt_rst();
process contents of the file
(may also be empty file)
}
dur_evt_wait();
}
---------------------- Process B --------------------
dur_att()
...
dur_rcv()
...

Generate Events Event Mechanism
while (1)
{
Read from screen;
Put in file;
dur_evt_gen();
}
...
Note: The processing of the file in the example is performed
between the reset of the flag and the wait-for-event.
This must be done in order to avoid missing events.
4.5 Generate Events

Once you have attached the process to an event flag, it is possible to
generate events by setting that flag using routine:
dur_evt_gen()
When more processes are attached to the same event flag, the flag might
be set already before you generate the event. In that case no action is
performed. The flag remains set as it was. No facility is implemented to
check the status of the event flag.
For integration of (M)DUR events with system events, reference should
be made to the system-dependent information in the appendices.
4.6 Reset Event Flags

In order to find out the state of an event flag, you may test the state with
the routine:
dur_evt_test().
This routine enables you to poll the flag in a loop, as an alternative for
the wait-for-event routines.
After having tested the flag, the flag can be reset by means of routine:
dur_evt_rst()
In normal circumstances only the owner will reset the flag.
Complications might arise, however, when more than one process is the
owner of the same flag.

Event Mechanism Using Event Flags for Timing Purposes
When you reset the flag immediately after the occurrence of the event,
whether or not the other waiting processes will still receive that event is
not defined. The application programmer should be aware of this
problem and act accordingly.
4.7 Using Event Flags for Timing Purposes

Two routines are available to use event flags as a timer:
• dur_evt_mark()
• dur_evt_can()
Using routine dur_evt_mark() you may mark a flag to be a timer. The
timer is started as soon as the routine is called. The time-out is specified
in milli-seconds. When the specified time has elapsed, the event is
generated. When you want to cancel the timer before it is expired, use
dur_evt_can().

Using Event Flags for Timing Purposes Event Mechanism

Communication Status Monitoring Introduction
5 Communication Status
Monitoring
5.1 Introduction
Multi Processor DUR communicates with other nodes via special
processes. A typical configuration is depicted below.
Node 1
DURM_2
3 2 Node 3
DURM_1 2 3
1
3 DURM_3
1
4 1 2 DURM_4
2
DURM_5
Node 2 1
2
5
3
1 Physical line
DURM_2
1 no.
3
DURM_1 1 Logical channel
no.
Fig. 6-1 Inter-node communication via MDUR
Inter-node Communication between nodes is performed by so-called MDUR

Communication processes. These processes take care of all communication that is
performed via a specific physical line. This physical line, however, may
have been connected to two or more computers (nodes).
Consider for example an Ethernet link that is connected to a number of
nodes. Via this link, communication with each of these nodes is
Logical
Channels possible. Each of these possibilities is called a logical channel. In other
words: a physical line represents one or more logical channels. In the
figure above, three nodes communicate with each other.

The Mechanism Communication Status Monitoring
Let us examine node 3, which communicates with both node 1 and node
2. Physical line number 4 is connected to node 1 and 2. This allows node
3 to communicate via two channels: via channel 1 to node 1, via channel
2 to node 2. Note that the channels are always numbered in relation to
the sender. This means that the channel has the same number as the
destination node. There is no similar convention for physical lines. This
number is a set-up parameter with the only restriction that it should be
unique in the same node. Hence, the same physical line may have a
different number on the various nodes. Consider node 3 again, for
example. Process DURM_5 supports a physical line with number 5.
This same line has number 1 in node 2.
Note: To avoid confusion, let the number of the DURM
process be identical to the physical line number.
There are many situations in which you would like to monitor the status
of communication links. Questions like "How can I be informed when
the communication status with node 2 changes?" or "How can I find out
about the communication status of channel 3?" could arise. The
following mechanism is available to obtain such information.
5.2 The Mechanism

The mechanism for communication status monitoring strongly
resembles the Clock Queue Mechanism. Very briefly, the mechanism is
as follows:
1 You request the Communication Status Manager (CSM) to send a
message when the communication status changes.
2 The CSM continuously monitors the status of all MDUR processes
in its node.
3 When the requested communication status does change, a status
message with some previously specified information is returned.
The request remains active until a ’cancel’ command is given.

Communication Status Monitoring What Information Can be Obtained?
Node 3
CSM
4 1 2 DURM_4 Message
Request
2
Node 2 DURM_5 Process A
3 2
5
DURM_2
1
3 1 Physical line
DURM_1 no.
1 Logical channel
no.
Fig. 6- 2 Clock queue mechanism
5.3 What Information Can be Obtained?

Communication As previously discussed, it is possible to have contact with another node
Status via one or more logical channels. Now you may be interested either in
the availability of a specific channel or (more likely) in the possibility of
communicating with a specific node irrespective of the channel. You
send such a request using routines:
dur_com_i_cr() (DUR COMunication Insert of a Channel
Request)
dur_com_i_nr() (DUR COMunication Insert of a Node
Request)
These routines require a number of parameters to be passed, some of
which are described below.
• Channel/Node
Depending on the routine to be used, either the desired channel or
the desired node is to be passed.
• Immediate
You will receive the status immediately irrespective of whether
there is a status change or not

What Information Can be Obtained? Communication Status Monitoring
• Destination address
The destination process to which the status message is to be sent.
This will typically be your own address. It is, however, possible to
route the messages to another destination.
• Reference number
This number is used to uniquely distinguish the request from others:
the combination of destination address and reference number is
unique.
• The message-id
This message-id will be returned in the status message. When you
receive a status message in your application, the message will have
a message-id as specified by you in the request.
The message will have the following layout:
• Node
When you asked for a message for node status change, this member
will contain that node number. When you requested a message for
a channel status change, the node number will contain the channel
number.
• Line
This member is only significant when you requested a message for
a channel status change. In the case of a node request, this number
will be 0.
In the example above, node 3 has two channels through which it can
communicate with node 2. The difference between these channels
is the physical line. If you requested a message on status change of
channel 2, the CSM will monitor both channels. When the status of
one of them changes, the physical line number indicates the
channel.
• Old Status
Either True (channel is OK) or False
• New Status
Either True (channel is OK) or False. Note that there is one
situation in which the New status is equal to the old status: if you
requested a message immediately.
• Reference number
This number was passed in the request and is returned
transparently.

Communication Status Monitoring What Information Can be Obtained?
In order to cancel the request again, two routines are available: one for
channel status change requests and one for node status change request:
dur_com_c_cr() (DUR COMmunication Cancel Channel
Request)
dur_com_c_nr() (DUR COMmunication Cancel Node
Request)
For these routines, the destination/reference number combination is
important since this unique combination is used to identify the request
to delete.
5.3.1 Specials for redundant host

Normally a host connection is reported by the node number of the
remote host. In case of a redundant host this would be the same number
than our own node. To avoid confusion, connections with a remote host
with the same node number will be reported with node/channel number
-2.
Remote node communication changes are only reported when explicit is
asked for node/channel -2, so asking for node up/down messages for
node -1 will report all node up/down changes except for the redundant
node.

What Information Can be Obtained? Communication Status Monitoring

Clock Queue Mechanism Message Generation on Request
6 Clock Queue Mechanism
6.1 Message Generation on Request
6.1.1 Introduction
There are many situations in which an application needs to send
messages at regular intervals. In order to eliminate the need to write
special timer processes for this purpose, the Clock Queue Mechanism
(CQM) has been introduced.
Request for messages
Process
Process CQM
CQM
A
A
Queue
Messages at
regular intervals
Fig. 5-1 Clock queue mechanism
Consider a situation in which you write an application program to test

the status of a communication link every 60 seconds. Instead of creating
a timer in the conventional way, you now put a request to the Clock
Queue Manager (CQM) “Please send me a message every 60 seconds”.
From that moment on the CQM will start sending messages with the
specified interval. These messages will be put in your queue just as any
other message.
Note: The name ’clock queue’ should not be confused with the
notion ’message queue’ as used for message passing.

Message Generation on Request Clock Queue Mechanism
6.1.2 Send messages regularly

Let us have a look at the request and the CQM messages.
A request is a normal (M)DUR message. This request is put to the clock
queue manager using routine dur_clq_imsg(). This request contains:
• The destination address
• A message-id
• The interval
• The start time
• A reference code
The destination address will typically be your own address. It is,

however, possible to route the messages to another process by
specifying another destination.
The message-id you specify in the request will be returned in the CQM
message transparently. It makes a distinction between different
messages possible.
The period between consecutive messages is specified in interval time
and is given in seconds and microseconds.
The start time specifies at what time the CQM should send the first
message. Specifying a start time that lies in the past will cause a message
to be sent immediately. From that moment on, the message will be sent
at intervals as though the first message had actually been sent at start
time. Messages between the start time and the present time are,
therefore, not transmitted, only the initial message
start time messages
0 10 20 30
request interval
start time
Fig. 5-2 Clock Queue
This feature offers the possibility to fix the interval exactly on the time
axis. Suppose, for example, that you want a message to be sent every 10
seconds, exactly on the 9 -> 10 transition of the clock. In this case you

Clock Queue Mechanism Message Generation on Request
specify the time 0 to be the start time, which is 1 January 1970 00:00:00.
The messages will be sent at intervals of 10 seconds as if the first
message had been sent at time 0.
The reference code in the request is added to uniquely distinguish
requests from one another. Suppose, for example, you want your
application to stop scanning the status of the communication link. In that
case you want to tell the CQM to cancel your request. In order to
uniquely identify that request the combination of destination address and
reference code is used.
When you receive a CQM message in your application, the message
(with the specified message id) will have the following layout:
• Requested Time
• Sent Time
• Interval Time
• Reference Code
The Requested Time is the time the CQM should have sent the message.
The Sent Time is the time the message was actually sent by the CQM.
The Interval Time and Reference Code are a copy of the values in the
request.
6.1.3 Send one message at a specific time

When an interval time of 0 is specified, the message will be sent once
and once only: at the ’start time’.
If that time has already elapsed, it will be sent immediately at the time
of request. Once the message is sent, the request is canceled
automatically.
6.1.4 Cancel clock queue requests for messages

In order to stop messages from being sent, a cancel command is sent
with routine dur_clq_cmsg(). This routine requires the unique
combination of destination address and reference number to identify
which request to cancel.
When the destination process is detached, all requests related to that
process are automatically deleted.

Event Generation on Request Clock Queue Mechanism
6.2 Event Generation on Request
6.2.1 Introduction
There are situations in which the use of messages for timing purposes is
rather cumbersome. Instead of waiting for messages, you want to wait
for multiple events. Suppose, for example, your application program is
taking care of read/write actions via the communication link. An event
is generated as soon as the line is ready to send/receive. Additionally you
also want the program to check the status of the link each 60 seconds.
Instead of using the method mentioned previously, it is more elegant to
use the Event mechanism. You now request the CQM to generate a
request at intervals of 60 seconds. This enables you to start waiting for
multiple events (using dur_evt_wor).
6.2.2 Generate events at regular intervals

A request is put to the CQM with routine dur_clq_ievt(). This request
contains the following information:
• The event flag to use
• The Start Time
• The Interval Time
• The Reference Number
Before putting this request, you must first obtain an event flag. For
details, see Chapter 4 Event Mechanism.
Once the request has been made, the first event is generated exactly on
the ’start time’ and the event will be generated repeatedly at the specified
interval. The purpose of the reference code is the same as for (M)DUR
messages: to uniquely distinguish requests from one another.
A new request with an existing reference code will result in the old
request being deleted.
For the use of the start time and interval time, see the previous section.
6.2.3 Generate events at a specific time

When an interval time of 0 is specified, the event will only be generated
once: at the ’start time’. If that time has already elapsed, it will be
generated immediately. Once it has been generated, the request is
automatically canceled.

Clock Queue Mechanism Event Generation on Request
6.2.4 Cancel clock queue requests for events

In order to stop the events being generated, a cancel command is sent
with routine dur_clq_cevt(). This routine requires the reference code to
uniquely identify the request to cancel.
When the destination process is detached, all requests related to that
process are deleted automatically.

Event Generation on Request Clock Queue Mechanism

Display Utilities Functionality
7 Display Utilities
7.1 Functionality
Easy The DUR Display utility provides a number of powerful tools to make
Debugging the debugging of programs easier. The following main functions are
present:
• Monitoring overall message transfer
This option provides a simple (passive) way to monitor the message
transfer from one process to another.
• Configure DUR functions
This option allows you to configure the logical addressing table
on-line and to activate changed daylight saving time definitions.
• Analyzing messages
This option allows you to inspect a specific message which is
present in a queue. It also enables you to log the contents of all
messages being transferred from one process to another.
• Generate messages from the terminal
You may assemble a message at your terminal and send it to any
process in the system.
• Intervene in routing of messages or (M)DUR functions.
These options directly interfere with the (M)DUR actions.
Examples are: flushing queues, redirecting messages, blocking
queues etc. These options should be used with care as they might
alter the processing flow of running programs.
7.2 How to Use the DUR Display Utility

This utility can be started from any terminal connected to a system on
which (M)DUR is running. The utility is activated by simply typing:
DUR
followed by additional commands, if desired.
The user is guided through the utility by means of a menu-based
command structure. Options in the menus are selected by typing the first
letter(s) of the desired option.
For each option, HELP information is available, obtained by entering
the letter ’H’ followed by the desired option.

Options Display Utilities
When the utility is started on a console, printing all the menus is a waste
of paper. So in order to disable the printing of menus, enter command
’-m’. In order to start the menu print-out again: enter ’+m’
To step back through the menu path, enter the ’<’ command.
Experienced users often know the path to reach the desired information
by heart. Therefore the DUR Display utility accepts a number of options
in one command. The various letters (representing commands) should
be separated by a space or a comma character. For example:
M A
results in the display of the status of all queues present in this node. The
menus corresponding to these commands will not be shown.
The dynamic displays, i.e. those displays that are updated continuously,
can be exited in one way only by pressing <ctrl C>. The menus as they
are presented will not be discussed here, as they are self explanatory.
This chapter only highlights some specific options, which require some
extra information. For all other options, the reader is referred to the
on-line HELP information. It is recommended to walk through all menu
options once, in order to get acquainted with the various possibilities.
Note: The DUR Display facility can also be started from the
command line with parameters, e.g. dur M A.
7.3 Options
The options mentioned below can be entered by means of the commands
as specified between parentheses ().
7.3.1 Analyze messages in a queue (A O)

Sometimes a specific message is not accepted by the destination process,
because of an incorrect message identification number, for example.
This option enables you to check the contents of a message in a queue in
order to establish the reason for rejection.
It does not affect (M)DUR since a copy is made of the message to be
analyzed. This copy will be truncated if the message exceeds 1000 bytes.
The contents will be displayed on the terminal.
7.3.2 Log contents of messages being transferred

Display Utilities Options
(A L or I I I)
Messages transferred from one process to another may be intercepted for
logging purposes. To make this possible, you must create an intercept
block. This is a kind of filter which is used by (M)DUR. Each message
being queued in any of the queues present is checked against this filter
and those that match up are routed to the printer. In the intercept block,
you specify the sender address, the destination, the message-id, etc.
This option will affect the (M)DUR performance to some extent since
(M)DUR will check all messages being sent by any of the processes
against the specified selection criteria.
The messages that meet the selection criteria are logged. However,
(M)DUR does not know the structure of the message and will therefore
log the message in various representations:
• Hexadecimal, in bytes and in TLS_LONG format
• Decimal, in bytes, words and TLS_LONG format
• ASCII
• Floating point notation
7.3.3 Redirect messages to other destinations

(I I I )
Redirection also affects the message flow in a significant manner and
therefore might disturb synchronization of processes.
Again, an intercept block must be created in order to specify which
messages should be redirected. Now you also have to specify to which
process the messages must be sent. When a message meets the criteria,
the message will be redirected as specified. Note that the original
destination will no longer receive this message.
The comments about performance in the previous section also apply
here.
7.3.4 Generate messages (G)

This option allows you to create messages on the terminal and to send it
to any process in the system (even in other nodes). In order to save
created messages, an option is available to store them on your current
directory before sending. Note that both the message contents and the
message attributes (parameter buffer) must be filled. By specifying an
alias address you can simulate being another process.

Options Display Utilities
7.3.5 Block queues (I B)

When you want to disable a process from receiving any message, you
may ’block’ its queue. This results in all newly received messages being
shunted to a temporary queue. If desired, you can also put all messages
currently in the queue to be transferred to the temporary queue.
The messages of the blocked queue can now be examined one by one.
After examination each message may be put in the actual queue again,
deleted or left in the temporary queue, as desired.
Note that this disturbs the message flow a great deal, and may also
disturb synchronization between related processes. It does not, however,
affect other processes, either in terms of performance or of processing.
7.3.6 Flush queues (I F)

Using this option you can selectively delete messages present in the
queue of a specified process. You have to specify a selection block in
which you specify which messages should be deleted. Additionally, you
may limit the number of messages to be deleted by specifying a
maximum.
7.3.7 Unlock common data area BUSCOM

(I R U)
It may happen that a program is aborted at the moment that the common
area is locked. This might be caused by a program crash (very unlikely)
or a manual action (e.g. interrupting the debugger when in locked
situation). In that case BUSCOM remains locked and none of the
processes using BUSCOM can continue: the whole application is
stopped. This option unlocks BUSCOM again. Note that BUSCOM
might be corrupt. To be sure of a non-corrupted BUSCOM, you have to
run the DUR initialization process (see the FAST/TOOLS Installation
Manual).
7.3.8 Loading the time table in BUSCOM

(I R D)
The file time_table.sup can be found on directory tls_sup. This table
contains summer/winter time transition points. This file may be
modified (using a ordinary text editor) and loaded afterwards with this
utility. After loading, the new table is immediately active.

Reference guide to DUR routines Conventions
8 Reference guide to DUR

routines
8.1 Conventions
All (M)DUR routines have C-type interfaces. The syntax of all routines
as well as the examples comply with C Language Bindings.
In the routine descriptions the pointer to each parameter - not being a
scalar argument - is declared.
Note: Unless otherwise stated, the parameter itself has to be
declared as well!
The direction of the argument is indicated with:
• (R) - indicates the return value of the routine, which in most cases
is a TLS_BOOLEAN returning TRUE or FALSE.
• (I) - indicates that the buffer must contain information which will
be used by the routine.
• (O) - indicates that information is returned in that argument.
• (M) - is a combination of both: it means that the contents of the
buffer you pass as input might be modified when the routine
returns.
Example: the syntax of routine dur_rcv() looks like this:
Syntax [status=] dur_rcv (dur_cont, err_cont, dur_par_rcv,
reply_found)
Arguments TLS_BOOLEAN status; /* (R) TRUE (success) */

struct dur_context *dur_cont;
/* (I) DUR context */
struct umh_context *err_cont;
/* (M) UMH error context */
struct dur_par_rcv *dur_par_rcv;
/* (M) Parameters */
TLS_BOOLEAN *reply_found; /* (O) TRUE if reply */
Virtually all routines return a TLS_BOOLEAN as status indicator. In the

syntax this is indicated with [status=]. Normally, however, this return
value will not be put in a variable, but will be tested directly e.g.:

Compiling, Linking and Running Programs Reference guide to DUR routines
if(!dur_routine())
{
*/ Error encountered.Use UMH to log errors */
}
The type TLS_BOOLEAN is defined in header file global.h (which is
included in tools.h).
In certain routines, it is necessary to enter symbol definitions. These are
defined in dur.h which must always be included in your source.
The symbol definitions are written in upper case, e.g. the dur_rcv()
routine requires a sync-type to be entered. The sync-type may be
DUR_SYNC_NOWAIT or DUR_SYNC_WAIT.
The names of the routines in (M)DUR and the names of the data structs
start with the three letters ’DUR’.
Note: Do not use a routine or variable name in your
application that start with these letters.
8.2 Compiling, Linking and Running

Programs
Before you can use (M)DUR in your programs, the following actions
have to be performed:
• (M)DUR must be installed
• tools.h must be included
• dur.h must be included
• Sources must be linked with the BUS libraries
The (M)DUR package can be run on several computer architectures,

each having their own specific characteristics. Therefore, an appendix is
included for each of the systems (Appendix C and onwards).
8.3 Error Handling

Nearly all (M)DUR routines use standard error handling with the UMH
facilities. These routines require a buffer to be passed as argument in
which error context is returned. When a routine returns it will contain
either error information or status information. Errors are normally
logged, status information is used to test on. In the routine description
(section 8.5) you will only find error codes indicated that are useful to
test on. In appendix B you will find a list of all error and status messages
that can be returned by (M)DUR calls.

Reference guide to DUR routines Error Handling
8.3.1 How is UMH integrated?

The (M)DUR routines perform a umh_set_code() in the case of an error.
This means that the buffer is cleared and filled with the error (or
warning) message. When the routine returns with status FALSE, the
buffer contains only the most recent error message or messages. When
the routine returns with status TRUE, the contents of the error buffer
remain unchanged.
We recommend using the following program body to log (M)DUR
errors:
...

...
if (!dur_routine())
{ /* an error has been detected
*/
umh_log(err_cont);/* use UMH to log error */
...
}
When you want to add an error message to the buffer and return to the
calling routine, you may use the following program body:
...

...
if (!dur_routine())
{
umh_add_code(err_cont, ERROR_CODE);
return FALSE;
}
Some of the (M)DUR routines return warnings or errors that the

application programmer might want to test on. These messages are
mentioned in the description of the routines when applicable.
All messages, i.e. serious and fatal errors, are listed in Appendix B
together with a short description of the possible cause.
When you want to test the returned error message, you can use the body
shown overleaf:

Data Structures Reference guide to DUR routines
...
...
if (!dur_rcv())
{ /* DUR error example */
if (umh_error(err_cont) == DUR_E_TIMEOUT)
{
... /* handle time-out error */
}
else
{
umh_log(error); /* log all other errors*/
}
}
For more detailed information about error handling please consult the
UMH Programmer’s Guide.
8.4 Data Structures

The following data structures are of importance for the application
programmer. It is possible to alter some of these data structures, while
others may only be read. Never alter the contents of a structure not
mentioned in this section!
8.4.1 Address buffer

struct dur_adr
{
TLS_SHORT node; /*(I) System node */
char name[DUR_PRC_NAM_SIZ]; /*(I)Process name */
TLS_SHORT task; /*(I) Task number */
};
• All members of this struct may be accessed.
• The process name is given in ASCII (is not terminated with a zero).
• Specifying 0 for node means: default (local node). Other legal node
numbers are in range 1 - 254 inclusive.
• Specifying 0 for task number can have various meanings:
- In a receiver address it means ’main-task’.
- In an alias sender address it means the task number which is
currently active in dur_context)
- In an alias receive, the task number has no meaning at all.
• Specifying -1 for task number means ’main-task’ (in the case of
sub-tasks in a process).

Reference guide to DUR routines Data Structures
• Specifying a negative number other than -1 means that the task

number field is divided into a task number (6 bits) and a
synchronization number (10 bits).
• Specifying a negative number for node is reserved.
Note: DUR_PRC_NAM_SIZ is defined in dur.h. Under no
circumstances is it allowed to alter
DUR_PRC_NAM_SIZ, as this will lead to problems
with inter-node communication.
8.4.2 DUR context

struct dur_context
{
TLS_SHORT task; /* Active task number*/
int *own_rhb; /* Internal use only
*/
TLS_LONG proc_id; /* Id of this process
*/
char *access_check;
/* Internal use only*/
};
Only member task may be altered, and only then when multi-tasking in
a single process.
This number indicates the task number in the sender reference. The
receiver knows which task the message came from. Normally this will
be task -1 (main process). In the case of sub-tasking, the main process
has to change this member to indicate which of the tasks is active. When
the number is 0 (default) than the number will be changed to -1 (main
task).
8.4.3 Send parameter buffer

struct dur_par_snd
{
char *msg_buf_pnt; /*(I)pointer to msg
buf */
int msg_size; /*(I) message size */
TLS_SHORT msg_id; /*(I) message ID */
struct dur_adr rcv_adr; /*(I) receiver address */
struct dur_adr alias_adr; /*(I) alias address */
TLS_BOOLEAN expedite; /*(I) expedite flag */
TLS_BOOLEAN reply_required; /*(I) reply required
flag */
int system_type; /*(I) alias system
format */
int sync_type; /*(I) node confirmation
and queue filling

limit */
int time_out; /*(I) MDUR send timeout */
};
All members of this struct may be altered.

The following equations are allowed:
sync_type = DUR_SYNC_NOWAIT; /* asynchronous (do not
wait for node
confirmation) */
sync_type = DUR_SYNC_WAIT; /* synchronous (wait for
node confirmation) */
When DUR_SYNC_WAIT is used together with the time_out
parameter, during the time specified the process will wait for
confirmation. If confirmation does not come in time, the error
DUR_F_POS_LOST will be returned and internally the message will be
handled as DUR_SYNC_NOWAIT.
In the high part of element sync_type a queue filling limit can be
specified:
sync_type |= (<queue filling perc> * DUR_SYNC_QLIM_BASE)
& DUR_SYNC_QLIM_FIELD;
Normally, the system type is filled automatically by (M)DUR.
Conversion routines are available in the FSL library for converting
messages from one system to another.
8.4.4 Receive parameter buffer

struct dur_par_rcv
{
char *msg_buf_pnt; /*(I) pointer to msg buf */
int msg_buf_size; /*(I) message buffer size */
int msg_size; /*(O) message size */
TLS_SHORT msg_id; /*(O) message ID */
struct dur_adr snd_adr; /*(O) sender ID */
struct dur_adr alias_adr; /*(I) alias receive ID */
TLS_SHORT rcv_task; /*(O) receiver task number */
TLS_BOOLEAN expedite; /*(O) expedite flag */
TLS_BOOLEAN reply_required; /*(O)reply required flag */
int system_type; /*(O) system format type */
int sync_type; /*(I) wait method to use */
int time_out; /*(I) time-out count to use */
struct dur_evt_blk *event_block_pnt;
/*(I) pnt to event block */
struct dur_sel_blk *select_buf_pnt;
/*(I) pnt to sel. buffer */
};

All input members may be altered. The output members are filled when
a message is received.
The following equations are allowed:
sync_type = DUR_SYNC_NOWAIT /* asynchronous (do not wait
for messages in the queue */
sync_type = DUR_SYNC_WAIT /* synchronous (wait for a
message to be queued */
Using DUR_SYNC_WAIT it is possible to specify an event buffer with

event_block_pnt. If event_block_pnt != NULL, the receive routine will
return immediately. When an appropriate message is queued, the event
will be generated.
When zero is specified for time_out, the timer will not be started.
Negative numbers are reserved.
8.4.5 Node information buffer

struct dur_nod_inf
{
TLS_BOOLEAN communication; /* communication status */
TLS_SHORT node; /* node number */
char name[24]; /* node name */
};
This struct is used to obtain node information with dur_inf_node().

When TRUE the communication status is good, when FALSE, no
communication is possible.
The node name consists of 24 characters, not ending in a 0).
8.4.6 Event block

The struct dur_evt_blk is system-specific. The dur_evt_blk structs are
described in the appendices ’Using (M)DUR on UNIX’, ’Using
(M)DUR on Windows’, etc.
We advise you not to alter members in this struct. The only time it is
permissible to do this is when you want to integrate SYSTEM events and
(M)DUR events (e.g. when you want to wait for these simultaneously).
For more detailed information, please consult the relevant appendix.
8.4.7 Clock-queue message

struct dur_clq_msg

{
TLS_LONG owner_ref; /* owner reference */
struct ftm_time que_time; /* queue entry time */
struct ftm_time int_time; /* interval time */
struct ftm_time act_time; /* activation time */
};
8.4.8 Communication status message

struct dur_com_msg
{
TLS_LONG owner_ref; /* owner reference */
TLS_SHORT line; /* line number (0 = no line) */
TLS_SHORT node; /* node number */
TLS_BOOLEAN old_stat; /* true = OK */
TLS_BOOLEAN new_stat; /* true = OK */
};
8.4.9 Overflow indication message

struct dur_ovf_msg
{
TLS_LONG count; /* overflow count */
};
8.4.10 User attachment message

struct dur_usr_msg
{
struct dur_adr proc; /* user proc */
TLS_LONG att_count; /* attach count */
TLS_LONG reason; /* message reason */
};
8.4.11 Snap information

This structure is used in the dur_snap() routine to return the snapped
information:
union dur_snap_info /* Snapshot info */
{
struct dur_general_info /* General info*/
{
TLS_LONG node_nr; /* Node number*/

TLS_LONG procs; /* Number of processes queues */

TLS_LONG nodes; /* Number of known nodes */
TLS_LONG common_size; /* Common size (bytes) */
TLS_LONG common_act; /* Common in use (bytes) */
TLS_LONG common_high; /* Common max used (bytes) */
TLS_LONG event_size; /* Event count */
TLS_LONG event_act; /* Events in use */
TLS_LONG queue_transferred; /* Messages transferred*/
TLS_LONG queue_failed; /* Messages failed */
char version[10]; /* FAST/TOOLS version */
char customer_name[DUR_CUS_NAM_SIZ+2];
/* Customer name */
char node_name[DUR_NOD_NAM_SIZ+2];
/* Node name */
} general_info;
struct dur_queue_info /* Queues */
{
TLS_LONG process_id; /* OS process id */
TLS_LONG queue_size; /* Queue size (bytes) */
TLS_LONG queue_act; /* Queue in use (bytes) */
TLS_LONG queue_high; /* Queue max in use(bytes) */
TLS_LONG queue_in; /* Messages queued */
TLS_LONG queue_transferred;
/* Messages transferred */
TLS_LONG queue_failed;/* Messages failed */
TLS_BOOLEAN waiting; /* Process is waiting */
char queue_name[DUR_PRC_NAM_SIZ+2];
/* Queue name */
} queue_info;
structdur_node_info /* Nodes */
{
TLS_LONG node_number; /* Node number */
TLS_LONG node_size; /* Node queue size (bytes) */
TLS_LONG node_act; /* Node queue in use (bytes) */
TLS_LONG node_high; /* Node queue max in use (bytes)
*/
TLS_LONG node_in; /* Messages in node queue */
TLS_LONG node_transferred;/* Messages transferred */
TLS_LONG node_failed; /* Messages failed */
TLS_BOOLEAN communication;
/* TRUE when communicating */
TLS_LONG paths; /* via number of paths */
TLS_LONG path_quality;/* Current path quality */
TLS_LONG line; /* DURM line number */

Routines Reference guide to DUR routines
TLS_LONG process_id; /* DURM process id */

char node_name[DUR_NOD_NAM_SIZ+2];
/* Node name */
} node_info;
struct dur_lock_info /* Locks */
{
TLS_LONG collisions; /* Number of collisions */
char lock_name[10]; /* Lock name */
char queue_name[DUR_PRC_NAM_SIZ+2];
/* Current queue that has lock
*/
} lock_info;
};
8.5 Routines

Reference guide to DUR routines Routines
8.5.1 Compare Two Addresses
Syntax [status=]dur_adr_cmp (adr1, adr2)
Arguments TLS_BOOLEAN status; /*(R)TRUE (success) */

struct dur_adr *adr1,*adr2; /*(I)Addresses to compare */
Semantics This routine compares two DUR addresses. The routine returns TRUE
if the addresses are the same, otherwise FALSE.
If the task number of one or both addresses is negative and not -1, the
high order 10 bits of the task number is not compared. These 10 bits
contain the synchronization code. Because of this feature this routine is
preferred, rather than memcmp(), for comparing dur addresses.
Note that this routine does not use UMH or DUR context.
Related dur_adr_def()
routines Routine to replace defaults in an address with real values.

8.5.2 Fill Defaults of Address Struct
Syntax [status=]dur_adr_def (dur_cont, adr)
Arguments TLS_BOOLEAN status; /*(R)Always TRUE (success)*/

struct dur_context *dur_cont; /*(M)Buffer for DUR context */
struct dur_adr *adr; /*(M)Address buffer of which
default must be filled */
Semantics This routine checks whether defaults are specified in the address adr. If
so, it will replace the defaults with the current values.
• If specified node number is 0: it finds the current node number and
replaces it.
• If process name starts with ’ ’ (space), it finds the own process name
and replaces it.
• If task number is 0, it fills in -1 (main task).
Notes This routine always returns TRUE.

8.5.3 Initialize Address Buffer
Syntax [status=]dur_adr_ini (adr, node, name, task)
Arguments TLS_BOOLEAN status; /* (R) Always TRUE (success) */

struct dur_adr *adr; /* (O) Address */
int node; /* (I) Node number */
char *name; /* (I) Process name */
int task; /* (I) Task number */
Semantics This routine is used to fill address buffers. The routine performs the
following actions:
• It converts the name to upper case.
• It truncates the process name to 12 characters (if necessary).
• It extends the name with spaces to 12 characters (if necessary).
When the process name consists of less than 12 characters, the string
must end in a zero. When the name is exactly 12 characters, this is not
necessary.
Notes • For some systems the size of the process name may be different
(depending on DUR generation). Note, however, that the name-size
of the addresses in all connected nodes must be equal to allow
communication to take place.
• Negative node numbers are reserved. For task the only allowed
negative number is -1. Other negative numbers are reserved.

8.5.4 Obtain Own Process Address
Syntax [status=]dur_adr_own (dur_cont, adr)
Arguments TLS_BOOLEAN status; /*(R)Always TRUE*/

struct dur_context *dur_cont; /*(I)DUR context*/
struct dur_adr *adr; /*(O)Address*/
Semantics This routine finds the address of the current process and places it in
argument adr. Note that this is the (M)DUR name and this is not
necessarily the same as the system name.

8.5.5 Test Whether a Common Area is Locked
Syntax [status=] dur_any_lock ()
Arguments TLS_BOOLEAN status; /*(R)TRUE: a common area is locked */
Semantics This routine checks if a common area is locked.

Notes This routine is typically used in interrupt (asynchronous signal handling)
routines to test if the interrupt occurred while the process has locked a
common area.

8.5.6 Request Program to Exit
Syntax [status=] dur_ask_exit (signal)
Arguments TLS_BOOLEAN status; /* (R)Always FALSE*/

int signal; /* (I)The sinal which causes
the program to exit*/
Semantics This routine is used to exit the program while executing an

asynchronous function. The identification of the signal (for example
SIGINT or SIGHUP), which caused the asynchronous function to be
called, is an argument to dur_ask_exit().
When dur_ask_exit() is called and there is no common area locked by
the process then the function does not return and the program exits.
When a common area is locked by the program then the routine returns
FALSE and the program continues until it has released the lock. When
the lock is released, the program exits.
routines to exit the program.
Related dur_sig_exit()
routines Routine to exit when the signal SIGINT or SIGHUP is received.

8.5.7 Attach to (M)DUR
Syntax [status] = dur_att (dur_cont, err_cont, max_storage,

def_size, p_name)
Arguments TLS_BOOLEAN status; /* (R)TRUE:(success) */

struct dur_context *dur_cont; /* (O)DUR context */
struct umh_context *err_cont; /* (M)UMH error context */
int max_storage; /* (I)Maximum queue-size in
Kbyte units */
int def_size; /* (I)Future extension.
Currently not used */
char *p_name; /* (I)Process name in
(M)DUR actions */
Semantics Using the dur_att() routine the process is attached to (M)DUR. By

attaching, a process identifies itself to (M)DUR. As a result, process
information is stored in DURCOM.
The routine returns a context buffer (dur_cont). This buffer has to be
passed as argument in nearly all (M)DUR routines.
The contents of this buffer should not be altered. Only in the case of
multi tasking in one process, it is allowed to change one member:
dur_cont.task
This member is used by the send-message routines to indicate which
task the message originates from. If the task number is -1, the main
process is indicated.
The max_storage determines the maximum queue size (in Kbytes) that
is allowed to queue messages. The required maximum queue-size
depends on the application. A typical value is 2 (Kbytes). Negative
values are reserved.
The default message size (def_size) is currently not used. In later
releases of DUR this value can be read by other processes. It then allows
the sending process to find out what the maximum length of the message
may be. At the moment this value can only be monitored using DUR
DISPLAY routines.
With p_name you are able to specify the name you want the process to
have for (M)DUR actions. When you pass the NULL pointer as
*p_name, the (M)DUR process name will be identical to the system’s
process name. Note that for those systems that give numbers to
processes, the name will be given the letters P_ (Process Ident), followed
by the system number. The process name you supply may end with an

’*’ (for example: ’myprocess_*’). In this case the ’*’ will be replaced by
the process id of the process whenever possible. When the process name
would become too long then the ’*’ is replaced by a random string.
This routine should always be preceded by umh_res_msg(). However, in
the case of an error, this routine is not able to log the error using UMH.
You may only use umh_log() when the process is actually attached to
(M)DUR. Instead, you should use umh_panic() to log the error (see
UMH Programmer’s Guide).
Defaults The task number in the context buffer is set to -1, indicating the main
process (or: no sub-tasking).
Notes • This routine increases the maximum queue size to a block
boundary. Consequently, the actual size reserved might be greater
than actually specified.
• When specifying max_storage, keep in mind that the queue-size
covers all messages, including expedited messages, requests,
replies, and blocked queues (see DUR Display Utilities). Moreover,
the message is divided into units of typically 132 bytes, which
introduces extra space.
• When a process with the same name is already active, the attach
will not succeed.
Related routines dur_umh_init()

This routine combines the dur_att() with the UMH initialization routine
umh_res_msg().
dur_att_chk()
This routine is used to check whether the process is already attached to
(M)DUR. When it is attached then the dur_context is returned.

8.5.8 Check attached to (M)DUR
Syntax [status] = dur_att_chk (dur_cont)
Arguments TLS_BOOLEAN status; /* (R)TRUE:(success)*/

struct dur_context *dur_cont; /* (O)DUR context*/
Semantics This routine is used to check whether the process is attached to

(M)DUR. When the process is already attached then the routine returns
TRUE and the dur_context is filled with the related information else
FALSE is returned an the dur_context remains unchanged.
This routine is particular useful when FAST/TOOLS are accessed
within a shared library and on forehand it is unknown whether the
hosting process is attached to (M)DUR.
Related routines dur_att()
This routine is used to attach to (M)DUR.

8.5.9 Obtain Process Identification number
Syntax [number=] dur_att_cnt (dur_cont, err_cont, process)
Arguments TLS_LONG number; /* (R)Process ident */

struct dur_context *dur_cont; /* (I)DUR context */
struct dur_adr *process; /* (I)Process address */
Semantics This routine is used to obtain the process identification number for a
process attached to the BUSCOM common area. This number is unique
and allocated to a process at the moment the process attaches to the
common area BUSCOM.
It is possible to obtain the identification number of a process running on
another node. However care must be taken that his routine call is not
made to often for processes running on another node. This is because
calling the routine for a ’remote process’ puts a relatively high stress on
the DURM connections
When the requested process is no longer present, the routine returns 0.

If a NULL pointer is passed for the process argument, then the own
process identification number is taken.

8.5.10 Attach to (M)DUR common memory
Syntax (void) dur_att_mem ()
Arguments None.
Semantics This routine is used to attach to the (M)DUR common memory. It does
not attach to (M)DUR as dur_att() does. No other function can be called
then dur_snap().
Related routines dur_snap()
This routine is used to take snapshot from the common memory for
monitoring purposes.

8.5.11 Overflow-Detection Request
Syntax [status=] dur_can_ovf (dur_cont)
Arguments TLS_BOOLEAN status; /*(R)Always TRUE */

struct dur_context *dur_cont; /*(I)DUR context */
Semantics This routine will cancel a request for overflow detection. After this call,
no further overflow detection messages will be sent.
Notes It is possible for an overflow message to be present in the queue (not yet
read) when this command is issued. That message will not be removed.
Related routines dur_req_ovf()

This routine is used to request overflow detection.

8.5.12 Cancel User Attachment updates
Syntax [status=] dur_can_usr (dur_cont, err_cont, node, dest)
Arguments TLS_BOOLEAN status /* (R)TRUE: Success */

struct dur_context *dur_cont; /* (M)DUR context */
struct umh_context *umh_cont; /* (M)UMH error context */
int node; /* (I)node not interested in*/
struct dur_adr *dest; /* (I)address of destination*/
Semantics A process may request to cancel the update messages about all
attachments and detachments other processes make to the DUR common
area. The destination process starts receiving these messages after
(another) process has issued a dur_req_usr() request for it.
Related routines dur_req_usr()

8.5.13 Cancel Wait-for-Message / Queue-size
Syntax [status=]dur_can_wts (dur_cont, err_cont)

Semantics Using dur_can_wts() you can cancel events used for message passing.
The receive-routines as well as the queue-size inquiry routine, can be
used with event generation: (M)DUR continuously checks if a certain
condition is true. If so, (M)DUR generates an event.
This routine stops (M)DUR from checking for these conditions. This
routine only affects the events related to message passing; i.e. only
events related to routines:
• dur_rcv()
• dur_rcv_rep()
• dur_rcv_req()
• dur_que_size()
All other events remain unaffected.
It is not possible to specify a single event. All wait-for-events that are
related to your process are cancelled simultaneously.
Related routines dur_que_size()

This routine deletes pending wait-for-que-size
events for a specific queue only. Wait-for message events are ignored.

8.5.14 Cancel Clock-Queue Requests for Events
Syntax [status=]dur_clq_cevt (dur_cont, err_cont, evt_blk, ref_code)
Arguments TLS_BOOLEAN status; /* (R) Always TRUE */

struct dur_context *dur_cont;/* (I) DUR context */
struct umh_context *err_cont;/* (M) UMH error context */
struct dur_evt_blk *evt_blk; /* (I) Context of previously
obtained event flag*/
TLS_LONG ref_code; /* (I) User reference code */
Semantics This routine cancels event requests from the clock queue which were
previously made with routine dur_clq_ievt().
The event block elements node and number, and the reference code are
used as key in the timer block list.
Related routines dur_clq_cmsg()

This routine is used to cancel requests for messages.

8.5.15 Cancel Clock Queue Requests

for Messages
Syntax [status=]dur_clq_cmsg (dur_cont, err_cont, dest, ref_code)
Arguments TLS_BOOLEAN status; /* (R)Always TRUE */

struct dur_adr *dest; /* (I)Destination */
TLS_LONG ref_code; /* (I)User reference code
*/
Semantics This routine cancels message requests from the clock queue which were
previously made with routine dur_clq_imsg().
The destination dur address and the reference code are used as key in the
timer block list.
Related routines dur_clq_cevt()

This routine is used to cancel requests for events.

8.5.16 Put Request to Clock Queue for an Event
Syntax [status=] dur_clq_ievt (dur_cont, err_cont, start_time,

interval, evt_blk, ref_code,)
TLS_BOOLEAN status; /* (R)TRUE: success */

struct ftm_time *start_time; /* (I) Start time (GMT) */
struct ftm_time *interval; /* (I)Interval (microsecs)
*/
struct dur_evt_blk *evt_blk; /* (I) Obtained event */
TLS_LONG ref_code; /* (I) User reference code
*/
Semantics This routine is used to request the clock queue mechanism to send events
repeatedly.
The first time the event is generated is when the start_time is reached.
Note that start time is in GMT. From that moment on the events are
generated at intervals as specified in interval. If the start_time has
already elapsed, the first event will be generated immediately the request
is queued. The following event will be generated at intervals related to
this start_time as though the first event was actually generated at that
moment.
When the interval is specified as 0, an event will only be generated when
the start_time arrives (or immediately, if the start time lies in the past).
Directly after this event, the request is automatically deleted.
The event block elements node and number and the reference code are
used as key in the timer block list. If a timer block of type event with the
same key is found, that block is re-used.
Notes • You need fsl_ftm.h (or just fsl.h) for the struct ftm_time.
• It is not allowed to request messages to be sent to another node.
Errors DUR_F_ILL_EVT_NOD
It is not allowed to request events on another node.
Related routines dur_clq_imsg()

This routine generates messages to be generated repeatedly

8.5.17 Put Request to Clock Queue for a Message
Syntax [status=] dur_clq_imsg (dur_cont, err_cont, start_time,

interval, dest, ref_code, msg_id)
TLS_BOOLEAN status; /* (R)TRUE: success */

struct ftm_time *start_time; /* (I)Start time */
struct ftm_time *interval; /* (I)Interval(microsecs)
*/
struct dur_adr *dest; /* (I)Destination */
TLS_LONG ref_code; /* (I)User reference code
*/
int msg_id; /* (I)Message-id */
Semantics This routine is used to request the clock queue mechanism to send
messages repeatedly.
The message will be sent to the process as specified in dest.
The first time the message is sent is when the start_time is reached. Note
that start_time is in GMT. From that moment on the messages are sent
at intervals as specified in interval. If the start_time has already elapsed,
the first message will be sent immediately the request is queued. The
following message will be sent at intervals related to this start_time as
though the first message was actually sent at that moment.
When the interval is specified to be 0, only one message will be sent
when the start_time arrives (or immediately, if the start time has
elapsed). Directly after sending the message, the request is deleted
automatically.
The destination dur address and the reference code are used as key in the
timer block list. If a timer block of type message with the same key is
found, that block is re-used.
When the destination process ceases to exist, all requests related to that
process are deleted automatically.

The message sent to the destination process contains the following data:
struct dur_clq_msg
{
TLS_LONG owner_ref; /* Reference Code */
struct ftm_time que_time; /* Time the message should
have been sent */
struct ftm_time int_time; /* Interval in microsecs */
struct ftm_time act_time; /* Time the message was
actually sent */
}
This struct is sent as a message that complies with
FAST/CONVENTIONS:
{
TLS_SHORT msg_size; /* Message size */
TLS_SHORT msg_id; /* Message-id */
struct dur_clq_msg body; /* See previous page */
}
Note that there may be a difference between the time that was requested
and the time the message was actually sent. Therefore both times are
returned in the message.
Notes • You need fsl_ftm.h (or just fsl.h) for the struct ftm_time.
• It is not allowed to request messages to be sent to another node.
Errors DUR_F_UNKNOWN_CLQ
The requested process is not active at the moment.
Related routines dur_clq_ievt()

This routine requests events to be generated repeatedly.

8.5.18 Convert logical address
Syntax [status=] dur_cnv_lnam (dur_cont, err_cont, adr)
Arguments TLS_BOOLEAN status; /* (R)Alwais TRUE */

struct dur_adr *adr; /* (M)Logical address to
convert */
Semantics This routine translates a logical address to a DUR address. See "Logical
address support" in the BUS/FAST Systems Integrator’s Manual for
more information.

8.5.19 Convert Node Name to Node Number
Syntax node = dur_cnv_node (dur_cont, name)
Arguments int node; /* (R)Requested node number */

char *name; /* (I)Node name in ASCII */
Semantics This routine returns the number of a node whose name has been passed.
The name may be less than 24 characters, in which case it must end in a
0 (ASCIZ). If the name has exactly 24 characters, this 0 is not required.
If the routine returns 0, the node name is not found.

8.5.20 Cancel Request for Message on Channel

Status Change
Syntax [status=] dur_com_c_cr (dur_cont, err_cont, dest,

ref_no)

struct umh_context *err_cont; /* (I)UMH error context */
struct dur_adr *dest; /* (I)Destination process
to send message to
*/
TLS_LONG ref_no; /* (I)Reference number */
Semantics This routine is used to cancel a request for a message on channel status
change. Such requests are uniquely distinguished by their combination
of reference number and destination.
Errors None
Related routines dur_com_c_nr()

This routine cancels a request for a message on node status change.

8.5.21 Cancel a Request for a Message on Node

Status Change
Syntax [status=] dur_com_c_nr (dur_cont, err_cont, dest, ref_no)

struct umh_context *err_cont; /* (I)UMH error context */
struct dur_adr *dest; /* (I)Destination to send
message to */
Semantics This routine is used to cancel a request for a message on node status
change. Such requests are uniquely distinguished by their combination
of reference number and destination.
Errors None
Related dur_com_c_cr()
routines This routine cancels a request for a message on channel status change.

8.5.22 Request a Message on

Channel Status Change
Syntax [status=] dur_com_i_cr (dur_cont, err_cont, channel, immed,

dest, ref_no, msg_id)
Arguments TLS_BOOLEAN status; /* (R)TRUE: success*/

int channel; /* (I) Channel for which the
message is requested
*/
TLS_BOOLEAN immed; /* (I)Immediate flag*/
struct dur_adr *dest; /* (I)Address to send
message to*/
TLS_LONG ref_no; /* (I)Reference number*/
int msg_id; /* (I)Message-id of
status message*/
Data The Communication Status Message returned by the CSM has the
types following layout:
{
TLS_SHORT size; /*Size of the message */
TLS_SHORT code; /*Requested message-id */
struct dur_com_msg com_stat_msg; /* Status information
*/
}
in which:
struct dur_com_msg
{
TLS_LONG owner_ref; /* Reference number specified in
request */
TLS_SHORT line; /* Physical line of the channel */
TLS_SHORT node; /* channel number */
TLS_BOOLEAN old_stat; /* Previous status */
TLS_BOOLEAN new_stat; /* New status */
}
Semantics This routine is used to request a message when the status of a specific
channel changes. This routine can also be used to request a
Communication Status Message when communication via any channel
is lost. In that case the channel should be specified to be -1.

Communication status changes with a redundant node with the same

node number as the own node can be requested by using channel number
-2. These communication changes are not reported when channel
number -1 is specified.
The Communication Status Message will have a message-id as specified
in msg_id. It will be sent to the process specified in dest.
A node may have more than one channel to another node. These
channels all have the same node number. That is the reason that you will
find the channel number in member dur_com_msg.node.
In order to distinguish between the channels, the line number is returned.
This line number represents the physical line of the channel. The
old_stat and new_stat are either TRUE (channel OK) or FALSE.
Normally these two complement each other except in one situation.
When the immediate flag was TRUE in the request, old_stat and
new_stat are identical in the first message that is returned.
Notes • It is not allowed to request the message to be sent to a process

located in another node.
• The process that is specified as destination. to which the message is
to be sent, must exist at the time of request. Otherwise an error is
returned.
Errors • DUR_F_ILL_NCR_NOD
The requested process is located on another node
• DUR_F_UNKNOWN_NCR
The process does not exist (anymore).
Related routines dur_com_i_nr()

This routine is used to request a Communication Status Message when
the status of communication with a node changes, regardless of the
channel being used for message transfer.

8.5.23 Request a Message on Node Status Change
Syntax [status=] dur_com_i_nr (dur_cont, err_cont, node, immed,

dest, ref_no, msg_id)
Arguments TLS_BOOLEAN status; /* (R)TRUE:success*/

struct umh_context *umh_cont; /* (M)UMH error context*/
int node; /* (I)Node for which the
message is requested
*/
TLS_BOOLEAN immed; /* (I)Immediate flag*/
struct dur_adr *dest; /* (I)Address to send
message to */
int msg_id; /* (I)Message-id of status
message
*/
Data structures The Communication Status Message returned by the CSM has the
following layout:
{
TLS_SHORT size; /* Size of the message */
TLS_SHORT code; /* Requested message-id */
struct dur_com_msg com_stat_msg; /* status info */
}
in which:
struct dur_com_msg
{
TLS_LONG ref_no; /* Reference nr of request */
TLS_SHORT line; /* Physical line == 0 */
TLS_SHORT node; /* Node number */
TLS_BOOLEAN old_stat; /* Previous status */
TLS_BOOLEAN new_stat; /* New status */
}
Semantics This routine is used to request a message when the status of the
communication with a specific node changes. A node may have more
than one channel of communication to any other node. When either no
communication is possible anymore, or communication becomes
possible again via any of these channels the Communication Status
Message is returned. This routine can also be used to request a
Communication Status Message when communication changes with any
node. In that case the node should be specified to be -1.

Communication status changes with a redundant node with the same

node number as the own node can be requested by using node number
-2. These communication changes are not reported when node number
-1 is specified.
The Communication Status Message will have a message-id as specified
in msg_id. It will be sent to the process specified in dest. The old_stat
and new_stat are either TRUE (node communication OK) or FALSE.
Normally these two complement each other except in one situation. If
the immediate flag was TRUE in the request, old_stat and new_stat are
identical.
Notes • It is not allowed to request the message to be sent to a process

• The process that is specified as destination, to which the message is
to be sent, must exist at the time of request. Otherwise an error is
returned.
Errors • DUR_F_ILL_NCR_NOD
The requested process is located on another node
• DUR_F_UNKNOWN_NCR
The requested process does not exist (anymore)
Related routines dur_com_i_cr()

This routine is used to request a Communication Status Message when
the status changes of communication with a node, via a specific channel.

8.5.24 Delete Messages From a Queue
Syntax [status=]dur_del (dur_cont, err_cont, dur_par_rcv,

max_delete)
Arguments TLS_BOOLEAN status; /* (R)TRUE: success */

struct dur_par_rcv *dur_par_rcv;/* (I)Parameter buffer */
int max_delete; /* (I)Maximum number of
messages to delete
*/
Semantics Messages are deleted selectively from the queue. When a selection
buffer is specified in dur_par_rcv, only messages meeting the selection
criteria are deleted.
You pass the number of messages to be deleted as argument max_delete.
If this number is greater than the number of messages present in the
queue, the routine deletes all messages present, and returns without
warning. Negative values for max_delete causes all messages to be
deleted.
Note that when an alias receiver address has been specified, the
messages in the alias queue are deleted!
Related routines • dur_del_rep()
This routine deletes only reply-messages
Requests are ignored.
• dur_del_req()
This routine deletes only request-messages.
Replies are ignored.

8.5.25 Delete Reply Messages from a Queue
Syntax [status=]dur_del_rep (dur_cont, err_cont, dur_par_rcv,

max_delete)
Arguments TLS_BOOLEAN status; /* (R) TRUE: success*/

struct dur_context *dur_cont; /* (I) DUR context*/
struct umh_context *err_cont; /* (M) UMH errorcontext*/
struct dur_par_rcv *dur_par_rcv; /* (I) Parameter buffer */
int max_delete; /* (I) Maximum number
of messages to
delete*/
Semantics Reply messages are deleted selectively from the queue. When a
selection buffer is specified in dur_par_rcv, only replies meeting the
selection criteria are deleted.
If this number is greater than the number of messages present in the
queue, the routine deletes all replies present and returns, without
deleted.
messages in the alias queue are deleted!
Related routines dur_del()

This routine deletes both reply messages and request messages.
dur_del_req()
This routine deletes only request messages.
Replies are ignored.

8.5.26 Delete Request Messages From a Queue
Syntax [status=]dur_del_req (dur_cont, err_cont, dur_par_rcv,

max_delete)

struct umh_context *err_cont; /* (M)UMH errorcontext */
struct dur_par_rcv *dur_par_rcv;/* (I)Parameter buffer */
int max_delete; /* (I)Maximum number
of messages to
delete*/
Semantics Request messages are deleted selectively from the queue. When a
selection buffer is specified in dur_par_rcv, only requests meeting the
selection criteria are deleted.
If this number is greater than the number of request messages present in
the queue, the routine deletes all requests present, and returns without
deleted.
messages of the alias queue are deleted!
Related routines dur_del()

This routine deletes both request messages and reply messages.
dur_del_rep()
This routine deletes only reply-messages.
Requests are ignored.

8.5.27 Detach from DUR
Syntax [status=]dur_det (dur_cont, err_cont)
Arguments TLS_BOOLEAN status; /* (R)TRUE : success */

Semantics This routine is used to detach from (M)DUR. All context related to the
process in DURCOM is removed and all messages in the existing queues
of the process are deleted. In addition, all wait-for-event actions are
terminated, all attached event flags are detached and all processes
waiting for this process receive a warning message (see applicable
routines).
It is always advisable to detach from (M)DUR before your process exits.
Notes Be careful not to use dur_umh_init() and dur_det() in a loop. Since

dur_det() does not release the memory allocated by dur_umh_init() for
the UMH send and receive buffers. Each time you call dur_umh_init()
new memory is allocated. The memory is only released again when your
program exits. (See description of dur_umh_init()). If it is absolutely
necessary to perform a loop as described above, use umh_res_msg() and
dur_att() instead of dur_umh_init().

8.5.28 Attach to an Event Flag
Syntax [status=]dur_evt_att (dur_cont, err_cont, evt_blk)
Arguments TLS_BOOLEAN status; /* (R)TRUE : success */

struct dur_evt_blk *evt_blk; /* (M)Event to obtain */
Semantics This routine attaches a process to an event flag.

The event block of the flag has to have been sent by the owner of the
flag.
Events physically located in another node may also be attached and
generated (see dur_evt_gen).
Notes • A process may be attached to a maximum of typically 10 event

flags (this number includes the obtained flags).
• You do not have to attach ’obtained’ event flags since these were
attached implicitly when you obtained the flag.
• Never alter the contents of evt_blk.

8.5.29 Cancel Timer Event flag
Syntax [status=]dur_evt_can (dur_cont, err_cont, evt_blk)

struct dur_evt_blk *evt_blk; /* (M)Timer event */
Semantics This routine is used in combination with routine dur_evt_mark(), which

uses an event_flag as timer. In order to prevent the associated event_flag
being generated, use dur_evt_can().
Only events in the same node may be canceled.
Related routines dur_evt_mark()

This routine starts a timer. When the timer expires, an event is generated.

8.5.30 Detach From an Event flag
Syntax [status=]dur_evt_det (dur_cont, err_cont, evt_blk)

struct dur_evt_blk *evt_blk; /* (M)Flag to detach */
Semantics Before a flag can be released, the process has to be detached from the
event flag. The flag is free for use again once all the attached processes
have detached.
When a process detaches from (M)DUR, it does not have to detach from
the event flags explicitly since the process is automatically detached
from all event flags, even the flags that are physically located in another
node.

8.5.31 Fix an Event Flag so That it Survives a

Process Stop
Syntax [status=] dur_evt_fix (dur_cont, err_cont, evt_blk)

struct dur_context *dur_cont; /* (M)DUR context*/
struct umh_context *umh_cont; /* (M)UMH error context*/
struct dur_evt_fix *evt_blk; /* (I)Event to be fixed*/
Semantics This routine will cause an event to stay ’alive’ even when the process
that owns the flag is exited. This allows event flags to be obtained by
processes other than those that use the event flag. The event flag will
never be free to be used for other purposes even when all attached
processes have detached again. It will only be released after a
dur_evt_unf() call.
Note It is only allowed to fix an event in the local node

8.5.32 Generate an Event
Syntax [status=] dur_evt_gen (dur_cont, err_cont, evt_blk)

struct dur_evt_blk *evt_blk; /* (I)Event flag to be set */
Semantics This routine is used for generating events.

Generation of events in another node is allowed, in which case the event
block itself contains the node information.
No acknowledgment will be given as to whether the generation was
effective or not. If the flag was already set (e.g. by another process), the
status will remain TRUE (no error or warning).

8.5.33 Use Event Flag as Timer
Syntax [status=]dur_evt_mark (dur_cont, err_cont, time_out,

evt_blk)
Arguments TLS_BOOLEAN status; /*(R)TRUE: success */

struct dur_context *dur_cont; /*(I)DUR context */
struct umh_context *err_cont; /*(M)UMH error context */
TLS_LONG time_out; /*(I)Time (millisecs) */
struct dur_evt_blk *evt_blk; /*(M)Event_flag generated
when timer expires */
Semantics This routine is used if an event has to be generated after a specific period
of time has elapsed. The event to be generated is specified in evt_blk and
the time-out period is specified in time_out (in milliseconds). The timer
starts up as soon as the routine is called.
Only events in the same node may be generated.
This routine may also return system errors. Refer to the system manual
in that case.
Related routines dur_evt_can()

This routine cancels the timer, resulting in the event not being generated.

8.5.34 Obtain the First Event Flag
Syntax [status=] dur_evt_obt (dur_cont, err_cont, evt_blk)

struct dur_context *dur_cont; /* (I)DUR context 41 */
struct dur_evt_blk *evt_blk; /* (O)Event flag to obtain */
Semantics Using this routine, a process becomes the owner of an event flag.
When the process becomes the owner of the flag, it receives an event
block, containing (internal) information identifying the flag. The
contents of this event block may not be altered (unless otherwise stated
in the appendices ’Using (M)DUR on ...’).
You have to send this event block to all processes that have to attach to
this event flag. A process can only generate an event if it is attached. It
is possible to generate an event in another node, but it is not possible to
be the owner of a flag physically located in another node. In other words,
you cannot wait for events whose event flags are physically located in
other nodes.
Notes • Owners of event flags (processes that have obtained an event flag)
are automatically attached. This means that you do not have to
attach these event flags explicitly.
• A process may be attached to a maximum of typically 10 event
• When you obtain a number of event flags using this routine, it is not
defined whether or not these event flags are ’related’. It is not
allowed to wait for these flags simultaneously (see routine
dur_evt_wor).
• The flag is reset automatically.
Related routines dur_evt_orl()

This routine obtains ’related’ event flags. It allows you to wait for a
number of events simultaneously.

8.5.35 Obtain Multiple Event Flags
Syntax [status=] dur_evt_orl (dur_cont, err_cont, evt_blk,

rel_evt_blk)

struct dur_evt_blk *evt_blk; /* (O)Event to obtain */
struct dur_evt_blk *rel_evt_blk;/* (I)the related flag */
Semantics A process will often need to wait for several events at the same time (see
dur_evt_wor), in which case it has to be the owner of the corresponding
event flags.
Using this routine, you indicate to (M)DUR that another event flag has
already been obtained. Passing the evt_blk as argument enables
(M)DUR to find a flag related to a particular event.
You must always obtain the first event flag using routine dur_evt_obt().
The dur_evt_blk returned by that routine is passed as argument in
dur_evt_orl().
It is not possible to obtain an event flag that is physically located in
another node.
Notes • Owners of event flags, i.e. processes that have obtained an event
flag, are attached automatically which means that it is not necessary
to attach these event flags explicitly.
• A process may be attached to a maximum of typically 10 event
• Because of system constraints, it may occur that no related event is
returned, even though the limit of available event flags has not been
reached yet. Release unused events with dur_evt_det().
• The flag is reset automatically.
Related routines dur_evt_(obt)

This routine obtains ’un-related’ event flags. The first event flag must be
obtained with this routine.

8.5.36 Reset an Event Flag
Syntax [status=]dur_evt_rst (dur_cont, err_cont, evt_blk)
Arguments TLS_BOOLEAN status; /* (R)TRUE:success */

struct dur_evt_blk *evt_blk; /* (M)Event flag to reset
*/
Semantics This routine is used to reset an event flag prior to waiting for the
corresponding event.
Events are said to be generated when an event flag is set. Consequently,
prior to generating an event, the corresponding event flag must be reset.
Any process that is attached to the event flag is allowed to reset the flag.
Usually however, the flag is reset by the owner.
When an event is generated, and the waiting process continues by
resetting the event flag, it is not defined whether or not the remaining
(waiting) owners receive the event. This situation should be taken care
of by the application program.
Notes You cannot reset an event flag that is physically present in another node.

8.5.37 Test State of an Event Flag
Syntax [status=]dur_evt_test (dur_cont, err_cont, evt_blk,

evt_stat)

struct dur_evt_blk *evt_blk; /* (M)Flag to be tested */
TLS_BOOLEAN *evt_stat; /* (R)TRUE if set */
Semantics This routine checks the state of the specified event_flag. The state is
returned in evt_stat, which is TRUE if the flag was set.
Only events in the same node may be tested. This routine may also return
system errors.

8.5.38 Release a Previously Fixed Event Flag
Syntax [status=] dur_evt_unf (dur_cont, err_cont, evt_blk)

struct dur_evt_fix *evt_blk; /* (I)Event to be unfixed
*/
Semantics This routine is used to release a previously fixed event flag. When all
processes that once attached to this event flag are detached again, the
event flag is free to be used for other purposes.

8.5.39 Wait for a Single Event
Syntax [status=] dur_evt_wait (dur_cont, err_cont, evt_blk)

struct dur_evt_blk *evt_blk; /* (M)Event flag to wait
for */
Semantics This routine is used when waiting for a single event. The routine returns
as soon as the event is generated. Setting the flag before your process
starts waiting is allowed. In that case the routine will return immediately.
It is allowed to wait for an event that is generated by a process physically
located in another node. In that case you must send the dur_evt_blk to
that particular process enabling the process to generate the event. The
evt_blk contains all required node information.
Notes The event flag must have been reset prior to calling this routine. If this
is not done, the event flag cannot be set by any process. The flag can be
reset with routine dur_evt_rst().

8.5.40 Wait for Multiple Events
Syntax [status=] dur_evt_wor (dur_cont, err_cont, time_out,

evt_blk_t, evt_number, evt_count,
evt_blk_1[,...,evt_blk_4])
Arguments TLS_BOOLEAN status; /* (R)TRUE : success*/

struct umh_context *err_cont; /* (M)UMH error context*/
int time_out; /* (I)Timer value in secs*/
struct dur_evt_blk *evt_blk_t; /* (M)Timer event*/
int *evt_number; /* (I)Sequence number-1 of
event flag to start
scan cycle with
(O)Sequence number of
activated event*/
int evt_count; /* (I)Number of event flags
passed as arguments
(timer excluded) */
struct dur_evt_blk *evt_blk_1; /* (M)First flag to wait
for*/
struct dur_evt_blk *evt_blk_4; /* (M)4th flag to wait
for*/
Semantics This routine is used to wait for a number of events simultaneously. The
routine returns as soon as one of the event flags is set (Wait for logical
OR of flags).
Furthermore this routine can be used for timing purposes. When you
specify 0 for the time_out, the timer is not started.
It is allowed to wait for an event that is generated by a process physically
For each event that the process is waiting for, the corresponding event
block has to be passed as arguments in the routine call.
The number of events the process wants to wait for must be specified in
evt_count. This number must be less then or equal to the number of
event blocks that are passed as arguments, with a maximum of 4. Do not
include the timer-event in this count (see example).
The timer event should be treated the same as any other event flag. When
you use the timer in combination with another event flag, the flags must
be related (use dur_evt_orl).

You may enter NULL as evt_blk. In that case the routine skips that
argument. Always include the NULL arguments in the value of
evt_count (see example).
Using argument evt_number as an input, it is possible to force the scan
cycle to start at a specific point. This allows you to give priorities to
events you are waiting for (see example). The sequence in which the
arguments are passed is significant. When the routine returns,
evt_number contains the sequence number (of your argument list) of the
event that has been generated (see example).
Note that if you do not change this value when you call the routine again,
the scan cycle always continues with the next event flag.
Example Suppose a process waits for 2 events and has started the timer with the
following routine call:
{
TLS_BOOLEAN status;
int time_out=10;
int evt_number=1;
int evt_count=3;
struct dur_context dur_cont;
struct umh_context err_cont;
struct dur_evt_blk evt_blk_t,evt_blk_x, evt_blk_y;
...
dur_evt_wor (&dur_cont,&err_cont,
time_out,&evt_blk_t,
&evt_number,
evt_count,
&evt_blk_x,NULL,&evt_blk_y);
...
}
Timer event_x event_y
sequence
0 1 3 number
event flags
DUR scan cycle
Fig. 8-3
The timer event flag (evt_blk_t) always has number 0. The timer is
started and will expire after 10 seconds. The remaining flags follow in

the order of the argument list: first evt_blk_x then evt_blk_y.

Note that the NULL event is included in the evt_count value (=3) but
does not represent a flag.
DUR always scans the flags in ascending order. The value of
evt_number determines where the scan cycle starts. Scanning always
begins with the flag following the one specified in evt_number. In the
example evt_number=1 so scanning starts with number 3 (number 2 is
NULL!).
Suppose evt_blk_y is generated. In that case the routine returns with
evt_number =3.
When the routine is called again, scanning continues with the following
flag, being flag 1 (timer has a lower priority), unless the value of
evt_number was changed prior to calling the routine. You might do so
when you want a particular event to have priority over the remaining
flags.
When the timer has expired the routine returns with evt_number=0.
Notes • The event flags that the process is waiting for must have been reset
prior to calling the routine, otherwise the events cannot be
generated (see dur_evt_rst).
• The maximum number of events that can be awaited at the same
time depends on the DUR implementation
can be found in the appendices.

8.5.41 Get Own Node Number
Syntax node_ = dur_get_node (dur_cont)
Arguments short node; /* (R)No of own node */

Semantics This routine is used to request the number of your local node and instead
of a status, it returns the actual node number. To obtain the name of your
local node, use the dur_inf_node() routine.

8.5.42 Get queue size
Syntax [status=] dur_get_qsiz (dur_cont, err_cont, adr, size)

struct dur_adr *adr; /* (I)Address of queue */
int *size; /* (O)Actual queue size */
Semantics This routine is used to get the queue size of a process or node.
To get the process’s local queue size, a NULL pointer may be given as
adr. To get the queue size of another process, the adr struct must contain
the name of that process. To get the queue size of a node, the name
element of the adr struct must contain "~" and the node element must
contain the node number.
The actual queue size is returned in the size as a number of kbytes.
Related routines • dur_mod_qsiz()

Used to change the size of a queue
Errors • DUR_F_UNKNOWN_MQS
You have specified an unknown queue.
• DUR_F_ILL_MQS_NOD
You have specified a process on another node.

8.5.43 Get variable
Syntax [value=] dur_get_var (dur_cont, err_cont, name)
Arguments char *value; /* (R)The value of the var */

char *name; /* (I)The name of the var */
Semantics This routine is used to get the value of a variable stored in the DUR
common area.
If the variable is not found then NULL is returned.
It returns the pointer to the location in the DUR common area where the
value is stored. It is not allowed to write data to this location.
Related routines • dur_set_var()

Used to set or add the value of a variable.
Errors • DUR_E_ILL_PAR
The specified variable is not found.

8.5.44 Get Node Information
Syntax [status=] dur_inf_node (dur_cont, err_cont, node, node_info)

int node; /* (I)Number of node */
struct dur_nod_inf *node_info; /* (O)Node information */
Semantics This routine is used to request information about a specific node and
requires the node number as input. The result of the routine is placed in
struct dur_nod_inf.
The communication status is found in struct
dur_nod_inf.communication, which indicates a good status if TRUE.
Specifying 0 as node number will result in the actual node number being
placed in the member dur_nod_inf.node. In member dur_nod_inf.name
the node name can be found in ASCII format (not ending in a 0).
This routine also provides information about the type of FAST/TOOLS
node (server, HMI, enterprise server, etc.), the role within the DURM
routing scheme (router, endpoint, private) as well as the FAST/TOOLS
major and minor release number. Please refer to the structure definition
and associated constant definition in dur.h for detailed information.
Related routines • dur_com* routines

Used to request a message to be sent with status information.
• dur_get_node()
Use this routine to obtain your local node number.

8.5.45 Modify queue size
Syntax [status=] dur_mod_qsiz (dur_cont, err_cont, adr, size)

struct dur_adr *adr; /* (I)Address of queue */
int size; /* (I)Wanted queue size */
Semantics This routine is used to modify the queue size for a process or node.
To change the process’s local queue size, a NULL pointer may be given
as adr. To change the queue size of another process, the adr struct must
contain the name of that process. To change the queue size of a node, the
name element of the adr struct must contain "~" and the node element
must contain the node number.
The desired queue size must be specified in kbytes in the size parameter.
When queue overflow indication was requested on the affected queue,
the queue blocking size (in%) can be decremented a little. After many
queue size changes, a maximum reduction in queue size of 7% is
possible.
Related routines • dur_get_qsiz()
Used to request the size of a queue
Errors • DUR_F_UNKNOWN_MQS
• DUR_F_ILL_MQS_NOD
You have specified a process on an other node.

8.5.46 Wait for Queue Size
Syntax [status=]dur_que_size (dur_cont, err_cont,proc,

wait_type,wait_size,act_que_size,
evt_blk,time_out)

struct dur_adr *proc; /* (I)Process address */
int wait_type; /* (I)Wait mode */
int wait_size; /* (I)Number of queued
messages */
int *act_que_size; /* (O)Actual queue size
in no of messages */
struct dur_evt_blk *evt_blk; /* (I)Event to generate
*/
int time_out; /* (I)Max time to wait
(secs) */
Semantics This routine allows you to wait for a queue to achieve a value above or
below a given value (number of messages or percentage). You can wait
for any queue, including your own, or the queue of a process in another
node.
The queue is identified by the process-address.
The routine can be used in several modes. One of the arguments passed
with this routine is the wait_type. The following defined names may be
entered as wait_type:
• DUR_WAIT_NOT
The actual number of queued messages is returned immediately.
• DUR_WAIT_NOT
Immediately return the actual queue size as an integer percentage
(0-100).
• DUR_WAIT_LOW
Wait until the number of queued messages drops below the
specified number.
• DUR_WAIT_PRC_LOW
Wait until the queue drops below the specified percentage.
• DUR_WAIT_HIGH
Wait until the number of queued messages becomes greater than the
specified number.
• DUR_WAIT_PRC_HIGH
Wait until the queue grows above the specified percentage

• DUR_WAIT_LOW_EVENT
An event is generated when fewer messages are queued than
specified.
• DUR_WAIT_PRC_LOW_EVENT
Generates an event when the queue drops below the specified
percentage.
• DUR_WAIT_HIGH_EVENT
Generate an event when the number of queued messages has
become greater than the specified number.
• DUR_WAIT_PRC_HIGH_EVENT
Generates an event when the queue grows above the specified
percentage.
The queue-size to wait for (wait_size) is expressed as the number of

messages or percentage, in contrast to the maximum queue size
specified in dur_att() or dur_umh_init(), which is the size in Kbytes.
Negative numbers are reserved.
When you want an event to be generated, you have to pass the event
block of the corresponding event flag in evt_blk.
The time-out is only significant if you have specified
DUR_WAIT_LOW or DUR_WAIT_HIGH, time-out is given in
seconds. Specifying 0 means that the timer is not activated (wait
indefinitely).
Notes • Specifying DUR_WAIT_NOT or DUR_WAIT_PRC_NOT for

wait-type results in all pending wait-for-queue-size events being
cancelled for that specific queue. (M)DUR will no longer generate
events which had been requested previously with
DUR_WAIT_LOW_EVENT, DUR_WAIT_PRC_LOW_EVENT,
DUR_WAIT_HIGH_EVENT or
DUR_WAIT_PRC_HIGH_EVENT.
• Specifying DUR_WAIT_LOW, DUR_WAIT_PRC_LOW,
DUR_WAIT_LOW_EVENT or
DUR_WAIT_PRC_LOW_EVENT results in all pending events
that had been requested previously with
DUR_WAIT_LOW_EVENT or
DUR_WAIT_PRC_LOW_EVENT for the same queue being
cancelled.
• Specifying DUR_WAIT_HIGH, DUR_WAIT_PRC_HIGH,
DUR_WAIT_PRC_HIGH_EVENT results in the cancellation of

all pending events that had been requested previously with

DUR_WAIT_PRC_HIGH_EVENT for the same queue.
Related routines • dur_can_wts()
This routine cancels all pending wait-for-queue-size events for all
queues as well as the wait-for-message events.
Errors • DUR_F_UNKNOWN_QUE
• DUR_W_EVT_QUEUED
This warning indicates that the requested condition (either for
DUR_WAIT_LOW_EVENT, DUR_WAIT_PRC_LOW_EVENT
DUR_WAIT_PRC_HIGH_EVENT) was not valid. (M)DUR will
generate an event as soon as the condition becomes valid.
• DUR_E_TIMEOUT
Request has timed out

8.5.47 Receive any Message
Syntax [status=] dur_rcv (dur_cont, err_cont, dur_par_rcv,

reply_found)

struct dur_par_rcv *dur_par_rcv;/* (M)Parameters */
TLS_BOOLEAN *reply_found; /* (O)TRUE if reply */
Semantics This routine enables messages to be read from the queue. Both replies
and requests are returned. Whether the message was a reply or not is
indicated in reply_found (TRUE for reply, FALSE for request).
The routine takes the message priority into account and scans the queue
in the following sequence:
1 Expedite replies
2 Expedite requests
3 Normal replies
4 Normal requests
(M)DUR will perform this function according to the options you have
specified in the parameter buffer dur_par_rcv (see Data Structures). A
brief summary of options:
• Use alias address
(M)DUR will only read messages from the queue of the process
you have specified.
• Select a synchronization type
Either synchronous (with or without event) or asynchronous.
• Indicate a selection buffer
When you specify a selection buffer in dur_par_rcv, only messages
meeting the selection criteria are read.
When the routine returns, the message is passed to the buffer specified
in dur_par_rcv. The parameters received with the message can be found
in dur_par_rcv.

Errors The following list is a summary of error messages that you might want
to test on in your application program. Other (often more serious) errors
can be found in Appendix B.
• DUR_W_NO_MSG_FND
This warning is returned in asynchronous mode (sync_type =
DUR_SYNC_NOWAIT), or in synchronous mode (sync_type =
DUR_SYNC_WAIT) with event, indicating that no appropriate
message was queued.
• DUR_E_MSG_TRUNC
This error is returned if the receiver buffer was too small for the
message. The message is truncated and the part remaining is
deleted from the queue.
• DUR_E_TIMEOUT
This error is only returned in synchronous mode
(sync_type=DUR_SYNC_WAIT) without event generation. In that
case you can start a timer. When the timer expires, without having
received a message, this error is returned.
• DUR_E_UNKNOWN_ALI
You have specified an unknown receiver name as alias.
• DUR_E_RHB_DEL
This error is only returned in synchronous mode, waiting for a
message in another queue (alias). This process became inactive
while your process was waiting.
Related routines • dur_rcv_rep()
Routine to read reply messages only.
• dur_rcv_req()
Routine to read request messages only

8.5.48 Initialize Receive Parameter Buffer
Syntax [status=] dur_rcv_ini (dur_cont, err_cont, dur_par_rcv,

msg_buf, max_size)
Arguments TLS_BOOLEAN status; /* (R)TRUE: Success*/

struct dur_par_rcv *dur_par_rcv;/* (O)Parameters*/
char *msg_buf; /* (I)Receive buffer
May be any type*/
int max_size; /* (I)in bytes*/
Semantics This routine is used to initialize dur_par_rcv to a typical (normally used)

state. When this routine returns you are ready to receive messages.
When you want special options, you have to enter those options
explicitly in dur_par_rcv.
The following members of dur_par_rcv are initialized:
msg_buf_pnt = msg_buf
msg_buf_size = max_size
alias_adr.node = 0 (own node number)
alias_adr.name = " " (own process name)
alias_adr.task = 0 (own task number)
sync_type = DUR_SYNC_WAIT(wait for
message)
time_out = 0 (wait for ever)
event_block_pnt = NULL (no event block given)
select_buf_pnt = NULL (no select buffer given)
As can be seen from the above, the message buffer msg_buf may be of
any type. When you know what type will be sent to your process, you
declare your message buffer to be of the same type. Use an array of
LONGs for the receiver buffer only when the type is not known
beforehand. Depending on the message-id, you can convert the type
using a cast expression.
For some systems it is not necessary to have the buffer declared on
TLS_LONG boundaries. In that case you may declare the buffer as short
msg_buf or even char msg_buf. Note, however, that your application
will no longer be portable.
The message size of the receive buffer must be at least equal to the
largest message to be expected.

Errors None.

8.5.49 Receive Reply Message
Syntax [status=]dur_rcv_rep (dur_cont, err_cont, dur_par_rcv)

struct dur_context *dur_cont; /* (I)DUR context*/
struct dur_par_rcv *dur_par_rcv;/* (M)Parameters*/
Semantics This routine is used for receiving reply messages from the queue.
1 Expedite replies.
2 Normal replies.
1 Use alias address
you have specified.
2 Select a synchronization type
3 Indicate a selection buffer
When the routine returns, the message is passed to the buffer you have
specified in dur_par_rcv. The parameters received with the message can
also be found in dur_par_rcv.
message was queued.

• DUR_E_MSG_TRUNC
• DUR_E_TIMEOUT
This error message is only returned in synchronous mode
(sync_type = DUR_SYNC_WAIT) without event generation, in
which case you can start a timer. If the timer expires without having
• DUR_E_RHB_DEL
message of another queue (alias). That process has detached from
DUR while waiting.
Related routines • dur_rcv()

Routine to read both request messages and reply messages.
• dur_rcv_req()
Routine to read request messages only

8.5.50 Receive Request-Message
Syntax [status=]dur_rcv_req (dur_cont, err_cont, dur_par_rcv)

struct umh_context *err_cont; /* (M)UMH error context
*/
struct dur_par_rcv *dur_par_rcv;/* (M)Parameters*/
Semantics Routine to read request-messages from the queue.

• Expedite requests
• Normal requests
1 Use alias address
you have specified.
2 Select a synchronization type
3 Indicate a selection buffer
When the routine returns, the message is passed to the buffer you have
specified in dur_par_rcv. The parameter received with the message can
also be found in dur_par_rcv.
Errors The following list is a summary of messages that you might want to test
on in your application program. Other (often more serious) errors can be
found in Appendix B.


message was queued.
• DUR_E_MSG_TRUNC
This error-message is returned when the receiver buffer was to
small for the message. The message is truncated and the part
remaining is deleted from the queue.
• DUR_E_TIMEOUT
This message is only returned in synchronous mode
(sync_type = DUR_SYNC_WAIT) without event generation. In
that case you can start a timer. If the timer expires without having
• DUR_E_RHB_DEL
message of another queue (alias). That process has detached from
DUR while waiting.
Related routines • dur_rcv()

Routine to read both reply messages and request messages.
• dur_rcv_rep()
Routine to read reply-messages only.

8.5.51 Request an Overflow Indication for

Own Queue
Syntax [status=] dur_req_ovf (dur_cont, msg_id, perc)

int msg_id; /* (I)Message-id to be
returned in Overflow
Message */
int perc; /* (I)Queue blocking size
in percent */
Semantics This routine causes the local queue to be tested continuously for
overflow situations. When such a situation is detected, the queue is
’blocked’ for all messages until the queue size drops below the specified
size in percentage terms. At that moment an Overflow Indication
Message is put in the queue and the queue is opened again. The perc
value must lie between 0 (queue must be empty before it is unblocked)
and 100 (not blocked at all). Depending on the real queue size, the perc
value can be truncated internally up to a maximum of 7%.
When the queue size is changed with the function dur_mod_qsiz(), the
internal perc value can go down a little, but never more than 7% below
the specified number.
Notes The overflow indication messages cannot be intercepted with the DUR
display utility.
Related routines • dur_can_ovf()
This routine is used to cancel the request again.

8.5.52 Request a User Attachment
Syntax [status=] dur_req_usr (dur_cont, err_cont, node, immed, dest,

msg_id)

int node; /* (I)node interested in
*/
TLS_BOOLEAN immed; /* (I)immediate flag */
struct dur_adr *dest; /* (I)address of destination
*/
int msg_id; /* (I)Message-id to use for
Message */
Semantics A process may request to receive information about all attachments and
detachments other processes make to the DUR common area. The
requesting process specifies the message code that will be used for the
reply message and the DUR destination of the process to which the
message must be sent. By specifying the immediate flag, the destination
process receives immediately a sequence of messages for all processes
that are attached to DUR. From that moment on, only the changes are
reported (e.g. a process that is started and attaches to DUR).
The replies sent to the destination, all have the same message structure:
struct dur_usr_msg
{
struct dur_adr proc; /* user proc */
TLS_LONG att_count; /* attach count */
TLS_LONG reason; /* message reason */
};
The reason variable returned in the dur_usr_msg holds one of the
following statuses:
DUR_USR_ATT /* user attached */
DUR_USR_DET /* user detached */
DUR_USR_REM /* user removed */
DUR_USR_RBA /* user removed by new attach
*/
DUR_USR_IMM /* user immediate message
*/
Related routines dur_can_usr

8.5.53 Select Messages by Sender Reference
Syntax [status=]dur_sel_adr (err_cont,sel_blk, sel_op, eval_level,

relation, dur_adr)
Arguments TLS_BOOLEAN status; /* (R)TRUE: Success */

struct umh_context *err_cont; /* (M)UMH Error context */
struct dur_sel_blk *sel_blk; /* (M)Selection-buffer */
int sel_op; /* (I)Selection operation
*/
int eval_level; /* (I)Evaluation level */
int relation; /* (I)Relation with
previous element */
struct dur_adr *adr_id; /* (I)Sender address to
which sel_op and
relation apply */
Semantics This routine is used to create elements in a selection buffer for selecting
messages according to sender address.
The following predefined selection operations are available, which you
may specify in sel_op:
DUR_FIRST (Indicates first element of selection buffer)
DUR_AND (Logical AND function with previous operation)
DUR_OR (Logical OR function with previous operation)
The following relations (with the sender address) may be specified:
DUR_EQ (Equal)
DUR_NE (Not Equal)
Notes • The maximum number of elements in a selection buffer is typically

10. This number is defined at generation time.
• The highest evaluation level typically is 5. This number is defined
at generation time.
Related routines • dur_sel_ext()

Routine to select messages by expedite status.
• dur_sel_msg()
Routine to select messages by message-id.
• dur_sel_rep()
Routine to select messages by reply status.
• dur_sel_tsk()
Routine to select messages by task-number.

8.5.54 Select Messages by Expedite Status
Syntax [status=]dur_sel_exp (err_cont,sel_blk, sel_op, eval_level,

relation)

int sel_op; /* (I)Selection
operation */
previous element */
messages according to expedite status.
The following relations (with the expedite status) may be specified:
DUR_EQ (Equal)
DUR_NE (Not Equal)

at generation time.
Related routines • dur_sel_adr()

Routine to select messages by address-id.
• dur_sel_msg()
• dur_sel_rep()
• dur_sel_tsk()

8.5.55 Select Messages by Message-id

Syntax [status=]dur_sel_msg (err_cont, sel_blk, sel_op, eval_level,
relation, msg_id)

int sel_op; /* (I)Selection
operation */
previous element */
int msg_id; /* (I)Message-id to which
sel_op and relation
apply */
messages according to message-id. The following predefined selection
operations are available and can be specified in sel_op:
The following relations (with the message-id) may be specified:
DUR_EQ (Equal)
DUR_NE (Not Equal)
DUR_LT (Less Than)
DUR_GT (Greater Than)
DUR_LE (Less Than or Equal)
DUR_GE (Greater Than or Equal)
Notes • The maximum number of elements in a selection buffer typically is

10. This number is defined at generation time (see Installation
Manual).
• The highest evaluation level typically is 5. This maximum number
is defined at generation time.

• dur_sel_exp()

• dur_sel_rep()
• dur_sel_tsk()
Routine to select messages by task-number

8.5.56 Select Messages by Reply Status
Syntax [status=]dur_sel_rep (err_cont,sel_blk, sel_op, eval_level,

relation)

*/
previous element */
messages according to reply status.
The following relations (with the expedite status) may be specified:
DUR_EQ (Equal)
DUR_NE (Not Equal)

at generation time.

• dur_sel_exp()
• dur_sel_msg()
• dur_sel_tsk()

8.5.57 Select Messages by Task Number
Syntax [status=]dur_sel_tsk (err_cont, sel_blk, sel_op,

eval_level, relation, task)

struct dur_sel_blk *sel_blk; /* (M)Selection buffer */
*/
int relation; /* (I)Relation with previous
element */
int task; /* (I)Task-id to which
sel_op and relation
apply */
messages according to task number. This routine will only be used with
sub-tasks in a process. In which case only those messages for which the
destination address is specified to be one of your tasks is selected
The following predefined selection operations are available and can be
specified in sel_op:
The following relations (with the task-id) may be specified:
DUR_EQ (Equal)
DUR_NE (Not Equal)
DUR_LT (Less Than)
DUR_GT (Greater Than)
DUR_LE (Less Than or Equal)
DUR_GE (Greater Than or Equal)
Notes • The maximum number of elements in a selection buffer typically is

10. This number is defined at generation time
• The highest evaluation level typically is 5. This maximum number
is defined at generation time.
Related routines
• dur_sel_adr()

• dur_sel_exp()
• dur_sel_msg()
• dur_sel_rep()

8.5.58 Set variable
Syntax [status=] dur_set_var (dur_cont, err_cont, name, value, flags)

char *name; /* (I)The name of the var */
char *value; /* (I)The value for the var*/
TLS_ULONG flags /* (I)Flags */
Semantics This routine is used to set the value of a variable to be stored in the DUR
common area.
The routine returns FALSE if name is NULL, strlen(name) > 39, value
!= NULL and strlen(value) > 79.
If the variable is not found then it will be added else its value will be
updated.
If value is NULL then the variable will be removed from the DUR
common area.
flags can be one of:
• DUR_VAR_FLG_PUB
The variable is marked as public. Public variables are visualized in
the FAST/TOOL Performance Monitor.
• DUR_VAR_FLG_PRV
The variable is marked as private.
Related routines • dur_get_var()

Used to get the value of a variable.
Errors • DUR_E_ILL_PAR
One of the inputs in invalid.
• DUR_F_NO_SPACE
No space in the DUR common area to store the variable.

8.5.59 Exit when a SIGINT or SIGHUP Signal

is Received
Syntax (void) dur_sig_exit ()
Arguments None.
Semantics When this routine is called, the program will exit when a SIGINT or
SIGHUP signal is received in the future by the program.
The routine returns immediately and sets up an asynchronous interrupt
routine which is called when the program receives the SIGINT or
SIGHUP signal. The asynchronous interrupt routine calls dur_ask_exit()
to exit the program.
Notes This routine is typically used to setup that an interactive program has to
exit when it receives a Ctrl-C from the user.
Related dur_ask_exit()
routines Routine which exits the program, unlocking any locked common area
before exiting.

8.5.60 Snap information in the common area
Syntax [status=] dur_snap(handle, snap_info, mode)
Arguments TLS_BOOLEAN status; /* (R)TRUE when success */

void **handle; /* (I)Snap handle */
union dur_snap_info *snap_info;/* (M)Snap info */
int mode; /* (I)Mode */
Semantics This function is used to make a snapshot of the common area, to browse
through the snapshot and to release the snapshot. The handle is filled
when the snapshot is taken, it is used while browsing through the
snapshot and it is freed afterwards. The function to perform is indicated
by the mode argument. The snapshot is taken without locking the DUR
common area while the _L mode variant locks the DUR common area
while taking the snapshot. When no locking is used the snap may
sometimes return invalid information:
Value Description
DUR_SNAP_GENERAL Takes a snapshot of general informa-
DUR_SNAP_GENERAL_L tion. The general snapshot contains
only one item.
DUR_SNAP_QUEUE Takes a snapshot of all queues, their
DUR_SNAP_QUEUE_L characteristics and performance.
DUR_SNAP_NODE Takes a snapshot of all know con-
DUR_SNAP_NODE_L nected nodes, their characteristics
and performance.
DUR_SNAP_LOCK Takes a snapshot of all locks, their
DUR_SNAP_LOCK_L characteristics and performance.
DUR_SNAP_VAR Takes a snapshot of all public vari-
DUR_SNAP_VAR_L ables stored in the DUR common
area.
DUR_SNAP_ROUT Takes a snapshot of all routing info.
DUR_SNAP_ROUT_L
DUR_SNAP_FRST Obtain the first item from the snap-
shot.

Value Description
DUR_SNAP_NEXT Obtain the next item from the snap-
shot. Obtains the first item when
called directly after taking the snap-
shot.
DUR_SNAP_FREE Release the snapshot. Must be called
before taking another snapshot.
The next example shows how to use the snap function to list all the
queues and the number of messages transferred:
void handle;
union dur_snap_info snap_info;
dur_att_mem(); /* May only be called once */

dur_snap(&handle, &snap_info, DUR_SNAP_QUEUE);
/* Obtain queue information */
while (dur_snap(&handle, &snap_info, DUR_SNAP_NEXT))
{ /* Get next queue snapped */
printf("Queue name: %s\n",
snap_info.queue_info.queue_name);
printf("Transferred: %ld\n",
snap_info.queue_info.queue_transferred);
};
dur_snap(&handle, &snap_info, DUR_SNAP_FREE);
/* Free snapshot */
Notes None.
Related dur_att_mem()
routines Attaches the process to the common area prior calling dur_snap().

8.5.61 Send Request Message
Syntax [status=]dur_snd (dur_cont, err_cont, dur_par_snd)

struct dur_par_snd *dur_par_snd;/* (I)Parameters */
Semantics This routine is used to send request messages. The send options have to
be specified in the send parameter buffer dur_par_snd. Do not forget to
specify the pointer to the message buffer and the message size in
dur_par_snd.
A brief summary of the available options:
• Use an alias sender address
• Specify the message-id
• Give priority to a message
• Send message with ’reply required’
• Indicate system type
• Wait for confirmation (of another node)
• DUR_F_UNKNOWN_RCV
You have specified an unknown receiver.
• DUR_F_OVF_RCV
There was not enough space to queue the message for the receiver.
The message has not been transferred.
• DUR_F_OVF_NODE
There was not enough space to queue the message in the other node.
• DUR_F_NDF_NODE
There has never been a connection with the specified node.
• DUR_F_DWN_NODE
There is no connection with the specified node anymore.

• DUR_F_POS_LOST
The connection with the other node went down. The message is
possibly lost.

8.5.62 Initialize Send Parameter Buffer
Syntax [status=]dur_snd_ini (dur_cont, err_cont, dur_par_snd,

msg_buf,msg_size,rcv_proc_adr)

struct umh_context *err_cont; /* (M)UMH Error context*/
struct dur_par_snd *dur_par_snd;/* (O)Parameters*/
char *msg_buf; /* (I)Send buffer May be any
type*/
int msg_size; /* (I)Size of message to be
sent in bytes*/
struct dur_adr *rcv_proc_adr; /* (I)Destination*/
Semantics This routine is used to initialize dur_par_snd to a typical (normally used)

state. When this routine returns you are ready to send messages. When
you want special options, you have to enter those options explicitly in
dur_par_snd.
The following members of dur_par_snd are initialized:
msg_buf_pnt = msg_buf
msg_size = msg_size
rcv_adr = *rcv_proc_adr (specified receiver)
msg_id = 0
alias_adr.node = 0 (own node number)
alias_adr.name = " " (own process name)
alias_adr.task = 0 (own task number)
expedite = FALSE (low priority)
reply_required = FALSE (no reply required)
system_type = 0 (own system type)
sync_type = DUR_SYNC_WAIT (wait for confirmation)
time_out = 0 (MDUR send timeout)
As can be seen from the above, the message buffer msg_buf may be of
any type.
Specifying NULL for argument rcv_adr, means that the current contents
of the address in the parameter buffer are not altered.
Errors None.

8.5.63 Send and Receive Message
Syntax [status=]dur_snd_rcv (err_cont, dest, snd_buf, snd_siz,

rcv_buf, rcv_buf_siz, timeout,
flags, siz_rcv)

struct umh_context *err_cont; /* (M)UMH Error context
*/
struct dur_adr *dest; /* (I)Destination*/
char *snd_buf; /* (I)Message to send*/
int msg_siz; /* (I)Size of message*/
char *rcv_buf; /* (O)Buffer for answer
*/
int rcv_buf_siz; /* (I)Size of rcv_buf*/
int timeout; /* (I)Timeout*/
int flags; /* (I)flags*/
int *siz_rcv; /* (O)Size of answer*/
Semantics This routine is used for sending a message and receiving the
corresponding reply. The routines dur_snd_ini() and dur_rcv_ini() are
not needed to use this routine. To get internally calls the dur_snd() and
dur_rcv_rep() routines. For getting the right reply internally the
synchronization form of the task number is used.
If the receive buffer address is NULL, only a send will be done.
The timeout parameter is used for the send (in case node confirmation is
required) and for the receive.
The flags parameter is a bit-wise OR of the following flags:
• DUR_SR_NO_SYNC_CHK
Do not use reply synchronisation if this bit is set
• DUR_SR_NO_NODE_CONF
Send with DUR_SYNC_NOWAIT if this bit is set.
• DUR_SR_EXPEDITE
Send the message expedited if this bit is set.
• DUR_SR_NO_DEL_OLD
Do not delete out of sync replies from the reply queue. Setting
DUR_SR_NO_SYNC_CHK implies setting of
DUR_SR_NO_DEL_OLD.

Errors The following list is a summary of error-messages that you might want
can be found in appendix B.
• DUR_F_OVF_RCV
• DUR_F_OVF_NODE
• DUR_F_NDF_NODE
• DUR_F_DWN_NODE
The specified node is no longer connected.
DUR_F_POS_LOST
possibly lost.
• DUR_E_MSG_TRUNC
• DUR_E_TIMEOUT
This error message is returned in case the send node confirmation
times out or if the receive times out.
• DUR_E_RHB_DEL
message from another queue (alias). That process has detached
from DUR while waiting.

8.5.64 Send Reply Message
Syntax [status=]dur_snd_rep (dur_cont, err_cont, dur_par_snd)

struct umh_context *err_cont; /* (M)UMH Error context
*/
struct dur_par_snd *dur_par_snd;/* (I)Parameters*/
Semantics This routine is used for sending reply-messages. The send options have
to be specified in the send parameter buffer dur_par_snd. A brief
summary of the available options:
• Use an alias sender address
• Specify the message-id
• Give priority to a message
• Send message with ’reply required’
• Indicate system type
• Wait for confirmation (of another node).
Errors The following list is a summary of error-messages that you might want
can be found in appendix B.
• DUR_F_OVF_RCV
• DUR_F_OVF_NODE
• DUR_F_NDF_NODE
• DUR_F_DWN_NODE
The specified node is no longer connected.
• DUR_F_POS_LOST
possibly lost.

8.5.65 Get a One-second Time-stamp
Syntax seconds = dur_time_sec (dur_cont)
Arguments TLS_ULONG seconds /* (R)Seconds since 1970

*/
Semantics This routine is used to obtain the time in seconds since 00:00, 1 January,
1970. It is advised to use this routine where time-stamps of only a
resolution of 1 or 2 seconds are required.
This routine does not perform a system call to obtain the time, but uses
internal (M)DUR information instead. (M)DUR itself updates this value
on a one-second scan basis.
Notes • Depending on the (M)DUR generation, the time information may

be updated every x seconds instead of every second. You can check
this with the DUR Display Utility (DUR M O).
• The time is in GMT
8.5.66 Test Whether BUSCOM is Locked

Syntax [status=] dur_tst_lock (dur_cont)
Arguments TLS_BOOLEAN status; /* (R)TRUE: BUSCOM locked

*/
Semantics This routine checks if the BUSCOM area is locked.

routines to test if the interrupt itself is the cause of the lock.

8.5.67 Attach to DUR and Initialize UMH
Syntax dur_umh_init (dur_cont, err_cont, max_storage, def_size,

err_snd, err_rcv, p_name)
Arguments struct dur_context *dur_cont; /* (O)DUR context */

int max_storage; /* (I)Maximum queue-size
in units of 1Kbyte
*/
int def_size; /* (I)default buffer size
*/
int err_snd; /* (I)max error send size
*/
int err_rcv; /* (I)max error receive */
char *p_name; /* (I)Process name to be
used */
Semantics Using the dur_umh_init() routine, the process is attached to (M)DUR

and buffers are allocated for use by UMH.
The routine returns a context buffer (dur_cont) and an error buffer
(err_cont). Both buffers have to be passed as arguments in virtually all
(M)DUR routines.
The contents of these buffers should not be altered. Buffer err_cont
should only be accessed using UMH routines.
You may alter one member of dur_context:
dur_context.task
max_storage determines the maximum queue-size (in Kbytes) that is
allowed to queue messages. The required maximum queue-size depends
on the application. A typical value is 2.
The default message-size (def_size) is not currently used. At the
moment this value can only be monitored using DUR DISPLAY
facilities.
The two sizes (err_snd and err_rcv) are used to allocate buffers to be
used by UMH as send- and receive buffer. When you do not use the
receive buffer, you may specify 0 for the size. A typical value for the
send buffer is 512 (bytes).
Note that this routine actually allocates memory space (in contrast to
umh_res_msg()). Consequently, it is strongly advised not to use
dur_umh_init() and dur_det() in a loop. Each time you enter the loop,
memory is allocated. The memory is released only when the program

exits.
In these situations it is advisable to use umh_res_msg() and dur_att()
instead.
With p_name you are able to specify the name you want the process to
have for (M)DUR actions. When you pass the NULL pointer as
*p_name, the (M)DUR process name will be equal to the system’s
process name. Note that for those systems that give numbers to
processes, the name will be given the letters P_ (Process Ident), followed
by the process number. The process name you supply may end with an
’*’ (for example: ’myprocess_*’). In this case the ’*’ will be replaced by
the process id of the process whenever possible. When the process name
would become too long then the ’*’ is replaced by a random string.
When an error is encountered in dur_umh_init(),the routine does not
return to your process. An error is logged (using umh_panic()) and the
routine exits.
Defaults The task number in the context buffer is set to -1, indicating the main
process (or no sub-tasking).
Notes • When an error is encountered in this routine, it will not return: in

that case the routine calls umh_panic() to log the error after which
your process exits.
• When a process with the same name is already active, the attach
will not succeed.
• When an alias task number has been specified, the default task
number will be overruled by the alias, unless 0 is specified in the
alias.
• When specifying max_storage, keep in mind that the queue-size
covers all messages, including expedited messages, requests,
replies, and blocked queues (see DUR DISPLAY UTILITIES).
Moreover, the message is divided into units of 132 bytes
(typically), which introduces extra space per message.
• Some FSL library routines use BUSCOM (e.g. the date/time
routines). Only processes that are attached to DUR may use these
routines.
Related routines • dur_att()

This routine attaches to (M)DUR.

Using (M)DUR on UNIX systems Compiling, Linking and Running (M)DUR Programs
Appendix A: Using (M)DUR on

UNIX systems
A.1 Compiling, Linking and Running
(M)DUR Programs
Compiling, linking and running a program which uses (M)DUR on a
UNIX system, requires the following:
All program source files using (M)DUR facilities have to include two
header files which must be present on /tls/inc:
#include <tools.h>
#include <dur.h>
Once your application source code is complete, you compile it in the

usual manner:
For example:
> cc -I/tls/inc -c program.c
The program must be linked with buslib.a in the usual manner, for
example:
> cc program.o objects.o /tls/lib/buslib.a -o program

[...]
A.2 Process Names

It is possible to pass a name for the process in the dur_att() and
dur_umh_init() routines. This name will be used in the (M)DUR actions.
When you pass the NULL pointer as parameter, the name in (M)DUR
will be "PID_" followed by the (hexadecimal) process id.
A.3 Event Mechanism

BUS/FAST on UNIX has the following restrictions to the use of events:
• Typically 500 global events flags
• Typically 32 local events flags per process
The global event flags can be allocated by the normal routines.

The local event flags can be specified by filling the dur_evt_blk struct
manually:
node = own node number;
DUR Programmer’s Guide A-1

Event Mechanism Using (M)DUR on UNIX systems
int_event_number = -1;
local_flag = number [0....31];
It is allowed to generate local events (via dur_evt_gen) in a signal

intercept routine.
The dur_evt_blk struct has the following layout:
struct dur_evt_blk
{
TLS_SHORT node; /*Node number of the event*/
TLS_SHORT int_event_number;/* Internal number of
event*/
TLS_SHORT local_flag; /* Local flag number*/
TLS_SHORT body[5]; /* Spare*/
}
A-2 DUR Programmer’s Guide

Using (M)DUR on Windows systems Compiling, Linking and Running (M)DUR Programs
Appendix B: Using (M)DUR on

Windows systems
B.1 Compiling, Linking and Running
(M)DUR Programs
Compiling, linking and running a program which uses (M)DUR on a
Windows system, requires the following:
All program source files using (M)DUR facilities have to include two
header files which must be present on %TLS_ROOT_PATH%\tls\inc:
#include <tools.h>
#include <dur.h>

usual manner:
For example:
> cl -c -MD -D_WINNT -D_WIN32_WINNT=0x0500 -W1

-Ox -I. -I%TLS_ROOT_PATH%\tls\inc program.c
The program must be linked with dll’s of BUS/FAST in the usual

manner, for example:
> cl program.obj objects.obj

%TLS_ROOT_PATH%\tls\lib\busimp.lib
mpr.lib kernel32.lib user32.lib advapi32.lib
-o program [...]
B.2 Process Names

It is possible to pass a name for the process in the dur_att() and
dur_umh_init() routines. This name will be used in the (M)DUR actions.
When you pass the NULL pointer as parameter, the name in (M)DUR
will be "PID_" followed by the (hexadecimal) process id.
B.3 Event Mechanism

BUS/FAST on Windows has the following restrictions to the use of
events:
• Typically 500 global events flags
• Typically 32 local events flags per process
DUR Programmer’s Guide B-1

Event Mechanism Using (M)DUR on Windows systems
The global event flags can be allocated by the normal routines.

The local event flags can be specified by filling the dur_evt_blk struct
manually:
node = own node number;
int_event_number = -1;
local_flag = number [0....31];
It is allowed to generate local events (via dur_evt_gen) in a signal

intercept routine.
The dur_evt_blk struct has the following layout:
struct dur_evt_blk
{
TLS_SHORT node; /*Node number of the event*/
TLS_SHORT int_event_number;/* Internal number of
event*/
TLS_SHORT local_flag; /* Local flag number*/
TLS_SHORT body[5]; /* Spare*/
}
B-2 DUR Programmer’s Guide

Index
Index
Symbols selection 3-22

* 8-18, 8-94 D
A deadly embrace 3-28
debugging 7-1
adapting for UMH 2-2 debugging facilities 1-6
address delete
compare 3-27 message 3-22
destination 3-4, 3-9 destination address 3-8, 6-2
own process 3-27 destructive read 3-2
alias detaching 4-4
receive 3-19 DUR
send 3-11 detaching from 2-2
system type 3-12 dur_adr_cmp() 8-11
analyzing messages 7-1, 7-2 dur_adr_def() 8-12
attaching 4-4 dur_adr_ini() 8-13
dur_adr_own() 8-14
B dur_ask_exit() 8-16, 8-83
blocked queue 3-30 dur_att() 8-17
buffer dur_att_chk() 8-19, 8-21
message 3-16 dur_att_mem() 8-85
parameter 3-2 dur_can_ovf() 8-22
selection 3-22 dur_can_usr() 8-23
BUSCOM 2-1, 3-1, 3-11, 3-29 dur_can_wts() 8-24
attaching to 2-1 dur_clq_cevt() 8-25
locked 3-31, 3-32 dur_clq_cmsg() 8-26
dur_clq_ievt() 8-27
C dur_clq_imsg() 8-28
cancel dur_cnv_lnam() 8-30
events 3-26 dur_cnv_node() 8-31
Clock Queue Manager 6-1 dur_com_c_cr() 8-32
clock queue mechanism 6-1 dur_com_c_nr() 8-33
common data area dur_com_i_cr() 8-34
unlocking 7-4 dur_com_i_nr 8-36
common memory area 2-1 dur_del() 8-38
communication dur_del_rep() 8-39
inter-node 5-1 dur_del_req() 8-40
compare dur_det() 8-41
addresses 3-27 dur_evt_att() 8-42
confirmation dur_evt_can() 8-43
multi-node 3-12 dur_evt_det() 8-44
CQM messages 6-2 dur_evt_fix() 8-45
criteria dur_evt_gen () 8-46
DUR Programmer’s Guide 1

Index
dur_evt_mark() 8-47 example

dur_evt_obt() 8-48 selection 3-23
dur_evt_orl() 8-49 expedite
dur_evt_rst() 8-50 message 3-10
dur_evt_test() 8-51 expression
dur_evt_unf() 8-52 selection 3-23
dur_evt_wait() 8-53
dur_evt_wor() 8-54 F
dur_get_node() 8-57 flushing queues 7-1
dur_get_qsiz() 8-58
dur_get_var() 8-59, 8-82 G
dur_inf_node() 8-60
generating events 4-6
dur_mod_qsiz() 8-61
global event flags 4-1
dur_que_size() 8-62
dur_rcv() 8-65
dur_rcv_ini() 8-67 H
dur_rcv_rep() 8-69 help information 7-2
dur_rcv_req() 8-71
dur_req_ovf() 8-73 I
dur_req_usr() 8-74 identification number 8-20
dur_sel_adr() 8-75 initialize 3-21
dur_sel_exp() 8-76 inquiry
dur_sel_msg() 8-77 queue size 3-25
dur_sel_rep() 8-79 intercept block 7-3
dur_sel_tsk() 8-80 inter-node communication 5-1
dur_set_var() 8-59, 8-82 inter-process communication 2-4
dur_sig_exit() 8-16, 8-83 interval 6-1
dur_snap() 8-84
dur_snd() 8-86 L
dur_snd_ini() 8-88
logging messages 7-3
dur_snd_rcv() 8-89
dur_snd_rep() 8-91 M
dur_time_sec() 8-92
dur_tst_lock() 8-15, 8-92 MDUR 5-1
dur_umh_init() 8-93 mechanism
communication status 5-2
E receive 3-1
send 3-1
event block 4-2, 4-4 message
event flag 4-4 analysis 7-1
event flags 1-5, 4-3, 4-4, 4-6, 4-7 buffer 3-16
for timing purposes 4-7 delete 3-22
global 4-1 expedite 3-10
obtaining 4-3 id 3-10
polling 4-6 logging 7-3
resetting 4-6 passing 3-1
event mechanism 1-5, 4-1 priority 1-4, 3-10
events redirection 7-3
cancel 3-26 size 3-9
generating 4-6
message passing 1-3
2 DUR Programmer’s Guide

Index
message routing 7-1 queue size

mode inquiry 3-25
asynchronous receive 3-19
receive 3-18 R
synchronous 3-4 receive
monitoring alias 3-19
communication status 5-2 asynchronous mode 3-19
multi-node mode 3-18
confirmation 3-12 options 3-15
multi-processor DUR (MDUR) 2-3 parameters 3-5
paramters 3-15
N routines 3-15
node session 3-4
information 3-26 receive mechanism 3-1
receive options 1-4
O redirection of messages 7-3
options reply
receive 1-4, 3-15 required 3-2, 3-10
send 1-4 request 3-2
synchronization 1-4 routing of messages 7-1
overflow
detection 8-22 S
message 8-22 selection
own queue 3-29 buffer 3-22
own process criteria 3-22
address 3-27 example 3-23
own queue expression 3-23
overflow 3-29 send
alias 3-11
P mechanism 3-1
P_ 8-17, 8-94 option 3-7
parameter parameters 3-4, 3-7
buffer 3-2, 3-5 routines 3-7
parameters session 3-4
receive 3-15 send options 1-4
physical line 5-2 shared variables 1-2
priority SIGHUP 8-16, 8-83
message 1-4 SIGINT 8-16, 8-83
process size
restart 3-28 message 3-9
timer 6-1 synchronization options 1-4
process ident 8-20 synchronous mode 3-4
process task 3-9 system type
alias 3-12
Q
queue
T
blocked 3-30 task number 3-9
queue blocking 7-4 test
BUSCOM lock 3-31, 3-32
DUR Programmer’s Guide 3

Index
restart 3-28
time_table.sup 7-4
timer 6-1
processes 6-1
time-stamp 3-27
W
wait for events 4-5
4 DUR Programmer’s Guide

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction EQUIPMENT/FAST FAST/TOOLS
IM50L02L00-01EN/R10.03

IM50L02L00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction ..........................................................................1-1
1.1 About the product ......................................................1-1
1.2 About the environment ..............................................1-1
2 Message overview .................................................................2-1
2.1 General message layout .............................................2-1
2.2 Supported messages ...................................................2-1
3 Reference ...............................................................................3-1
3.1 Message layouts .........................................................3-1
3.1.1 Force total scan. ........................................................ 3-2
3.1.2 Save all on disk. ........................................................ 3-3
3.1.3 Force item update request. ........................................ 3-4
3.1.4 User actions on item request. .................................... 3-5
3.1.5 Read item on request. ................................................ 3-6
3.1.6 User request for a slave. ............................................ 3-7
3.2 Functions ...................................................................3-8
EQUIPMENT/FAST Programmer’s Guide iii

Table of Contents
iv EQUIPMENT/FAST Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives
functionality of the EQP-brick.
EQP-routines.

language. To understand the concept of EQP, the reader is assumed to
have knowledge of the BUS/FAST message passing facilities
((M)DUR).
Furthermore the reader is assumed to have knowledge of the BUS/FAST
error logging facility (UMH).

This manual contains the following chapters:
• Chapter 1 can be regarded as an introduction to the EQP
functionality, features, environment, etc.
• Chapter 2 contains a description of the EQP message interface
method.
• Chapter 3 contains a description of the available messages and their
replies.
EQUIPMENT/FAST Programmer’s Guide 0-1


1 EQUIPMENT/FAST Maintenance Manual
This manual contains information necessary to change the basic
EQP functions.
which are used.
software.
3 FAST/CONVENTIONS Reference Guide.

CONVENTION MEANING
passed.
optional.
DUR_NOWAIT.
input.
returns.
0-2 EQUIPMENT/FAST Programmer’s Guide


output.
literally.
n.u. not used.
a terminal.
from the user.


About the product Introduction
1 Introduction
1.1 About the product

The equipment manager brick (EQP) is a framework handling the
communication to the field. Together with the equipment plug-in
architecture (EPA) is it the link between the equipment (e.g. PLCs, DCS
systems or RTU equipment) and the item handler. EQP/EPA knows
about the relation of item ids in the FAST/TOOLS system and the I/O
addresses in the equipment. The conversion from binary data in the
equipment to engineering units in the FAST/TOOLS system is done by
EQP/EPA.
For each possible plug-in a separate EQP process is created, e.g.
EQPMDC (equipment manager with modbus master plug-in) and
EQPFCX (equipment manager with STARDOM plug-in).
An EQP process can handle a set of slave stations connected via one
logical communication line (with or without a backup communication
line).
When more sets of slave stations should be connected, more EQP
processes can be started.
1.2 About the environment

The equipment manager has a relationship with the following programs/
bricks:
• DSS
With this brick, slave station information and item information can
be inserted or changed.
• ITM
Changed input items are updated by the equipment manager in the
item table and output events from the item table are sent to the
equipment.
• EQPDBG
With this process statistical information can be shown and the
equipment manager can be parametrized and debugged.

Introduction About the environment
• Special utilities
There are some special utilities available such as a cold start
program.
• User utilities
Users are able to make their own utilities which communicate with
the equipment manager.

General message layout Message overview
2 Message overview
2.1 General message layout

The equipment manager can handle clustered messages up to a
maximum of 2000 bytes. The layout of a clustered message is:
TLS_SHORT size; /* first message size */
TLS_SHORT code; /* first message code */
struct message; /* first message */
TLS_SHORT size; /* second message size */
TLS_SHORT code; /* second message code */
struct message; /* second message */
...
The equipment manager will process the messages until the total size of
the handled messages is equal to the receive buffer size. Therefore
sending a buffer which is too long will have unpredictable results.
The reply messages will be clustered in the same way. The maximum
reply size is 7000 bytes. The code of a good reply message is the same
as the received message code. For the error reply code an extra bit
(0x8000) is set and the contents of the reply will be a UMH error buffer.
When the reply buffer is too small to contain the complete answer, an
error will be stored in the reply buffer. If there is also no space for the
error, an error is logged directly by the equipment manager.
2.2 Supported messages

The following messages may be sent to the equipment manager:
Code Description
EQP_COD_RES_STAT reset statistics.

EQP_COD_LINE_INS insert a line.
EQP_COD_SLAVE_INS insert a slave.
EQP_COD_SLAVE_MOD modify a slave.
EQP_COD_SLAVE_APPL insert/update slave application information.
EQP_COD_SLAVE_DEL delete slave info.

Message overview Supported messages
Code Description
EQP_COD_SLAVE_STAT get slave statistics.

EQP_COD_SLAVE_SCAN change slave scan status.
EQP_COD_SLAVE_ADR change slave address info.
EQP_COD_ITEM_INS insert item request.
EQP_COD_ITEM_CHA change item request.
EQP_COD_ITEM_DEL delete item request.
EQP_COD_TOTAL_SCAN force total scan.
EQP_COD_SAVE_ALL save all on disk.
EQP_COD_READ_MAIN read main info.
EQP_COD_READ_SLAVE read slave info.
EQP_COD_READ_SLAVE_SP read slave special info.
EQP_COD_READ_SLV_SCAN read slave scan status info.
EQP_COD_READ_TYPE read type info.
EQP_COD_READ_SCAN read scan rate info.
EQP_COD_READ_POINT read item pointer info.
EQP_COD_READ_ITEM read item info.
EQP_COD_READ_APPL read slave application info.
EQP_COD_ITEM_FU force item update request.
EQP_COD_ITEM_USER user actions on item request.
EQP_COD_ITEM_READ read item from PLC on request.
EQP_COD_SLAVE_USER user request message for a slave.
EQP_COD_GITEM get all info about one item.
EQP_COD_SLAVE_LOG change loging file size.
EQP_COD_RE_INIT re-initialize slave request.
EQP_COD_SUPR_OUTP modify output suppression.
EQP_COD_READ_DLL read shared code area name.

Message layouts Reference
3 Reference
3.1 Message layouts

This section describes the EQUIPMENT/FAST functions which may be
useful for application processes. For all other messages see the EQP.H
file for the information.
For each message a description is given of:
• The function of the message.
• The message code.
• The message format.
• The message layout.
• The reply layout.
• Notes.

Reference Message layouts
3.1.1 Force total scan.
Function Inform the equipment manager to handle a complete scan rate group in
the next tick.
Message code EQP_COD_TOTAL_SCAN
Message format EQP_COD_TOTAL_SCAN_FMT
Message layout struct eqp_total_scan

{
TLS_SHORT slave; /* slave number */
TLS_SHORT io_type; /* type of i/o */
TLS_SHORT scan_rate; /* scan rate to handle */
TLS_SHORT spare1;
};
Reply layout Reply message is empty.
Notes With this request, scan rates with a negative number can be read on
request (negative scan rate numbers are not read by the normal scan).

3.1.2 Save all on disk.
Function Inform the equipment manager to save all its information on disk.
Message code EQP_COD_SAVE_ALL
Message format EQP_COD_SAVE_ALL_FMT
Message layout struct eqp_save_all

{
TLS_BOOLEAN exit_flag; /* exit after save wanted */
};
Notes This message can be used to shutdown the equipment manager.

3.1.3 Force item update request.
Function Declare an item as being not yet initialized.
Message code EQP_COD_ITEM_FU
Message format EQP_COD_ITEM_FU_FMT
Message layout struct eqp_item_fu

{
TLS_SHORT io_type; /* type number */
TLS_LONG io_address; /* i/o address of item */
};

3.1.4 User actions on item request.
Function Ask the equipment manager to handle user defined action on an item.
Message code EQP_COD_ITEM_USER
Message format EQP_COD_ITEM_USER_FMT
Message layout struct eqp_item_user

{
TLS_LONG body[1]; /* (start of) body */
};
Reply layout Reply message is application dependent.
Notes The body of the message and the reply message are conversion type
dependent.The message layout is specified in the EQUIPMENT/FAST

3.1.5 Read item on request.
Function Ask the equipment manager to read an item synchronously from the
PLC.
Message code EQP_COD_ITEM_READ
Message format EQP_COD_ITEM_READ_FMT
Message layout struct eqp_item_read

{
};
Notes The reply is given after the item value is stored in the item table.

3.1.6 User request for a slave.
Function Ask the equipment manager to process a user specific message for a
certain slave.
Message code EQP_COD_SLAVE_USER
Message format EQP_COD_SLAVE_USER_FMT
Message layout struct eqp_slave_user

{
TLS_SHORT spare; /* spare */
TLS_LONG body[1]; /* slave dependent info */
};
Reply layout The reply is slave type dependent.
Notes The body of the message and the reply message are slave type
dependent. The message layout is specified in the EQUIPMENT/FAST

Reference Functions
3.2 Functions
EQUIPMENT/FAST contains a limited set of externally callable
functions. All these functions are specific for one of the supported
protocols and are therefor documented with the specific protocols.

Index
Index
D
DSS 1-1
E
environment 1-1
EQP 1-1
EQP_COD_ITEM_FU 3-4
EQP_COD_ITEM_READ 3-6
EQP_COD_ITEM_USER 3-5
EQP_COD_SAVE_ALL 3-3
EQP_COD_SLAVE_USER 3-7
EQP_COD_TOTAL_SCAN 3-2
eqp_item_fu 3-4
eqp_item_read 3-6
eqp_item_user 3-5
eqp_save_all 3-3
eqp_slave_user 3-7
eqp_total_scan 3-2
EQPDBG 1-1
I
ITM 1-1
M
message layout 2-1
messages overview 2-1
EQUIPMENT/FAST Programmer’s Guide 1

Index
2 EQUIPMENT/FAST Programmer’s Guide

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Manual GIN Programmer’s Guide
IM50B02B00-01EN/R10.03

IM50B02B00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 INTRODUCTION ................................................................1-1
1.1 What is GIN ...............................................................1-1
1.2 Environment of GIN ..................................................1-2
2 GIN Mechanisms ..................................................................2-1
2.1 Basic principle ...........................................................2-1
2.2 GIN database interface ..............................................2-2
2.2.1 Usage of GIN database interface .............................. 2-3
2.3 GIN in distributed item interface ...............................2-4
2.3.1 Item access scheme ................................................... 2-4
2.3.2 Initializing GIN distributed item interface ................ 2-6
2.3.3 Using the distributed GIN interface .......................... 2-7
2.4 GIN distributed event notification .............................2-8
2.4.1 Requesting items events ............................................ 2-9
2.4.2 Setting flow control ................................................ 2-11
2.4.3 Processing event messages ..................................... 2-12
2.4.4 Periodic housekeeping ............................................ 2-13
2.4.5 Event buffering ....................................................... 2-13
2.4.6 Terminating GIN distributed item interface ........... 2-13
2.4.7 Using GIN DII with ITEM/FAST routines ............. 2-14
3 Reference ...............................................................................3-1
3.1 Conventions ...............................................................3-1
3.2 Compiling, Linking and Running Programs ..............3-2
3.3 Error Handling ...........................................................3-2
3.3.1 How is UMH integrated? .......................................... 3-2
3.4 Data Structures ..........................................................3-3
3.4.1 Alarm-storage group parameters .............................. 3-3
3.4.2 Area of interest .......................................................... 3-3
3.4.3 Alarm selection area ................................................. 3-3
3.4.4 GIN context ............................................................... 3-4
3.4.5 GIN dIstributed item id ............................................. 3-4
3.4.6 GIN dIstributed item value ....................................... 3-5
3.4.7 GIN dIstributed AUDIT/FAST information ............. 3-5
3.4.8 Item alarm parameters .............................................. 3-6
GIN Programmer’s Guide iii

Table of Contents
3.4.9 Item id ....................................................................... 3-7

3.4.10 Item info .................................................................... 3-8
3.4.11 Item name .................................................................. 3-9
3.4.12 Item-id/item-name info ............................................. 3-9
3.4.13 User profile ............................................................... 3-9
3.5 Routines .................................................................. 3-11
3.5.1 Introduction ............................................................. 3-11
3.5.2 Delete area of interest ............................................. 3-13
3.5.3 Retrieve area of interest
(read mode “equal”) ................................................ 3-14
(read mode “first”) .................................................. 3-15
(read mode “greater- equal”) ................................... 3-16
(read mode “next”) .................................................. 3-17
3.5.7 Insert area of interest ............................................... 3-18
3.5.8 Retrieve alarm selection area
(read mode “equal”) ................................................ 3-19
(read mode “first”) .................................................. 3-20
(read mode “greater- equal”) ................................... 3-21
(read mode “next”) .................................................. 3-22
3.5.12 Initialization of gin-context data structure .............. 3-22
3.5.13 Obtain alarm parameters of an item (version 2)
(read mode “equal”) ................................................ 3-23
(read mode “equal”) ................................................ 3-25
(read mode “equal”) ................................................ 3-26
(read mode “equal”) ................................................ 3-28
3.5.17 Obtain id of an item giving the name of the item
(read mode “equal”) ................................................ 3-29
3.5.18 Obtain name of item giving the id of the item
(read mode “equal”) ................................................ 3-30
3.5.19 Obtain id and name of item giving the name of the
............................ item (read mode “greater-equal”) 3-31
item (read mode “greater”) ..................................... 3-32
3.5.21 Obtain specific item info (version 2)
(read mode “equal”) ................................................ 3-33
(read mode “equal”) ................................................ 3-34
(read mode “equal”) ................................................ 3-36
(read mode “greater”) .............................................. 3-36
(read mode “greater”) .............................................. 3-38
iv GIN Programmer’s Guide

Table of Contents
3.5.26 Delete entry from item-used file ............................. 3-39

3.5.27 Read entry from item-used file
(read mode “equal”) ................................................ 3-40
(read mode “greater-equal”) ................................... 3-42
(read mode “greater”) ............................................. 3-43
3.5.30 Insert entry in item-used file ................................... 3-45
3.5.31 Update entry in item-used file ................................. 3-46
3.5.32 Delete entry from user-file ...................................... 3-47
3.5.33 Delete entry from user-file (version 2) ................... 3-49
3.5.34 Obtain CWS info from user-file
(read mode “equal”) ................................................ 3-49
3.5.35 Obtain general info from user-file
(read mode “equal”) ................................................ 3-51
3.5.36 Obtain general info from user-file (version 2)
(read mode “equal”) ................................................ 3-53
(read mode “first”) .................................................. 3-53
(read mode “first”) .................................................. 3-55
(read mode “greater-equal”) .................................. 3-56
(read mode “greater-equal”) .................................. 3-57
(read mode “greater”) ............................................ 3-58
(read mode “greater”) ............................................ 3-60
(read mode “next”) .................................................. 3-61
(read mode “next”) .................................................. 3-63
3.5.45 Insert entry in user-file ............................................ 3-63
3.5.46 Insert entry in user-file (version 2) ......................... 3-65
3.5.47 Update CWS-info in user file ................................. 3-66
3.5.48 Update entry in user file .......................................... 3-67
3.5.49 Update entry in user file (version 2) ....................... 3-69
3.6 GIN distributed item interface .................................3-70
3.6.1 Allocate additional memory block for an item ....... 3-70
3.6.2 Enable/Disable event buffering ............................... 3-71
3.6.3 Periodic houskeeping function ................................ 3-71
3.6.4 Delete additional memory block for an item .......... 3-72
3.6.5 Translate textual attribute name to attribute id ....... 3-72
3.6.6 Get one or more attributes of an item ..................... 3-78
3.6.7 Get distributed item id by item id ........................... 3-83
3.6.8 Get distributed item id by item name ...................... 3-84
3.6.9 Get multiple distributed item ids by item names .... 3-85
3.6.10 Get distributed item id by PROCESS/FAST signal 3-86
3.6.11 Get multiple distributed item ids by PROCESS/FAST
signals 3-87
GIN Programmer’s Guide v

Table of Contents
3.6.12 Get pointer to additional memory block ................. 3-88

3.6.13 Process GIN DII message ....................................... 3-88
3.6.14 Initialize GIN DII interface ..................................... 3-89
3.6.15 Request/Cancel an event for an item ....................... 3-91
3.6.16 Set one or more attributes of an item ...................... 3-95
3.6.17 Enable/Disable flow control to a specified node .... 3-98
3.6.18 Connect additional memory block to an item ......... 3-99
3.6.19 Terminate GIN DII interface ................................. 3-100
vi GIN Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives
functionality of the GIN-brick.
GIN-routines.

language. To understand the concept of GIN, the reader is assumed to
((M)DUR).
Furthermore the reader is assumed to have knowledge of he BUS/FAST

This manual contains 4 chapters;
• Chapter 1 and 2 can be regarded as an introduction to the GIN
mechanism.
familiar with the concept of GIN.

• BUS/FAST Programmer’s Guide, Part UMH.
This manual provides a description of the standard error logging
GIN Programmer’s Guide 0-1

facilities which are used by the GIN routines.

• INTEGRATION System Integrator’s Manual
This manual provides (amongst some other subjects) a description
of the databases that will be indirectly accessed by means of the
GIN routines.

CONVENTION MEANING
DUR_NOWAIT.
input.
returns.
output.
literally.
0-2 GIN Programmer’s Guide


n.u. not used.
a terminal.
from the user.
|| Same as logical OR function.


What is GIN INTRODUCTION
1 INTRODUCTION
1.1 What is GIN

In essence the purpose of every FAST/TOOLS process is too manipulate
data. The source of the data can for example be an other process or a
database. If for any reason the layout of a database record has to be
changed, all processes that make use of this record must be adapted and
re-compiled.
The general interface (GIN) was introduced to avoid these problems.
GIN routines manipulate data by sending and receiving messages from
the integration server (int-server). If a data store is changed only the int-
server has to be adapted. The GIN interface can remain the same.
An other imported characteristic of GIN is that it makes the handling of
items transparent cross FAST/TOOLS nodes. Whenever an item
attribute is requested or changed in a distributed FAST/TOOLS system
via the GIN interface, GIN will make sure that these changes are updated
on the right node. If GIN can’t reach data on a specific node, it will try
to find an alternative route to that data. The cross node behavior of the
GIN can be controlled from a setup file.
GIN is an interface to those parts of FAST/TOOLS that are allowed to
be customized in the sense that a user is allowed to modify sources and/
or definitions of those parts of the FAST/TOOLS. In fact the only brick
that is allowed to be fully changed by a user is commonly known as INT.
The INT-brick is delivered in source form allowing end-users to modify

this brick to their specific needs (including record layout modifications).
However after modification of this brick, other bricks relying on certain
definitions made in this brick (especially definitions of record layouts),
will not work properly anymore.
The GIN brick provides primitives to create a more loose coupling
between the INT-brick and the rest of the system. In other words, the
GIN brick maintains a data flow between the INT-brick and all other
bricks, essentially not based on a routine interface but based on message
passing through BUS/FAST. By doing so, it is not necessary to
regenerate parts of the FAST/TOOLS as long as the layout of the
messages are not changed.

INTRODUCTION Environment of GIN
1.2 Environment of GIN

The functioning of GIN is dependent on three facts:
• The availability of BUS/FAST
• The execution of the INT-SERVER process.
• The execution of ITEM/FAST
The function of the INT-SERVER process will be explained in more
detail in chapter 2.
The availability of BUS/FAST and the execution of the INT-SERVER
process are the two runtime components that GIN is relying on. If they
are not available the GIN interface will not function properly.

Basic principle GIN Mechanisms
2 GIN Mechanisms
2.1 Basic principle

As outlined in the previous chapter the purpose of GIN is twofold:
• Offer a consistent interface to FAST/TOOLS databases
• Make item manipulation transparent across nodes
If we take a detailed look at the GIN interface it becomes clear there are
really two interface. One for databases access and one for item
manipulation. This is shown in the figure below.
Application
GIN Database Distributed item

Routines interface interface
INT-SERVER ITEM/FAST
Figure 2-1 GIN Basic principle
The database interface routines use the INT-SERVER process to read

and write information to and from FAST/TOOLS data stores. The
distributed item interface routines provide a node transparent layer on
top of ITEM/FAST.
GIN routines can be distinguished by name prefix:
• gin_..... GIN database interface routine
• gin_dii_.... GIN distributed item interface routine

GIN Mechanisms GIN database interface
2.2 GIN database interface

The GIN database interface uses the so-called INT-SERVER as a
transfer point between the INT-brick and other software interfacing with
this INT-brick.
The INT-SERVER (integration server) is a process that receives
requests via BUS/FAST, calls the appropriate routine after receiving a
certain request and sends a reply to the sender of the request.
The interface is fixed in the sense that the layout of existing request/
reply messages will never change whatever changes inside the INT-
brick. It is allowed to define additional request/reply messages for the
interface to the INT-SERVER.
Except for being a transfer point between the INT-brick and other
software, the INT-SERVER is also responsible for the creation of the
files being part of the INT-brick.
BUS/FAST interface
INT-brick other bricks

int-server
= gin routine
store A store B store C
Figure 2-2 GIN mechanism
Upon a certain information request, the INT-SERVER gathers the

required information. This information is translated by the INT-
SERVER into the format defined within the GIN definition. Once the
data is put into its correct format it is sent off to the requester.
Because the INT-SERVER is delivered in source form, end-users are
able to modify the INT-SERVER. This might be necessary after they
have made changes to the INT-brick. This modification of the INT-
SERVER code should be directed towards supplying a fixed format
interface. In other words, after a change in the INT-brick, nothing should
change in the format of the reply sent by the INT-SERVER, after an
information retrieval request.
For each type of INT-SERVER request, a separate gin-routine is
available. Each of these gin-routines has the following functions:

GIN database interface GIN Mechanisms
• Assembling the request message (filling up the header and the body
of the request).
• Sending the request to the INT-SERVER.
• Receiving the reply from the INT-SERVER.
• Unpacking the reply and passing the information in the reply to the
caller of the gin-routine.
The GIN routines enables the caller to manipulate data, physically stored
on another node, Therefore it is sometimes necessary to perform a
machine dependent data conversion. This conversion is done by the
INT-SERVER, thereby freeing the caller of the GIN routine from the
burden of machine dependent data conversion.
2.2.1 Usage of GIN database interface
The usage of the GIN database interface is straightforward.The first

thing to do is the initialization of a GIN data structure by a call to a
special GIN-routine (routine “gin_init()”). This GIN data structure
contains information necessary to communicate with the INT-SERVER.
This data structure is passed by reference to all other GIN-routines.
struct gin_context *gin_c; /* GIN context */

struct dur_context *dur_c; /* DUR context */
struct umh_context *umh_c; /* UMH context */
int node; /* Node of INT-SERVER process */
int timeout; /* Timeout on reply INT-SERVER */
node = 0;
timeout = 30;
. . .
. . .
if(!gin_init(gin_c,dur_c,umh_c,node,”INT_SERVER”,timeout))
{
return 0;
}
Now that the we have to initialize the GIN database interface we can call
any database routine. Example.
if (!gin_itm_getn(gin_c,itm_id,item_name))
return 0;
}

GIN Mechanisms GIN in distributed item interface
2.3 GIN in distributed item interface

In a distributed FAST/TOOLS environment GIN routines are used to
obtain and manipulate item attributes across nodes. When one of the
nodes goes off-line (is not reachable by other nodes) then the whole
distributed environment must continue to operated in the best possible
way. The other nodes must automatically try to find another
communication path to the data that went off-line. When the node comes
on-line again, the other nodes must automatically re-establish the
original data communication paths.
The GIN distributed item interface contains a number of routine that
take care of handling all these multi node aspects for you. The GIN
interface takes care of:
• Obtaining item attributes from the correct node.
• Setting item attributes on the correct node.
• Redirect event request to another node when the current node fails.
This functionality is performed transparently to the user. For example,
when the user is interested in real time updates, the GIN interface makes
sure that he gets the updates from the best available source in the
distributed system.
2.3.1 Item access scheme
The GIN distributed item interface ensures that all read and update
actions on items are handled in a consistent manner. Table 2.1 shows the
default GIN DII behavior. Depending on the type of item and the type of
FAST/TOOLS node (Host, Front-end, HMI) you can read from this
table where items are read (R), updated (U) or when event notification
was requested, which node is used a event source (E). A letter H in a
table cell indicates item action are done on the host node, a letter F
indicates the front-end node. If a table cell is empty no item can be
reached.

GIN in distributed item interface GIN Mechanisms
Table 2.1: Default behaviour GIN distributed item interface
Application running on:

Item type Node condition
Host Front-end HMI
R U E R U E R U E
Local Host both are up H H H H H H H H H
font-end is down H H H H H H
host is down
both are down
Local both are up F F F F F F F F F

Front-end
font-end is down
host is down F F F F F F
both are down
Distributed both are up H H H F F F H H H

Master on
Both font-end is down H H H H H H
both are down
Distributed both are up H F H F F F H F H

Master
Front-end font-end is down H H H H
both are down
Distributed both are up H H H F H F H H H

Master
Host font-end is down H H H H H H
host is down F F F F
both are down
This default behavior can be overwritten in the setup file gin.sup. The
behavior can be overruled for all tools or for a particular tool. If you
want to apply this rule to all processes you can use a ‘*’ wild card instead
of a process name:
ITEM_READ_PRIORITY= *,LOCAL, HOST, FRONT-END
However, you can apply a different scheme for a process by adding a

line for that process to the setup file:
ITEM_READ_PRIORITY= PROCESS, LOCAL, HOST, FRONT-END

GIN Mechanisms GIN in distributed item interface
This entry means that ‘PROCESS’ tries to access the item on its own
node first, when this fails it tries the host node and when this also fails it
tries the front-end node. The ITEM_READ_PRIORITY keyword can be
used to set any order in which items should be reached.
Updating an item is always performed on the master node. However for
the Distributed Master Both items access order is can be defined in
gin.sup:
ITEM_WRITE_PRIORITY= *, LOCAL, HOST, FRONT-END
This means that when the master node is down in case of a distributed-
master-host or a distributed-master-front-end item then updating the
item is not possible.
If you use the GIN DII interface to request item events from ITEM/
FAST the event source node is controlled by the
ITEM_READ_PRIORITY keyword.
2.3.2 Initializing GIN distributed item interface
The usage of the GIN distributed item interface is similar to using the
database interface. If you want to request item events you must initialize
the interface before use and specify the range of BUS/FAST message
codes you want to be handled by the GIN distributed item interface.
if(!gin_dii_init(umh_c, GIN_DII_OPTION_DUR_TIMEOUT, 45,

GIN_DII_OPTION_HOST_NODE, 161,
GIN_DII_OPTION_MSG_BASE, 100,
GIN_DII_OPTION_MSG_RANGE, 15,
GIN_DII_EOL));
The GIN_DII_OPTION_MSG_BASE option sets the start of the message code

range and the GIN_DII_OPTION_MSG_RANGE sets number of messages.
The gin_dii_init() can take a variable list of arguments. The last
argument must always be ‘GIN_DII_EOL’, indicating the end of the
argument list. The GIN distributed item interface is now ready for use.
Initializing the GIN distributed item interface is not necessary for
reading and writing item attributes

GIN in distributed item interface GIN Mechanisms
2.3.3 Using the distributed GIN interface
To use the distributed GIN interface on a item you need the item’s
distributed item id. Using the gin interface you can obtain the distributed
item id either by item name, by item id or by PROCESS/FAST signal
path. The routine gin_dii_gidn() takes the item id as argument and
returns the distributed item id:
struct gin_dii_id *dii_id; /* Distributed item id */
char *item_name; /* Item name */
dii_id = gin_dii_gidn(umh_c, item_name);
The layout of the item name is as follows:

[<node_name>:]<installation>.<unit>.<tag>[.<sub>]
When the optional node_name is specified than this node is used to read
and update item attributes, independent of any access scheme set for the
process as described in section 2.3.1 on page 4. When the node name is
omitted the current access scheme is used.
The routine gin_dii_gidi() returns the distributed item id of an item
specified by its item id.
int node; /* Item node */
char *itm_id item_id; /* Item id struct */
dii_id = gin_dii_gidi(umh_c, node, item_id);
When node argument is zero, then the routine uses the current access
scheme, else the specified node is used to read and update item
attributes.
The access scheme for the item will be used to determine where to obtain
item information. This is necessary because when the request is made,
the connections to other systems (e.g. host) may not be available at that
time.
The routine gin_dii_gids() takes the PROCESS/FAST objects name and
signal path as arguments and returns the distributed item id:
char *object_name; /* Object name */

GIN Mechanisms GIN distributed event notification
char *signal_path; /* Signal path */
dii_id = gin_dii_gids(umh_c, object_name, signal_path);
The layout of the object name is as follows:

[<node_name>:]<installation>.<unit>.<tag>
When the optional node_name is specified than this node is used to read
and update item attributes, independent of any access scheme set for the
process as described in section 2.3.1 on page 4. When the node name is
omitted the current access scheme is used.
Now that we have initialized the GIN interface and obtained the
distributed item id we can use GIN to get item attributes:
int attrib_id; /* Attribute id */
struct gin_dii_val *attrib_val; /* Attribute value buffer */
attrib_id = GIN_DII_VALUE;
gin_dii_gatr(umh_c, dii_id, attrib_id, (void *) &attrib_val,
GIN_DII_EOL);
The gin_dii_gatr routine is used to obtain item attributes is a distributed

FAST/TOOLS system. Each attribute that is available through the gin
interface is assigned a attribute id. In the example we use the
GIN_DII_VALUE to get the items value. The attribute value is stored in
the attribute value buffer that follows the attribute id. The gin_dii_gatr()
routine accepts a variable number of arguments and can thereby return
more than one item attributes in one call. The GIN_DII_EOL flag must
always be passed as last argument to indicate the end of the parameter
list.
2.4 GIN distributed event notification

The GIN distributed items interface should be used to request
notification of item attribute changes in a distributed FAST/TOOLS
system.

GIN distributed event notification GIN Mechanisms
2.4.1 Requesting items events
The gin_dii_revt( ) routine is used to request and cancel event

notifications for an item. You have to provide the routine with the
distributed item id and the attribute id for which you want notification.
Furthermore you have to provide a call-back function that will be called
when an event on an item occurs. This call-back takes the item id of the
item for which the event occurred and the attribute id of the attribute that
has changed as parameters. It can than use the gin_dii_gatr() the obtain
the new attribute value.
struct umh_context *dur_c; /* UMH context */
int flags; /* Contains optional flag bits */
void *context; /* Used to pass context info to
/* callback routine */
int attr_id; /* Attribute to be notified on */
TLS_BOOLEAN gin_dii_revt(umh_c, dii_id, flags,

GIN_DII_EVT_FNC callback_fnc,
context,
attr_id, ..., GIN_DII_EOL);
The distributed item id (dii_id) specifies the item. The flags argument
can contain two flags:
The GIN_DII_FLG_CANCEL_EVT field is set to stop notification for
the specified item / event combination.
If the GIN_DII_FLG_OLD_VAL field is set the old (previous) attribute
value is also made available through the gin_dii_gatr() function.
GIN_DII_EVT_FNC is a typedef defined in gin.h. It defines the
parameter list for callback_fnc()
Attribute id specifies the attributes to request events for. Multiple

attributes can be specified. The last attribute is terminated by the
GIN_DII_EOL. It is also possible to call the function multiple times to
with different attributes.
The callback routine could be used in the following manner:

int attr_id; /* Item attribute for which */

/* Event occurred */
int reason; /* Reason the callback occurred */
void *context; /* Used to receive context info */
/* from gin_dii_revt. */
TLS_BOOLEAN callback_fnc(umh_c, dii_id, attr_id, reason, context)

{
struct gin_dii_val *attrib_val; /* Attribute value buffer */
if (reason == GIN_DII_UPDATE)
{
gin_dii_gatr(umh_c, dii_id, attr_id, (void *) &attrib_val,
GIN_DII_EOL);
.....
.....
}
}
The callback_fnc routine is also called when communication with the

item goes off-line or on-line or switches to another node. The reason
why the callback was called is reflected in the ‘reason’ argument.

2.4.2 Setting flow control
This routine is used to enable or disable flow control to the specified

node. The flow control mechanism is used to periodically check the
connection to ITEM/FAST. When requested to do so ITEM/FAST will
notify other process of item attribute changes. If your process hasn’t
receive a message from ITEM/FAST this can be either because there
was no change in any item attribute or the connection to ITEM/FAST
was somehow lost.
To make sure there is no problem in the connection you can request flow
control messages from a specific node. ITEM/FAST will then make sure
you receive at least one message during the interval you specified. If
there aren’t any regular messages during that interval, ITEM/FAST will
send you a flow control message, just to let you know the connection is
working.
The flow control routine of the GIN distributed item interface lets you
start and stop flow control from a FAST/TOOLS node. If you wish it can
also inform you when the event flow has switch to another node:

int node; /* Node for which flow control */
/* is set */
int interval; /* Flow control interval */
void *context; /* Used to pass context info to */
/* callback routine */
TLS_BOOLEAN gin_dii_sflw(umh_c, node, interval,

GIN_DII_FLW_FNC callback_fnc,
context);
When node is -1 flow control enabled or is disabled for all nodes, else
flow control is enabled or disabled for the specified node. When interval
is set to number smaller than 1 then flow control is disabled. The interval
is in seconds.
The address of a function can be specified (NULL when omitted) that is
called when something in the flow of a node is changed. The node
involved is supplied as an argument. In case of a flow redirection then
the old node is also supplied as an argument.
parameter list for callback_fnc(). The context buffer can be used to pass

information on to the call-back routine.This routine can be used as a

logging function for example:
TLS_BOOLEAN callback_fnc(umh_c, node, old_node, reason, context)

{
int node; /* New node to recv events from */
int old_node;/ /* Previous node */
/* from gin_dii_sflw(). */
switch(reason)
{
case: GIN_DII_OFFLINE
printf(“Node %d is offline, no flow anymore\n”, node);
break;
case: GIN_DII_ONLINE
printf(“Node %d is online again\n”,node);
break;
case: GIN_DII_OFFON
printf(“Event flow switched from node: %d to node %d\n”,
node_old, node);
break
} }
2.4.3 Processing event messages
The GIN DII interface has is own routine to process messages that arrive
via BUS/FAST. These include item event messages and flow control
messages.
struct dur_context *umh_c; /* DUR context */
struct fmc_elm *elm,; /* (M) Message element */
struct dur_par_rcv *par_rcv; /* Received DUR message */
TLS_BOOLEAN gin_dii_hdl(umh_c, fmc_elm, par_rcv);
Any (clustered) messages received by the calling process with a

message id within the range specified in gin_dii_init() should passed via
this routine.

2.4.4 Periodic housekeeping
This routine must be called each second, and performs housekeeping

functions for the DII interface.
TLS_BOOLEAN gin_dii_chk(umh_c);
It checks for flow control time-outs on all subscribed nodes and re-
initializes flow if necessary. Flushes any outstanding clustered messages
for each node.
2.4.5 Event buffering
This routine is called to enable/disable event buffering. You can request

ITEM/FAST to buffer event messages. ITEM/FAST will then create a
event buffer on it’s local node. All events are stored in the buffer and
sent to you in a single BUS/FAST message when then buffer is full or
an predefined time interval has elapsed, what ever happens first.
int node; /* Node to create buffer */
int size; /* Buffer size in bytes */
float timeout; /* Timeout in sec.millisec */
TLS_BOOLEAN gin_dii_cebf(umh_c, node, size, timeout);
When the node is -1 then all nodes are involved otherwise the specified
node only. When a size of zero is specified then event buffering is
disabled. The timeout is specified in seconds and may contain a fraction
to represent milli-seconds.
2.4.6 Terminating GIN distributed item interface
If you have initialized the GIN DII you should terminate your
connection to free resources before you exit your program exists. The is
done simply by calling gin_dii_term()
TLS_BOOLEAN gin_dii_term(umh_c);

2.4.7 Using GIN DII with ITEM/FAST routines
The GIN distributed item interface makes use of ITEM/FAST routines

that use their own context. Therefore is not possible to use ITEM/FAST
routines (itm_....) and GIN DII routines (gin_dii_....) in the same
process.

Conventions Reference
3 Reference
3.1 Conventions
All GIN routines have C-type interfaces. The syntax of all routines as
well as the examples comply with C Language Bindings.
In the routine descriptions the pointer to each parameter - not being a
scalar argument - is declared.
Note: Unless otherwise stated, the parameter itself has to be
declared as well!
The direction of the argument is indicated with:
• (R) - Indicates the return value of a routine, which in most cases
is a TLS_BOOLEAN returning TRUE or FALSE.
• (I) - Input argument containing information used by a routine.
• (O) - Output argument containing information produced by a
routine.
• (M) - Is a combination of both input and output: it means that the
contents of the argument you pass as input might be
modified when the routine returns.
Example: the syntax of routine gin_init() looks like this:

Syntax [status=] gin_init(gin,dur_c,umh_c,node,name,timeout)

struct gin_context *gin_c; /* (M)GIN context */
struct dur_context *dur_c; /* (I)DUR context */
struct umh_context *umh_c; /* (I)UMH context */
int node; /* (I)Node of INT-SERVER
process */
char *name; /* (I)Name of INT-SERVER */
int timeout; /* (I)Timeout on reply */

syntax this is indicated with [status=]. Normally, however, this return
value will not be put in a variable, but will be tested on directly e.g.:

Reference Compiling, Linking and Running Programs
if (!gin_routine())
{
/* Error encountered, use UMH to log errors */
}
The type TLS_BOOLEAN is defined in header file global.h (which is
The header file gin.h contains definitions that should be used when
calling gin-routines (e.g. the definition of the ‘gin_context’ data
structure). Therefore gin.h must always be included in your source when
you use the gin-routines.
The names of the routines and the names of the data structures that are
part of the GIN brick, start with the three letters ‘gin’.
Note: Do not use a routine or variable name in your
application that start with these letters.

Programs
Before you can use the gin-routines in your programs, the following
actions have to be performed:
• BUS/FAST must be installed.
• gin.h must be included.
• Sources must be linked with the BUS libraries.
• The INT-SERVER must be running.
3.3 Error Handling

All GIN routines use standard error handling with the UMH facilities. A
pointer to the UMH buffer in which error information is put by the GIN
routine, is available in the GIN context data structure. This context data
structure is initialized by calling a special GIN routine (gin_init()) and
passing, amongst some other information, a pointer to this UMH buffer.
3.3.1 How is UMH integrated?

The GIN routines perform a umh_set_code() in the case of an error. This
means that the UMH buffer is cleared and filled with the error (or
warning) message. When the routine returns the status FALSE, the
buffer contains only the most recent error message or messages. When
the routine returns the status TRUE, the contents of the error buffer

remain unchanged.
For more detailed information about error handling please consult the
BUS/FAST Programmer’s Guide, part UMH.
3.4 Data Structures

The following data structures are important for the application
programmer. The data structures are mentioned in alphabetical order.
3.4.1 Alarm-storage group parameters

struct gin_alh_stg
{
struct his_grp_nr grp_nr; /* Number of group */
char grp_name[HIS_GRP_NAME_SZ];
/* Name of group */
TLS_UBYTE type[HIS_OPT_TYPES];/*History option types*/
TLS_ULONG max_rec; /* Max. records to store*/
struct alm_sel_crit sel_crit;
/* Group sel. criteria */
};
3.4.2 Area of interest
struct gin_aoi_def
{
char name[GIN_MAX_AOI_NAME];/* AOI name */
TLS_SHORT alm_aoi_nr; /* AOI number */
};
3.4.3 Alarm selection area
struct gin_asa_def
{
char name[GIN_MAX_ASA_NAME];
/* ASA name */
TLS_USHORT seq_nr; /* Sequence number */
TLS_SHORT flags; /* Validation flags
0 is not validated
GIN_ASA_FLG_VALID */
char src_file[TLS_FSPEC_SZ];
/* Filename of ASA

expression */
char list_file[TLS_FSPEC_SZ];
/* Filename of ASA list
expression */
TLS_ULONG asa_info[(GIN_TOT_PFX_SZ+3)/4];
/* Postfix information */
};
3.4.4 GIN context
struct gin_context
{
struct dur_context *dur; /* DUR context */
struct umh_context *umh; /* UMH context */
struct dur_par_snd snd_par;/* Send parameters */
struct dur_par_rcv rcv_par;/* Receive parameters */
struct dur_sel_blk sel_blk;/* Selection criteria
during receive */
};
3.4.5 GIN dIstributed item id
struct gin_dii_id
{
struct itm_id itm_id; /* Item id */
TLS_USHORT fe_node; /* Front-end node */
TLS_USHORT dist_type; /* Distribution type */
TLS_ULONG dii_cache; /* Internal usage */
};

3.4.6 GIN dIstributed item value
union gin_dii_val
{
TLS_BYTE by;
TLS_UBYTE c;
TLS_SHORT s;
TLS_USHORT us;
TLS_LONG l;
TLS_ULONG ul;
TLS_FLOAT f;
TLS_DOUBLE d;
TLS_BOOLEAN b;
int i;
char str[GIN_DII_MAX_STR_LEN];
/* string item value */
struct tm_id itm_id; /* item id */
struct dur_adr excl_adr; /* Exclusion list */
char app_info[GIN_DII_MAX_STR_LEN];
/* Application info */
};
3.4.7 GIN dIstributed AUDIT/FAST information
Struct gin_dii_adt_inf
{
TLS_ULONG adt_src; /* AUDIT/FAST event
source id */
Struct dur_adr act_src; /* DUR address of
activator source */
char terminal[GIN_TERM_NAM_SIZ];
/* Terminal name of
event source */
char user[GIN_MAX_USER_NAME];
/* User who cause the
event */
char reason[GIN_SET_REASON_SIZ];
/* reason for event */
char appl_inf[GIN_SET_ADT_INF_FSIZ];
/* ASCII application
info */
char mod_appl_inf[GIN_SET_ADT_INF_MSIZ];
/* Modifiable ASCII

application info */
}
3.4.8 Item alarm parameters
struct gin_item_alm
{
struct itm_id itm_id; /* Id of the item */
struct gin_item_flnm item_name;
/* Name of the item */
TLS_SHORT alm_wtd; /* 0 = no alarms wanted */
TLS_SHORT alm_grp; /* Alarmgroup */
TLS_SHORT fo_grp; /* First-out group */
TLS_SHORT fo_item; /* 0 = no first-out item*/
TLS_ULONG repeat; /* Repeat time in
seconds */
TLS_ULONG delay; /* Delay time in seconds*/
TLS_SHORT sel_array[GIN_ITEM_MAX_SEL_ROW]
[GIN_ITEM_MAX_SEL_COL];
/* Selection array */
TLS_SHORT ack_type; /* Ack. type */
TLS_SHORT valid_stati; /* Number of valid item
statusses */
struct gin_itm_asta alm_stati[1];
/* Item statusses */
};

struct gin_item_alm2
{
struct itm_id itm_id; /* Id of the item */
/* Name of the item */
TLS_SHORT alm_wtd; /* 0 = no alarms wanted */
TLS_SHORT alm_grp; /* Alarmgroup */
TLS_SHORT fo_grp; /* First-out group */
TLS_SHORT fo_item; /* 0 = no first-out item*/
TLS_ULONG repeat; /* Repeat time in
seconds */
TLS_ULONG delay; /* Delay time in seconds*/
TLS_SHORT sel_array[GIN_ITEM_MAX_SEL_ROW]
TLS_SHORT ack_type; /* Acknowledge-type */
char item_desc[GIN_ITEM_MAX_ITM_DES];
/* Item description */
char eng_unit[GIN_ITEM_MAX_ENG_UNIT];
/* Engineering units */
TLS_USHORT aoi_number[GIN_ITEM_MAX_AOI];
/* Areas of interest */
char dummy[GIN_ITEM_ALM_FREE_SPACE];
/* Spare */
TLS_SHORT diag_item; /* 0 = no diagnostic
item */
TLS_SHORT valid_stati; /* Number of valid item
statusses */
TLS_SHORT opc_ae_item; /* 0 = not mapped on opc
AE tag */
struct gin_itm_asta alm_stati[1];
/* Item statusses */
};
3.4.9 Item id
struct gin_item_id
{
TLS_UBYTE node; /* Node number */
TLS_UBYTE group; /* Item group number */
TLS_USHORT number; /* Item sequence number */
TLS_UBYTE subno; /* Item subnumber */
TLS_UBYTE attno; /* Item attribute number*/
TLS_UBYTE nu1; /* Spare */
TLS_UBYTE nu2; /* Spare */
};

3.4.10 Item info
struct gin_item_inf2
{
struct gin_item_flnm name;/* Item name */
struct itm_id id; /* Item id */
TLS_BYTE repres; /* Item representation */
TLS_BYTE limits; /* Number of limits */
TLS_SHORT elements; /* Number of array
elements */
TLS_BOOLEAN scf_type; /* Indicates sequence
control item */
TLS_BOOLEAN display; /* Currently not in use */
TLS_BOOLEAN change; /* Currently not in use */
TLS_TLS_DOUBLE_Smin_val; /* Currently not in use */
TLS_TLS_DOUBLE_Smax_val; /* Currently not in use */
TLS_SHORT distr_type; /* Distribution type */
TLS_SHORT fe_node; /* Front-end node */
TLS_SHORT inp_auth_lvl; /* Proces area, item
belongs to */
TLS_SHORT outp_auth_lvl; /* Currently not in use */
TLS_SHORT proc_area[GIN_PROCESS_AREA];
/* Multiple process
areas */
TLS_LONG spare[1]; /* Spare */
};
struct gin_item_info
{
struct gin_item_flnm name; /* Item name */
TLS_BYTE repres; /* Item representation */
TLS_BYTE limits; /* Number of limits */
TLS_SHORT elements; /* Number of array
elements */
TLS_BOOLEAN scf_type; /* Indicates sequence
control item */
TLS_BOOLEAN display; /* Currently not in use */
TLS_BOOLEAN change; /* Currently not in use */
TLS_DOUBLE_S min_val; /* Currently not in use */
TLS_DOUBLE_S max_val; /* Currently not in use */
};

3.4.11 Item name
struct gin_item_flnm
{
char name[GIN_MAX_ITEM_FLNM];
};
3.4.12 Item-id/item-name info
struct gin_item_name_info
{
struct gin_item_flnm name; /* Item name */
};
3.4.13 User profile
COLOUR/FAST-WS specific user profile information:

struct gin_user_cws
{
char user_name[GIN_MAX_USER_NAME];
/* User name */
char password[GIN_MAX_PASSWORD];
/* Password */
char user_info[GIN_MAX_USER_INFO];
/* Descriptive text */
char initial_display[GIN_CWS_MAX_DIS_NAM];
/* COLOUR/FAST-WS display
after login */
TLS_SHORT cws_auth_lvl; /* Authorization level for
COLOUR /FAST-WS */
TLS_SHORT language; /* UMH language
selection */
TLS_LONG proc_area_map[32]; /* Process area privilege
map */
char asa[GIN_MAX_ASA_NAME];
/* Alarm selection area*/
TLS_LONG cws_extra[2]; /* Spare */
};
Currently an item can be subdivided in one of the 1000 possible process

areas. A user can be granted permission to modify items that are related
to certain process areas. Which process areas a certain user has ‘modify
privileges’ for, is coded in the array ‘proc_area_map’. This array

contains 1024 bits (of which only the first 1000 are used), each bit
signalling whether or not the user has ‘modify privileges’ to the process
area related to that bit.
“General” user profile information

struct gin_user_def
{
/* User name */
/* Password */
char tdf_first_form[GIN_MAX_FORM_NAME];
/* First form for TMG */
char tdf_file_name[GIN_MAX_FILE_NAME];
/* Hierarchy file */
TLS_SHORT tdf_auth_lvl; /* Authorization level for
TMG */
char cfs_def_dir_name[GIN_MAX_DIR_NAME];
/* Default dir. name */
char cfs_top_dir_name[GIN_MAX_DIR_NAME];
/* Dir. name of top picture
*/
char cfs_top_pic_name[GIN_MAX_PIC_NAME];
/* Picture name of top
picture */
TLS_SHORT cfs_sys_dir_num; /* System directory nr. */
TLS_SHORT cfs_auth_lvl; /* Authorization level for
COLOUR/FAST-TS. */
selection */
struct gin_user_a_o_i a_o_i;
/* Currently not in use */
};

Routines Reference
struct gin_usr2_def
{
/* User name */
/* Password */
char tdf_first_form[GIN_MAX_FORM_NAME];
/* First form for TMG */
char tdf_file_name[GIN_MAX_FILE_NAME];
/* Hierarchy file */
TLS_SHORT tdf_auth_lvl; /* Authorization level for
TMG */
char cfs_def_dir_name[GIN_MAX_DIR_NAME];
/* Default dir. name */
char cfs_top_dir_name[GIN_MAX_DIR_NAME];
/* Dir. name of top picture
*/
char cfs_top_pic_name[GIN_MAX_PIC_NAME];
/* Picture name of top
picture */
TLS_SHORT cfs_sys_dir_num; /* System directory nr. */
TLS_SHORT cfs_auth_lvl; /* Authorization level for
COLOUR/FAST-TS. */
selection */
struct gin_user_a_o_i a_o_i;
/* Currently not in use */
char asa[GIN_MAX_ASA_NAME];
/* Alarm selection area */
char adt_sgp_name [GIN_ADT_SGP_NAME_SZ];
/* AUDIT/FAST selection
group */
TLS_LONG extra[10];
};
3.5 Routines
3.5.1 Introduction
This section describes the GIN routine set. For each GIN routine a
description is given of:
• the syntax of the routine

Reference Routines
• the arguments of the routine

• the semantics of the routine
• the error codes that may be returned by the routine
• other GIN routines related to the GIN routine in question
For some GIN routines more than one version of a routine is available
(with a different name). This is due to the fact that in some situations the
need existed to extend the interface offered by the former version of such
a routine. Because the interface offered by a certain version of a GIN
routine is not allowed to change, a newer version of such a routine had
to be developed. Currently this applies to the following routines:
• gin_itm_galm() (first version), gin_itm_gal2() (second version),
gin_itm_gal3() (third version) and gin_itm_gal4() (fourth version)
• gin_itm_info() (first version), gin_itm_inf2() (second version) and
gin_itm_inf3() (third version).
• gin_itm_nalm() (first version), gin_itm_nal2() (second version)
and gin_itm_nal3() (third version).
• gin_usr_del() (first version) and gin_usr_del2() (second version)
• gin_usr_geq() (first version) and gin_usr_geq2() (second version)
• gin_usr_gf() (first version) and gin_usr_gf2() (second version)
• gin_usr_gge() (first version) and gin_usr_gge2() (second version)
• gin_usr_ggt() (first version) and gin_usr_ggt2() (second version)
• gin_usr_gn() (first version) and gin_usr_gn2() (second version)
• gin_usr_ins() (first version) and gin_usr_ins2() (second version)
• gin_usr_upd() (first version) and gin_usr_upd2() (second version)

Routines Reference
3.5.2 Delete area of interest
Syntax [status=]gin_aoi_del(gin_c,aoi_def_in)

struct gin_aoi_def *aoi_def_in; /* (M)AOI to delete */
Semantics This routine deletes an area of interest from the database. It is sufficient
to fill in the field name in the data structure aoi_def_in is pointing at.
Errors • GIN_E_DELETE
An error occurred while deleting the record from the file in which
the information is stored.
• GIN_E_NO_FILE
File to obtain the information from is currently not opened/created.
• GIN_F_COM_ERR
Communication error detected. While sending a request to, or
waiting for a reply from the INT-SERVER something went wrong
• GIN_F_UMH_COPY
Unable to copy error information coming from INT-SERVER into
the error buffer.
Related routines • gin_init()

Initialization of gin-context data structure.
• gin_aoi_geq()
Retrieve area of interest (read mode “equal”).
• gin_aoi_gf()
Retrieve area of interest (read mode “first”).
• gin_aoi_gge()
Retrieve area of interest (read mode “greater- equal”).
• gin_aoi_gn()
Retrieve area of interest (read mode “next”).
• gin_aoi_ins()
Insert area of interest.

Reference Routines

(read mode “equal”)
[status=]gin_aoi_geq(gin_c,aoi_def_in,aoi_def_out)

struct gin_aoi_def *aoi_def_in; /* (I)AOI definition input */
struct gin_aoi_def *aoi_def_out; /* (O)AOI definition
output */
Semantics This routine reads an area of interest from the database. Either name or
alm_aoi_nr may be specified. If both name and alm_aoi_nr are
specified then the name will be the key to search with.
The routine returns FALSE if the specified area of interest could not be
found.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_aoi_del()
Delete area of interest.
• gin_aoi_gf()
• gin_aoi_gge()
• gin_aoi_gn()
• gin_aoi_ins()

Routines Reference

(read mode “first”)
[status=]gin_aoi_gf(gin_c,aoi_def_in,aoi_def_out)

output */
Semantics This routine reads an area of interest from the database. The routine
returns the first area of interest entry from the database. If the database
is empty then this routine will return FALSE.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_aoi_del()
• gin_aoi_gf()
• gin_aoi_gge()
• gin_aoi_gn()
• gin_aoi_ins()

Reference Routines

(read mode “greater- equal”)
[status=]gin_aoi_gge(gin_c,aoi_def_in,aoi_def_out)

output */
The routine returns FALSE if no area of interest could be found which
is greater or equal to the key specified.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_aoi_del()
• gin_aoi_geq()
• gin_aoi_gf()
• gin_aoi_gn()
• gin_aoi_ins()

Routines Reference

(read mode “next”)
[status=]gin_aoi_gn(gin_c,aoi_def_in,aoi_def_out)

output */
The routine returns FALSE if no next area of interest could be found.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_aoi_del()
• gin_aoi_geq()
• gin_aoi_gf()
• gin_aoi_gge()
• gin_aoi_ins()

Reference Routines
3.5.7 Insert area of interest
[status=]gin_aoi_ins(gin_c,aoi_def_in)

Semantics This routine inserts an area of interest into the database.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_aoi_del()
• gin_aoi_geq()
• gin_aoi_gf()
• gin_aoi_gge()
• gin_aoi_gn()

Routines Reference

[status=]gin_asa_geq(gin_c,asa_def_in,asa_def_out)

struct gin_asa_def *asa_def_in; /* (I)ASA input */
struct gin_asa_def *asa_def_out; /* (O)ASA output */
Semantics This routine reads an alarm selection area from the database. Either name
or seq_nr may be specified. If both name and seq_nr are specified then
the name will be the key to search with.
The routine returns FALSE if the specified alarm selection area could
not be found.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_asa_gf()
Retrieve alarm selection area (read mode “first”).
• gin_asa_gge()
Retrieve alarm selection area (read mode “greater- equal”).
• gin_asa_gn()
Retrieve alarm selection area (read mode “next”).

Reference Routines

[status=]gin_asa_gf(gin_c,asa_def_in,asa_def_out)

Semantics This routine reads an alarm selection area from the database. The routine
returns the first alarm selection area entry from the database. If the
database is empty then this routine will return FALSE.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_asa_gf()
• gin_asa_gge()
• gin_asa_gn()

Routines Reference

(read mode “greater- equal”)
[status=]gin_asa_gge(gin_c,asa_def_in,asa_def_out)

The routine returns FALSE if no alarm selection area could be found
which is greater or equal to the key specified.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_asa_geq()
Retrieve alarm selection area (read mode “equal”).
• gin_asa_gf()
• gin_asa_gn()

Reference Routines

[status=]gin_asa_gn(gin_c,asa_def_in,asa_def_out)

The routine returns FALSE if no next alarm selection area could be
found.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_asa_geq()
Retrieve alarm selection area (read mode “equal”).
• gin_asa_gf()
• gin_asa_gge()
3.5.12 Initialization of gin-context data structure

Syntax [status=]gin_init(gin_c,dur_c,umh_c,node,name,timeout)

Routines Reference

struct dur_context *dur_c; /* (I)DUR context */
struct umh_context *umh_c; /* (I)UMH context */
int node; /* (I)Node of INT-SERVER
process */
char *name; /* (I)Name of INT-SERVER */
int timeout; /* (I)Timeout on reply from
INT-SERVER */
Semantics This routine is used to initialize the gin-context data structure the
argument ‘gin_c’ is pointing to.
This routine needs to be called prior to the call of any other gin-routine.
When a NULL pointer is passed for the ‘name’ argument, the routine
assumes the name “int_server”.
The routine always returns ‘TRUE’.
Errors • none

Syntax [status=]gin_itm_gal2(gin_c,item_id,buf_size,info)

struct gin_item_id *item_id; /* (I)Item id */
int buf_size; /* (I)Size of buffer to put
reply in */
struct gin_item_alm2 *info; /* (O)Alarm parameter info */
Semantics This routine is used to obtain information about the alarm parameters of
an item. The item id of the item to obtain the information for, should be
This routine is the successor of the routine gin_itm_galm().
Development of the routine gin_itm_gal2() routine was necessary after
the number of alarm parameters for an item were extended.
Because the size of the reply varies in length (depending on the number
of item specific status definitions), the size of the buffer to put the reply

Reference Routines
in, should also be passed to this routine. This value is used by this routine
to check whether or not the reply will fit in the buffer the argument ‘info’
is pointing to.
When declaring space for the buffer the argument ‘info’ is pointing to,
one should bear in mind that the size of this buffer is large enough to
hold the maximum number of item specific status definitions. The size
of this buffer follows from:
size = sizeof(struct gin_item_alm2) +
(max_defs - 1) * sizeof(struct gin_itm_asta).
where ‘max_defs’ stands for the maximum allowed number of item
specific status definitions.
Errors • GIN_E_BUF_TO_SMAL
Reply buffer is too small to contain the data obtained.
• GIN_E_GET
An error occurred while reading the required information from the
file in which the information is stored. The exact cause of the error
is indicated by deeper nested error information.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
Communication error detected. While sending a request to the INT-
SERVER or waiting for a reply from the INT-SERVER, something
went wrong. The exact cause of the error is indicated by deeper
nested error information.
• GIN_F_UMH_COPY
the error buffer.

• gin_itm_galm()
Obtain alarm parameters of an item (version 1) (read mode
“equal”).
• gin_itm_nal2()
“greater”).
• gin_itm_nal3()
“greater”).
• gin_itm_nalm()

Routines Reference
“greater”).


reply in */
This routine is the successor to the routine gin_itm_gal2() and makes
alarm colors and status available from the alarm parameters.
is pointing to.
(max_defs - 1) * sizeof(struct gin_itm_asta2).
• GIN_E_GET
• GIN_E_NO_FILE

Reference Routines

• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itm_galm()
“equal”).
• gin_itm_nal2()
“greater”).
• gin_itm_nal3()
“greater”).
• gin_itm_nalm()
“greater”).


reply in */
This routine is the successor to the routine gin_itm_gal3() and makes

Routines Reference
information about shelving enabling available from the alarm

parameters.
is pointing to.
(max_defs - 1) * sizeof(struct gin_itm_asta3).
• GIN_E_GET
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itm_galm()
“equal”).
• gin_itm_nal2()
“greater”).

Reference Routines
• gin_itm_nal3()
“greater”).
• gin_itm_nalm()
“greater”).

Syntax [status=]gin_itm_galm(gin_c,item_id,buf_size,info)

reply in */
struct gin_item_alm *info; /* (O)Alarm parameter info*/
Semantics See section 3.5.13.

This routine is the predecessor of the routine gin_itm_gal2().
Development of the latter routine was necessary after extension of the
number of alarm parameters for an item.
• GIN_E_GET
• GIN_E_NO_FILE
File to obtain the information from is currently not opened/created
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
Related routines Unable to copy error information coming from INT-SERVER into
the error buffer.
• gin_init()

Routines Reference

• gin_itm_gal2()
“equal”).
• gin_itm_nal2()
“greater”).
• gin_itm_nal3()
“greater”).
• gin_itm_nalm()
“greater”).
3.5.17 Obtain id of an item giving the name of the item

Syntax [status=]gin_itm_geti(gin_c,item_name,item_id)

struct gin_item_flnm *item_name; /* (I)Item name */
struct gin_item_id *item_id; /* (O)Item id */
Semantics This routine is used to obtain the id of an item giving the name of the
item. If the item does not exists, the routine returns FALSE.
Errors • GIN_E_GET
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

Reference Routines

• gin_itm_getn()
Obtain name of item giving the id of the item (read mode “equal”).
• gin_itm_gge()
Obtain id and name of item giving the name of the item (read mode
“greater-equal”).
• gin_itm_ggt()
“greater”).
3.5.18 Obtain name of item giving the id of the item

Syntax [status=]gin_itm_getn(gin_c,item_id,item_name)

struct gin_item_flnm *item_name; /* (O)Item name */
Semantics This routine is used to obtain the name of an item giving the id of the
item. If the item does not exists, the routine returns FALSE.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
Related routines the error buffer.
• gin_init()

Routines Reference

• gin_itm_geti()
Obtain id of an item giving the name of the item (read mode
“equal”).
• gin_itm_gge()
• gin_itm_ggt()
“greater”).

item (read mode “greater-equal”)
Syntax [status=]gin_itm_gge(gin_c,item_name,item_id)

struct gin_item_flnm *item_name; /* (M)Item name */
Semantics This routine is used to obtain the id of an item giving the name of the
item. If the item does not exists, the routine returns the id of the item
which name is lexicographically greater than the specified item name.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
• gin_init()

Reference Routines

• gin_itm_geti()
“equal”).
• gin_itm_getn()
• gin_itm_ggt()
“greater”).

item (read mode “greater”)
Syntax [status=]gin_itm_ggt(gin_c,item_name,item_id)

struct gin_item_flnm *item_name; /* (M)Item name */
Semantics This routine is used to obtain the id of an item which name is

lexicographically greater than the specified item name.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itm_geti()

Routines Reference

“equal”).
• gin_itm_getn()
• gin_itm_gge()

Syntax [status=]gin_itm_inf2(gin_c,name_id,item_info)

*name_id; /* (I)Id or name of item */
struct gin_item_inf2 *item_info; /* (O)Info obtained */
Semantics This routine is used to obtain some very specific info for a certain item.
This routine is the successor of the routine gin_itm_info(). Development
of the routine gin_itm_inf2() routine was necessary after the need exists
to obtain more parameters for an item.
The item to obtain the info for, can be selected by either specifying the
name of the item or the id of the item. This is done by putting the item
name or the item id of this item into the data structure the argument
‘name_id’ is pointing at. This data structure contains two sub-structures
both for the item name and the item id. If the ‘number’ field in the item
id sub-structure is filled with the value ‘-1’, the routine will search for
the item information by using the item name. If this ‘number’ field in the
item id sub-structure contains a value not equal to ‘-1’, the routine will
search for the item information by using the item id.
• GIN_E_NO_FILE
• GIN_F_COM_ERR

Reference Routines

• GIN_F_UMH_COPY
the error buffer.

• gin_itm_info()
Obtain specific item info (version 1) (read mode “equal”).

Syntax [status=]gin_itm_inf3(gin_c,name_id,item_info)

*name_id; /* (I)Id or name of item */
struct gin_item_inf3 *item_info; /* (O)Info obtained */
Semantics This routine is the successor of the routine gin_itm_inf2(). Development

of the routine gin_itm_inf3() routine was necessary after addition of
scale high and low to the item definition.
The item to obtain the info for, can be selected by either specifying the
name of the item or the id of the item. This is done by putting the item
name or the item id of this item into the data structure the argument
‘name_id’ is pointing at. This data structure contains two sub-structures
both for the item name and the item id. If the ‘number’ field in the item
id sub-structure is filled with the value ‘-1’, the routine will search for
the item information by using the item name. If this ‘number’ field in the
item id sub-structure contains a value not equal to ‘-1’, the routine will
search for the item information by using the item id.

Routines Reference
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itm_info()

Reference Routines

Syntax [status=]gin_itm_info(gin_c,name_id,item_info)

*name_id /* (I)Id or name of item */
struct gin_item_info *item_info /* (O)Info obtained */

This routine is the predecessor of the routine gin_itm_inf2().
Development of the latter routine was necessary after the need existed to
obtain more parameters for an item.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itm_inf2()

(read mode “greater”)
Syntax [status=]gin_itm_nal2(gin_c,item_id,buf_size,info)

Routines Reference

reply in */
an item whose item-id is greater than the item-id supplied as an
argument to this routine. This routine can be used to read the item
definition file sequentially.
This routine is the successor of the routine gin_itm_nalm().
Development of the routine gin_itm_nal2() routine was necessary after
extension of the number of alarm parameters for an item. This routine
has been succeeded by the routine gin_itm_nal3().
of item specific status definitions), the size of the buffer to put the alarm
parameter info in, should be passed to this routine. This value is used by
this routine to check whether or not the reply will fit in the buffer the
argument ‘info’ is pointing at.
By declaring space for the buffer the argument ‘info’ is pointing at, one
should bear in mind that the size of this buffer is large enough to hold all
possible item specific status definitions. The size of this buffer follows
from:
(max_defs - 1) * sizeof(struct gin_itm_asta).
• GIN_E_GET
• GIN_E_NO_FILE
• GIN_F_COM_ERR

Reference Routines

• GIN_F_UMH_COPY
the error buffer.

• gin_itm_gal2()
“equal”).
• gin_itm_gal3()
Obtain alarm parameters of an alrm (version 3) (read mode
“equal”).
• gin_itm_galm()
“equal”).
• gin_itm_nalm()
“greater”).

Syntax [status=]gin_itm_nalm(gin_c,item_id,info)

struct gin_item_alm *info; /* (O)Alarm parameter info */

This routine is the predecessor of the routine gin_itm_nal2().
Development of the latter routine was necessary after extension of the
number of alarm parameters for an item.
• GIN_E_NO_FILE

Routines Reference
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itm_gal2()
“equal”).
• gin_itm_gal3()
“equal”).
• gin_itm_galm()
“equal”).
• gin_itm_nal2()
“greater”).
3.5.26 Delete entry from item-used file

Syntax [status=]gin_itmu_del(gin_c,item_id,brick,key_siz,key)

struct gin_item_id *item_id /* (I)Id of item */
int brick; /* (I)Number of brick using
this item */
int key_siz; /* (I)Size of brick
dependent key part */
char *key /* (I)Brick dependent key
part */
Semantics This routine is used to delete an entry from the item used file. The key
on this file is the composition of the entities ‘item-id’, ‘brick number’
and one or other string pointed to by the argument ‘key’.

Reference Routines
For detailed information concerning the usage of brick numbers, please

consult the appropriate section in the FAST/CONVENTIONS
Reference Guide.
An error occurred while deleting a record from the file in which the
information is stored. The exact cause of the error is indicated by
deeper nested error information.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itmu_geq()
Read entry from item-used file (read mode “equal”).
• gin_itmu_gge()
Read entry from item-used file (read mode “greater-equal”).
• gin_itmu_ggt()
Read entry from item-used file (read mode “greater”).
• gin_itmu_ins()
Insert entry in item-used file.
• gin_itmu_upd()
Update entry in item-used file.

Syntax [status=]gin_itmu_geq(gin_c,item_id,brick,key_siz,key,
text,max_text_size)


Routines Reference

this item */
part */
char *text; /* (O)Descriptive text */
int max_text_size /* (I)Maximum size of
descriptive text to
return */
Semantics This routine is used to obtain the descriptive text that can be stored with
each record of the item used file. By means of the keydata ‘item_id’,
‘brick number’ and ‘brick dependent key’, an attempt is made to localize
the record. If the record is found, the descriptive text stored with the
record will be returned. If the record with the specified key data is not
found, the routine returns FALSE.
Reference Guide.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itmu_del()
Delete entry from item-used file.
• gin_itmu_gge()

Reference Routines
• gin_itmu_ggt()
• gin_itmu_ins()
• gin_itmu_upd()

(read mode “greater-equal”)
Syntax [status=]gin_itmu_gge(gin_c,item_id,brick,key_siz,key,
max_key_size,text,max_text_size)

struct gin_item_id *item_id /* (M)Id of item */
int *brick; /* (M)Number of brick using
this item */
int *key_siz; /* (M)Size of brick
char *key /* (M)Brick dependent key
part */
int max_key_size; /* (I)Maximum size of key to
return */
int max_text_size /* (I)Maximum size of text to
return */
Semantics See section 3.5.27. However the following applies:

The routine operates in read mode ‘greater-equal’, which means the
routine will return the information that is stored in a record whose key
either:
• matches the specified keydata (in case a key exists with the
specified keydata)
• is greater than the specified keydata (in case no record exists with
a key exactly matching the specified keydata)
The arguments ‘item_id’, ‘brick’, ‘key_siz’ and ‘key’ are used to
• specify the keydata to search for
• return the information stored for the record found (the argument
‘text’ is only used for the latter purpose)

Routines Reference
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itmu_del()
• gin_itmu_geq()
• gin_itmu_ggt()
• gin_itmu_ins()
• gin_itmu_upd()

Syntax [status=]gin_itmu_ggt(gin_c,item_id,brick,key_siz,key,
max_key_size,text,max_text_size)

struct gin_item_id *item_id /* (M)Id of item */
int *brick; /* (M)Number of brick using
this item */
int *key_siz; /* (M)Size of brick

Reference Routines
char *key /* (M)Brick dependent key

part */
int max_key_size; /* (I)Maximum size of key to
return */
int max_text_size /* (I)Maximum size of text to
return */
Semantics See section 3.5.27. However the following applies:

The routine operates in read mode ‘greater’, which means the routine
will return the information that is stored in a record whose key is greater
than the specified keydata.
The arguments ‘item_id’, ‘brick’, ‘key_siz’ and ‘key’ are used to
• specify the keydata to search for
• return the information stored for the record found (the argument
‘text’ is only used for the latter purpose)
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_itmu_del()
• gin_itmu_geq()
• gin_itmu_gge()
• gin_itmu_ins()

Routines Reference
• gin_itmu_upd()
3.5.30 Insert entry in item-used file

Syntax [status=]gin_itmu_ins(gin_c,item_id,brick,key_siz,key,
text)

this item */
part */
char *text; /* (I)Descriptive text */
Semantics This routine is used to insert an entry in the item-used file.

The argument ‘brick’ is used to identify the brick inserting the entry in
the item-used file.
Reference Guide.
Errors • GIN_E_INSERT
An error occurred while inserting information into the file in which
the information should be stored. The exact cause of the error is
indicated by deeper nested error information.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
• gin_init()

Reference Routines

• gin_itmu_del()
• gin_itmu_geq()
• gin_itmu_gge()
• gin_itmu_ggt()
• gin_itmu_upd()
3.5.31 Update entry in item-used file

Syntax [status=]gin_itmu_upd(gin_c,item_id,brick,key_siz,key,
text)

this item */
part */
char *text; /* (I)Descriptive text */
Semantics This routine is used to update the descriptive text part of an entry in the
item-used file.
Reference Guide.
Errors • GIN_E_NO_FILE
• GIN_E_UPDATE
An error occurred while updating information in the file in which
the information is stored that should be updated. The exact cause of
the error is indicated by deeper nested error information.
• GIN_F_COM_ERR

Routines Reference

• GIN_F_UMH_COPY
the error buffer.

• gin_itmu_del()
• gin_itmu_geq()
• gin_itmu_gge()
• gin_itmu_ggt()
• gin_itmu_ins()
3.5.32 Delete entry from user-file

Syntax [status=]gin_usr_del(gin_c,user_def)

struct gin_user_def *user_def; /* (I)User info */
Semantics This routine is used to delete an entry from the user-file. It is sufficient
to fill up the field ‘user_name’ in the data structure the argument
‘user_def’ is pointing at.
• GIN_E_NO_FILE
• GIN_F_COM_ERR

Reference Routines

• GIN_F_UMH_COPY
the error buffer.

• gin_usr_gcws()
Obtain CWS info from user-file (read mode “equal”).
• gin_usr_del2()
Delete entry from user-file (version 2).
• gin_usr_geq()
Obtain general info from user-file (read mode “equal”).
• gin_usr_geq2()
Obtain general info from user-file (version 2) (read mode “equal”).
• gin_usr_gf()
Obtain general info from user-file (read mode “first”).
• gin_usr_gf2()
Obtain general info from user-file (version 2) (read mode “first”).
• gin_usr_gge()
Obtain general info from user-file (read mode “greater-equal”).
• gin_usr_gge2()
Obtain general info from user-file (version 2) (read mode “greater-
equal”).
• gin_usr_ggt()
Obtain general info from user-file (read mode “greater”).
• gin_usr_ggt2()
Obtain general info from user-file (version 2) (read mode
“greater”).
• gin_usr_gn()
Obtain general info from user-file (read mode “next”).
• gin_usr_gn2()
Obtain general info from user-file (version 2) (read mode “next”).
• gin_usr_ins()
Insert entry in user-file.
• gin_usr_ins2()
Insert entry in user-file (version 2).
• gin_usr_ucws()
Update CWS-info in user file.
• gin_usr_upd()
Update entry in user file.

Routines Reference
• gin_usr_upd2()
Update entry in user file (version 2).
3.5.33 Delete entry from user-file (version 2)

Syntax [status=]gin_usr_del2(gin_c,user_def)

struct gin_usr2_def *user_def; /* (I)User info */

This routine is the successor of the routine gin_usr_del(). Development
of this routine was necessary after extension of the gin_user_def
structure into gin_usr2_def structure.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.
Related routines • See section 3.5.32
3.5.34 Obtain CWS info from user-file

Syntax [status=]gin_usr_gcws(gin_c,user_in,user_out)


Reference Routines
struct gin_user_cws *user_in; /* (I)User info input */

struct gin_user_cws *user_out; /* (O)User info output */
Semantics This routine is used to obtain the COLOUR/FAST info part from an
entry in the user-file. The read mode is ‘equal’ which means that the
routine returns FALSE in case no entry is found with a user name
exactly matching the user name offered to this routine.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_usr_del()
Delete entry from user-file.
• gin_usr_del2()
• gin_usr_geq()
• gin_usr_geq2()
• gin_usr_gf()
• gin_usr_gf2()
• gin_usr_gge()
• gin_usr_gge2()

Routines Reference
equal”).
• gin_usr_ggt()
• gin_usr_ggt2()
“greater”).
• gin_usr_gn()
• gin_usr_gn2()
• gin_usr_ins()
• gin_usr_ins2()
• gin_usr_ucws()
• gin_usr_upd()
• gin_usr_upd2()

Syntax [status=]gin_usr_geq(gin_c,user_in,user_out)

struct gin_user_def *user_in; /* (I)User info input */
struct gin_user_def *user_out; /* (O)User info output */
Semantics This routine is used to obtain some general info from an entry in the
user-file. The read mode is ‘equal’ which means that the routine returns
FALSE in case no entry is found with a user name exactly matching the
user name offered to this routine.
• GIN_E_NO_FILE
• GIN_F_COM_ERR

Reference Routines

• GIN_F_UMH_COPY
the error buffer.

• gin_usr_del()
• gin_usr_del2()
• gin_usr_gcws()
• gin_usr_geq2()
• gin_usr_gf()
• gin_usr_gf2()
• gin_usr_gge()
• gin_usr_gge2()
equal”).
• gin_usr_ggt()
• gin_usr_ggt2()
“greater”).
• gin_usr_gn()
• gin_usr_gn2()
• gin_usr_ins()
• gin_usr_ins2()
• gin_usr_ucws()

Routines Reference
• gin_usr_upd()
• gin_usr_upd2()

Syntax [status=]gin_usr_geq2(gin_c,user_in,user_out)

struct gin_usr2_def *user_in; /* (I)User info input */
struct gin_usr2_def *user_out; /* (O)User info output */
Semantics See section 3.5.36

This routine is the successor of the routine gin_usr_geq(). Development
structure.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

Reference Routines

Syntax [status=]gin_usr_gf(gin_c,user_out)

Semantics This routine is used to obtain the very first entry from the user-file.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_usr_del()
• gin_usr_del2()
• gin_usr_gcws()
• gin_usr_geq()
• gin_usr_geq2()
• gin_usr_gf2()
• gin_usr_gge()
• gin_usr_gge2()

Routines Reference

equal”).
• gin_usr_ggt()
• gin_usr_ggt2()
“greater”).
• gin_usr_gn()
• gin_usr_gn2()
• gin_usr_ins()
• gin_usr_ins2()
• gin_usr_ucws()
• gin_usr_upd()
• gin_usr_upd2()

Syntax [status=]gin_usr_gf2(gin_c,user_out)

Semantics See section 3.5.37

This routine is the successor of the routine gin_usr_gf(). Development
structure into the gin_usr2_def structure.
• GIN_E_NO_FILE

Reference Routines
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

Syntax [status=]gin_usr_gge(gin_c,user_in,user_out)

Semantics This routine has the same functionality as the routine ‘gin_usr_geq’ (see
section 3.5.36), except that the read mode is ‘greater equal’. This means
the routine will return the info for the entry whose user name is
lexicographically equal or greater than the user name offered as input to
this routine.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY

Routines Reference
the error buffer.

• gin_usr_del()
• gin_usr_del2()
• gin_usr_gcws()
• gin_usr_geq()
• gin_usr_geq2()
• gin_usr_gf()
• gin_usr_gf2()
• gin_usr_gge2()
equal”).
• gin_usr_ggt()
• gin_usr_ggt2()
“greater”).
• gin_usr_gn()
• gin_usr_gn2()
• gin_usr_ins()
• gin_usr_ins2()
• gin_usr_ucws()
• gin_usr_upd()
• gin_usr_upd2()

Reference Routines

Syntax [status=]gin_usr_gge2(gin_c,user_in,user_out)


This routine is the successor of the routine gin_usr_gge(). Development
of the latter routine was necessary after extension of the gin_user_def
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

Syntax [status=]gin_usr_ggt(gin_c,user_in,user_out)


Routines Reference
Semantics This routine has the same functionality as the routine ‘gin_usr_geq’ (see
section 3.5.35), except that the read mode is ‘greater’. This means the
routine will return the info for the entry whose user name is
lexicographically greater than the user name offered as input to this
routine.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_usr_del()
• gin_usr_del2()
• gin_usr_gcws()
• gin_usr_geq()
• gin_usr_geq2()
• gin_usr_gf()
• gin_usr_gf2()
• gin_usr_gge()
• gin_usr_gge2()

Reference Routines

equal”).
• gin_usr_gn()
• gin_usr_gn2()
• gin_usr_ggt2()
“greater”).
• gin_usr_ins()
• gin_usr_ins2()
• gin_usr_ucws()
• gin_usr_upd()
• gin_usr_upd2()

Syntax [status=]gin_usr_ggt2(gin_c,user_in,user_out)


This routine is the successor of the routine gin_usr_ggt(). Development
• GIN_E_NO_FILE
• GIN_F_COM_ERR

Routines Reference

• GIN_F_UMH_COPY
the error buffer.

Syntax [status=]gin_usr_gn(gin_c,user_out)

Semantics This routine is described here for compatibility reasons. The use of this
routine is not encouraged because the result of calling this routine is not
predictable. This comes from the fact that the ‘read next’ action is
always related to the last read action performed on a file. Because read
actions take place via the INT-SERVER, the INT-SERVER owns the
‘read context’ in this case. When the caller of the ‘gin_usr_gn’ routine
did not perform the last read action via this routine, the info returned
deviates from what one would expect.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY

Reference Routines

the error buffer.

• gin_usr_del()
• gin_usr_del2()
• gin_usr_gcws()
• gin_usr_geq()
• gin_usr_geq2()
• gin_usr_gf()
• gin_usr_gf2()
• gin_usr_gge()
• gin_usr_gge2()
equal”).
• gin_usr_ggt()
• gin_usr_ggt2()
“greater”).
• gin_usr_gn2()
• gin_usr_ins()
• gin_usr_ins2()
• gin_usr_ucws()
• gin_usr_upd()
• gin_usr_upd2()

Routines Reference

Syntax [status=]gin_usr_gn2(gin_c,user_out)


This routine is the successor of the routine gin_usr_gn(). Development
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.
3.5.45 Insert entry in user-file

Syntax [status=]gin_usr_ins(gin_c,user_in)


Reference Routines
Semantics This routine is used to insert an entry in the user-file. Fields of a record
in the user file not being part of the structure ‘gin_user_def’, are filled
with zero.
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_usr_del()
• gin_usr_del2()
• gin_usr_gcws()
• gin_usr_geq()
• gin_usr_geq2()
• gin_usr_gf()
• gin_usr_gf2()
• gin_usr_gge()
• gin_usr_gge2()
equal”).
• gin_usr_ggt()

Routines Reference

• gin_usr_ggt2()
“greater”).
• gin_usr_gn()
• gin_usr_gn2()
• gin_usr_ins2()
• gin_usr_ucws()
• gin_usr_upd()
• gin_usr_upd2()
3.5.46 Insert entry in user-file (version 2)

Syntax [status=]gin_usr_ins2(gin_c,user_in)


This routine is the successor of the routine gin_usr_ins(). Development
• GIN_E_NO_FILE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY

Reference Routines

the error buffer.
Related routines • See section 3.5.45.
3.5.47 Update CWS-info in user file

Syntax [status=]gin_usr_ucws(gin_c,cws_in,cws_out)

struct gin_user_cws *cws_in; /* (I)CWS info input */
struct gin_user_cws *cws_out; /* (O)CWS info output */
Semantics This routine is used to update the CWS-info part of an entry in the user-
file. The fields of the entry in the user-file being updated, are defined by
the structure ‘gin_user_cws’.
• GIN_E_UPDATE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_usr_del()
• gin_usr_del2()
• gin_usr_gcws()

Routines Reference

• gin_usr_geq()
• gin_usr_geq2()
• gin_usr_gf()
• gin_usr_gf2()
• gin_usr_gge()
• gin_usr_gge2()
equal”).
• gin_usr_ggt()
• gin_usr_ggt2()
“greater”).
• gin_usr_gn()
• gin_usr_gn2()
• gin_usr_ins()
• gin_usr_ins2()
• gin_usr_upd()
• gin_usr_upd2()
3.5.48 Update entry in user file

Syntax [status=]gin_usr_upd(gin_c,user_in)


Reference Routines
Semantics This routine is used to update certain information of an entry in the user-
file. The fields of the entry in the user-file being updated, are defined by
the structure ‘gin_user_def’.
• GIN_E_UPDATE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY
the error buffer.

• gin_usr_del()
• gin_usr_del2()
• gin_usr_gcws()
• gin_usr_geq()
• gin_usr_geq2()
• gin_usr_gf()
• gin_usr_gf2()
• gin_usr_gge()
• gin_usr_gge2()
equal”).
• gin_usr_ggt()

Routines Reference
• gin_usr_ggt2()
“greater”).
• gin_usr_gn()
• gin_usr_gn2()
• gin_usr_ins()
• gin_usr_ins2()
• gin_usr_ucws()
• gin_usr_upd2()
3.5.49 Update entry in user file (version 2)

Syntax [status=]gin_usr_upd2(gin_c,user_in)


This routine is the successor of the routine gin_usr_upd(). Development
of the latter routine was necessary after extension of the gin_user_def
• GIN_E_UPDATE
• GIN_F_COM_ERR
• GIN_F_UMH_COPY

Reference GIN distributed item interface

the error buffer.
Related routines • See section 3.5.48.
3.6 GIN distributed item interface
3.6.1 Allocate additional memory block for an item

Syntax [mem=]gin_dii_ainf(umh_c, itm_did, info_id, size)
Arguments void *mem; /* (R)Pointer to allocated */

/* memory, NULL if error */
struct umh_context *umh_c; /* (M)UMH context */
struct gin_dii_id *itm_dii; /* (I)Distributed item id */
int info_id; /* (I)Memory block id */
int size; /* (I)Memory block size */
Semantics This routine allocates a block of memory with the specified size and
connects it to the specified item. Application programmers can use this
option to allocate memory to store additional application specific
information with the item. It is labelled with specified information
identifier. It is possible to allocate memory for the same 'itm_did' more
than once under the condition that the 'info_id' differs from previously
memory allocation actions. The same info_id can not be specified more
than once for the same 'itm_did' without deleting a previous allocated
block of memory (see routine gin_dii_dinf()).
The routine returns a NULL pointer if an error occurs.
Errors • GIN_E_DII_BADPARS
Bad parameters supplied to GIN DII interface.
GIN_E_DII_AINF_ID
Info id already used for item.
Related routines • gin_dii_dinf()

Delete additional memory block for an item.
• gin_dii_ginf()
Get pointer to additional memory block.

GIN distributed item interface Reference
• gin_dii_sinf()
Connect additional memory block to an item.
3.6.2 Enable/Disable event buffering

Syntax [status =] gin_dii_cebf(umh_c, node, size, timeout)

int node; /* (I)Node number */
int size; /* (I)Event buffer size */
float timeout; /* (I)Buffering timeout */
Semantics This routine is used to enable and disable event buffering. If he node is
-1 then all nodes are involved otherwise the specified node only. When
a size of zero is specified then event buffering is disabled. The timeout
is specified in seconds and may contain a fraction.
Related routines • None.
3.6.3 Periodic houskeeping function

Syntax [status =] gin_dii_chk(umh_c)

Semantics This routine must be called each second, and performs housekeeping
functions for the DII interface.
The following functions are performed:
• Checks for flow control time-outs on all subscribed nodes and re-
initializes flow if necessary.
• Flushes any outstanding clustered messages for each node.
Errors
• None.

3.6.4 Delete additional memory block for an item

Syntax [status =] gin_dii_dinf(umh_c, itm_dii, info_id)

Semantics This routine de-allocates a block of memory connected it to the specified

item. The memory block is specified by the info_id. If the memory it
added to the item using gin_dii_ainf() it is also freed.
Related routines • gin_dii_ainf()

Allocate additional memory block for an item.
• gin_dii_ginf()
• gin_dii_sinf()
3.6.5 Translate textual attribute name to attribute id

Syntax [attr_id =] gin_dii_gaid(umh_c, attr_name)
Arguments TLS_ULONG attr_id; /* (R)Attribute id, */

/* 0 indicates error */
char attr_name; /* (I)Attribute name */

Semantics This routine can be used to translate a textual attribute name a into a
numeric attribute identifier. The textual attribute can be provided in
either English, French or German. The table below shows the textual
attribute name in the three languages and the attribute id that is returned.
Table 3. 2: Textual attributes
Attribute Id Textual attribute
GIN_DII_ACKNOWLEDGED ACKNOWLEDGED
ACQUITTE
BESTAETIGT
GIN_DII_ALARM_COLOR ALARM COLOR

ALARM COULEUR
ALARM COLOR
GIN_DII_ALARM_ENABLED ALARM ENABLED

ALARM ENABLED
ALARM ENABLED
GIN_DII_ALARM_MNEMONIC ALARM MNEMONIC

ALARM MNEMONIC
ALARM MNEMONIC
GIN_DII_ALARM_PRIORITY ALARM PRIORITY

PRIORITE ALARME
ALARM PRIORITAT
GIN_DII_ALARM_TEXT ALARM TEXT

ALARM TEXT
ALARM TEXT
GIN_DII_ALARM_TYPE ALARM TYPE

TYPE D 'ALARME
ALARMTYP
GIN_DII_APP_FLAG APPLICATION FLAG

DRAPEAU D'APPLICATION
APPLIKATIONSFAHNE
GIN_DII_APP_FLAG_MSK APPLICATION FLAG MASK

MASQUE D 'APPLICATION
APPLIKATIONSFAHNE-MASKE
GIN_DII_APP_FLAG_SET APPLICATION FLAG SET

METTEZ D 'APPLICATION
APPLIKATIONSFAHNE SETZEN
GIN_DII_APP_INFO APPLICATION INFO

APPLICATION INFO
APPLIKATION INFO
GIN_DII_APP_INFO_SIZE APPLICATION INFO SIZE

APPLICATION INFO SIZE
APPLIKATION INFO SIZE

GIN_DII_ATTACHED ATTACHED
ATTACHED
ATTACHE
GIN_DII_AVAILABLE AVAILABLE
DISPONIBLE
ERHALTLICH
GIN_DII_BLOCKED BLOCKED
BLOCQUE
BLOCKIERT
GIN_DII_COMMENT_1 COMMENT 1
KOMMENTAR 1
COMMENTAIRE 1
GIN_DII_COMMENT_2 COMMENT 2
KOMMENTAR 2
COMMENTAIRE 2
GIN_DII_CONTROL_STATUS CONTROL STATUS

ETAT CONTROLE
KONTROLLESTATUS
GIN_DII_DEADBAND DEADBAND
BANDE DE MORTE
TOTZONE
GIN_DII_DESCRIPTION DESCRIPTION
DESCRIPTION
BESCHREIBUNG
GIN_DII_ENG_UNIT ENGINEERING UNIT

UNITE PHYSIQUE
PHYSIKALISCHE EINHEIT
GIN_DII_FORCE_ALARM ALARM FORCE ALARM

FORCE D ' ALARME ALARMER
ALARM ZU ALARM
GIN_DII_FORCE_NORMAL ALARM FORCE NORMAL

FORCE D 'ALARME NORMALE
ALARM ZU NORMAL
GIN_DII_HIGH_HIGH_LIMIT HIGH HIGH LIMIT

LIMITE TRES HAUTE
OBERSTER GRENZWERT
GIN_DII_HIGH_LIMIT HIGH LIMIT

LIMITE HAUTE
OBERER GRENZWERT
GIN_DII_HIGH_LIMIT_PRC HIGH LIMIT %

LIMITE HAUTE %
OBERER GRENZWERT %

GIN_DII_ID ID
ID
ID
GIN_DII_INTEGRATOR_TIME INTEGRATOR TIME

TEMPS D'INTEGARTION
INTEGRATOR-ZEIT
GIN_DII_ITEM_GROUP ID GROUP
ID GROUPE
ID GRUPPE
GIN_DII_ITEM_INST_NAME INSTALLATION
INSTALLATION
ANLAGEBEREICH
GIN_DII_ITEM_NAME NAME
NOMBRE
NAME
GIN_DII_ITEM_NODE ID NODE
ID NOEUD
ID KNOTEN
GIN_DII_ITEM_NODE_NAME NODE
NOEUD
KNOTEN
GIN_DII_ITEM_NUMBER ID NUMBER
ID NUMERO
ID NUMMER
GIN_DII_ITEM_SECTION_NAME SECTION
SECTION
SECTION
GIN_DII_ITEM_SUB ID SUB
ID CALCUL
ID ZUSATZ
GIN_DII_ITEM_SUB_NAME SUB
SOUS NOM
ZUSATZ
GIN_DII_ITEM_TAG_NAME TAG
NOM
DATENPUNKTKENNUNG
GIN_DII_ITEM_UNIT_NAME UNIT
UNITE
TEILANLAGE
GIN_DII_LOCATION LOCATION
EMPLACEMENT
LAGE

GIN_DII_LOCATION_WITH_NAME LOCATION WITH NAME

EMPLACEMENT AVEC LE NOMBRE
LAGE MET DEM NAMEN
GIN_DII_LOCKED LOCKED
LOCKED
LOCKED
GIN_DII_LOCK_ID LOCK ID
LOCK ID
LOCK ID
GIN_DII_LOCK_TERMINAL LOCK TERMINAL

LOCK TERMINAL
LOCK TERMINAL
GIN_DII_LOCK_TIMEOUT LOCK TIMEOUT

LOCK TIMEOUT
LOCK TIMEOUT
GIN_DII_LOCK_USER LOCK USER

LOCK USER
LOCK USER
GIN_DII_LOW_LIMIT LOW LIMIT

LIMITE BASSE
UNTERER GRENZWERT
GIN_DII_LOW_LIMIT_PRC LOW LIMIT %

LIMITE BASSE %
UNTERER GRENZWERT %
GIN_DII_LOW_LOW_LIMIT LOW LOW LIMIT

LIMITE TRES BASSE
UNTERSTER GRENZWERT
GIN_DII_OPTION_STATUS OPTION STATUS

ETAT D'OPTION
OPTION-STATUS
GIN_DII_PROC_AREAS PROCESS AREAS

PROCESS AREAS
PROCESS AREAS
GIN_DII_QUALITY QUALITY
QUALITE
QUALITAET
GIN_DII_REFRESH_TIME REFRESH TIME

TEMPS DE RAFRAICHISSEMENT
AKTUALISIERUNGSZEIT
GIN_DII_SCALE_HIGH SCALE LOW LIMIT

SKALE UNTERGRENZE
LIMITE BASSE D\'ECHELLE

GIN_DII_SCALE_LOW SCALE LOW LIMIT

SKALE OBERGRENZE
LIMITE HAUTE D\'ECHELLE
GIN_DII_STATUS STATUS
ETAT
STATUS
GIN_DII_STATUS_COLOR STATUS COLOR

COULEUR D’ETAT
STATUSFARBE
GIN_DII_STATUS_MERGED MERGED_STATUS
ETAT COMBINE
KOMBINIERTE STATUS
GIN_DII_STATUS_MERGED_TEXT MERGED STATUS TEXT

TEXTE D 'ETAT COMBINE
KOMBINIERTE STATUSTEXT
GIN_DII_STATUS_MNEMONIC STATUS MNEMONIC

MOYEN MNEMOTECHNIQYE D'ETAT
STATUSMERKHILFE
GIN_DII_STATUS_TEXT STATUS TEXT

TEXTE D 'ETAT
STATUSTEXT
GIN_DII_TREND_LOWER TREND LOWER LIMIT

LIMITE BASSE DE TENDANCE
TREND UNTERGRENZE
GIN_DII_TREND_UPPER TREND UPPER LIMIT

LIMITE HAUTE DE TENDANCE
TREND OBERGRENZE
GIN_DII_UPD_INF UPDATE INFO

UPDATE INFO
UPDATE INFO
GIN_DII_UPDATE_TIME UPDATE TIME

DATE DE M.A.J.
AKTUALISIERUNGSZEIT
GIN_DII_VALUE_OWR VALUE OVERWRITE

REMPLACER DE LA VALEUR
UEBERSCHREIBUNG WERT
GIN_DII_VALUE_PRC VALUE %
VALEUR %
WERT %
GIN_DII_VALUE VALUE
VALEUR
WERT

Errors • None.
Related routines • gin_dii_gidi()

Get distributed item id by item id.
• gin_dii_gidn()
Get distributed item id by name.
• gin_dii_gids()
Get distributed item id by PROCESS/FAST signal path.
3.6.6 Get one or more attributes of an item

Syntax [status =] gin_dii_gatr(umh_c, itm_dii, attr_id,
attr_val,..., GIN_DII_EOL)
Arguments TLS_BOOLEAN status; /*(R) TRUE:(success) */

struct umh_context *umh_c; /*(M) UMH context */
struct gin_dii_id *itm_dii; /*(I) Distributed item id */
int attr_id; /*(I) Atribute id */
void *attr_val; /*(O) Pointer to receive buff. */
Semantics This routine returns one or more attributes of an item. It takes a variable
length argument list, It uses the access scheme to determine where to
obtain the attribute of the item in a distributed environment unless the
itm_dii was requested with a node prefix. In that case item attributes are
read from the specified node.
The attr_val buffer must be large enough to receive the attribute value.
The following table lists the defined attribute identifiers (attr_id) and the
default of the returned attribute (attr_val). An attribute id can be OR-red
by one of the REP_ defines to force return of the attribute value in this
representation. For low limit, high limit and value this can also be
REP_PERCENT. A pointer to the attribute is returned.
Table 3. 3: Item attribute id’s
Default
Attribute id representation of Description
attribute value
GIN_DII_ACKNOWLEDGED TLS_BOOLEAN Item is acknowledged
GIN_DII_ALARM_COLOR char[] The color related to the

alarm

Default
attribute value
GIN_DII_ALARM_ENABLED TLS_BOOLEAN If TRUE then the other

GIN_DII_ALARM..
attributes contain valid infor-
mation
GIN_DII_ALARM_MNEMONIC char[] The mnemonic related to the

alarm
GIN_DII_ALARM_PRIORITY TLS_LONG The priority related to the

alarm
GIN_DII_ALARM_TEXT char[] The text related to the alarm
GIN_DII_ALARM_TYPE int Alarm type (T1 T2 bits)
GIN_DII_APP_FLAG TLS_ULONG Application flag
GIN_DII_APP_INFO char[} Application info as an array

of chars. The length of the
application info can be
obtained using
GIN_DII_APP_INFO_SIZE
GIN_DII_APP_INFO_SIZE int The size of the application

info
GIN_DII_ARRAY_INDEX int Indicates the index of an

array item to read when item
is array type.
GIN_DII_ATTACHED TLS_BOOLEAN Indicated whether an item is

attached to the signal
GIN_DII_AVAILABLE TLS_BOOLEAN Whether the item is availa-

ble. E.g. the item is currently
available in the Enterprise
Solution
GIN_DII_BLOCKED TLS_BOOLEAN Item is blocked
GIN_DII_COMMENT_1 char[] Comment 1
GIN_DII_COMMENT_2 char[] Comment 2
GIN_DII_CONTROL_STATUS int Control status
GIN_DII_DEADBAND TLS_DOUBLE Deadband
GIN_DII_DESCRIPTION char[] Description
GIN_DII_ENG_UNIT char[] Engineering unit
GIN_DII_FORCE_ALARM TLS_BOOLEAN Force to alarm option flag
GIN_DII_FORCE_NORMAL TLS_BOOLEAN Force to normal option flag
GIN_DII_HIGH_HIGH_LIMIT TLS_DOUBLE High High limit

Default
attribute value
GIN_DII_HIGH_LIMIT TLS_DOUBLE High limit
GIN_DII_HIGH_LIMIT_PRC TLS_DOUBLE High limit %
GIN_DII_ID Struct gin_itm_id Item id
GIN_DII_INTEGRATOR_TIME int Start or reset time of integra-

tor sub-item
GIN_DII_INTEGRATOR_TIME_DEF int Integrator time of a sub item

(the configuration value, only
valid for sub items of type
integrator).
GIN_DII_ITEM_FORMAT char[] Item format
GIN_DII_ITEM_GROUP int Item group number
GIN_DII_ITEM_INST_NAME char[] Item installation
GIN_DII_ITEM_NAME char[] Item name as stored in item

table
GIN_DII_ITEM_NODE int Item node number
GIN_DII_ITEM_NODE_NAME char[] Item node name
GIN_DII_ITEM_NUMBER int Item number
GIN_DII_ITEM_OFFLINE TLS_BOOLEAN Item offline
GIN_DII_ITEM_SECTION_NAME char[] The section path
GIN_DII_ITEM_SUB int Item sub number
GIN_DII_ITEM_SUB_NAME char[] Item sub name
GIN_DII_ITEM_TAG_NAME char[] Item tag name
GIN_DII_ITEM_UNIT_NAME char[] Item unit name
GIN_DII_LOCATION char[] The location (FAST/TOOLS

node name) where the item is
found
GIN_DII_LOCATION_WITH_NAME char[] The location with the full

item name in the format:
<location>:<item name>
GIN_DII_LOCKED TLS_BOOLEAN Item is locked
GIN_DII_LOCK_TERMINAL char[] The name of the terminal

where the item is locked
GIN_DII_LOCK_USER char[] The name of the user who

locked the item
GIN_DII_LOW_LIMIT TLS_DOUBLE Low limit

Default
attribute value
GIN_DII_LOW_LIMIT_PRC TLS_DOUBLE Low limit %
GIN_DII_LOW_LOW_LIMIT TLS_DOUBLE Low Low limit
GIN_DII_OPTION_STATUS int Option status
GIN_DII_PROC_AREAS int[] Process area (can be

obtained as a string of proc-
ess area numbers (like
'3,5,10-23' or an array of
GIN_PROCESS_AREA
integers where each integer
represents a process area of
the item
GIN_DII_QUALITY TLS_ULONG Quality code
GIN_DII_REFRESH_TIME TLS_ULONG The time the item was

updated
GIN_DII_RESET_TYPE int Specifies how a sub item

should be reset directly after
a read (only valid for sub
items). When omitted the sub
item is not reset. Must be one
of ITM_RST_DEF,
ITM_RST_MIN or
ITM_RST_MAX.
GIN_DII_SCALE_HIGH TLS_DOUBLE Scale high limit
GIN_DII_SCALE_LOW TLS_DOUBLE Scale low limit
GIN_DII_STATUS int Item status
GIN_DII_STATUS_COLOR char[] String containing the name

of the color that represents
the current status.
GIN_DII_STATUS_MERGED int Merged item status
GIN_DII_STATUS_MERGED_TEXT char[] Merged status text (can also

be obtained reading
GIN_DII
STATUS_MERGED with
string representation)
GIN_DII_STATUS_MNEMONIC char[] String containing the mne-

monic that represents the
current status.
GIN_DII_STATUS_TEXT char [] Status text (can also be

obtained reading GIN_DII
_STATUS with string repre-
sentation)

Default
attribute value
GIN_DII_TREND_LOWER TLS_DOUBLE Trend lower limit
GIN_DII_TREND_UPPER TLS_DOUBLE Trend upper limit
GIN_DII_UPD_INF Struct gin_upd_inf Update information
GIN_DII_UPDATE_TIME TLS_DOUBLE Time of last item update
GIN_DII_VALUE Union gin_dii_val Item value. The item default

representation can be
obtained using the
GIN_DII_VALUE_REP
attribute. Unless you OR-red
the attribute id with one of
the REP_ defines to force
return of the attribute value
in this representation.
See additional remarks
below.
GIN_DII_VALUE_PRC TLS_DOUBLE Item value %
GIN_DII_VALUE_REP int The default representation of

the value
Some special remarks are made about GIN_DII_VALUE:

• In case a value is read from an offline node, then the item value will
contain a special value TLS_INV_DBLVAL to indicate that the
item value is invalid (2.56347e-08).
• If the representation requested for GIN_DII_VALUE is

REP_STRING and the item is not a string item, then the value
format field of the item definition will be used automatically to
format the returned value string.
The routine gin_dii_gaid() can be used for the attr_id argument. It

translates a textual attribute name to a numeric attribute identifier.
• GIN_E_DII_OPT_ARG
Too many optional arguments supplied to routine.
• GIN_E_DII_UNK_ARG
Unknown argument supplied to routine.
• GIN_E_DII_RD_ARG

Argument is not a readable type.

GIN_E_DII_ITMOFL
No alternative node available for item.
• GIN_E_DII_UNS_OPT
Unsupported attribute type.
Related routines • gin_dii_satr()

Set one or more attributes of an item.
3.6.7 Get distributed item id by item id

Syntax [struct *gin_dii_id =] gin_dii_gidi(umh_c, node, itm_id)
Arguments struct *gin_dii_id; /* (R) Distributed itm_id,

*/
/* NULL indicates error */
int node; /* (I)FAST/TOOLS node */
struct itm_id *itm_id; /* (I)item id */
Semantics This routine is used to get the distributed itm_id for an item using the
ITEM/FAST item id. The routine will try to use the specified node to
obtain the item information. If the node is zero the routine will use the
access scheme for the item to find itself a path to obtain the information.
Note that it is the programmer’s responsibility to allocate memory and
copy the returned id for future use, since the value of this pointer will
change with successive calls.
• GIN_E_DII_BADCTXT
Unable to obtain GIN DII context information.
• GIN_E_DII_GIDNND
Unable to find node for item definition info.
Related routines • gin_dii_gidn()

Get distributed item id by name.
• gin_dii_gids()
Get distributed item id by PROCESS/FAST signal.

3.6.8 Get distributed item id by item name

Syntax [struct *gin_dii_id=] gin_dii_gidn(umh_c, item_name)
Arguments struct *gin_dii_id; /* (R) Distributed itm_id */

char *item_name; /* (I)Item name */
Semantics This routine is used to get the distributed itm_id for an item using the
item name.
The layout of the item name is as follows:
[<node_names>:][<section_path>.]<tag>[.<sub>]
When the optional node_names is specified than these nodes are used to
read and update item attributes, independent of any access scheme set
for the process as described in chapter 2 of the manual. When the node
names are omitted the current access scheme is used.
The node names are can be specified in three different formats:
<node_name or node number>:
or
{<node_name or node number 1>[:<node name or number 2>][:<node
name or number 3>][:<node name or number 4>]}:
or
{-}:
In the first format the item is searched on the specified node. In the
second format the item is first searched on node 1, then on node 2, node
3 and finally on node 4. When a node name is omitted then own node is
used.
The third format specifies that GIN DII searches the item in the
Enterprise Solution. The Enterprise Servers are searched for the item to
be distributed on the Enterprise Servers.
When not found then the
The function will return a filled gin_dii_id structure to the caller. Note
that it is the programmer’s responsibility to allocate memory and copy
the returned id for future use since the value of this pointer will change
with successive calls.

If for the second and third format the item is not found then still a filled
gin_dii_id is returned. Internally this id contains information indicating
that the item was not found. This id is valid to be used in the other GIN
DII functions. In this case the gin_dii_ratr() returns FALSE for the
GIN_DII_AVAILABLE attribute. The GIN_DII_LOCATION and
GIN_DII_LOCATION_WITH_NAME return the location (BUS/FAST
node name) where the item is found.
GIN_E_DII_BADCTXT
• GIN_E_DII_GIDNNM
Invalid item name supplied.
Related routines • gin_dii_gidns()

Get multiple item ids by names.
• gin_dii_gidi()
• gin_dii_gids()
3.6.9 Get multiple distributed item ids by item names

Syntax [status=] gin_dii_gidns(umh_c, count, item_names, diis)

int count; /* (I)Item count */
char **item_names; /* (I)Item names */
struct gin_dii_id *diis; /* (I)Item ids */
Semantics This routine is used to get the distributed itm_ids for items using the item
names.
The count gives the number of item names passed by item_name. This
is an array of pointers to item names in a format as described with
gin_dii_gidn().
The caller must supply a buffer by diis that is large enough to return
count itm ids.

GIN_E_DII_BADCTXT
• GIN_E_DII_GIDNNM
Invalid item name supplied.
Related routines • gin_dii_gidn()

Get item id by name.
• gin_dii_gidi()
• gin_dii_gids()
3.6.10 Get distributed item id by PROCESS/FAST signal

Syntax [struct *gin_dii_id=] gin_dii_gids(umh_c, object_name,
signal_path)
Arguments struct *gin_dii_id; /* (R)Distributed itm_id, */

char *object_name; /* (I)Object name */
char *signal_path; /* (I)Signal path */
Semantics This routine is used to get the distributed itm_id for a PROCESS/FAST
signal using the object name and signal path.
The layout of the object name is as follows:
[<node_names>:][<section_path>.]<tag>
For a description of node names see dss_dii_gidn().
The layout of the signal path is as follows:
[<included_class_1>.][<include_class_n>.]<signal_name>
Instead of supplying separate object name and a signal path, a combined
path can be specified for object name. In this case signal_path must be a
NULL or empty:
[<node_names>:][<section_path>.]<tag>..[<included_class_1>.][<incl
ude_class_n>.]<signal_name>

This function returns a filled gin_dii_id structure to the caller. Note that
it is the programmer’s responsibility to allocate memory and copy the
returned id for future use since the value of this pointer will change with
successive calls.
GIN_E_DII_BADCTXT
Related routines • gin_dii_gidss()

Get multiple distributed item ids by multiple signal names.
• gin_dii_gidi()
• gin_dii_gidn()
Get distributed item id by item name.
3.6.11 Get multiple distributed item ids by PROCESS/FAST

signals
Syntax [status=] gin_dii_gidss(umh_c, count, signal_names, diis)

int count; /* (I)Item count */
char **signal_names; /* (I)Signal names */
struct gin_dii_id *diis; /* (I)Item ids */
Semantics This routine is used to get multiple distributed itm_ids for a PROCESS/
FAST signals using the signal names.
The layout of the signal name is as follows:
[<node_names>:][<section_path>.]<tag>..[<included_class_1>.][<incl
ude_class_n>.]<signal_name>
For a description of node names see dss_dii_gidn().
The caller must supply a buffer by diis that is large enough to return
count itm ids.

GIN_E_DII_BADCTXT
Related routines • gin_dii_gids()

Get distributed item id by signal name.
• gin_dii_gidi()
• gin_dii_gidn()
Get distributed item id by item name.
3.6.12 Get pointer to additional memory block

Syntax [mem=]gin_dii_ginf(umh_c, itm_did, info_id)
Arguments void *mem; /* (R)Pointer to memory */

Semantics This routine returns a pointer to an additional information block of

memory for the specified item and info block id

• gin_dii_dinf()
• gin_dii_sinf()
3.6.13 Process GIN DII message

Syntax [status =] gin_dii_hdl(umh_c, elm, par_rcv)


struct fmc_elm *elm,; /* (M)Message element */
struct dur_par_rcv *par_rcv; /* (M)receive buffer */
Semantics Messages received by the calling process with a message id within the
range specified in gin_dii_init() should be passed via this routine.
Note that this routine does not handle clustered messages. Clustered
messages have to be unpacked and then passed to gin_dii_hdl
individually.
Bad parameters supplied to GIN DII interface
3.6.14 Initialize GIN DII interface

Syntax [status =] gin_dii_init(umh_c, option_id, option, .....,
GIN_DII_EOL)

int option_id; /* (I)Option id */
option; /* (I)Option value. */
/* for representation see */
/* table */
Semantics This routine initializes the GIN item interface. If you want to request
item events you must use this routine to initialize the interface Passing
zero or more options can set its general behavior :

Table 3. 4: GIN initialization option
Representation
Option id of option Description
value
GIN_DII_OPTION_DEL_TIME Integer Time unused items should remain

under administration. A value of 0
means items will always remain
until gin_term() is called. When
omitted 0 is used.
GIN_DII_OPTION_DUR_TIMEOUT Integer Reply timeout used for a send/

receive. When omitted 60 seconds
is used.
GIN_DII_OPTION_HOST_NODE Integer Node number of host. If not sup-

plied then dur.sup will be used to
determine the host node.
GIN_DII_OPTION_MSG_BASE Integer Base message code indicating the

start of the range of codes to be
handled by the GIN DII interface.
When omitted, no events can be
requested.
GIN_DII_OPTION_MSG_RANGE Integer Indicates the maximum offset to be

used for message codes to be used
by the GIN DII interface. When
omitted, no events can be
requested.
If you plan to request event notification from you must use the
initialization options, GIN_DII_OPTION_MSG_BASE and
GIN_DII_OPTION_MSG_RANGE. Initializing the GIN distributed
item interface is not necessary for reading and writing item attributes.
Related routines • gin_dii_term()

Terminate GIN DII interface

3.6.15 Request/Cancel an event for an item

TLS_BOOLEAN gin_dii_revt(umh_c, itm_dii, flags,
GIN_DII_EVT_FNC callback_fnc,
context,
attr_id, ..., GIN_DII_EOL);
struct umh_context *dur_c; /* (M) UMH context */

struct gin_dii_id *itm_dii; /* (I) Distributed item id */
int flags; /* (I) Contains optional flag bits */
GIN_DII_EVT_FNC callback_fnc;/* (O) Callback function */
void *context; /* (I) Used to pass context info to */
/* (I) callback routine */
int attr_id; /* (I) Attribute to be notified on */
This routine is used to request and cancel event notifications for an item.
You have the provide the routine with the distributed item id and the
attribute id for which you want notification. Furthermore you have to
provide a call-back function that will be called when an event on an item
occurs. This call-back takes the item id of the item fore which the event
occurred and the attribute id of the attributes that has changes as
parameters. It can than use the gin_dii_gatr() the obtain the new attribute
value. It is possible to call this function multiple time with different
attributes.
The distributed item id (itm_dii) specifies the item.
The flag argument can be contain the following fields.
Table 3. 5: Event request values
Flag Description
GIN_DII_FLG_CANCEL_EVT Do not subscribe to the specified events any more.

When attr_id is GIN_DII_ALL then events for all
attributes will be cancelled.
GIN_DII_FLG_OLD_VAL If this flag is set it will be possible to retrieve the pre-
vious value of an attribute. If for example the item
value changes you could receive the previous item
value using the gin_dii_gatr(). function with the
GIN_DII_FLG_OLD flag. Previous attribute values
are available for the following attributes: item value,
status, option bits en quality code and merged status.

parameter list for callback_fnc()
Attribute id specifies the attributes to request events for. Multiple
attributes can be specified. The last attribute is terminated by the

GIN_DII_EOL.
The callback routine could be used in the following manner:
TLS_BOOLEAN callback_fnc(umh_c, itm_dii_id, attr_id, reason,

context)
int attr_id; /* Item attribute for which */
/* Event occurred */
/* from gin_dii_revt. */
struct gin_dii_id itm_dii; /* Distributed item id. */
{
void *attrib_val; /* Attribute value buffer */
if (reason == GIN_DII_UPDATE)
{
gin_dii_gatr(umh_c, itm_dii_id, attr_id, (void*) attrib_val,
GIN_DII_EOL);
.....
.....
}
}
The valid attributes are:

Table 3. 6: Event attribute id’s
Attribute id Description
GIN_DII_ACKNOWLEDGED Acknowledged (includes GIN_DII_OPTION)
GIN_DII_ALARM_COLOR The color related to the alarm
GIN_DII_ALARM_ENABLED Whether the GIN_DII_ALARM... attributes con-

tain valid information
GIN_DII_ALARM_MNEMONIC The mnemonic related to the alarm
GIN_DII_ALARM_PRIORITY The priority of the alarm
GIN_DII_ALARM_TEXT The text related to the alarm
GIN_DII_ALARM_TYPE Alarm type (includes GIN_DII_OPTION)
GIN_DII_APP_FLAG Application flag
GIN_DII_AVAILABLE Whether the item is available in the Enterprise

Solution
GIN_DII_BLOCKED Blocked (includes GIN_DII_OPTION)
GIN_DII_CONTROL_STATUS Control status (includes GIN_DII_OPTION)

GIN_DII_DEADBAND Deadband
GIN_DII_FORCE_ALARM Alarm force alarm (includes GIN_DII_OPTION)
GIN_DII_FORCE_NORMAL: Alarm force normal (includes

GIN_DII_OPTION)
GIN_DII_HIGH_HIGH_LIMIT High high limit
GIN_DII_HIGH_LIMIT High limit (includes

GIN_DII_HIGH_LIMIT_PRC)
GIN_DII_HIGH_LIMIT_PRC High limit % (includes GIN_DII_HIGH_LIMIT)
GIN_DII_ITEM_OFFLINE The item is offline
GIN_DII_LOCATION The location of the item (FAST/TOOLS node

name) in the Enterprise Solution
GIN_DII_LOCATION_WITH_NAME The full name of the item (<location>:<item

name>) in the Enterprise Solution
GIN_DII_LOCKED The item is locked
GIN_DII_LOCK_TERMINAL The name of the terminal where the item is

locked
GIN_DII_LOCK_USER The name of the user who locked the item

GIN_DII_LOW_LIMIT Low limit (includes
GIN_DII_LOW_LIMIT_PRC)
GIN_DII_LOW_LIMIT_PRC Low limit % (includes GIN_DII_LOW_LIMIT)
GIN_DII_LOW_LOW_LIMIT Low low limit
GIN_DII_OPTION_STATUS Option bits (includes

GIN_DII_ACKNOWLEDGED,
GIN_DII_BLOCKED,
GIN_DII_CONTROL_STATUS,
GIN_DII_ALARM_TYPE,
GIN_DII_FORCE_NORMAL and
GIN_DII_FORCE_ALARM)
GIN_DII_QUALITY Quality code
GIN_DII_REFRESH_TIME The time that the item was updated
GIN_DII_SCALE_HIGH Scale high limit
GIN_DII_SCALE_LOW Scale low limit
GIN_DII_STATUS Status (includes GIN_DII_STATUS_TEXT)
GIN_DII_STATUS_COLOR The color related to the status of the item
GIN_DII_STATUS_MERGED Status merged (includes GIN_DII_STATUS,

GIN_DII_OPTION and
GIN_DII_STATUS_MERGED_TEXT)
GIN_DII_STATUS_MERGED_TEXT Status merged text (includes

GIN_DII_STATUS_MERGED,
GIN_DII_STATUS_COLOR and
GIN_DII_STATUS_MNEMONIC)

GIN_DII_STATUS_MNEMONIC The mnemonic related to the status
GIN_DII_STATUS_TEXT Status text (includes GIN_DII_STATUS)
GIN_DII_UPD_INF Always available
GIN_DII_UPDATE_TIME Always available
GIN_DII_VALUE Item value (includes GIN_DII_VALUE_PRC

and GIN_DII_VALUE_OWR))
GIN_DII_VALUE_OWR The overwrite value (same as GIN_DII_VALUE)
GIN_DII_VALUE_PRC Item value % (includes as GIN_DII_VALUE)
The callback_fnc routine is also called when communication with the

item goes off-line or on-line or switches to another node. The reason
why the callback was called is reflected in the ‘reason’ argument.
Table 3. 7: Reason for callback
Reason Description
GIN_DII_DONE All requested attributes are returned. This is the last call to the
callback_fnc to notify the event is completely processed. In
This case the attribute id is 0.
GIN_DII_OFFLINE The item is off-line, no flow any more
GIN_DII_OFFON The event source is changed to another node
GIN_DII_ONLINE The item is on-line again
GIN_DII_UPDATE The attribute supplied in attr_id is updated, gin_dii_gatr() can

be used to obtain the attribute
• GIN_E_DII_MSGBASE
No message codes reserved: unable to send request.
• GIN_E_DII_DYNATTR
Requests can only be made for dynamic attribute types.

3.6.16 Set one or more attributes of an item

Syntax [status =] gin_dii_satr(umh_c, itm_dii, attr_id,
attr_val,..., GIN_DII_EOL)

int attr_id; /* (I)Attribute id */
void *attr_val; /* (O)Pointer to receive
buff.*/
Semantics This routine sets one or more attributes of an item. It uses the access
scheme to determine where to set the attribute of the item in a distributed
environment.
The attr_val buffer must be large enough to receive the attribute value.
The default representation of the attribute value can be overruled by OR-
ring the attribute identifier with one of the REP_ defines. For value, high
limit and low limit this can also be REP_PERCENT. The following
(control) attributes can be set:
Table 3. 8: Attribute id for setting.
Default
Option id representation of Description
attribute value
GIN_DII_ACKNOWLEDGED TLS_BOOLEAN Acknowledge alarm (when value is true)
GIN_DII_APP_FLG_SET TLS_ULONG Set application flag set/reset bits
GIN_DII_APP_INFO char[] Application info
GIN_DII_AUDIT Struct Set AUDIT/FAST event info.

gin_dii_adt_inf Used to audit the update action
GIN_DII_BLOCKED TLS_BOOLEAN Block/Unblock
GIN_DII_DEADBAND TLS_DOUBLE Set deadband
GIN_DII_EXCLUDE struct dur_adr Exclude the specified process from being

notified of the update, this control attribute
may be specified more than once.

Default
attribute value
GIN_DII_FLAGS int One or more or-red:
GIN_DII_FLG_VALUE_ADD - A value
specified is added to the current value
GIN_DII_FLG_SAVE - The new value is

saved on disk
GIN_DII_FLG_QC_ADD - A quality code

specified is added to the current one
GIN_DII_FLG_QC_AND - A quality code

specified is and-ed to the current one.
GIN_DII_FLG_QC_OR - A quality code

specified is or-red to the current one
GIN_DII_FLG_OWR - Overwrite even if

item is blocked.
GIN_DII_FORCE_ALARM TLS_BOOLEAN Force alarm state to alarm
GIN_DII_FORCE_NORMAL TLS_BOOLEAN Force alarm state to normal
GIN_DII_HIGH_HIGH_LIMIT TLS_DOUBLE Set high high limit
GIN_DII_HIGH_LIMIT TLS_DOUBLE Set high limit
GIN_DII_HIGH_LIMIT_PRC TLS_DOUBLE Set high limit %
GIN_DII_LOCKED TLS_BOOLEAN Item is locked
GIN_DII_LOCK_ID TLS_ULONG Unique lock id to lock, unlock or mod-

ify the value of the item
GIN_DII_LOCK_TIMEOUT TLS_ULONG Timeout to remain the lock

GIN_DII_LOW_LIMIT TLS_DOUBLE Set low limit
GIN_DII_LOW_LIMIT_PRC TLS_DOUBLE Set low limit %
GIN_DII_LOW_LOW_LIMIT TLS_DOUBLE Set low low limit
GIN_DII_ITEM_OFFLINE TLS_BOOLEAN To set item off/on-line
GIN_DII_QUALITY TLS_ULONG Set quality code value (may be influenced

by GIN_DII_FLAGS)
GIN_DII_SCALE_HIGH TLS_DOUBLE The scale high limit
GIN_DII_SCALE_LOW TLS_DOUBLE The scale low limit
GIN_DII_STATUS int Set item status
GIN_DII_UPD_INF Struct gin_upd_inf Update item with update info
GIN_DII_VALUE Union gin_dii_val Set item value.
GIN_DII_VALUE_OWR Union gin_dii_val Same as GIN_DII_VALUE with

GIN_DII_FLAGS to GIN_DII_FLG_OWR

Default
attribute value
GIN_DII_VALUE_PRC TLS_DOUBLE Set item value %
The audit trail information (GIN_DII_AUDIT) is can be set using the

GIN_DII_ADT_INF structure. Note that the item name will be supplied
automatically to AUDIT/FAST when GIN_DII_AUDIT is used.
The audit trail information is also used to register the name of the user
and the terminal when an item is locked (see GIN_DII_LOCKED).
When more than one attribute of an item is set in a single call, then this
will result in a single request to the item handler, in order to handle
related item attributes as a single atomic action (e.g. item value and force
to normal).
• GIN_E_DII_WR_ARG
Argument name:s is not a writable type.
• GIN_E_DII_ITMOFL
No alternative node available for item.
• GIN_E_DII_INV_VAL
Invalid value supplied to set attributes.
• GIN_E_DII_NO_LIM
Item does not have the specified limits to be set.
• GIN_E_DII_ALMACK
Unable to acknowledge alarm: host/fe nodes down.
Related routines • gin_dii_gatr()

Get one or more attributes of an item.

3.6.17 Enable/Disable flow control to a specified node

Syntax [status =] gin_dii_sflw(umh_c, node, interval,
callback_fnc,
context);
Arguments TLS_BOOLEAN status; /* (R) TRUE:(success) */

struct umh_context *umh_c; /* (M) UMH context*/
int node /* (I) FAST/TOOLS Node */
int interval; /* (I) Flow control interval */
GIN_DII_FLW_FNC callback_fnc; /* (I) callback function */
void * context; /* (I) Context info buffer */
Semantics
This routine is used to enable or disable flow control to the specified
node. The flow control routine of the GIN distributed item interface lets
you start and stop flow control from a FAST/TOOLS node. If you wish
it can also inform you when the event flow has switch to another node.
When node is -1 flow is enabled or disabled for all nodes else flow
control is enabled or disabled for the specified node. When interval is set
to number smaller than 1 then flow control is disabled. The interval is in
seconds. In case you want to change the interval you first have to disable
the flow control by calling the gin_dii_sflw() function with interval
value 0 and then enable the flow control again by calling it with the new
interval.
The address of a function can be specified (NULL when omitted) that is
called when something in the flow of a node is changed. The node
involved is supplied as an argument. In case of a flow redirection then
the old node is also supplied as an argument.
parameter list for callback_fnc(). The context buffer can be used to pass
information on to the call-back routine.
TLS_BOOLEAN callback_fnc(umh_c, node, old_node, reason, context)

{
int node; /* New node to recv events from */
int old_node; /* Previous node */
/* from gin_dii_sflw() */

The node involved is supplied as an argument. In case of a flow

redirection then the old node is also supplied as an argument. This
routine can be used as a logging function for example. The reason can
be one of the following:
Table 3. 9: Reason for callback
Reason Description
GIN_DII_OFFLINE The node is off-line, no flow any more
GIN_DII_OFFON The flow source is changed to another node
GIN_DII_ONLINE The node is on-line again
In addition, the reason is also available in the umh context.
3.6.18 Connect additional memory block to an item

Syntax [status =] gin_dii_sinf(umh_c, itm_dii, info_id, info)

struct gin_dii_id *itm_dii; /* (I)distributed item id */
void *info; /* (I)Memory info block */
Semantics This routine connects a block memory to the specified item. It is labelled
with specified information identifier. It is allowed to specify a
previously defined info_id for a given 'itm_did'. In that case the memory
pointer 'info' will replace the pointer currently related to combination
'info_id' and 'itm_did'. If that "old pointer" points to memory allocated
via 'gin_dii_ainf()', the routine will free this "old memory"
Errors
• GIN_E_DII_BADPARS


• gin_dii_dinf()
• gin_dii_ginf()
3.6.19 Terminate GIN DII interface

Syntax [status =] gin_dii_term(umh_c)

Semantics
This routine should be called when the GIN distributed item interface is
no longer used. It cancels outstanding event requests and frees all
resources.
Errors • None
Related routines • gin_dii_init()

Initialise GIN DII interface.

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction HISTORY/FAST FAST/TOOLS
IM50G02G00-01EN/R10.03

IM50G02G00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction ..........................................................................1-1
1.2 About the environment ..............................................1-1
2 Function overview ................................................................2-1
2.1 Design constraints ......................................................2-1
2.2 Process overview .......................................................2-1
2.3 Global structure .........................................................2-2
2.4 The history administrator ...........................................2-3
2.5 The environment administrator .................................2-3
2.6 The scheduler .............................................................2-4
2.7 File naming and usage ...............................................2-5
2.8 Locking groups ..........................................................2-6
2.9 Typical history specific process ................................2-6
2.10 History backup and restore ........................................2-7
3 Interface ................................................................................3-1
3.1 General structs ...........................................................3-1
3.1.1 Group number struct. ................................................ 3-1
3.1.2 Group sequence struct. .............................................. 3-1
3.1.3 Group definition struct. ............................................. 3-1
3.1.4 Group schedule struct. .............................................. 3-2
3.1.5 Group info struct. ...................................................... 3-2
3.1.6 Group command struct. ............................................. 3-3
3.1.7 Group command with user information struct. ......... 3-3
3.1.8 Login struct. .............................................................. 3-3
3.1.9 Unit delete struct. ...................................................... 3-6
3.1.10 Unit info struct. ......................................................... 3-6
3.1.11 Unit info with user information struct. ..................... 3-7
3.1.12 Restore unit struct ..................................................... 3-7
3.1.13 Block unit deletion struct .......................................... 3-7
3.2 Available functions ....................................................3-9
3.2.1 Introduction ............................................................... 3-9
3.2.2 Create group ............................................................ 3-11
3.2.3 Modify group .......................................................... 3-12
HISTORY/FAST Programmer’s Guide iii

Table of Contents
3.2.4 Delete group ............................................................ 3-13

3.2.5 Modify schedule information .................................. 3-14
3.2.6 Finish group or schedule action .............................. 3-15
3.2.7 Cancel group or schedule action ............................. 3-17
3.2.8 Process login ........................................................... 3-18
3.2.9 Process logout ......................................................... 3-20
3.2.10 Process reset ............................................................ 3-21
3.2.11 Delete unit ............................................................... 3-22
3.2.12 Force rollover .......................................................... 3-23
3.2.13 Force rollover with user information ...................... 3-24
3.2.14 Get group information ............................................. 3-25
3.2.15 Get unit information ................................................ 3-26
3.2.16 Get unit with user information ................................ 3-27
3.2.17 Get process information .......................................... 3-28
3.2.18 Get login information .............................................. 3-29
3.2.19 Get statistics ............................................................ 3-30
3.2.20 Finish reply ............................................................. 3-31
3.2.21 Cancel reply ............................................................ 3-32
3.2.22 Restore unit ............................................................. 3-33
3.2.23 Disable “before delete” warning ............................. 3-34
3.2.24 Allocate free unit ..................................................... 3-35
3.2.25 Change unit information ......................................... 3-36
3.2.26 Block unit deletion temporary ................................. 3-37
3.2.27 Create file name ...................................................... 3-38
3.2.28 Initialize save-set selection ..................................... 3-39
3.2.29 Select units for save-set ........................................... 3-40
3.2.30 Terminate save-set selection ................................... 3-41
3.2.31 Initialize save-set merging ...................................... 3-42
3.2.32 Merge save-set ........................................................ 3-43
3.2.33 Terminate save-set merging .................................... 3-44
iv HISTORY/FAST Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives
functionality of the history manager (HIS).
HIS-routines.

language. To understand the concept of HIS, the reader is assumed to
have a knowledge of the BUS/FAST message passing facilities
((M)DUR).
Furthermore the reader is assumed to have a knowledge of the BUS/
FAST error logging facility (UMH).

This manual contains 4 chapters;
• Chapter 1 can be regarded as an introduction to the HIS
• Chapter 2 described the functions handled by the history manager.
familiar with the concept of HIS.

1 HISTORY/FAST Systems Integrator’s Manual.
HISTORY/FAST Programmer’s Guide 0-1

2 BUS/FAST Programmer’s Guide, Parts UMH, DUR and FSL.

which are used.
software.

CONVENTION MEANING
() Brackets used in routine syntax to indicate a
list of arguments that need to be passed.
[] Parentheses used in routine syntax to
... Indicates that not all statements are shown.
DUR_NOWAIT.
input.
returns.
output.
0-2 HISTORY/FAST Programmer’s Guide


literally.
n.u. not used.
a terminal.
from the user.


1 Introduction

The history manager (HIS) handles all history actions which are not
history kind dependant.
The functions of the history manager are:
1 Control the start, rollover and stop times of history storage.
2 Control the naming of the data files.
3 Know about all history information stored on the disks.
4 Control the deletion of old history information.
5 Supply information about the available history information.
6 Supply information about processes working for a specific history
part.
1.2 About the environment

Before the history manager can work, the BUS/FAST environment and
the ISF brick must be available.
When the history manager is started, history kind dependant bricks can
login to the history manager. The history manager will inform them
about the work to do.

Introduction About the environment

Design constraints Function overview
2 Function overview
2.1 Design constraints

The following constraints and considerations led to the design:
• The history manager is capable of managing various types of
historical information.
• The historical information itself is handled by the appropriate
bricks. How this must be done is described in files. These files are
administrated by the history manager.
• The history manager supplies a uniform interface to all history
bricks.
• Bricks can be added, removed or replaced without affecting the
history manager.
• The history manager can give a survey of the historical information
that is maintained by the history bricks.
• The history manager will handle received requests synchronously.
• The history manager will receive replies asynchronously.
• The history manager will handle send requests/messages to other
processes asynchronously.
2.2 Process overview

The history manager consists of the following processes:
• HIS
This process handles all history manager actions. All BUS/FAST
requests and messages must be sent to this process.
• HISDBG
This process gives the system manager the possibility to inspect the
working of the history manager.
• HISBCK
With this process a save-set can be composed. It gives the user the
possibility to select data units for the groups for a given time period.
Two files with the selected information of the selected groups and
units will be generated together with a log file which describes all
files to be saved in the save-set.

Function overview Global structure
• HISWRN
This process can be used after the backup of a save-set. It will reset
the warning time for each unit in a save-set.
• HISRES
With this process it is possible to select some data units from a save-
set. Plus generate a log file with all file names to restore and to
inform the history manager (HIS) that files have been restored.
• HISRECOVER
With this process “lost” data units can be given back to the history
manager.
2.3 Global structure

The history manager provides a uniform interface to all history bricks.
This is achieved by introducing the concept of storage groups and
storage units. A storage group is a logical entity of historical
information, which is handled by one brick. This can be an alarm group,
which holds alarm messages for signals that are associated with some
part of an industrial process. Or a group of items, that are scanned with
the same frequency.
Each storage group is associated with a number of so-called storage
units. A storage unit covers the historical information of the group for a
limited period of time. It consists of a data file and a description file. The
latter describes how the former looks, what information it contains etc.
Each rollover time a new storage unit will be created. Mostly the layout
of the data file is not changed, so only a new data file and not a new
description file has to be created.
The layout of these files is only known to the brick that handles the
storage group. The history manager administrates which brick handles a
group and which units cover the history of those groups. Besides, it is an
aid for the storage and retrieve functions of the bricks. By telling them
which groups there are, what its units are, which unit is to be used for
storage (current unit).
The concept of groups and units gives the opportunity to manage the
historical information of storage groups in the following way:
• information can be backed-up, restored or deleted selectively
• information can be deleted automatically after a predefined period
The fact that the history of a group is divided in separate units will be
hidden as much as possible. For instance, when a user wants to reference

The history administrator Function overview
historical information. There is no need to specify in which unit the

information can be found. Only the time window in which the
information lies need be specified.
The basic functions of the history manager are:
- Administration of all kinds of history
- Administration of environment which handles the history info
- Inform environment about all changes.
- Control the start, stop and deletion of history units (scheduling).
These functions are described in the following sections. After that some
other aspects will also be explained.
2.4 The history administrator

The history administrator maintains an administration of all storage
groups and units in the system (part of which may be in use by the
bricks). This information can be used to determine which unit must be
used by the brick when data for a specified period must be retrieved, or
to check if a storage group/unit is in use in case someone wants to delete
it.
The history administrator is notified each time a significant structure
change has taken place. In general, this is when a control or
configuration request is processed, as described elsewhere in this
document.
Two disk files are maintained by the history administrator, which
contain data about all storage groups and their units. Besides this, a
memory resident structure is maintained. This structure is initialized at
start-up by processing the disk files. It reflects the status of which
storage groups and units are in use etc.
2.5 The environment administrator

The environment administrator maintains an administration of all
processes which want to be notified about changes in the history and
environment administration. A process can e.g. ask to be notified when
for a history type a rollover should be done, a unit should be closed
because the history manager wants to delete it. Is is also possible to get

Function overview The scheduler
a notification when another process asks to be notified about e.g unit

creations.
A process can select the information it wants to get by specifying the
next key’s:
Action type Kind of action e.g. delete unit, rollover
History type Type of the history group (items, alarms)
Option types History type dependant types
Specifying zero for one of these keys means: select all.
When the history manager detects that it has to send a notification to a
process, that message will be queued in a list of notifications. It is
possible that the same message must be sent to different processes but
that one process must receive it before the other. E.g. when the history
manager wants to delete a unit, first the type specific retrieve process
must be informed to close the file and then the history manager itself
must be informed to delete the file. To make this possible a priority can
be given to each info request. A higher priority notification (lower
number) must be sent first, and the reply received, before the lower
priority notification will be sent. So the sequence of sending
notifications within one action is on priority.
For one process the sequence of messages for different actions is always
the same as the sequence they occur in time. So if a low priority message
can not yet be sent, a newer high priority message to the same process
will not be sent either.
2.6 The scheduler

The scheduler function of the history manager is used to issue some
control commands at a specified time. These commands are; rollover,
start, stop and delete unit. The rollover command can also be
rescheduled. This gives the opportunity to start the first unit for some
group at 12:30 pm and to rollover every 24 hours to a new unit and delete
each unit 4 days after it is closed.
The scheduling information is part of the storage group and unit
information, as administrated by the HIS.
The scheduler sets a timer, which expires each minute. When the timer
expires, all time-outs will be checked first. Then each group is checked
for the need of a start, rollover or stop action. And last, some older units
are checked for deletion.

File naming and usage Function overview
2.7 File naming and usage

The following files are handled by the history manager:
his_procs.dat This file contains the names of all processes
ever to be connected with the history manager.
The history manager will send a “history
manager up” message to all these processes at
start-up.
his_groups.dat This file contains one record for each history
group with information like group name,
scheduling info and next unit number.
his_units.dat This file contains one record for each unit with
info like group number, unit number, time
period store in unit data file, wanted deletion
time of this unit, and user information. The
user information is of importance when a
rollover is requested by a user independent
from the scheduling of the history group.
h01002000000.his History group description file. The contents of
this file is history type specific. It describes
the information to be stored in the next
unit.The part 01 in the name is the node
number and 002 is the group number. Each
digit of these elements can have the values 0-
9 and letters a-v together representing a
number range 0-31.
h01002003000.his History unit description file. The contents of
this file is history type specific. It describes
the layout of the associated data files. The part
003 is the unit number. After each unit
description change this number is
incremented.
h01002003004.his History unit data file. The contents of this file
is the real history data stored. The part 004 is
the unit data number. After each rollover this
number is incremented. If the unit number was
incremented, this number starts with 001
again. If incrementing of this number results
in the number 000, the unit number will be
incremented, a new unit description file will

Function overview Locking groups
be created and the data number 001 will be

used.
2.8 Locking groups

There are some actions during which no change is allowed on a group.
E.g. when a rollover is activated a message is sent to the storage process.
That process has to close the old file and to open the new one. The exact
time of the rollover is not yet known. So the history manager can not
create the right unit records and can not answer correctly on unit info
requests. During such actions the history manager will lock the group.
When the answer for the storage process is received, the group will be
unlocked again. When the storage process does not answer within one
minute, the action is aborted The group will be set on error and will be
unlocked. The group will be set on no error again by a new log-in of the
storage process or by a schedule info change request of the group.
2.9 Typical history specific process

A typical history specific process with store and retrieve function has, at
start-up, first to send a reset message to the history manager to get rid of
all context to earlier runs. Than it has to log-in to the history manager.
In this log-in request the history type must be specified and at least the
next information should be requested:
• HIS_ACT_R_START or storage start request.
HIS_ACT_R_START_USR On receiving this request an initial
storage unit should be created and
storing of history info for this
group should be started.
• HIS_ACT_R_ROLLOVER or storage unit rollover request.
HIS_ACT_R_ROLLOVER_USR
On receiving this request a new
storage unit file should be created.
• HIS_ACT_R_STOP or storage stop request.
HIS_ACT_R_STOP_USR On receiving this request saving of
history information for this group
should be stopped.

History backup and restore Function overview
• HIS_ACT_DEL_UNIT unit deletion notification.

If this message if received, the
specified file should be closed.
After this the process can wait for messages in its queue. The history
manager will send a start message for each group of the selected history
type. When such a message is received, the process can ask for old unit
information for the group.
Apart from the messages requested by the log-in, the message
HIS_HISUP (history manager restarted) message should be handled. If
this message is received, all files should be closed and the log-in request
should be send again.
2.10 History backup and restore

A number of routines available to support the backup and restore of
history files.
Before history files can be copied to the backup medium, a save-set must
be composed by selecting data units for groups for a given time period.
The routines his_bck_ini(), his_bck_sel() and his_bck_cls() are used for
this purpose.
When a save-set has been restored from the backup medium, the units
restored must be introduced by the history manager. The routines
his_res_ini(), his_res_mrg() and his_res_cls() are used for this purpose.
Note that this functionality is superseded by the archive functionality
performed by the HAS brick.

Function overview History backup and restore

General structs Interface
3 Interface
3.1 General structs

The following structs are used in several interfaces:
3.1.1 Group number struct.
The group number struct gives a unique identification for a history

group. The node number of the history manager process is stored in the
first member and a unique group sequence number within that node is
stored in the second member. The group sequence number is in the range
of 1 till 32767.
struct his_grp_nr
{
TLS_SHORT node; /* Group node number */
TLS_SHORT group; /* Group id */
};
3.1.2 Group sequence struct.
Within a group the group sequence struct gives a unique identification

for a history unit description or a unit data file. The first number gives
the unit number in the range 1 till 32767. If it identify’s a unit data file,
the second member gives the data number in the range 1 till 32767.
struct his_grp_seq
{
TLS_SHORT unit_seq; /* Group modif. seq. */
TLS_SHORT data_seq; /* Unit data sequence */
};
3.1.3 Group definition struct.
The group definition struct contains all group related information,

except the timing information, stored by the history manager. The struct
should initially be sent by the application when a group is created.
Further this struct will be used as input and/or output layout for most of
the functions of the history manager.

Interface General structs
struct his_grp_def /* Group definition */

{
char path[TLS_FPATH_SZ]; /* History files path*/
char sh_path[TLS_FPATH_SZ]; /* Backup path */
char name[HIS_GRP_NAME_SZ]; /* Group name */
struct his_grp_nr grp_nr; /* Group number */
struct his_grp_seq grp_seq; /* Group sequence */
TLS_SHORT his_type; /* History type */
TLS_SHORT spare;
TLS_UBYTE opt_type[HIS_OPT_TYPES];
/* Option types*/
};
3.1.4 Group schedule struct.
The group schedule struct contains the actual timing info of a history
group. It will be a part of the input and/or output layout for all functions
of the history manager where group timing info is needed.
struct his_schedule
{
TLS_ULONG start; /* Start of storage */
TLS_ULONG stop; /* End of storage */
TLS_ULONG roll_first; /* First rollover */
TLS_ULONG roll_int; /* Rollover interval */
TLS_ULONG life_time; /* Auto delete lifetime */
TLS_BOOLEAN roll_flg; /* Rollover flag */
TLS_ULONG warn_time; /* Warning before time */
};
3.1.5 Group info struct.
The group info struct is a collection of the group definition struct and the
group schedule struct. Further some extra elements are added for
retrieving some status information about a group.
struct his_grp_inf
{
struct his_grp_def grp_def;/*Group info*/
struct his_schedule schedule;
/* Schedule info */
struct dur_adr lock_proc; /* Actual locker */
TLS_LONG lock_inf; /* Reason of lock */
TLS_BOOLEAN error; /*Start/rollover error */
};

3.1.6 Group command struct.
The group command struct is used by the history manager when a group
action request or report message has to be sent to a history server
process.
struct his_grp_cmd
{
char path[TLS_FPATH_SZ]; /* History files path */
char sh_path[TLS_FPATH_SZ];
/* Backup path */
struct his_grp_nr grp_nr; /* Group nr */
/* Option types */
struct his_grp_seq grp_seq;
/* New unit sequence */
struct his_grp_seq grp_seq1;
/* Old sequence */
TLS_ULONG start; /* Unit started stamp */
};
3.1.7 Group command with user information struct.
The group command struct with user information is used by the history
manager when a group action request or report message has to be sent to
a history server process. What type of message has to be send,
his_grp_cmd or his_grp_cmd_usr, is determined by the login parameters
of the server process.
struct his_grp_cmd_usr
{
struct his_grp_cmd grp_cmd;
/* Group command */
struct his_usr_inf usr_inf;
/* User info */
};
3.1.8 Login struct.
The login struct must be used by a history server process to ask the
history manager for which kinds of information it wants to receive
requests or messages.

struct his_login
{
TLS_SHORT his_type; /* history type */
TLS_UBYTE opt_type[HIS_OPT_TYPES];/* option types */
TLS_SHORT action; /* action type */
TLS_SHORT msg_code; /* user message id */
TLS_SHORT priority; /* priority */
};
The available action types are:
HIS_ACT_CREATE Create group
After each group creation a message
will be sent.
HIS_ACT_MODIFY Modify group
After each group modification a
message will be sent.
HIS_ACT_DEL_GRP Delete group
After each group deletion a message
will be sent.
HIS_ACT_LOGIN Process log-in
After each log-in of a process a
message is sent. Besides the
his_type and opt_type’s also the
action is checked. If action 0 is
specified, one log-in request can
result in several messages.
HIS_ACT_LOGOUT Process logout
After each log-out of a process
messages will be sent.
HIS_ACT_START Unit start
After each unit start done a message
will be sent.
HIS_ACT_ROLLOVER Unit rollover
After each unit rollover done a
message will be sent.
HIS_ACT_STOP Unit stop
After a unit stop is done a message
will be generated.
HIS_ACT_RESTORE Unit restore
After a unit is restored from e.g
tape a message will be sent.
HIS_ACT_DEL_UNIT Unit delete
Before a unit will be deleted a
message is sent.
HIS_ACT_RETRIEVE General unit retrieve
No message is sent. This action is
supported to get info from other
process log-in’s.
HIS_ACT_R_START Request unit start

A message (of type struct

his_grp_cmd) will be sent before a
unit start. The unit must be started
by the server. Only one server will
receive start messages for a
specific history group.
HIS_ACT_R_START_USR
Request unit start with user info
his_grp_cmd_usr) will be sent before
a unit start. The unit must be
started by the server. Only one
server will receive start messages
for a specific history group. Only of
of HIS_ACT_R_START or
HIS_ACT_R_START_USR may be specified
in the login request.
HIS_ACT_R_ROLLOVER Request unit rollover
unit rollover. The unit must be
rolled over by the server. Only one
for a specific history group.
HIS_ACT_R_ROLLOVER_USR
Request unit rollover with user info
a unit rollover. The unit must be
rolled over by the server. Only one
for a specific history group. Only of
of HIS_ACT_R_ROLLOVER or
HIS_ACT_R_ROLLOVER_USR may be
specified in the login request.
HIS_ACT_R_STOP Request unit stop
unit stop. The unit must be stopped
specific history group.
HIS_ACT_R_STOP_USR Request unit stop with user info
a unit stop. The unit must be stopped
specific history group. Only of of

HIS_ACT_R_STOP or HIS_ACT_R_STOP_USR
may be specified in the login
request.
Messages are only sent if the his_type and the opt_type’s are the same
or zero. The message layout’s used are specified at the log-in request
description.
The possible priorities are:
HIS_PRIO_DEF default priority (= high priority)
HIS_PRIO_HIGH high priority
HIS_PRIO_NORMAL normal priority
HIS_PRIO_LOW low priority
3.1.9 Unit delete struct.
The unit delete struct must be sent to the history manager when a
specific unit must be deleted. This message will typically sent by the
history manager to itself.
struct his_unit_del
{
struct his_grp_seq grp_seq;
/* data seq. nr */
};
3.1.10 Unit info struct.
The unit info struct can be used for retrieving the timing information
about available units for one group.
struct his_unit_inf
{
char name[HIS_GRP_NAME_SZ];
/* Group name */
TLS_ULONG start; /* Group active window */
TLS_ULONG stop;
TLS_SHORT count; /* units count */
/* Option types */
struct his_unit unit[1]; /* Found units */
};

3.1.11 Unit info with user information struct.
The unit info with user information struct can be used for retrieving the
timing information, including user information about available units for
one group.
struct his_unit_usr_inf
{
char name[HIS_GRP_NAME_SZ];
/* Group name */
TLS_ULONG start; /* Group active window */
TLS_ULONG stop;
TLS_SHORT count; /* units count */
/* Option types */
struct his_unit_usr unit[1];
/* Found units */
};
3.1.12 Restore unit struct
The restore unit struct need to be used when a history unit data file is
restored from a tape. After placing the file(s) on the right directory, this
struct must be sent to the history manager to make the file available
again.
struct his_restore
{
char path[TLS_FPATH_SZ]; /* History files path */
char sh_path[TLS_FPATH_SZ];/* Shadow files path */
struct his_grp_seq grp_seq; /* data seq. nr */
TLS_ULONG start; /* Start of unit */
TLS_ULONG stop; /* Stop of unit */
};
3.1.13 Block unit deletion struct
The block unit deletion struct is used to suspend unit deletion temporary.
struct his_blk_del
{
TLS_ULONG time_out; /* Temporary unit deletion

time-out */
};

Available functions Interface
3.2 Available functions
3.2.1 Introduction
This section describes the HISTORY/FAST functions. For each HIS

function a description is given for:
• the purpose of the function
• the BUS/FAST message id.
• the request struct
• the reply struct
• the semantics of the function
• the error codes that may be returned by the routine
The following DUR request/message functions are available:

• Create group
• Modify group
• Delete group
• Modify schedule information
• Finish group or schedule action
• Cancel group or schedule action
• Process login
• Process logout
• Process reset
• Delete unit
• Force rollover with or without user information
• Get group information
• Get unit information
• Get process information
• Get login information
• Get statistics
• Finish command for logged in process
• Cancel command for logged in process
• Restore unit
• Disable ‘before delete’ warning
• Allocate free unit
• Change unit information
• Block unit deletion temporary
The following routine interface functions are available:

Interface Available functions
• Create file name

• Initialize save-set selection
• Select units for save-set
• Terminate save-set selection
• Initialize save-set merging
• Merge save-set
• Terminate save-set merging
The functions are described in the following paragraphs.

3.2.2 Create group
Function Start the creation of a group
BUS/FAST HIS_CREATE
Message id.
Request struct his_grp_def (only element “name” must be filled)
Reply struct his_grp_def
Semantics When an application wants to create a group, first this create group
command must be sent. The history manager will allocate a group
number and administration space. After receiving the reply, the
application can create the group description file etc. When the
application create actions are ready a finish group command should be
sent to the history manager. The history manager will complete its
administration and the group will be ready for use.
On receive of the create message the element name will be checked to
see if it is unique. If so, the name is stored in memory and a free group
number is sought. The search is started with the last allocated group
number, stored in a special record in the his_group.dat file.
The reply struct will be a copy of the request struct with the “grp_nr”
element filled. The group will be locked until a finish or cancel group
action message is received.
Errors • HIS_E_ERROR
• HIS_E_GROUPALREXI

3.2.3 Modify group
Function Start the modification of a group
BUS/FAST HIS_MODIFY
Message id.
Request struct his_grp_def (only element “name” or “grp_nr” must be filled)
Semantics If the first character of the “name” is given, the group is sought by name,
else the search is done by “grp_nr”. It will be checked to see if the group
exists and is not locked.
The reply struct will contain the actual known group information. The
group will be locked until a finish or cancel group action message is
received.
• HIS_E_GROUPNOTEXI
• HIS_E_IS_LOCKED

3.2.4 Delete group
Function Start the deletion of a group
BUS/FAST HIS_DEL_GRP
Message id.
exists and is not locked and if there is no active unit for this group.
received.
• HIS_E_IS_LOCKED
• HIS_E_GROUPHASUNT

3.2.5 Modify schedule information
Function Start the change schedule information of a group
BUS/FAST HIS_SCHEDULE
Message id.
Request struct his_grp_inf (only element “name” or “grp_nr” must be filled)
Reply struct his_grp_inf
exists and is not locked.
received.
• HIS_E_IS_LOCKED

3.2.6 Finish group or schedule action
Function Activate the requested group create, modify or delete action or the
change schedule information action.
BUS/FAST HIS_GRP_DONE
Message id.
Request struct his_grp_def (all except schedule) or

his_grp_inf (only schedule)
Reply struct his_grp_def (all except schedule) or

Semantics First there will be checks to see if the group (sought by “grp_nr”) exists
and is locked by this process. The rest is dependant from the kind of
action finishing:
• Create
The internal group information definition struct is filled and stored
on disk. All processes interested in group creations of this history
type are informed.
• Modify
First there will be checks to see if the name of the group has
changed. If so, there will be check if the new name is unique. If not,
the name will not be changed and, after handling the other changes,
the HIS_W_SAME_NAME warning will be returned to the caller.
The internal group information definition struct is updated and
stored on disk. All processes interested in group modifications of
this history type are informed.
• Delete group
First the caller will get a reply message. Second it will be checked
to see if there is still a unit for this group. If so, all processes
interested in unit deletions for this history type are notified and the
units will be deleted. Lastly, processes interested in group deletions
for this history type are notified and the group will be deleted.
Warning: The caller will get a reply before the group is really
deleted.

• Change schedule information

The internal group information schedule struct is filled and stored
on disk. Further the group will be check for the need of a start,
rollover or stop action. This is done by the general routine
hisi_chk_grp.
The reply struct will contain the actual known group information.
• HIS_W_SAME_NAME (only modify)
• HIS_E_NOT_LOCKED

3.2.7 Cancel group or schedule action
Function Abort the requested group create, modify or delete action or the change
schedule information action.
BUS/FAST HIS_GRP_CANCEL
Message id.
Request struct his_grp_def (all except schedule) or

Reply struct his_grp_def (all except schedule) or

Semantics First there will be a check to see if the group (sought by “grp_nr”) exists
and is locked by this process. If so, the group is unlocked. If it was a
create group request, all information about this group will be deleted.
• HIS_E_NOT_LOCKED

3.2.8 Process login
Function Store command interest info for a process.
BUS/FAST HIS_LOGIN
Message id.
Request struct An array of his_login structs
Reply struct Only size and code
Semantics If the sender process is already known, all old command interest blocks
and all command busy blocks will be deleted. Then each command
interested in the input struct is stored and other processes interested in
these logins are informed. If this process is interested in logins of other
processes, these are also sent.
When all command interests are stored, all groups are checked for start,
rollover or stop requests. (If a group is in an error state, this state will be
reset).
The reply struct will contain only size and code.
The information, logged in processes asked for, will be sent in the
following format structs:
Code struct
HIS_ACT_LOGOUT his_login_inf
HIS_ACT_LOGIN his_login_inf
HIS_ACT_RESTORE his_restore
HIS_ACT_DEL_UNIT his_unit_del
HIS_ACT_CREATE his_grp_def
HIS_ACT_MODIFY his_grp_def
HIS_ACT_DEL_GRP his_grp_def
HIS_ACT_R_START his_grp_cmd
HIS_ACT_R_START_USR his_grp_cmd_usr
HIS_ACT_R_STOP his_grp_cmd

Code struct
HIS_ACT_R_STOP_USR his_grp_cmd_usr
HIS_ACT_R_ROLLOVER his_grp_cmd
HIS_ACT_R_ROLLOVER_USR his_grp_cmd_usr
HIS_ACT_START his_grp_cmd
HIS_ACT_STOP his_grp_cmd
HIS_ACT_ROLLOVER his_grp_cmd
HIS_ACT_RETRIEVE no messages send
The answers on the HIS_ACT_R_* request must also be of type

his_grp_cmd and his_grp_cmd_usr, the other answers must at least have
size and code.

3.2.9 Process logout
Function Delete command interest info for a process.
BUS/FAST HIS_LOGOUT
Message id.
Request struct Only size and code.
Reply struct Only size and code.
Semantics If the sender process is known, all old command interest blocks and all
command busy blocks will be deleted.
The reply struct will contain only size and code.
Errors None

3.2.10 Process reset
Function Delete all info for a process.
BUS/FAST HIS_RESET_PROC
Message id.
Request struct Only size and code.
Reply struct Only size and code.
Semantics If the sender process is known, all old command interest blocks and all
command busy blocks will be deleted. Further all locks done by this
process are cancelled. The reply struct will contain only size and code.
Errors None

3.2.11 Delete unit
Function Activate a delete units action.
BUS/FAST HIS_DEL_UNIT
Message id.
Request struct his_unit_del
Reply struct his_unit_del
Semantics First there will be a check to see if the group exists and is not locked.
Then there will be a further check to see if the unit exists for this group
and is not active. If so, all processes interested in unit deletions for this
history type are notified and the unit will be deleted.
Warning: The caller will get a reply before the unit is really deleted. The
group will be locked until the unit is really deleted. The reply struct will
be the same as the request struct.
• HIS_E_IS_LOCKED
• HIS_E_UNITACTIVE

3.2.12 Force rollover
Function Activate an extra rollover for a group.
BUS/FAST HIS_ROLLOVER
Message id.
Request struct his_grp_nr
Reply struct his_grp_nr
Semantics First there will be a check to see if the group exists and is not locked.
Second, there will be checked if there is an active unit for this group. If
so, the first process found which is interested in unit rollovers for this
history type will be informed.
Warning: The caller will get a reply before the unit is really rolledover.
If there is no interested process, the caller will get an error. All DUR
messages sent for the rollover request of a unit are:
• User request for rollover (HIS_ROLLOVER).
• Unit rollover message from HIS to interested process.
• Reply from HIS to user.
• Reply from interested process to HIS.
The group will be locked until the unit rollover is really done. The reply
struct will be the same as the request struct.
• HIS_E_IS_LOCKED
• HIS_E_UNITNOTACT
• HIS_E_NO_SERVER

3.2.13 Force rollover with user information
Function Activate an extra rollover for a group with user information.
BUS/FAST HIS_ROLLOVER_USR
Message id.
Request struct his_roll_usr
Reply struct his_roll_usr
Semantics This request has the same functionality as the HIS_ROLLOVER

request. However, with the request information about the user that
requested the rollover can be supllied. This information is stored with
the unit and can be retrieved with the HIS_INFO_UNIT_USR request or
via access to the his_unit data set.
• HIS_E_IS_LOCKED
• HIS_E_UNITNOTACT
• HIS_E_NO_SERVER

3.2.14 Get group information
Function Retrieve the information known for a group.
BUS/FAST HIS_INFO_GRP or
Message id.
HIS_INFO_GRP_NXT
Semantics If the first character of the “name” is given, the group is sought by name.
Otherwise the search is done by “grp_nr”. If the command
HIS_INFO_GRP_NXT is used, the search will be done with the “greater
than” mode, else the “greater equal” mode will be used. There will be a
check to see if a group exists.
The reply struct will contain the actual known group information.

3.2.15 Get unit information
Function Retrieve information about the units from a group.
BUS/FAST HIS_INFO_UNIT
Message id.
Request struct his_unit_inf (only element “name” or “grp_nr” must be filled, together
with the elements “start” and “stop”)
Reply struct his_unit_inf
else the search is done by “grp_nr”. There will be a check to see if the
group exists. Information of all units for this group, for which the storage
time has some overlap with the requested interval, are stored in the reply
struct at time order. (start time 0 means “from the oldest”, stop time 0
means “till the newest”). If not all information will fit in the reply buffer,
then the stop time will be corrected to the stop time of the last stored unit.

3.2.16 Get unit with user information
Function Retrieve information about the units, including user information, from a
group.
BUS/FAST HIS_INFO_UNIT_USR
Message id.
Request struct his_unit_usr_inf (only element “name” or “grp_nr” must be filled,

together with the elements “start” and “stop”)
Reply struct his_unit_usr_inf
group exists. Information of all units for this group, for which the storage
time has some overlap with the requested interval, are stored in the reply
struct at time order (start time 0 means “from the oldest”, stop time 0
means “till the newest”). If not all information will fit in the reply buffer,
then the stop time will be corrected to the stop time of the last stored unit.

3.2.17 Get process information
Function Retrieve the addresses of all known processes.
BUS/FAST HIS_INFO_PROC
Message id.
Request struct Only size and code
Reply struct his_proc_inf

Layout:
struct his_proc_inf
{
struct dur_adr proc[1];
};
Semantics The reply struct will contain the addresses of all known processes.

3.2.18 Get login information
Function Retrieve the command interest info from a logged in process.
BUS/FAST HIS_INFO_LOGIN
Message id.
Request struct his_login_inf (only element “proc” must be filled)

Layout:
struct his_login_inf
{
struct dur_adr proc;
struct his_login login[1];
};
Reply struct his_login_inf
Semantics The reply struct will contain the command interest information available
for the given process.

3.2.19 Get statistics
Function Retrieve statistics
BUS/FAST HIS_STAT
Message id.
Request struct Only size and code
Reply struct his_statistics

Layout:
struct his_statistics
{
TLS_SHORT gib_cnt; /* number of groups */
TLS_SHORT lpl_cnt; /* number of proc’s */
TLS_SHORT cib_cnt; /* ~# cmd interests */
TLS_SHORT cbb_cnt; /* outstanding cmd’s */
struct /* stat. counters */
{
TLS_ULONG grp_crt; /* group creations */
TLS_ULONG grp_del; /* group deletions */
TLS_ULONG grp_mod; /* group modify. */
TLS_ULONG schedul; /* schedule modif. */
TLS_ULONG uni_sta; /* unit starts */
TLS_ULONG uni_sto; /* unit stops */
TLS_ULONG uni_rol; /* unit rollovers */
TLS_ULONG uni_del; /* unit deletions */
TLS_ULONG msg_cnt; /* message count */
} stat;
TLS_ULONG cm_num; /* command number */
};
Semantics All statistic information will be returned.

3.2.20 Finish reply
Function Handle the “good” reply on a command to an interested process.
Reply code Same as request code
Reply struct his_grp_cmd or only size and code
Semantics This reply must be send by an application process when a request from
the history manager is handled with success. The request from the
history manager was sent, because the application process had asked for
it by its login command.
The command busy block of the sender process is searched. If this block
is not available or has another request code, the reply message is
ignored. If the correct block is found, and the action was not a start,
rollover or stop action, then the block is deleted. In the case of start,
rollover or stop the real action time from the reply struct is used to
update the internal structures and the disk files and the group is
unlocked.

3.2.21 Cancel reply
Function Handle the “error” reply on a command to an interested process.
Reply code Same as request code
Reply struct Only size and code, error bit of the code must be set
Semantics This reply must be send by an application process when a request from
the history manager is not handled with success. The request from the
history manager was sent, because the application process had asked for
it by its login command.
The command busy block of the sender process is searched. If this block
is not available or has another request code, the reply message is
ignored. If the correct block is found, and the action was not a start,
rollover or stop action, then the block is deleted. In the case of start, the
group will be declared in error state and the lock will be released. In case
of rollover, the active unit will be stopped, the group will be declared in
error state and the lock will be released. In case of stop, the active unit
will be stopped and the lock will be released.

3.2.22 Restore unit
Function Restore a unit of an existing group
BUS/FAST HIS_RESTORE
Message id.
Request struct his_grp_inf
Semantics The group is sought by “grp_nr”. It will be checked to see if the group
exists and is not locked for a delete group action. If the group name,
history type or option types are not correct, the error illegal group
characteristics is given. At least one of the two paths must also be
correct.
Furthermore the given unit and data sequence may not be zero and the
start and stop time must have the correct values. If the group has an
active unit, then that unit sequence is the high limit for the restore unit
sequence. After storing the unit record in the his_units.dat file, the
interested processes are informed.
• HIS_E_ILLGRPCHAR
• HIS_E_IS_LOCKED
• HIS_E_ILLUNITNUM
• HIS_E_ILLUNITTIM
• HIS_E_TOONEWUNIT

3.2.23 Disable “before delete” warning
Function Disable the “before delete” warning of a unit
BUS/FAST HIS_WARNING_OFF
Message id.
Request struct his_warning_off

Layout:
struct his_warning_off
{
struct his_grp_seq grp_seq;/*data seq. nr */
};
Reply struct his_warning_off
Semantics The unit is sought in the his_units.dat file. If found, the warning time is
reset. The reply struct will contain a copy of the request struct.

3.2.24 Allocate free unit
Function Allocate a unused unit in a group.
BUS/FAST HIS_FREE_UNIT
Message id.
Request struct his_grp_def (only element “name” or “grp_nr” must be filled).
group exists and is not locked. The reply will deliver a free unit number
in element “grp_seq.unit_seq” and 1 in the element “grp_seq.data_seq”.
The history manager will deliver a unit number for which no information
is present in the system. This means that normally the actual unit number
+ 1 is returned. Furthermore the history manager will not start using this
unit number. A user may create unit and data files for this unit number
and connect them to the history group by using the “restore unit”
function.
Errors • HIS_E_GROUPNOTEXI
• HIS_E_IS_LOCKED

3.2.25 Change unit information
Function Change the timing of a data unit.
BUS/FAST HIS_CHANGE_UNIT
Message id.
Request struct his_grp_inf (A complete filled “grp_def” element must be delivered,

together with the schedule elements “start” and “stop”).
Semantics With this command the start and/or stop time of a unit can be corrected.
The schedule start and stop time elements are used to specify the new
times for the unit.
Errors • HIS_E_GROUPNOTEXI
• HIS_E_ILLGRPCHAR
• HIS_E_UNITACTIVE
• HIS_E_ERROR
• HIS_E_IS_LOCKED

3.2.26 Block unit deletion temporary
Function Temporary suspends deletion of units
BUS/FAST HIS_COD_BLK_DEL
Message id.
Request struct his_blk_del
Reply struct his_blk_del
Semantics With this command deletion of units can be temporary suspended. This
may be required when, for example, an archive process copies units to a
tape.
When the “time_out” is set to a certain value (in seconds), deletion is
suspended until the time-out is elapsed or unit the time-out is set to zero
be a new command.
Errors • HIS_E_DEL_NOTBLCK
• HIS_E_DEL_BLOCKED

3.2.27 Create file name
Function Create a history file name.
Syntax [stat=] his_fname (err, path, nr, seq, ftype, fname)
Arguments TLS_BOOLEAN stat; /* (R)FALSE if error */

struct umh_context *err; /* (M)umh cont */
char *path; /* (I)Path to use */
struct his_grp_nr *nr; /* (I)Group no */
struct his_grp_seq *seq; /* (I)Seq. no */
int ftype; /* (I)Name type wanted */
char *fname; /* (M)Created file name */
Possible name types:
HIS_GRP_FNAME /* group descript. name */
HIS_UNIT_FNAME /* unit description name*/
HIS_DATA_FNAME /* unit data file name */
Semantics A file name (inclusive of path name) will be generated for the required
file type.
Errors • HIS_E_FNAMTOLONG

3.2.28 Initialize save-set selection
Function This functions initializes the creation of a save-set.
Syntax [stat=] his_bck_ini (dur, err, path, prefix, grp_fp,

uni_fp, log_fp)

struct dur_context *dur; /* (M)dur cont */
char *path; /* (I)Directory path */
char *prefix; /* (I)Save-set prefix */
struct isf_file_info **grp_fp;
/* (M)Created group file */
struct isf_file_info **uni_fp;
/* (M)Created unit file */
FILE **log_fp; /* (M)Created log file */
Semantics Before the units of groups for a time period can be selected, the selection
procedure must be initialized. The routine creates a group control file, a
unit control file and a log file. The files are created on the specified
directory. The names of the group and unit control file are preceded by
the specified prefix:
file type file name
group control file <path><prefix>grp.bck

unit control file <path><prefix>uni.bck
log file <path>hisbackup.inp
Following this routine his_bck_sel() can be called a number of times to

select the units for the save set and finally the his_bck_cls() must be
called to terminate the selection process.

3.2.29 Select units for save-set
Function This functions selects units for a save set.
Syntax [stat=] his_bck_sel (dur, err, group, start, end, grp_fp

uni_fp, log_fp, count)

char *group; /* (I)Group name */
struct ftm_time *start; /* (I)Start time */
struct ftm_time *end; /* (I)End time */
struct isf_file_info *grp_fp;
/* (I)Group file */
struct isf_file_info *uni_fp;
/* (I)Unit file */
FILE *log_fp; /* (I)Log file */
int *count /* (M)Unit count */
Semantics When the selection process has been initialized by the his_bck_ini()
routine, units for groups for a time period can be selected. Multiple calls
can be issued, for more groups or multiple time periods for a group. The
group name and time period must be specified. Information about the
selected units is written in the group and unit control files and the log file
created and initialized by the his_bck_ini() call. The number of selected
units is returned by the count argument. The his_bck_cls() must be
called to terminate the selection process.

3.2.30 Terminate save-set selection
Function This functions ends the selection of units for a save set.
Syntax [stat=] his_bck_cls (grp_fp, uni_fp, log_fp)

/* (I)Group file */
/* (I)Unit file */
FILE *log_fp; /* (I)Log file */
Semantics When all the units are selected by the his_bck_sel() routine, the selection
process is terminated by this routine. The group and unit control files
and the log file are closed.
Now the log file (an ASCII file) contains a list of all physical files to be
written to the backup medium.
Errors None

3.2.31 Initialize save-set merging
Function This functions initializes the merge of a save-set.
Syntax [stat=] his_res_ini (dur, err, path, prefix, grp_fp,

uni_fp, log_fp)

char *path; /* (I)Directory path */
char *prefix; /* (I)Save-set prefix */
struct isf_file_info **grp_fp;
/* (M)Opened group file */
struct isf_file_info **uni_fp;
/* (M)Opened unit file */
Semantics A save-set is restored from the backup medium by extracting all the files
in the save set from the backup medium. Afterwards all the units
restored must be made know to the history manager. This is called the
merging process.
The merge process is initialized by the his_res_ini() routine. This routine
opens the group and unit control file of the save-set. The directory path
and the save-set prefix must be specified.
Following this routine his_res_mrg() must be called which makes all the
units listed in the group and unit control files known by the history
manager. Finally the his_res_cls() must be called to terminate the merge
process.

3.2.32 Merge save-set
Function This functions makes the units in a save set known to the history
manager.
Syntax [stat=] his_res_mrg (dur, err, grp_fp, uni_fp)

/* (I)Group file */
/* (I)Unit file */
Semantics When the merge process has been initialized by the his_res_ini() routine,
this routine makes all the units listed in the group and unit control file
know to the history manager.
The routine reports non-fatal errors directly to UMHLOG.
The his_res_cls() must be called to terminate the merge process.

3.2.33 Terminate save-set merging
Function This functions ends the merge of a save set.
Syntax [stat=] his_res_cls (grp_fp, uni_fp)

/* (I)Group file */
/* (I)Unit file */
Semantics The merge process is terminated by this routine. The group and unit
control files are closed.
Errors None

Index
Index
A H
action type 2-4 HIS 2-1
administrator 2-3 HIS_ACT_CREATE 3-4
Allocate free unit 3-35 HIS_ACT_DEL_GRP 3-4
HIS_ACT_DEL_UNIT 2-7, 3-4
B HIS_ACT_LOGIN 3-4
backup 2-7 HIS_ACT_LOGOUT 3-4
block unit deletion 3-37 HIS_ACT_MODIFY 3-4
HIS_ACT_R_ROLLOVER 2-6, 3-5
C HIS_ACT_R_ROLLOVER_USR 2-6,
3-5
cancel group or schedule action 3-17 HIS_ACT_R_START 2-6, 3-4
cancel reply 3-32 HIS_ACT_R_START_USR 2-6, 3-5
change unit information 3-36
HIS_ACT_R_STOP 2-6, 3-5
create file name 3-38 HIS_ACT_R_STOP_USR 2-6, 3-5
create group 3-11 HIS_ACT_RESTORE 3-4
HIS_ACT_RETRIEVE 3-4
D HIS_ACT_ROLLOVER 3-4
delete group 3-13 HIS_ACT_START 3-4
delete unit 3-22 HIS_ACT_STOP 3-4
disable “before delete” warning 3-34 his_bck_cls() 2-7, 3-39, 3-40
his_bck_ini() 2-7, 3-39, 3-40
F his_bck_sel() 2-7, 3-39, 3-40, 3-41
file naming 2-5 his_blk_del 3-7
finish group or schedule action 3-15 HIS_CHANGE_UNIT 3-36
finish reply 3-31 HIS_COD_BLK_DEL 3-37
force rollover 3-23 HIS_CREATE 3-11
Force rollover with user information 3- HIS_DATA_FNAME 3-38
24 HIS_DEL_GRP 3-13
functions 3-9 HIS_DEL_UNIT 3-22
his_fname() 3-38
G HIS_FREE_UNIT 3-35
get group information 3-25 his_groups.dat 2-5
get login information 3-29 HIS_GRP_CANCEL 3-17
get process information 3-28 his_grp_cmd 3-3
get statistics 3-30 his_grp_def 3-2
get unit information 3-26 HIS_GRP_DONE 3-15
get unit with user information 3-27 HIS_GRP_FNAME 3-38
group error 2-6 his_grp_inf 3-2
group information 3-25 his_grp_nr 3-1
his_grp_seq 3-1
HIS_INFO_GRP 3-25
HIS_INFO_GRP_NXT 3-25
HISTORY/FAST Programmer’s Guide 1

Index
HIS_INFO_LOGIN 3-29 M
HIS_INFO_PROC 3-28
merge save-set 3-43
HIS_INFO_UNIT 3-26, 3-27
modify group 3-12
HIS_INFO_UNIT_USR 3-24
modify schedule information 3-14
HIS_LOGIN 3-18
his_login 3-4
his_login_inf 3-29 O
HIS_LOGOUT 3-20 option types 2-4
HIS_MODIFY 3-12
HIS_PRIO_DEF 3-6 P
HIS_PRIO_HIGH 3-6 priority 2-4
HIS_PRIO_LOW 3-6 process information 3-28
HIS_PRIO_NORMAL 3-6 process login 3-18
his_proc_inf 3-28 process logout 3-20
his_procs.dat 2-5 process reset 3-21
his_res_cls() 2-7, 3-42, 3-43, 3-44
his_res_ini() 2-7, 3-42, 3-43 R
his_res_mrg() 2-7, 3-43
restore 2-7
HIS_RESET_PROC 3-21
restore unit 3-33
HIS_RESTORE 3-33
his_restore 3-7
HIS_ROLLOVER 3-23
S
HIS_ROLLOVER_USR 3-24 scheduler 2-4
HIS_SCHEDULE 3-14 select units for save-set 3-40
his_schedule 3-2 statistics 3-30
HIS_STAT 3-30 storage unit 2-2
his_statistics 3-30 structs 3-1
his_unit_del 3-6
HIS_UNIT_FNAME 3-38 T
his_unit_inf 3-6, 3-7 terminate save-set merging 3-44
his_units.dat 2-5 terminate save-set selection 3-41
HIS_WARNING_OFF 3-34
his_warning_off 3-34 U
HISBCK 2-1 unit information 3-26
HISDBG 2-1 unit with user information 3-27
HISRECOVER 2-2
HISRES 2-2
history type 2-4
HISWRN 2-2
I
initialize save-set merging 3-42
initialize save-set selection 3-39
L
locking 2-6
login information 3-29
2 HISTORY/FAST Programmer’s Guide

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Manual ISF Programmer’s Guide
IM50F02F02-01EN/R10.03

IM50F02F02-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction to ISAM ..........................................................1-1
1.1 What is ISF ................................................................1-1
1.2 Design consideration .................................................1-1
1.3 X/OPEN definitions ...................................................1-2
2 Data types ..............................................................................2-1
2.1 Overview ...................................................................2-1
2.2 CHARTYPE ..............................................................2-2
2.3 INTTYPE and LONGTYPE ......................................2-2
2.4 FLOATTYPE and DOUBLETYPE ..........................2-3
3 Indexing .................................................................................3-1
3.1 Index definition and manipulation .............................3-1
3.2 Index compression .....................................................3-3
4 Locking ..................................................................................4-1
4.1 Overview ...................................................................4-1
4.2 Locking on file level ..................................................4-1
4.2.1 Exclusive file locking ............................................... 4-1
4.2.2 Manual file locking ................................................... 4-1
4.3 Record level locking ..................................................4-2
4.3.1 Automatic Record Locking ....................................... 4-2
4.4 Manual record locking ...............................................4-3
5 Remote database access ......................................................5-1
5.1 Remote database access .............................................5-1
6 Reference ...............................................................................6-1
6.1 Call specifications ......................................................6-1
6.1.1 Return value/Error indication ................................... 6-1
6.1.2 isam.h and isf.h header files ...................................... 6-1
6.1.3 Key Structure ............................................................ 6-2
6.1.4 Record number of last call ........................................ 6-3
6.1.5 Current record position ............................................. 6-3
6.2 ISF routines ................................................................6-4
ISF Programmer’s Guide iii

6.2.1 Add index to ISAM file ............................................ 6-4
6.2.2 Create ISAM file with one index .............................. 6-6
6.2.3 Close an ISAM file ................................................... 6-8
6.2.4 Create ISAM file with multiple indexes ................... 6-9
6.2.5 Delete current record ............................................... 6-11
6.2.6 Delete record specified by primary key ................. 6-12
6.2.7 Delete index ............................................................ 6-13
6.2.8 Delete record specified by record number .............. 6-14
6.2.9 Delete an ISAM file ................................................ 6-15
6.2.10 Define flow control ................................................. 6-16
6.2.11 Get information about index ................................... 6-17
6.2.12 Lock an ISAM file .................................................. 6-18
6.2.13 Open an ISAM file .................................................. 6-19
6.2.14 Open an event monitoring channel ......................... 6-21
6.2.15 Read a record .......................................................... 6-22
6.2.16 Unlock manually locked records ............................. 6-24
6.2.17 Rename an ISAM file ............................................. 6-25
6.2.18 Rewrite current record ............................................ 6-26
6.2.19 Rewrite record located by number .......................... 6-27
6.2.20 Rewrite record located by key ................................ 6-28
6.2.21 Set an event request ................................................. 6-29
6.2.22 Select an index ........................................................ 6-31
6.2.23 Delete an ISAM file ................................................ 6-34
6.2.24 Unlock an ISAM file ............................................... 6-36
6.2.25 Open or create an ISAM file ................................... 6-37
6.2.26 Rename an ISAM file ............................................. 6-41
6.2.27 Insert new record, and mark as current .................. 6-43
6.2.28 Insert new record ..................................................... 6-44
Appendix A Examples .................................................................. A-1
A.1 Building a file .......................................................... A-1
A.2 Adding data .............................................................. A-2
A.3 Sequential access ..................................................... A-4
A.4 Random access ......................................................... A-6
Appendix B UNIX and Windows specific information ...............B-1
B.1 Not Supported ISF Routines and Features ................B-1
B.2 Restrictions on ISF Routines and Features ...............B-2
B.3 ISAM files .................................................................B-2
iv ISF Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives
• Provide application programmers with an overview of the
functionality of DATABASE/FAST.
• Provide experienced users with a reference to DATABASE/FAST
usage.

This manual is intended for programmers who are familiar with the
language C.
The reader is assumed to have knowledge of BUS/FAST, especially the
Message passing principle (DUR) and the Unsolicited Message Handler
(see 0.4 Associated documents).

• Chapter 1 introduces the reader to the functionality, features,
environment of Indexed Sequential Files access.
• Chapter 2 the allowed data types.
• Chapter 3 describes how indexing is integrated.
• Chapter 4 describes the locking mechanism.
• Chapter 5 describes the remote database access facilities.
• Chapter 6 is a reference guide. Conventions and error handling is
described. Routine syntax is summarized in alphabetical order.
ISF Programmer’s Guide 0-1


1 BUS/FAST Programmer’s Guide consisting of the following
volumes:
- DUR Programmer’s Guide
- UMH Programmer’s Guide
which are used.
- FSL Programmer’s Guide
software.
2 The C Programming Language
By Brian Kernighan and Dennis Ritchie.
This manual is referred to when programming rules are mentioned.
3 X/OPEN portability guide
Volume 5, Indexed Sequential Access Method (ISAM).

CONVENTION MEANING
() Parentheses when used in routine syntax
indicates a list of arguments that need to be
passed.
DUR_NOWAIT.
input.
0-2 ISF Programmer’s Guide

returns.
output.
literally.
n.u. not used.
a terminal.
from the user.


What is ISF Introduction to ISAM
1 Introduction to ISAM
1.1 What is ISF

The input/output facilities supported by most operating systems consist
only of byte stream read and write operations on files. No facilities are
provided for operating on files, as sets of records. This leads to
application writers having to make their own arrangements for record
handling, resulting in both a multiplication of effort and a proliferation
of non-standard methods.
Data management is a key element in the integration of applications.
Applications, written in a variety of languages, must be able to work on
the same basic data given in the data entry-form. And data must be
passed easily and efficiently between applications.
As a first step towards addressing these issues, an interface has been
defined for the creation, management and manipulation of indexed files,
generally known as the Indexed Sequential Access Method (ISAM). The
availability of this interface on systems will not only provide application
portability, but will ease and encourage integration.
The FAST brick ISF (Indexed Sequential File access) is based on these
ISAM definitions.
1.2 Design consideration

In order to keep applications, using the ISF brick, portable the
conventions as defined by the X/OPEN Group were chosen. They have
fully defined a portable ISAM functionality.
The formation of the X/OPEN Group represents a major initiative by an
international group of suppliers of computer systems to create a free and
open market. Offering Independent Software Vendors (ISVs) as wide a
market as possible for their products. As well as giving users an
increased return on investment in application software.
The objective shared by members of the X/OPEN Group is to establish
a Common Applications Environment to the mutual advantage of users.
That is to say, Independent Software Vendors and computer suppliers.
Applications written to operate in this environment will be portable at

Introduction to ISAM X/OPEN definitions
the source code level to a wide range of machines. Thereby releasing the
user from dependence on a single supplier. Reducing the necessary
investment in applications, considerably increasing the market for
independent software and opening up the market for systems suppliers.
The existence of these “Open Systems” allows users to mix and match
systems from different suppliers. Also the ability to move applications
between machines to meet changing requirements as business grows.
Thereby giving protection of investment in applications software into
the future.
1.3 X/OPEN definitions

As stated before, the software brick ISF is a layer upon the X/OPEN
definitions. The reason for this layer is the fact that these routines do not
support UMH error logging facilities. In order to be able to integrate a
foreign ISAM package into the FAST environment, ISF was designed.
Consequently, the functionality of ISF is identical to the one defined by
X/OPEN.
The X/OPEN ISAM definition specifies a set of C-language functions
that create and manipulate indexed files.
These functions provide for:
• the creation of files and associated primary indexes
• the addition, and deletion, of further indexes
• the opening, closing and deletion of existing files
• the selection of the index to be used for subsequent reading and/or
writing of records, and the start point within the file
• the reading, writing and updating of data records
• the locking and unlocking of files and records
When a file is created, two conceptual entities are formed, the container
for holding data records and a primary index. The programmer can
specify the field, or fields for each record that is to be used as the primary
key for distinguishing the records within the file. As each record is
written to the file, an entry is made in the index which stores key value(s)
together with the location of the data record in the file. For subsequent
reads on the file, individual records are located by searching the index
for the required key and using the location stored with it to go straight to
the data. Access to a file can be sequential or random.

X/OPEN definitions Introduction to ISAM
Indices additional to the primary index can be created. These provide

alternative access paths to the same data records by allowing different
fields to be used as the keys. The definition puts no limit on the number
of alternative indexes that can be created for a file. In an additional
index, the same key value is allowed to occur in different records,
“duplicates”, although a facility is provided to inhibit this on any
particular file.
The definition includes the facility to specify index key compression.
This allows the density of key storage in an index to be increased, by the
use of such techniques as suppression of redundant spaces at the
beginning and end of keys and by the elimination of duplicate entries.
Only no compression and maximum compression are fully defined.
However, it is recognized that intermediate levels may be provided on
any particular member system, and mode values are defined to allow for
this. All X/OPEN systems will accept these values to ensure application
portability, although the degree of resulting compression may vary.
Facilities are defined for the locking of files and records, to ensure
reliable update and access in the multi-user environment. File locking
locks out a whole file. It may be exclusive, in that all other accesses to
the file are inhibited, or it may be write-only, allowing read accesses to
continue. Record level locking may be automatic. In this case it is
specified at file open time and a record is automatically locked before it
is read, and remains locked until the next function call is completed.
Alternatively, it may be manual in that it is activated as a result of a
parameter in a read call.

Introduction to ISAM X/OPEN definitions

Overview Data types
2 Data types
2.1 Overview
The types of data that can be defined and manipulated are described in
this chapter. Descriptions of how each data type is stored in files and
how each data type must be treated are also included.
The following types are defined in isam.h:
CHARTYPE character
INTTYPE 2-byte integer
LONGTYPE 4-byte integer
FLOATTYPE machine float
DOUBLETYPE machine double
These data types are not supported as key data types by our
implementation. The reason for not implementing this, is that most
underlying systems do not support this feature. Moreover, the benefit of
using types other than chartype is dubious.
As all types are treated as chartypes, it is necessary to have a proper
definition of how the various types are stored in a record. Suppose e.g.
that the key consists of an inttype and the index is supposed to be
ascending. As the value in the record is stored as characters, it depends
on the system whether or not the most significant bytes are stored first,
hence it will be unpredictable if the indexing order really will be
ascending.
In order to solve this, X/OPEN has laid down a definition of how each
of these types must be stored. Integer data e.g. is always stored in files
as high/low, most significant byte first, least significant byte last. This
storage technique is independent of the form in which integers are stored
in the machine on which the system is executing. Therefore, depending
on the operating environment, the format of storage for integers in the
files may differ from the format of storage for integer stored in executing
programs.
For this purpose the programmer has a number of macro definitions
available which are describes in the sections to follow.

Data types CHARTYPE
2.2 CHARTYPE
The data type CHARTYPE comprises a string of characters, for example
a city name or an address. Obviously, no conversion routines are
necessary for these types.
2.3 INTTYPE and LONGTYPE

The data types INTTYPE and LONGTYPE consist of 2- and 4-byte
binary signed integer data. Four routines are supplied for the conversion
to and from ISAM integer storage format.
The four format conversion routines for integers are:
• ldint(p)
returns a machine-format integer; p is a char pointer to the starting
byte of format INTTYPE.
• stint(i,p)
stores a machine-format integer i as format INTTYPE at location p,
where p is a char pointer to the first byte of format INTTYPE.
• ldlong (p)
returns a machine-format long integer; p is a char pointer to the first
bye of format LONGTYPE
• stlong(l,p)
stores a machine-format long integer l as format LONGTYPE at
location p, where p is a char pointer to the first byte of format
LONGTYPE.
These routines are macros defined in isam.h.
The typical use for the above routines occurs after a data record has been
read into the user buffer. Integer values that are to be used by the user
program first have to be converted to machine-usable format by using
ldint() for type INTTYPE and ldlong() for LONGTYPE.
Similarly, storage of machine-format integer data requires the use of the
stint() and stlong() routines.
Note: Formatted integers need not be aligned
along word boundaries as do machine-
formatted integers.
Note: When a file is opened with the isf_uopen()
routine with the format specifier filled,

FLOATTYPE and DOUBLETYPE Data types
these format convertion routines should

not be used.
2.4 FLOATTYPE and DOUBLETYPE

The data types FLOATTYPE and DOUBLETYPE are two floating
point data types. The data type FLOATTYPE is the same as the C data
type float, while the data type DOUBLETYPE is the same as the C data
type double. Both data types differ in length and format from machine
to machine. There is no difference between the floating point format
used and its counterpart in the C language except that floating point
numbers may be placed on non-word boundaries. For this reason, four
more routines, allow the user to retrieve or replace these non-aligned
floating point numbers from their positions in data records. These
routines are:
• ldfloat(p)
returns a machine-format float; p is a char pointer to the starting
byte of format FLOATTYPE
• stfloat(f,p)
stores a machine-format float f at location p, where p is a char
pointer to the starting (leftmost) byte of format FLOATTYPE
• lddb(p)
returns a machine-format double; p is a char pointer to the starting
byte of format DOUBLETYPE
• stdb(d,p)
stores a machine-format double d as format DOUBLETYPE at
location p, where p is a char pointer to the starting (leftmost) byte
of format DOUBLETYPE
The use of the floating point load and store routines is analogous to the
use of the integer load and store routines.
Note: When a file is opened with the isf_uopen()
routine with the format specifier filled,
these format convertion routines should
not be used.

Data types FLOATTYPE and DOUBLETYPE

Index definition and manipulation Indexing
3 Indexing
3.1 Index definition and manipulation

The C language structure that describe an index to any given function
call are the keydesc and keypart structures. These structures are shown
below. They are defined in the file isam.h, which must be included in
any program which uses the function calls.
The structure keydesc contains the following members:
short k_flags; /* compression and duplicates */
short k_nparts; /* nr of parts in key */
struct keypart k_part[NPARTS];/* each key part */
The structure keypart contains the following members;
short kp_start; /* starting byte of key part */
short kp_leng; /* length in bytes of key part*/
short kp_type; /* type of key part */
It is the purpose of this chapter to show how to initialize the keydesc
structure for use with any of the functions that require it as a parameter.
The first sample index to be described here has one part which has the
data type of INTTYPE. Integers are 2 bytes; therefore, the length of the
index is 2 bytes. The index begins in the first byte of the record. No data
compression is desired for keys stored in this index. The order of the
index is to be ascending (lowest key value to highest key value). Finally,
duplicate key values for this index are not to be allowed.
The following C program creates an ISAM file with the index described
above.
#include <isf.h>/* Includes isam.h */
main()
{
struct keydesc first_key;
struct isf_file_info *fdesc;
first_key.k_flags = 0; /* no dups, no
compression */
first_keyk_nparts = 1; /* index has one part */
/* The starting byte of an index is always defined as
the byte offset from the beginning of the record.
Since this index begins at the beginning of the
record, its byte offset is zero: */

Indexing Index definition and manipulation
first_key.k_part[0].kp_start = 0;
/* offset */
first_key.k_part[0].kp_leng = 2;
/* Length 2 bytes */
first_key.k_part[0].kp_type = 0;
/* TYPE not supported */
if ((fdesc = isf_build (err_cont,”myfile”,
84,&first_key,
ISINOUT | ISEXCLLOCK))
== NULL)
{
umh_log(err_cont);
exit (BADEXIT);
}
...
} /* end main */
Note that, in the above example, the structure element k_flags is
initialized to zero. This indicates that no special characteristics are to be
attributed to this index. Since k_flags is zero, duplicate key values will
not be allowed, and no compression will be performed on key values as
they are placed in the index.
If duplicate key values have to be allowed, k_flags should have been
initialized to ISDUPS as in the following statement:
first_key.k_flags = ISDUPS; /* allow duplicate key
values */
If key value compression had been desired, k_flags should have been
initialized to ISDUPS | COMPRES. This would allow duplicate key
values and would indicate that they should be compressed in the index.
first_key.k_flags = ISDUPS | COMPRESS;
Note, also, that the index defined by the keydesc structure first_key has
only one part. The number of keyparts that make up the index is defined
by the structure element k_nparts, which in the above example is
initialized to one.
first_key.k_nparts = 1; /* index has one part */
In the previous example, the index defined had only one part. That part
had a data type of INTTYPE. However, a particular application could
require that a multi-part index be used. Within the keydesc structure
there exists an array of keypart structures. Each keypart structure defines
one part of the index. It holds the starting byte offset from the beginning
of the record, the part’s length, and the part’s data type. In order for a
multi-part index to be described, the user’s program must initialize each

Index compression Indexing
of these structures to reflect the desired position, length, and data type
for each index part.
The structure keypart contains the following members:
short kp_start; /* starting byte */
short kp_leng; /* length in bytes */
short kp_type; /* type (not used) */
3.2 Index compression

This section discusses key value compression. This allows the density of
key storage in an index to be increased by the use of such techniques as
suppression of redundant spaces at the beginning and end of keys and the
elimination of duplicate entries.
Using these techniques, significant savings can be made in disc space,
and substantial improvements obtained in response to random access
requests.
Different levels of compression may be available on different
machines.To allow for this, the X/OPEN definition is non-specific, but
ensures that applications will run across X/OPEN systems without
change.
Two levels of space compression are defined: no compression and
maximum compression. The latter calls for the maximum level of space
compression available on the machine on which the application is
running. The levels apply to each index individually.
In addition, an application can specify whether duplicates are to be
allowed for each index.
Duplicates are allowed by setting the value ISDUPS into the k_flags
field of the keydesc structure for a given index, and are inhibited by the
value ISNODUPS. (As no default value is defined, either ISDUPS or
ISNODUPS must be defined). Space suppression is specified by a
logical OR of COMPRESS to ISDUPS or ISNODUPS. All other values
in the k_flags field are implementation defined, but the X/OPEN system
will accept such values as advisory (i.e. applications will not fail, but the
level of compression obtained may vary from machine to machine).

Indexing Index compression

Overview Locking
4 Locking
4.1 Overview
Two levels of locking are defined; file level locking and record level
locking. Both are built on the System V lock features. Within these two
levels there are several methods. The user can choose the one which best
suits application requirements.
4.2 Locking on file level
4.2.1 Exclusive file locking
File locking may be accomplished in two ways. One method prevents

other processes ‘reading from’ or ‘writing to’ a given file. This method
is referred to as an exclusive lock and remains in effect from the moment
the file is opened, using isf_open() or isf_build(), until the file is closed
using isf_close(). Exclusive file locking is specified when
ISEXCLLOCK is logically ORed with the mode parameter of the
isf_open() or isf_build() function call.
Exclusive file level locking is not necessary for most situations, but it
must be used when an index is being logically ORed using
isf_addindex() or when an index is being deleted using isf_delindex().
The skeleton program shown below illustrates how exclusive file level
locking is done:
myfd = isf_open("myfile",ISEXCLLOCK | ISINOUT);
.
.
.
isf_close(myfd);
4.2.2 Manual file locking
Manual file level locking prevents other processes from writing to a

given file but allows them to read the locked file. This kind of file

Locking Record level locking
locking is specified by use of the isf_lock() and isf_unlock() function

calls. When a file is to be locked in this manner, ISMANULOCK must
be logically ORed with the mode parameter of the isf_open(), isf_create
or isf_build() call. Later in the program, when locking is desired,
isf_lock() should be called to lock the file. When the file is to be
unlocked, isf_unlock() should be called.
Note: The isf_lock() and isf_unlock() routines are
not supported on all system.
4.3 Record level locking

There are two basic types of record level locking: automatic and manual.
Automatic record locking locks a record just before it is read using the
isf_read() call. It unlocks the record after the next call has completed.
Automatic record locking is used when the user wants to lock one record
at a time and is unconcerned about when or for how long that record will
be locked.
Manual record locking, on the other hand, can lock any number of
records. Manual locking locks a record when that record is read using
isf_read(). It unlocks that record, and any other records that are currently
locked, when isf_release() is called. Manual record locking is used when
more control is required over when a record, or set of records, is to be
locked and unlocked.
Both automatic and manual locking techniques allow other processes to
read records locked by the current process, but they may not lock, re-
write, or delete them.
4.3.1 Automatic Record Locking
Automatic record locking must be specified when the file is opened.

This is done when ISAUTOLOCK is ORed with the mode parameter of
the isf_open(), isf_create() or isf_build() function call. From when the
file is opened until it is closed, every record will be locked automatically
before it is read. Each record remains locked until the next function call
is completed for the current file. Therefore, while using the automatic
record locking mechanism, only one record per file may be locked at a
given time.
The following illustration shows how automatic record locking is used:

Manual record locking Locking
myfd = isf_open("myfile",ISINOUT | ISAUTOLOCK);

.
.
.
isf_read(MYFD, MYRECORD, ISNEXT);
. /* record locked here */
. /* before record is read*/
.
isf_rewcurr(myfd,myrecord);
. /* record unlocked here */
. /* after completion */
.
isf_close(myfd);
4.4 Manual record locking

The user’s intention to use manual record locking must be specified
before any processing takes place. This is done when ISMANULOCK
is ORed with the mode parameter in isf_open(), isf_create() or
isf_build() function calls when the file is opened. After the file is open,
if the user wishes a record to be locked, ISLOCK must be ORed with the
mode parameter of the isf_read() function call that is reading that record.
Each and any record that is read in this manner remains locked until they
are all unlocked by a call of the isf_release() function. The number of
records that may be locked in this manner at any one time is system
dependent.

Locking Manual record locking

Remote database access Remote database access
5 Remote database access

This chapter describes the remote database access facilities offered by
DATABASE/FAST and is divided into two sections:
• A tutorial introducing the reader to the remote database access

facilities offered by DATABASE/FAST.
• A reference guide in which the routines providing the remote
database access facilities are described.
5.1 Remote database access

DATABASE/FAST provides facilities enabling the program to access
databases located on a BUS/FAST node not being the node the program
is running on. These facilities are implemented by means of callable ISF
routines. These routines are:
• isf_uopen() to open or create a remote database.

• isf_uerase() to delete a remote database.
• isf_urename() to rename a remote database.
These routines establish communications with a remote database server

performing the actual database access on the remote node. Commands
and data are transported to and from the remote database server by
means of the message passing facilities offered by BUS/FAST. Data
conversions are handled by the DATABASE/FAST run-time system
(isf_*() routines and the remote database server, isfserver).
Note that the same routines can also be used to open databases locally,
so it is not necessary to use separate calls for remote and local databases.
However it is dangerous to mix the remote routines with non-remote
calls on the same databases since this can give unpredictable results. As
a result it is always preferable to use isf_uopen().
The isf_uopen() routine replaces the isf_open and isf_create() routines

offering the following advantages:
• Local and remote database access. The isf_uopen() routine can be

used to open both local and remote databases.
• Database creation. A flag can be given to isf_uopen() to create the

Remote database access Remote database access
database before it is opened.

• System and key conversions. A format string can be supplied to the
isf_uopen() routine. System and key conversions are done
automatically by the run-time system eliminating the usage of the
st*() and ld*() routines (for example, the stlong() and ldlong()
routines). The DATABASE/FAST Data Dictionary Language
(DDL) can be used to describe a database. The DDL compiler can
produce the parameters (format string) required by the isf_uopen()
routine.

Call specifications Reference
6 Reference
6.1 Call specifications

This chapter contains detailed descriptions of the ISF ISAM functions.
The following general notes apply throughout.
6.1.1 Return value/Error indication
Most calls return either TRUE or FALSE as the value of the function. In
the case of FALSE additional information is passed in the UMH context.
In the case of isf_build() or isf_open(), the return value will be a legal
file descriptor or a NULL. A NULL indicates that an error has occurred,
and that additional information is found in the UMH context.
ISF always returns errors with severity E. These errors are found in each
routine description. Information may be added with severity I, which is
not described explicitly with the routine: this information is not intended
to test on, merely to give history information.
As mentioned before, ISF uses an ISAM routine set, which either is
based on the Operating System’s file primitives or special primitives for
FAST/TOOLS. In the former case, only iserrno values are returned by
this routine set. In the latter case, however, besides the iserrno values
also ISF errors may be returned. These errors can be recognized by the
fact that these errors always have fatal severity.
The application, using ISF does not have to deal with these: they are
handled by ISF. An error with severity E is added as described in this
manual.
6.1.2 isam.h and isf.h header files
Some parameters in this chapter are declared to be structure types that

are defined in the isam.h header file or in the isf.h. These files contain
definitions of structures that are used in the calls.
Definitions that specify limits give the limit that can be assumed by
applications for full portability across X/OPEN machines.
For example, NPARTS gives the maximum number of key parts, and is
set to 8. This means that all X/OPEN systems allow at least 8 key parts.

Reference Call specifications
It also means that, for full portability, an application should not require
more than this number.
It is recommended to take notice of the contents of the isam.h and isf.h
files.
6.1.3 Key Structure
The structures keydesc and keypart, defined in isam.h, are used for index
definition and are further explained below:
The structure keydesc contains the following members:
struct keydesc
{
short k_flags; /* flags */
short k_nparts; /* number of parts in key */
struct keypart k_part[NPARTS]; /* each key part */
}
The structure keypart contains the following members:
struct keypart
{
short kp_star /* starting byte of key part */
short kp_leng; /* length in bytes */
short kp_type; /* type of key part */
}
In the keydesc structure, the integer k_flags is used to hold duplicate and
compression information for the index that is being added, deleted or
selected. The symbolic values that are defined in isam.h should be used
to indicate the compression techniques that are desired. If more than one
feature is specified, the values are logically ORed together. The meaning
of these symbolic values are:
ISDUPS Duplicate values are allowed for this index
ISNODUPS No duplicates
COMPRESS Full compression for this index
One of ISDUPS and ISNODUPS must be specified. Compression is
requested by the addition of COMPRESS.
k_nparts is an integer that indicates how many parts make up the index.
These parts must be described in the k_part array of keypart structures.
A keypart structure defines each part of the index individually. The
number of elements in the k_part array should be equal to the integer
value in k_nparts.

Call specifications Reference
The elements in the keypart structure are used as follows. kp_start

indicates the starting byte of the key part that is being defined. kp_leng
is a count of the number of bytes in the part, and kp_type designates the
data type of the part. The types allowed are defined in the header file,
isam.h. If this part of the key is in descending order, the type constant
should be ORed to the ISDESC constant (defined in isam.h). Values in
the kp_type field that are not zero are actually not supported by any of
the operating systems. For more information about creating and
manipulating indexes, see Chapter 3, “Indexing”.
6.1.4 Record number of last call
Isrecnum is a 4-byte field that is set following the successful completion

of all record-based calls. It identifies, in an implementation-dependent,
shorthand way, the record just referenced. This returned value may be
used as input to the isf_delrec(), isf_read(), and isf_rewrec() calls to
perform optimized deletes, reads, and updates. If used to perform
sequential processing, the records will be read according to their
physical layout on disc, and not according to any logical key order. Note
that as the actual value returned is implementation-dependent, the user
should not attempt to interpret its actual value, as this could compromise
portability.
The following calls set isrecnum:
isf_delcurr()
isf_delete()
isf_delrec()
isf_read()
isf_rewurr()
isf_rewrec()
isf_rewrite()
isf_start()
isf_wrcurr()
isf_write()
6.1.5 Current record position
The current record position should not be confused with isrecnum (see
above). The current record position (which is a member of struct
isf_file_info) allows sequential processing to be performed according to
a logical key order. The mode parameters ISNEXT and ISPREV are thus
always relative to this value, while ISCURR indicates that this (the
current) record should be read. If the current record is deleted (by using

Reference isf_addindex()
isf_delcurr()), the current record position will not change and will
continue to indicate the currently deleted record. The current record may
be rewritten directly using isf_rewcurr().
The current record position is set after the successful completion of the
following calls:
isf_open()
isf_read()
isf_start()
isf_wrcurr()
and used in input to:
isf_delcurr()
isf_read()
isf_rewcurr()
6.2 ISF routines
6.2.1 Add index to ISAM file
Syntax [stat=] isf_addindex(err_cont,fdesc, keydesc)
Arguments TLS_BOOLEAN stat; /* (R)TRUE if success */

struct umh_context *err_cont;/*(M)Used for error logging
*/
int *fdesc; /* (M)File description */
struct keydesc *keydesc; /* (I)Key description */
Semantics The routine isf_addindex() is used to add an index to an ISAM file. The
index will be built for the file indicated by the fdesc parameter and will
be defined according to the information in the keydesc structure. This
call will execute only if the file has been opened for exclusive access.
There is no limit to the number of indexes that may be added through the
isf_addindex() call. However, the maximum number of parts that may
be defined for an index is NPARTS, and the maximum number of bytes
that can exist in an index is MAXKEYSIZE (see the isam.h).
Notes • This routine is not supported on all systems (portability!). See the
appropriate appendix for more information.

isf_addindex() Reference
Errors • ISF_E_FILE_ERR
This message is added to an ISAM error.
Related Routines
Errors • isf_create()
This routine creates an ISAM file with multiple indexes.

Reference isf_build()
6.2.2 Create ISAM file with one index
Syntax fdesc = isf_build (err_cont, filename, recordlength,

keydesc, mode)
Arguments struct isf_file_info fdesc; /* (R)File descriptor */

struct umh_context *err_cont;/*(M)Used for error
logging */
char *filename; /* (I)File to be created */
int recordlength; /* (I)Record length in
bytes */
struct keydesc *keydesc; /* (I)Key descriptions */
int mode; /* (I)Creation mode */
Semantics The routine isf_build() is used to create an ISAM file. This call will
create and initialize appropriate disc structures to contain data and
indexes.
After isf_build() has completed successfully, the file will remain open
for further processing. The isf_build() function returns a file descriptor
fdesc in which file context is stored. If an error is encountered, NULL is
returned.
The filename parameter should contain a null-terminated character
string of which the maximum size is ISF_MAXFILENAME (see isf.h).
The recordlength parameter is the length of the record. Its value is the
sum of the number in bytes in each field of the record. See Chapter 2,
“Data types” for the length of each data type.
All ISAM files are required formally to have a primary index. The
keydesc parameter of this call is used to specify the structure of the
primary index. Setting k_nparts = 0 is not allowed. Additional indexes
may be added later using isf_addindex(). See Appendix A “Examples”
for more details on key definition and use.
The mode parameter is used to specify locking information. The user has
three options:
• manual
• automatic
• exclusive
Selecting the manual option indicates that the user wishes to be
responsible for locking records at the appropriate times. Using either the
isf_lock() and isf_unlock() calls or the ISLOCK modeflag of the
isf_read() call and the isf_release() function call.
Selecting automatic locking indicates that the user wishes to lock each

isf_build() Reference
record at the time it is read and unlock each record after the next function
call is made. Selecting exclusive locking will deny file access to anyone
other than this process. More information about locking can be found in
Chapter 4, “Locking”. The mode is specified by using the define macros
that are found in the header file isam.h.
Modes that are used in the isf_build() call are:
one or none of these Logically ORed with one of these:
ISEXCLLOCK ISINPUT
ISMANULOCK ISOUTPUT
ISAUTOLOCK ISINOUT
This message is added to an ISAM error. See description in section
Return value/error indication in SubSection 6.1.1.
Related Routines
Errors • isf_create()
This routine creates an ISAM file with multiple indexes.

Reference isf_close()
6.2.3 Close an ISAM file
Syntax [stat=] isf_close(err_cont,fdesc)
Arguments TLS_BOOLEAN stat; /*(R) TRUE if success */

struct umh_context *err_cont; /*(M) Used for error
logging */
struct isf_file_info *fdesc; /*(M) File descriptor */
Semantics The routine isf_close() is used to close an ISAM file. Any locks that are
held for the file by the process issuing the isf_close() call are released.
This function also closes all open event requests for an ISAM file.
Notes • It is mandatory to close ISAM files after processing has finished.

Failure to do so could cause unpredictable results.
• This routine is not supported on all systems (portability!). See the

isf_create() Reference
6.2.4 Create ISAM file with multiple indexes
Syntax fdesc = isf_create(err_cont,filename,recordlength,

n_keys,keydesc,mode)
Arguments struct isf_file_info *fdesc; /*(R) File descriptor */

logging */
char *filename; /*(I) File to be
created */
int recordlength; /*(I) Record length in
bytes */
int n_keys; /*(I) Number of keys */
struct keydesc *keydesc; /*(I) Key descriptor
array */
int mode; /*(I) Creation mode */
Semantics The routine isf_create() is used to create an ISAM file with one or more
indexes. This routine is used instead of an isf_build() followed by a
number of isf_addindex() calls. Note using isf_create() should be
avoided and it is preferable to use the isf_uopen() routine instead, since
it offers remote database functionality and is completely compatible
with the equivalent local node version.
This call will create and initialize appropriate disc structures to contain
data and indexes.
After isf_create() has completed successfully, the file will remain open
for further processing. The isf_create() function returns a file descriptor
fdesc in which file context is stored.
The filename parameter should contain a null-terminated character
string of which the maximum size is ISF_MAXFILENAME (see isf.h).
The recordlength parameter is the length of the record. Its value is the
sum of the number of bytes in each field of the record. See Chapter 2,
“Data types” for the length of each data type.
The keydesc parameter is used to specify the structure of the key
indexes. For each additional key, n_keys must be incremented and a key
description must be added to the keysdesc array. Setting n_keys = 0 is
not allowed. See Appendix A “Examples” for more details on key
definition and use.
The mode parameter is used to specify locking information. The user has
three options:
• manual

Reference isf_create()
• automatic
• exclusive
responsible for locking records at the appropriate times using either the
isf_lock() and isf_unlock() calls or the ISLOCK modeflag of the
isf_read() call and the isf_release() function call.
Selecting automatic locking indicates that the user wishes to lock each
record at the time it is read and unlock each record after the next function
call is made. Selecting automatic locking will deny file access to anyone
other than this process. More information about locking can be found in
Chapter 4, “Locking”. The mode is specified by using the define macros
that are found in the header file isam.h.
Furthermore it is possible to specify whether writing a record should be
deferred, if this feature is available for your system. This means that
each time a record is written, it is not actually written to disk but
buffered for a time to save on overhead.
Modes that are used in the isf_build() call are:
one or none of these added arithmetically to one of these:
ISEXCLLOCK ISINPUT
ISMANULOCK ISOUTPUT
ISAUTOLOCK ISINOUT
ISF_DEF_WRT
Notes • This routine is not defined by X/OPEN. It is ISF specific. The

reason for developing this routine was to allow for files with
multiple indexes to be created on systems that do not support
isf_addindex().
Related Routines
Errors • isf_build()
This routine creates an ISAM file with one index only.

isf_delcurr() Reference
6.2.5 Delete current record
Syntax [stat=] isf_delcurr(err_cont,fdesc)

struct umh_context *err_cont; /* (M)Used for error
logging */
struct isf_file_info *fdesc; /* (M)File description */
Semantics The routine isf_delcurr() differs from isf_delete() in that it deletes the
current record from the file, rather than the record indicated by the
primary key. The appropriate values will be deleted from each index that
is defined. This call is useful when the primary key is not unique and the
record cannot be located and deleted in one call. Isrecnum is set to
indicate the current record, (the record just deleted), whose position is
left unchanged.
Errors • ISF_E_LOCKED
Record or file locked
• ISF_E_FILE_ERR
Related Routines
Errors • isf_delete()
Deletes the record pointed to by the primary key
• isf_delrec()
Deletes a record by number

Reference isf_delete()
6.2.6 Delete record specified by primary key
Syntax [stat=] isf_delete(err_cont,fdesc,record)

struct umh_context *err_cont; /* (M)Used for error
logging */
struct isf_file_info *fdesc; /* (M)File descriptor */
char *record; /* (I)Record with primary
key */
Semantics The routine isf_delete() deletes the record specified by a unique primary
key from the file indicated by fdesc. The appropriate values will also be
deleted from each index. If the primary index allows duplicates, the
isf_read() and isf_delcurr() should be used instead. Isrecnum is set to
indicate the record just deleted, while the current record position is left
unchanged.
• ISF_E_FILE_ERR
Related Routines
Errors • isf_delcurr()
Deletes the current record
• isf_delrec()
Deletes a record by number

isf_delindex() Reference
6.2.7 Delete index
Syntax [stat=] isf_delindex(err_cont,fdesc,keydesc)

logging */
struct keydesc *keydesc; /*(I) Key descriptor */
Semantics The routine isf_delindex() is used to remove an existing index. The

index will be removed from the file indicated by fdesc. The index to be
removed will be defined by the information in the keydesc structure. All
indexes may be deleted except the primary index. Attempts to delete the
primary index will cause an error code to be returned.
This call will execute only if the file has been opened for exclusive
access.

Reference isf_delrec()
6.2.8 Delete record specified by record number
Syntax [stat=] isf_delrec(err_cont,fdesc, recnum)

logging */
long recnum; /*(I) Record number */
Semantics The routine isf_delrec() differs from isf_delete() in that it deletes the
record specified by recnum from the file indicated by fdesc rather than
the record indicated by the primary key. The appropriate values will be
deleted from each index that is defined. Recnum must be a previously
obtained isrecnum value. This call will set isrecnum to the value of
recnum, while the current record position is left unchanged.
• ISF_E_FILE_ERR
Related Routines
Errors • isf_delete()
Deletes the record pointed to by the primary key
• isf_delcur()
Deletes the current record

isf_erase() Reference
6.2.9 Delete an ISAM file
Syntax [stat=] isf_erase(err_cont,filename)

logging */
char *filename; /*(I) File to delete */
Semantics The routine isf_erase() will remove the file specified by filename.
Note using isf_erase() should be avoided and it is preferable to use the
isf_uerase() routine instead, since it offers remote database functionality
and is completely compatible with the equivalent local node version.
Notes • This routine has some extra restrictions on some systems. See the
Errors • ISF_E_NOFILE
File not found
• ISF_E_FILE_ERR

Reference isf_flw_evt()
6.2.10 Define flow control
Syntax [stat=] isf_flw_evt(err_cont,fd,mode,msg_id,interval)

logging */
struct isf_file_info *fd; /*(I) File to control */
int mode /*(I) Enable/disable */
int msg_id /*(I) ID of control msg*/
int interval; /*(I) Send frequency */
Semantics The routine isf_flw_evt() is used to enable and disable flow control
messages from a remote node for which ISAM event requests have been
made. Flow control messages are used to check for messages that may
have been lost and are sent after a period of inactivity (defined by
interval) to indicate that the peer is still available. An event request for
an ISAM file must have already been made with a call to isf_set_evt().
The file information is passed via the fd argument. The message code
used to identify flow control messages is supplied in msg_id. The flow
control messages received contain a structure of type isf_evt_flow.
Notes • This routine is not required in case event requests have been made
on the same node.
Errors • None.

isf_indexinf() Reference
6.2.11 Get information about index
Syntax [stat=] isf_indexinf(err_cont,fdesc,buffer,number)

logging */
struct keydesc *buffer; /*(O) May be pointer to a
dictinfo struct
instead */
int number; /*(I) Pos : indexnr to
obtain info
from in struct
keydesc
Zero: general info
in struct
dictinfo */
Semantics The routine isf_indexinf() gives the caller access to information about
the file. Such as, information about the defined indexes, their location
within the record, their length, and whether duplicate values are allowed.
Information about a particular index is obtained by specifying the
number of the index using the number parameter. General information
such as the number of indexes, index record size, and data record size is
obtained by calling isf_indexinf() with the number parameter set to 0
and reading the buffer into a structure of type dictinfo.
The buffer parameter can contain information in the format of either
keydesc or dictinfo depending on whether the number parameter is
positive or 0, respectively. As indexes are added and deleted, the number
of a particular index may vary. To ensure review of all indexes, loop
over the number of indexes indicated in dictinfo (see structure
definitions in the isam.h file).
Notes • This routine is not fully supported on all systems (portability!). See
the appropriate appendix for more information

Reference isf_lock()
6.2.12 Lock an ISAM file
Syntax [stat=] isf_lock(err_cont,fdesc)

logging */
Semantics The routine isf_lock() will lock the entire file that is specified by fdesc.
More discussion of locking can be found in Chapter 4, “Locking”.
appropriate appendix for more information
• ISF_E_FILE_ERR

isf_open() Reference
6.2.13 Open an ISAM file
Syntax fdesc = isf_open(err_cont,filename, mode)
Arguments struct isf_file_info *fdesc; /*(R) File descriptor */

logging */
char *filename; /*(I) File to be opened*/
int mode; /*(I) Open-mode */
Semantics The routine isf_open() is used to open an ISAM file for processing. The
function will return the file descriptor that should be used in subsequent
accesses to the file.
Note using isf_open() should be avoided and it is preferable to use the
isf_uopen() routine instead, since it offers remote database functionality
and is completely compatible with the equivalent local node version.
This call will automatically position the current record pointer to the first
record in order of the primary index. If another ordering is desired, the
isf_start() call can be used to select another index.
The filename parameter must contain a null-terminated string, which is
the name of the file to be processed.
The mode parameter determines the locking information. The user has
three options: manual, automatic or exclusive. Selecting the manual
option indicates that the user wishes to be responsible for locking
records at the appropriate times. Selecting automatic locking indicates
that the user wishes to lock each record as it is read and unlock it after
any subsequent function calls. Selection of exclusive locking will deny
file access to anyone other than this process. More information about
locking can be found in Chapter 4, “Locking”.
The mode parameter also specifies whether the file is opened for read,
write, or read/write access. Furthermore it is possible to specify whether
writing a record should be deferred, if this feature is available for your
system. This means that each time a record is written, it is not actually
written to disk but buffered for a time to save on overhead.
The mode is specified by using the define macros that are found in the
header file isam.h. Modes that are used in the isf_open() command are:
ISEXCLLOCK ISINPUT

Reference isf_open()
ISMANULOCK ISOUTPUT
ISAUTOLOCK ISINOUT
ISF_DEF_WRT
File not found
• ISF_E_FILE_ERR
RETURN VALUE/ERROR INDICATION in SubSection 6.1.1.

isf_opn_evt() Reference
6.2.14 Open an event monitoring channel
Syntax [fdesc=] isf_opn_evt(dur_cont, err_cont, node, dir_type,

filename, mode, msg_id, rec_siz,
rec_fmt)
Arguments struct isf_file_info *fdesc; /*(R) file descriptor */

struct dur_context *dur_cont; /*(M) Used for message
passing */
logging */
int node; /*(I) location of file */
int dir_type; /*(M) directory number */
register char *filename; /*(I) name of ISAM file*/
int mode; /*(I) not used */
int msg_id; /*(I) id for events */
int rec_siz; /*(I) length of record */
char *rec_fmt; /*(I) format string */
Semantics The routine isf_opn_evt() is used to initialize event monitoring for an

ISAM file. The ISAM file to monitor is identified by filename in the
FAST/TOOLS directory indicated by dir_type on the specified remote
node. A file descriptor is returned and should be used in further calls to
isf_set_evt() and isf_close(). The msg_id argument identifies the
message that will be received in case an action has taken place on the
file. The length and format of the record in the file are specified in
rec_siz and rec_fmt.
Notes • The routine isf_set_evt() must be used to identify which events

should be monitored.
• For event monitoring on the same node, use “0” for the node
argument.
• For a list of directory numbers see the description of the routine
isf_uopen().
Errors • Returns the same errors as defined in isf_uopen().

Reference isf_read()
6.2.15 Read a record
Syntax [stat=] isf_read(err_cont,fdesc,record,mode)

logging */
char *record; /*(O) Buffer to receive
in */
int mode; /*(I) Read mode */
Semantics The routine isf_read() is used to read records sequentially or randomly

as indicated by the mode parameter.
When sequential processing is desired, mode must specify which record
is to be read. It may take one of the following values:
ISCURR current
ISFIRST first record
ISLAST last record
ISNEXT next record
ISPREV previous record
When random selection is desired, mode must specify the value of the
record to be returned relative to the specified search value. This value
may be one of:
ISEQUAL equal to
ISGREAT greater than
ISGTEQ greater than or equal to
The search value is placed in the record buffer in the correct byte
positions.
Isf_read() will fill in the record with the results of the search. The mode
is specified by using the define macros that are found in the header file
isam.h.
Isf_read() can also read records specified by a previously set isrecnum.
First, call isf_start() with k_nparts=0 so that the file is set to read in
physical order. Then call isf_read() with mode = ISEQUAL. This will
cause isf_read() to look at isrecnum for the desired record.
Following the successful execution of this call, the current record
position and isrecnum will both be set to indicate the record just read.
If manual locking was specified when the file was opened and the record
is to be locked before being read, the ISLOCK flag may be Logically
ORed added with one of the above macros. The record will then remain

isf_read() Reference
locked until unlocked with the isf_release() call. Entire files may be
locked and unlocked by using the isf_lock() and isf_unlock() calls.
Modes that are used in the isread call are:
One of these optionally ORed with
ISCURR ISLOCK
ISNEXT
ISFIRST
ISGREAT
ISEQUAL
ISPREV
ISLAST
ISGTEQ
Notes • The modes ISLAST and ISPREV are not supported on all systems
(portability!). See the appropriate appendix for more information

Reference isf_release()
6.2.16 Unlock manually locked records
Syntax [stat=] isf_release(err_cont,fdesc)

logging */
Semantics The routine isf_release() unlocks records that have been locked using
the ISMANULOCK mode in the isf_read() call. All locked records in
the file indicated by fdesc will be unlocked. More information of how to
use isf_release(), can be found in Chapter 4, “Locking”.
Related Routines
Errors • isf_unlock()
This routine releases a whole file.

isf_rename() Reference
6.2.17 Rename an ISAM file
Syntax [stat=] isf_rename(err_cont,oldname, newname)

logging */
char *oldname; /*(I) Old filename */
char *newname; /*(I) New filename */
Semantics The routine isf_rename() will rename the file specified by the oldname
parameter to the name specified by the newname parameter.
Note using isf_rename() should be avoided and it is preferable to use the
isf_urename() routine instead, since it offers remote database
functionality and is completely compatible with the equivalent local
node version.
File not found
• ISF_E_FILE_ERR

Reference isf_rewcurr()
6.2.18 Rewrite current record
Syntax [stat=] isf_rewcurr(err_cont,fdesc, record)

logging */
char *record; /*(I) New record
information */
Semantics The routine isf_rewcurr() is used to rewrite the current record for the file
indicated by fdesc with the contents of the character array record. The
appropriate values will be rewritten to each index that is defined. The
primary key value may be changed. Isf_rewcurr() is useful when the
primary key is not unique and the record cannot be located and rewritten
in one call. Isrecnum is set to indicate the current record, whose position
is left unchanged.
Errors • ISF_E_DUPKEY
Duplicate key specified
• ISF_E_LOCKED
• ISF_E_FILE_ERR
Related Routines
Errors • isf_rewrite()
This routine rewrites the record located by key
• isf_rewrec()
This routine rewrites the record located by number (isrecnum)

isf_rewrec() Reference
6.2.19 Rewrite record located by number
Syntax [stat=] isf_rewrec(err_cont,fdesc,recnum,record)

logging */
long recnum; /*(I) Record nr to
rewrite */
information */
Semantics The routine isf_rewrec() is used to rewrite the record specified by

recnum in the file indicated by fdesc with the contents of the character
array record. Recnum must be a previously obtained isrecnum value.
Each index will be appropriately updated. This call will set isrecnum to
the value of recnum, while the current record position will remain
unchanged.
Notes • This routine is not (fully) supported on all systems (portability!).

See the appropriate appendix for more information
• ISF_E_FILE_ERR
Related Routines
Errors • isf_rewrite()
This routine rewrites the record located by key
• isf_rewcurr()
This routine rewrites the current record.

Reference isf_rewrite()
6.2.20 Rewrite record located by key
Syntax [stat=] isf_rewrite(err_cont,fdesc,record)

logging */
information */
Semantics The routine isf_rewrite() is used to change one or more values for a
record that is already in the file identified by fdesc. The primary key is
used to determine which record should be changed, and the record
parameter contains the changes. The primary key value must be unique
and may not be changed. The whole record is written to the data file.
Only the changed index values will be rewritten to each index that is
defined.
Isf_rewrite() does not change the position of the current record pointer,
while isrecnum is set to indicate this record.
Errors • ISF_E_NOREC
Record not found
• ISF_E_DUPKEY
Duplicate record
• ISF_E_LOCKED
• ISF_E_FILE_ERR

isf_opn_evt() Reference
6.2.21 Set an event request
Syntax [stat=] isf_set_evt(err_cont, fd, record, mode, ref_id)
Arguments TLS_BOOLEAN stat; /*(R) TRUE on success */

logging */
struct isf_file_info *fd; /*(I) file to request */
char *record; /*(I) specific record */
int mode; /*(I) type of events */
int ref_id; /*(I) event identifier */
Semantics The routine isf_set_evt() is used to indicate which types of events on an

ISAM file the application is interested in. The ISAM file to monitor is
identified by fd which is obtained by a previous call to isf_opn_evt(). If
a specific record in the file should be monitored, then a pointer to the
existing record should be specified in record. The supplied ref_id will be
included in event messages in order to distinguish requests for different
files or records from one another.
The mode argument is used to specify which events should be monitored
and is a combination of one or more of the following flags:
Table 1: ISAM file event modes
Mode Description
ISF_CRI_OPEN File has been opened

ISF_CRI_CLOSE File has been closed
ISF_CRI_WRITE A record has been added
ISF_CRI_REWRITE A record has been modified. If a par-
ticular record has been specified then
the event is sent only when this record
has changed.
ISF_CRI_DELETE A record has been deleted. If a particu-
lar record has been specified then the
event is sent only when this record has
been deleted
ISF_INF_INITIATOR Include the source of the event in the
event message.

Reference isf_opn_evt()
Table 1: ISAM file event modes
Mode Description
ISF_INF_OLD_RECORD Send the old record contents before it

was modified with the event. If used in
combination with ISF_CRI_WRITE
and ISF_CRI_DELETE, the actual
record is sent.
ISF_INF_NEW_RECORD Send the new record contents after it
was modified with the event. If used in
combination with ISF_CRI_WRITE
and ISF_CRI_DELETE, the actual
record is sent.
ISF_DO_ONCE Only the first event is sent.
In order to request events at file level, supply a NULL pointer for the
record argument. To remove these events, specify no criteria flags and a
NULL pointer for the record argument.
For event requests at record level, specify the particular record in the
record argument in combination with one or both of
ISF_CRI_REWRITE and ISF_CRI_DELETE. To remove these events,
clear these flags and specify the particular record.
When an event occurs the application will be notified by means of a
message containing an isf_evt structure. The event that occurred can be
identified in evt_cri, which will contain one of the ‘criteria’ flags
described in the table above. The file or record to which this event refers
can be identified with the ref_id. Whether the source, old record or new
record has been supplied in the message is identified by one of the
‘information’ flags described in the table above.
Notes • The routine isf_opn_evt() must first be used to open an event
channel.
• All subsequent event requests for the same record will overrule any
previous requests for that record.
• Using a different ref_id for a subsequent call on the same data set
or record will overrule the previous ref_id.
Errors • ISF_NO_REC
The specified record in ‘record’ does not exist.

isf_start() Reference
6.2.22 Select an index
Syntax [stat=] isf_start(err_cont,fdesc,keydesc,length,

record, mode)

logging */
struct keydesc *keydesc; /*(I) Key to position
at */
int length; /*(I) Significant part
of key */
char *record; /*(I) Buf to read
record in */
int mode; /*(I) How to position */
Semantics The routine isf_start() selects the index to be used in subsequent

operations. The key value to be sought should be placed in the record
parameter, in the positions described by the keydesc parameter. The
keydesc structure must describe an index that was specified in the
isf_build() or isf_create(), or that has been added previously using the
isf_addindex() call.
The record parameter need not to be filled if the mode parameter (see
below) is one of ISFIRST or ISLAST.
The length parameter is used to specify the part of the key to be
considered significant when doing the search. A zero indicates that the
whole key is significant; a positive value is used to indicate a shorter
length. If length is greater than zero, the response during searches will
be as if the index were originally defined to have that shorter length.
The mode parameter may be ISFIRST, ISLAST, ISEQUAL, ISGREAT
or ISGTEQ. It is used to position the user in the file in association with
the index selected by the keydesc argument.
ISFIRST positions the user’s program in the file just before the first
record in the ordering of the index specified in the keydesc parameter. A
subsequent call to isf_read() using the ISNEXT mode parameter reads
the first record in the current ordering.
ISLAST positions the user’s program just after the last record in that
ordering. A subsequent call to isf_read() using the ISPREV mode
parameter reads the last record in the current ordering.
Note that if mode is ISFIRST or ISLAST, the parameters length and
record are not needed and are not used by the isf_start() call.

Reference isf_start()
Use of the ISEQUAL, ISGREAT or ISGTEQ modes is different from

the use of the ISFIRST or ISLAST modes. When using the former
modes, the user’s program must place the key value to be searched for
in the record buffer before calling isf_start(). The value to be searched
for must be placed in the location in the record buffer where the keydesc
parameter claims the index exists.
ISEQUAL will give one of two possible results. It will either find a
record whose key value is equal to that found in the appropriate positions
of the record buffer parameter, or it will return an error. This error
indicates that no record with the key value specified in the record buffer
parameter exists in the file.
ISGREAT will also give one of two responses. It will either find the next
higher record whose key value is greater than that found in the record
buffer parameter, or isf_start() will return an error.
The ISGTEQ mode parameter finds the record that has the next higher
key value greater than or equal to the key value specified in the
appropriate positions of the record buffer parameter. If no such record is
found, isf_start() returns an error.
The above macros, ISFIRST, ISLAST, ISEQUAL, ISGREAT, and
ISGTEQ, are defined in the header file isam.h.
Isf_start() can also be used for sequential access in physical order by
specifying a previously defined key that has zero parts; that is, give a
value to keydesc to designate a structure in which k_nparts=0 (see
isf_read()).
Isf_start() performs two basic functions. It selects the index that is to be
used for subsequent reads, and it finds (but does not read) a record in the
file. Isf_start() need not be used to find each record before it is read using
isf_read().
position and isrecnum will both be set to indicate this record.
Notes • This routine has some extra restrictions on all systems. See the
Errors • ISF_E_NOREC
Record not found

isf_start() Reference
• ISF_E_FILE_ERR

Reference isf_uerase()
6.2.23 Delete an ISAM file
SYNTAX
Syntax [stat =]isf_uerase(dur_cont, err_cont, node, dir_type,
filename)
Arguments TLS_BOOLEAN stat /* (R)TRUE is success */

struct dur_context dur_cont;/*(M)Used for message
passing */
struct umh_context err_cont;/*(M)Used for error
logging */
int dir_type; /* (I)Path number */
char *filename; /* (I)Filename */
Semantics The routine isf_uerase() will remove the database specified by dir_type
and filename. Note using isf_erase() should be avoided and it is
preferable to use this isf_uerase() routine, since it offers remote database
functionality and is completely compatible with the equivalent local
node version.
The dur_cont parameter is used to allow the DATABASE/FAST run-
time system to use the BUS/FAST message passing facilities for
communication with the remote isfserver.
The err_cont contains the error indicating the failure when the function
does not return a success. The function returns a FALSE in case of such
failure.
The node specifies the node where the database to delete is located. A
zero specifies the local node. In this case, the run-time system will
access the database directly without intervention of the isfserver. If the
local node is specified by using the local node number (not zero), the
database is accessed by means of the isfserver. It is advisable to use zero
when the database has to be deleted on the local node.
The dir_type and filename specify the path and name of the database to
delete. The dir_type specifies one of the standard FAST/TOOLS
directories. These specifications can be found in tools.h and are:
• TLS_NODIR_T directory path in file name
• TLS_INIT_T the set-up directory
• TLS_SAVE_T the save directory
• TLS_LIST_T the list directory
• TLS_HELP_T the help directory
• TLS_DATA_T the data directory
• TLS_AUX_T the auxiliary directory

isf_uerase() Reference
• TLS_EXE_T the executable directory

• TLS_USER1_T the user 1 directory
• TLS_USER2_T
• TLS_USER3_T
• TLS_USER4_T
• TLS_USER5_T
• TLS_COMMAND_T the command procedure directory
• TLS_HIS_T the history directory
• TLS_DID_T the display directory
These specifications are system independent and are used by the run-
time system to create the actual path string.
The specified filename is appended to that path string to create the actual
database file name.
If a dir_type is specified that is not one of the above enumerated types,
the specified filename is used as the actual database file name. In this
case no file path is prefixed to the filename.
Notes This routine is not defined by X/OPEN. It is ISF-specific.
Errors • ISF_F_FNAME
The total length of the path, specified by dir_type and filename
exceeds the 80 bytes.
• ISF_E_NOFILE
The specified database could not be located.
• ISF_F_BAD_MEM
The run-time system could not allocate enough system resources.
Examples The following isf_uerase() call is compatible with an isf_erase() call:
status = isf_uerase ( dur_cont, err_cont, 0, 0, filename);

Reference isf_unlock()
6.2.24 Unlock an ISAM file
Syntax [stat=] isf_unlock(err_cont,fdesc)

struct umh_context *err_cont;/* (M)Used for error logging
*/
struct isf_file_info *fdesc; /* (M)File descriptor */
Semantics The routine isf_unlock() is used to release an existing file-level lock for
the file specified by the file descriptor fdesc. Further discussion of
locking can be found in Chapter 4, “Locking”.
Notes • This routine is not (fully) supported on all systems (portability!).

See the appropriate appendix for more information.
Related Routines
Errors • isf_release()
This routine releases locked records in a file.

isf_uopen() Reference
6.2.25 Open or create an ISAM file
SYNTAX
Syntax [fdesc =] isf_uopen(dur_cont, err_cont, node, dir_type,
filename, mode, n_keys, keydesc,
recordlength, recordformat, timeout)
Arguments struct isf_file_info fdesc;/*(R)File descriptor */

struct dur_context dur_cont;/*(M)Used for message
passing */
struct umh_context err_cont;/*(M)Used for error
logging */
int dir_type; /* (I)Path number */
char *filename; /* (I)File to open or create */
int mode; /* (I)Open or creation mode */
int n_keys; /* (I)Number of keys */
struct keydesc *keydesc; /* (I)Key description array */
int recordlength; /* (I)Record length in bytes */
char *recordformat; /* (I)Format layout of the
record */
TLS_ULONG timeout; /* (I)Remote keep alive time out
*/
Semantics The routine isf_uopen() is used to open an existing database or to create

a database. It returns a file descriptor that should be used in subsequent
access to the database. All isf_*() functions except isf_rename() and
isf_erase() can be used to access the database.
The dur_cont parameter is used to allow the DATABASE/FAST run-
time system to use the BUS/FAST message passing facilities for
communication with the remote isfserver.
does not return a success. The function returns a NULL pointer in case
of such failure.
The node parameter specifies the node where the database is located or
should be created. A zero specifies the local node. In this case, the run-
time system will access the database directly without intervention of the
isfserver. If the local node is specified by using the local node number
(not zero), the database is accessed by means of the isfserver. It is
advisable to use zero when the database has to be accessed on the local
node.

Reference isf_uopen()
The dir_type and filename specify the path and name of the database to
open or create. The dir_type specifies one of the standard FAST/TOOLS
directories. These specifications can be found in tools.h and are:
• TLS_NODIR_T directory path in file name
• TLS_EXE_T the executables directory
• TLS_USER2_T
• TLS_USER3_T
• TLS_USER4_T
• TLS_USER5_T
The specified filename is appended to that path string to create the actual
database file name.
If a dir_type is specified that is not one of the above enumerated types,
the specified filename is used as the actual database file name. In this
case, no file path is prefixed to the filename.
The mode parameter determines the locking information. The options
supplied are:
manual
automatic
exclusive
responsible for locking records at the appropriate times. Selecting
automatic locking indicates that the user wishes to lock each record as it
is read and unlock it after any subsequent function calls. Selection of
exclusive locking will deny file access to anyone other than this process.
More information about locking can be found in Chapter 4, ‘Locking’.
The mode parameter also specifies whether the file is opened for read,
write, or read/write access.
Furthermore it is possible to specify whether writing a record should be
deferred, if this feature is available for your system. This means that

isf_uopen() Reference
each time a record is written, it is not actually written to disk but

buffered for a time to save on overhead.The mode is specified by using
the define macros that are found in the header file isam.h. Modes that are
used in the isf_open() command are:
ISEXCLLOCK ISINPUT
ISMANULOCK ISOUTPUT
ISAUTOLOCK ISINOUT
The n_keys and keydesc describe the structure of the key indexes in
case of a database creation. When n_keys is zero, the database must exist
and is opened. In all other cases, the database is created using the
information supplied by n_keys and keydesc. N_keys specifies the
number of keys and keydesc is a pointer to the key description array.
When a zero is specified for n_keys, a NULL pointer can be supplied for
keydesc. It is not allowed to specify duplicate keys for the primary key.
The recordlength parameter specifies the record length in bytes. It has
to be supplied in all cases. When an existing ISAM file is opened and the
specified record length is not zero then the record length of the existing
ISMA file must match the specified record length.
The recordformat parameter specifies the layout of the record. A
NULL pointer can be supplied. In this case the run-time system does not
perform any system or key conversions.
The timeout parameter specifies the time in seconds the remote system
keeps the file open after the last file action. When no file actions are
done for timeout seconds, the file will be closed. A timeout of zero
means no timeout. (This feature is not implemented yet, so for the
moment the remote file will stay open till a close call is done).
Notes This routine is not defined by X/OPEN. It is ISF specific.
The total length of the path specified by dir_type, plus filename
exceeds 80 bytes.
• ISF_E_NOFILE
• ISF_E_LOCKED
The specified database is locked by another user.
• ISF_F_BAD_MEM

Reference isf_uopen()

• ISF_F_BAD_FORM
The supplied recordformat is not complete. Use routine
fsc_col_fmts() to create a complete recordformat.
• ISF_F_NOPRIMDUP
Duplicated are not allowed for the primary key.
• ISF_F_RECTOLARGE
The record length of the existing ISAM file is bigger than the one
specified.
• ISF_F_RECTOSMALL
The record length of the existing ISAM file is smaller than the one
specified.
Examples The following isf_uopen() call is compatible with an isf_open() call:
fdesc = isf_uopen ( dur_cont, err_cont, 0, 0, filename, mode, 0, (struct

keydesc *)NULL, recordlength, (char*)NULL, 0);
The following isf_uopen() call is compatible with a isf_create() call:
fdesc = isf_uopen ( dur_cont, err_cont, 0, 0, filename, mode, n_keys,

keydesc, recordlength, (char*)NULL, 0);

isf_urename() Reference
6.2.26 Rename an ISAM file
SYNTAX
Syntax [stat =] isf_urename (dur_cont, err_cont, node,
old_dir_type, oldname, new_dir_type,
newname)
Arguments TLS_BOOLEAN stat /* (R)TRUE is success */

struct dur_context dur_cont; /* (M)Used for message
passing */
struct umh_context err_cont; /* (M)Used for error
logging */
int old_dir_type; /* (I)Old path number */
char *oldname; /* (I)Old filename */
int new_dir_type; /* (I)New path number */
char *newname; /* (I)New filename */
Semantics The routine isf_urename() will rename the database specified by

old_dir_type and oldname to the database specified by new_dir_type
and newname. Note using isf_rename() should be avoided and it is
preferable to use this isf_urename() routine instead, since it offers
remote database functionality and is completely compatible with the
equivalent local node version.
The dur_cont is used to allow the DATABASE/FAST run-time system
to use the BUS/FAST message passing facilities for communication
with the remote isfserver.
does not return a success. The function returns a FALSE in the case of
such a failure.
The node specifies the node where the old database is located and where
the new database will be located. A zero specifies the local node. In this
case, the run-time system will access the database directly without
intervention of the isfserver. If the local node is specified by using the
local node number (not zero), the database is accessed by means of the
isfserver. It is advisable to use zero when the database has to be accessed
on the local node.
The old_dir_type and oldname specify the path and name of the
database to rename. The old_dir_type specifies one of the standard
FAST/TOOLS directories. These specifications can be found in tools.h
and are:
• TLS_NODIR_T directory path is in file name

Reference isf_urename()

• TLS_EXE_T the executables directory
• TLS_USER2_T
• TLS_USER3_T
• TLS_USER4_T
• TLS_USER5_T
The specified oldname is appended to that path string to create the actual
database file name.
If an old_dir_type is specified that is not one of the above enumerated
types, the specified oldname is used as the actual database file name. In
this case no file path is prefixed to the filename.
The new_dir_type and newname specifies the new name for the
database to rename. It is not possible to rename a database to another
storage volume (other physical disk).
Notes This routine is not defined by X/OPEN. It is ISF-specific.
The total length of the path, specified by old_dir_type and oldname
or new_dir_type and newname exceeds 80 bytes.
• ISF_E_NOFILE
• ISF_F_BAD_MEM
Examples The following isf_urename() call is compatible with an isf_rename()

call:
status = isf_urename ( dur_cont, err_cont, 0, 0, oldname, 0, newname);

isf_wrcurr() Reference
6.2.27 Insert new record, and mark as current
Syntax [stat=] isf_wrcurr(err_cont,fdesc,record)

logging */
information */
Semantics The routine isf_wrcurr() writes the record passed to it in the record
parameter to the data file identified by fdesc. The appropriate values will
be inserted into each index that is defined.
position and isrecnum will both be set to indicate this record.
Related Routines
Errors • isf_write()
This routine does not mark this record as current.

Reference isf_write()
6.2.28 Insert new record
Syntax [stat=] isf_write(err_cont,fdesc,record)

logging */
information */
Semantics The routine isf_write() writes the record passed to it in the record
parameter to the file. The appropriate values will be inserted into each
index that is defined.
The routine isf_write() does not change the position of the current record
pointer, but isrecnum is set to indicate this record.
Related Routines
Errors • isf_wrcurr()
This routine marks the record as current.

Building a file Examples
Appendix A Examples
A.1 Building a file

The following C language example creates an “employee” file. Note that
the primary key must be defined.
#include <tools.h>
#include <dur.h>
#include <umh.h>
#include <isf.h>
main()
{
struct isf_file_info *fp;
struct keydesc key;
struct record
{
TLS_LONG emp_nr;
char name[20];
char address[20];
char zipcode[8];
char city[10];
} rec;
/*---------------------------------------------------+
| Initialize BUS/FAST |
+---------------------------------------------------*/
dur_umh_init (&dur_cont,&err_cont,2,512,512,0,NULL);
/*---------------------------------------------------+
| Define the primary key to the file |
+---------------------------------------------------*/
key.k_flags = ISNODUPS; /* No duplicates allowed */

key.k_nparts = 1; /* Key has one part only */
key.k_start = 0; /* First part of the key ..*/
key.k_leng = 4; /* has offset 0, length 4..*/
key.k_type = 0; /* and is of type char */
/* For the first part of the key, special #defines are

available in isam.h:
key.k_start is same as key.k_part[0].kp_start

key.k_leng is same as key.k_part[0].kp_leng
ISF Programmer’s Guide A-1

Examples Adding data
key.k_type is same as key.k_part[0].kp_type
This is done to ease ISAM creation of files with

an index consisting of one part only.
... see isam.h */
/*---------------------------------------------------+
| Create the ISAM file |
+---------------------------------------------------*/
if (!(fp = isf_create (&err_cont,"EMPLOYEE.DAT",

sizeof(struct record),
1,&key,ISINOUT+ISEXC LLOCK)))
/* file is also opened
for read write! */
{
umh_log(err_cont); /* error: log, return */
return;
}
/*---------------------------------------------------+
| Close the file again and detach from DUR |
+---------------------------------------------------*/
isf_close(&err_cont,fp);
dur_det(&dur_cont,&err_cont);
}
A.2 Adding data

The following program simply adds records to the 'EMPLOYEE.DAT'
file. It is assumed in the program that the record has been filled.
#include <dur.h>
#include <umh.h>
#include <fsl.h>
#include <isf.h>
main()
{
static char inp_buf[FIO_MAX_INP] = {0};
long value;
struct keydesc key;
A-2 ISF Programmer’s Guide

Adding data Examples
struct record
{
TLS_LONG emp_nr;
char name[20];
char address[20];
char zipcode[8];
char city[10];
} rec;
/*---------------------------------------------------+
+---------------------------------------------------*/
/*---------------------------------------------------+
| Open file for read/write, with automatic locking |
+---------------------------------------------------*/
if ((fp=isf_open(&err_cont,"EMPLOYEE.DAT",
ISINOUT | ISAUTOLOCK)) == NULL)
{
umh_log(&err_cont);
exit(BAD_EXIT);
}
while (1)
/*---------------------------------------------------+
|First clear the record, then get new data |
+---------------------------------------------------*/
{
memset(&rec,'\0',sizeof(struct record));
/* init record buffer */
fio_get_long(inp_buf,&value,
"Employee number (0=exit)",FIO_RETRY);
if (value == 0) exit (GOOD_EXIT);
stlong(value,&rec.emp_nr);
inp_buf[0] = '\0';
fio_ltd_str(inp_buf,&rec.name,
"Name ",FIO_RETRY,20);
inp_buf[0] = '\0';
fio_ltd_str(inp_buf,&rec.address,
"Address ",FIO_RETRY,20);
inp_buf[0] = '\0';
fio_ltd_str(inp_buf,&rec.zipcode,
"Zipcode ",FIO_RETRY,7);
inp_buf[0] = '\0';
fio_ltd_str(inp_buf,&rec.city,

Examples Sequential access
"City ",FIO_RETRY,10);
/*-------------------------------------------------+
| Add record |
+-------------------------------------------------*/
if (!isf_write(&err_cont,fp,&rec))
{
umh_log(&err_cont);
exit(BAD_EXIT);
}
}
}
A.3 Sequential access

The next example shows how to read a file sequentially. In this example,
the file “EMPLOYEE.DAT” is read in order of the primary key emp_nr.
Since emp_key is defined as ascending with no duplicate key allowed,
the sequence of records will print from the lowest value of emp_nr to the
highest value. This will continue until the isf_read() routine returns the
error ISF_E_NOREC (end of file).
#include <dur.h>
#include <umh.h>
#include <fsl.h>
#include <isf.h>
main()
{
struct keydesc key;
struct record
{
TLS_LONG emp_nr;
char name[20];
char address[20];
char zipcode[8];
char city[10];
} rec;
/*---------------------------------------------------+
+---------------------------------------------------*/

Sequential access Examples
dur_umh_init (&dur_cont,&err_cont,2,0,512,,512,NULL);
/*---------------------------------------------------+
+---------------------------------------------------*/
{
umh_log(&err_cont);
exit (BAD_EXIT);
}
/*---------------------------------------------------+
| Define the key to search with (in this case the |
| primary key) |
+---------------------------------------------------*/
key.k_flags = ISNODUPS; /* No flags */
/*---------------------------------------------------+
| Position at first index |
+---------------------------------------------------*/
if (!(isf_start(&err_cont,fp,&key,0,&rec,ISFIRST)))
/* Whole key */
{
umh_log(&err_cont);
exit (BAD_EXIT);
}
/*---------------------------------------------------+
| Get first record |
+---------------------------------------------------*/
if (!isf_read(&err_cont,fp,&rec,ISFIRST))
{
if (umh_error(&err_cont) == ISF_E_NOREC)
{
printf("No more records\n");
exit (BAD_EXIT);

Examples Random access
umh_log(&err_cont); /* Serious error */

exit (BAD_EXIT);
}
/*---------------------------------------------------+
| Print on screen and get next record |
+---------------------------------------------------*/
while (1)
{
printf("\nEmployee nr: %ld",
ldlong((char *)&rec.emp_nr));
/* Note use of ldlong() */
printf("\nName : %s",rec.name);
printf("\nAddress : %s",rec.address);
printf("\nZipcode : %s",rec.zipcode);
printf("\nCity : %s",rec.city);
if (!isf_read(&err_cont,fp,&rec,ISNEXT))
{
{
printf("No more records\n");
exit (BAD_EXIT);
}
umh_log(&err_cont);
exit (BAD_EXIT);
}
}
}
A.4 Random access

The following program is an example of how to random access a file.
This program interactively retrieves an employee number from standard
input, searches it in file 'EMPLOYEE.DAT' and prints the output of its
search to standard output.
#include <dur.h>
#include <umh.h>
#include <fsl.h>
#include <isf.h>
main()
{
static char inp_buf[FIO_MAX_INP] = {0};

Random access Examples
long value;
struct keydesc key;
struct record
{
TLS_LONG emp_nr;
char name[20];
char address[20];
char zipcode[7];
char city[10];
} rec;
/*---------------------------------------------------+
+---------------------------------------------------*/
/*---------------------------------------------------+
+---------------------------------------------------*/
{
umh_log_term(&err_cont);
exit (BAD_EXIT);
}
/*---------------------------------------------------+
| Define the key to search with (in this case the |
| primary key) |
+---------------------------------------------------*/
key.k_flags = ISNODUPS; /* No flags */
/*---------------------------------------------------+
| Get employee number |
+---------------------------------------------------*/
while (1)

Examples Random access
{
inp_buf[0] = '\0';
fio_get_long(inp_buf,&value,
"\n\nEmployee number (0=exit)",FIO_RETRY);
if (value == 0) exit (GOOD_EXIT);
stlong(value,&rec.emp_nr);
if (!isf_read(&err_cont,fp,&rec,ISEQUAL))
/* Note use of ISEQUAL */
{
{
printf("No record found\n");
/* End of file detected */
}
else
{
umh_log_term(&err_cont); /* Serious error */
exit (BAD_EXIT);
}
}
else
{
/*------------------------------------------------+
| Print on screen |
+------------------------------------------------*/
printf("\nName : %s",rec.name);
printf("\nAddress : %s",rec.address);
printf("\nZipcode : %s",rec.zipcode);
printf("\nCity : %s",rec.city);
}
}
}

Not Supported ISF Routines and Features UNIX and Windows specific information
Appendix B UNIX and Windows

specific information
B.1 Not Supported ISF Routines and Features

The following functions are not supported by the UNIX and Windows
implementation. The reader should refer to the ISF Programmer’s Guide
to get a clear description of routines, variables and #defines used in the
list below. In all these cases the phrase “not supported” means that such
a call or value will not abort the program but that a testable error will be
returned and no action is performed.
• ISPREV: This is impossible when accessing records in
physical order.
• ISLAST: This is impossible when accessing records in
physical order.
• isf_addindex(): The addition of indexes afterwards is not allowed.
• isf_build(): The ISDESC constant should not be ORed to the
type constant of the kp_type fields, because this is
not supported.
Furthermore, specifying a keydesc with field
k_nparts=0 (indicating: actually no primary key) is
not supported either.
• isf_delindex(): As long as isf_addindex is not supported, this
routine is not either.
• isf_indexinf(): This function will always return 0 for the
di_nrecords field (the number of data records)
when calling the function with input parameter
“number” equal to zero (indicates: ask for
dictinfo). In other cases the routine performs its
normal function.
• isf_read(): Mode cannot be one of (not supported):
ISLAST
ISPREV
when using physical order access.
• isf_start(): Mode cannot be one of (not supported):
ISLAST
ISPREV
when using physical order access.
ISF Programmer’s Guide B-1

UNIX and Windows specific information Restrictions on ISF Routines and Features
B.2 Restrictions on ISF Routines and

Features
There are some issues within the functionality of routines on which
XOPEN/ISAM doesn’t point out a clear statement. In the ISF brick
some additional definitions have been made in the following routines:
• isf_erase(): This function will only work when the ISAM file to
erase is not anywhere opened in the system.
• isf_rename(): This function will only work when the ISAM file to
rename is not opened anywhere in the system.
• isf_read(): It is not allowed to manually lock more then 100
records. If an attempt is made to lock more records,
isf_read return lock errors. In this case it can be
better to use file locking.
• isf_start() For this function the length parameter is not
supported with a different value as the key length.
B.3 ISAM files

An ISAM file is a collection of three or four files:
• The database dictionary file contains the definition of the database.
• One or two key files contain the keys with pointers to there data
records in the data file.
• The data file contains the actually data records.
When creating an ISAM file, DATABASE/FAST creates those files
using the following naming convention:
• The dictionary file is created using the specified name. If no file
extension is specified then ‘.dat’ is used.
• The key file is created on the same directory as the dictionary with
the same name as the dictionary file but with file extension ‘.k01’.
A second key file will have the extension ‘.k02’.
• The data file is created on the same directory as the dictionary with
the same name as the dictionary file but with file extension ‘.d01’.
For example:
The call isf_create(..,"car.dat",..) will create the files car.dat, car.k01 and
car.d01.
This naming convention implies that the part of a filename in front of the
extension must be unique, otherwise you will have a problem. For
D-2 ISF Programmer’s Guide

ISAM files UNIX and Windows specific information
example:
A call isf_create(..,"car.dat",..) followed by a call
isf_create(..,"car.tmp"..) will overwrite the key and data file of car.dat.
If your program exits without closing a database in which one or more
records are locked by your program, those records will be locked
forever.
ISF Programmer’s Guide B-3

UNIX and Windows specific information ISAM files
D-4 ISF Programmer’s Guide

Index
Index
Symbols isf_create() 6-9

isf_delcurr() 6-11
.d01 B-2 isf_delete() 6-12
.dat B-2 isf_delindex() 6-13, B-1
.k01 B-2 isf_delrec() 6-14
.k02 B-2 isf_erase() 6-15, B-2
isf_indexinf() 6-17, B-1
C isf_lock() 4-2, 6-18
CHARTYPE 2-2 isf_open() 4-1, 6-19
COMPRES 3-2 isf_read() 4-2, 6-22, B-1, B-2
COMPRESS 6-2 isf_release() 6-24
isf_rename() 6-25, B-2
D isf_rewcurr() 6-26
data types 2-1 isf_rewrec() 6-27
DOUBLETYPE 2-3 isf_rewrite() 6-28
isf_start() 6-31, B-1, B-2
E isf_uerase() 5-1, 6-34
isf_unlock() 4-2, 6-36
error 6-1
isf_uopen() 5-1, 6-37
examples A-1
isf_urename() 5-1, 6-41
adding data A-2
isf_wrcurr() 6-43
building a file A-1
isf_write() 6-44
random access A-6
ISLAST B-1
sequential access A-4
ISMANULOCK 4-3
ISNEXT 6-3
F ISNODUPS 3-3, 6-2
file level locking 4-1 ISPREV 6-3, B-1
FLOATTYPE 2-3 isrecnum 6-3
I K
indexing 3-1 keydesc 3-1, 6-2
INTTYPE 2-2 keypart 3-1, 6-2
ISAM 0-2, 1-1
isam.h 6-1 L
2-1
ISAUTOLOCK 4-2 lddb() 2-3
ISCURR 6-3 ldfloat() 2-3
ISDUPS 3-2, 6-2 ldint() 2-2
ISEXCLLOCK 4-1 ldlong() 2-2
ISF 1-1 locking 4-1, 6-6
isf.h 6-1 LONGTYPE 2-2
isf_addindex() B-1
isf_build() 4-1, 6-6, B-1 R
isf_close() 4-1, 6-8 record level locking 4-2
ISF Programmer’s Guide 1

Index
remote database access 5-1
S
stdb() 2-3
stfloat() 2-3
stint() 2-2
stlong() 2-2
U
UNIX B-1
W
Windows B-1
X
X/OPEN definitions 1-2
2 ISF Programmer’s Guide

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction ITEM/FAST FAST/TOOLS
Manual ITM Programmer’s Guide
IM50J02J01-01EN/R10.03

IM50J02J01-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Manual objectives ......................................................0-1
1 Introduction ..........................................................................1-1
1.1 What is an item? ........................................................1-1
1.2 Environment of ITEM/FAST ....................................1-3
1.2.1 The basic tools ..............................................1-3
1.2.2 Interfaces with ITM ......................................1-4
2 ITEM/FAST mechanism ......................................................2-1
2.1 Basic principles ..........................................................2-1
2.1.1 Item structure ................................................2-1
2.1.2 Phase 1 ..........................................................2-2
2.1.3 Phase 2 ..........................................................2-2
2.1.4 Phase 3 ..........................................................2-4
2.2 Item values .................................................................2-4
2.3 Item statuses ..............................................................2-5
2.3.1 Value-related statuses. ..................................2-5
2.3.2 Additional statuses ........................................2-8
2.4 Item quality codes ....................................................2-10
2.5 Value clamping ........................................................2-11
2.6 Relative values .........................................................2-11
2.7 The PIT filter ...........................................................2-12
2.7.1 P-filter .........................................................2-12
2.7.2 I - filter .......................................................2-14
2.7.3 T-filter .........................................................2-15
2.8 Event requests ..........................................................2-17
2.8.1 Application information ..............................2-18
2.8.2 Application flags .........................................2-18
2.8.3 Update information .....................................2-19
2.8.4 Requester information ................................2-21
2.9 Main events ..............................................................2-22
2.10 Event buffers ............................................................2-24
2.11 Flow control .............................................................2-25
2.12 Subitems ..................................................................2-25
ITM Programmer’s Guide iii

Table of Contents
2.13 Storage on disk ........................................................ 2-28

2.14 Interfaces with ITM ................................................ 2-30
2.15 Item allocation (locking) ......................................... 2-32
2.16 API Locking ............................................................ 2-33
3 Item and event manipulations ............................................ 3-1
3.1 General ...................................................................... 3-1
3.2 The item-id ................................................................ 3-1
3.3 Gaining access to the common data area .................. 3-3
3.4 Item manipulations .................................................... 3-4
3.4.1 Creating a main/sub item ............................. 3-4
3.4.2 Defining the default representation .............. 3-5
3.4.3 Value and status ........................................... 3-5
3.4.4 Quality code ................................................. 3-7
3.4.5 Limit and deadband values .......................... 3-7
3.4.6 PIT values .................................................... 3-8
3.4.7 Dealing with array items .............................. 3-9
3.4.8 Dealing with blocked items .......................... 3-9
3.4.9 Dealing with offline items .......................... 3-10
3.4.10 How to acknowledge items ........................ 3-11
3.4.11 Using application information and flags .... 3-11
3.5 Event manipulations ................................................ 3-11
3.5.1 Requesting ’normal’ events ....................... 3-11
3.5.2 Requesting main events ............................. 3-14
3.5.3 Deleting event requests .............................. 3-15
3.5.4 Using event-message buffers ..................... 3-15
3.5.5 The force event mechanism ....................... 3-16
3.6 Saving item/event information on disk ................... 3-17
3.7 Miscellaneous ......................................................... 3-18
4 Reference guide .................................................................... 4-1
4.1 Conventions .............................................................. 4-1
4.2 Compiling, linking and running programs ................ 4-2
4.3 Error handling ........................................................... 4-2
4.4 Limits and deadband ................................................. 4-4
4.5 General data structs ................................................... 4-5
4.5.1 struct itm_id ................................................. 4-5
4.5.2 struct dur_adr .............................................. 4-5
4.5.3 struct itm_context ........................................ 4-5
4.5.4 Layout of an event message ......................... 4-6
4.5.5 union itm_val_union .................................. 4-11
4.5.6 struct itm_flow_msg .................................. 4-11
4.5.7 Update information layout ......................... 4-12
4.6 Routines and BUS/FAST messages ........................ 4-13
iv ITM Programmer’s Guide

Table of Contents
4.6.1 Acknowledge item status ............................4-14

4.6.2 Allocate an event buffer ..............................4-16
4.6.3 Attach to the data area ................................ 4-18
4.6.4 Block an item ..............................................4-19
4.6.5 Deallocate an event buffer .......................... 4-21
4.6.6 Delete an array item ....................................4-22
4.6.7 Delete an event request ...............................4-23
4.6.8 Delete an event request with flags ..............4-25
4.6.9 Delete an item .............................................4-27
4.6.10 Delete main event .......................................4-29
4.6.11 Detach from the data area ...........................4-30
4.6.12 Update application flags .............................4-31
4.6.13 Get value/status of array item .....................4-33
4.6.14 Get event buffer information ......................4-36
4.6.15 Get item information ..................................4-38
4.6.16 Get item information extended ...................4-42
4.6.17 Get item name .............................................4-46
4.6.18 Get item quality code ..................................4-48
4.6.19 Get item status ............................................4-49
4.6.20 Get value of an item ....................................4-51
4.6.21 Obtain group <-> node relation ..................4-53
4.6.22 Set application information ........................4-54
4.6.23 Insert an array item in the item table ..........4-56
4.6.24 General insert an item in the item table ......4-58
4.6.25 Insert an item in the item table ...................4-62
4.6.26 Add item id error line .................................4-67
4.6.27 Merge statuses ............................................4-68
4.6.28 Modify alarm info .......................................4-69
4.6.29 Modify alarm info exclusive .......................4-70
4.6.30 General modify an item ..............................4-71
4.6.31 Modify an item ...........................................4-75
4.6.32 Request a main event ..................................4-79
4.6.33 Obtain multiple item value/statuses ...........4-81
4.6.34 Obtain multiple item value/statuses
/quality codes ..............................................4-85
4.6.35 Declare an item offline ...............................4-88
4.6.36 Declare an item offline exclusive ...............4-90
4.6.37 Over-write a blocked item ..........................4-92
4.6.38 Return generation parameters .....................4-95
4.6.39 Obtain array-item parameters .....................4-96
4.6.40 Obtain item parameters ...............................4-98
4.6.41 Create a main event ..................................4-101
4.6.42 Create a main event extended ...................4-103
ITM Programmer’s Guide v

Table of Contents
4.6.43 Remove events ......................................... 4-105

4.6.44 Request an event ...................................... 4-106
4.6.45 Request an extended event ....................... 4-109
4.6.46 Request an event with flags ..................... 4-112
4.6.47 Request flow control ................................ 4-114
4.6.48 Save all items on disk ............................... 4-116
4.6.49 Save an item on disk ................................ 4-117
4.6.50 Update an array item ................................ 4-119
4.6.51 Update an array item exclusive ................ 4-121
4.6.52 Modify deadband or limits ....................... 4-122
4.6.53 Update general item information ............. 4-124
4.7.54 Update item value/status .......................... 4-133
4.7.55 Update item value/status exclusive .......... 4-136
4.7.56 Force event buffer to be sent .................... 4-138
4.7.57 Obtain item/value status (optimized) ....... 4-140
Appendix A:Using ITM on UNIX................................................. A-1
A.1 Compiling, Linking, Running ITM
programs on UNIX .................................................. A-1
Appendix B:Using ITM on Windows ............................................B-1
B.1 Compiling, Linking, Running ITM
programs ...................................................................B-1
vi ITM Programmer’s Guide

Manual objectives Preface
0 Preface
0.1 Manual objectives

functionality of ITM.
• To provide experienced users with a reference to the ITM usage.

language.
The reader is assumed to have a knowledge of BUS/FAST, particularly
the Message passing principle (DUR) and the Unsolicited Message
Handler (UMH) (see 0.4 Associated Documents).
The reader is also assumed to have some knowledge of the
FAST/TOOLS philosophy.

• Chapter 1 introduces the reader to the functionality, features,
environment, etc. of ITEM/FAST.
• Chapter 2 describes the ITM mechanism.
• Chapter 3 describes the item and event manipulations.
alphabetical order.

1 FAST/TOOLS INSTALLATION MANUAL
This manual provides information necessary to install ITEM/FAST
on your system.
2 BUS/FAST Programmer’s Guide
ITM Progammer’s Guide 0-1

- DUR Programmer’s Guide.

- UMH Programmer’s Guide.
which are used.
- FSL Programmer’s Guide
software.
3 The C Programming Language.
4 FAST/CONVENTIONS
This manual contains programming and interface conventions to
which all FAST/TOOLS comply.

CONVENTION MEANING
() Parentheses, used in routine syntax to indicate a list

one or more times.
... Indicates that not all of the statements re shown.
UPPERCASE Indicate reserved words and predefined letters

names, e.g. NULL, TRUE, DUR_NOWAIT.
(M) Indicates that the specified parameter may have
been modified when the routine returns.
(M)DUR Indicates that the description is valid for both DUR
and MDUR usage.
0-2 ITM Progammer’s Guide


variable.
n.u. not used.
output This typesetting is used to indicate output on a
terminal.
input This typesetting is used to indicate input from the
user.
|| Same as logical OR function
a==b True if a equals b
a!=b True if a does not equal b


What is an item? Introduction
1 Introduction
1.1 What is an item?
An item is a digitalized image of a specific process signal. When all
relevant variables of a process are represented by items, it is possible to
produce a complete image of the process in a computer system.
Item table All these items together are collected in a so-called item table where
each item can be accessed by FAST/TOOLS or application programs
unambiguously. In other words, the item table can be regarded as a real-
time database of process variables.
The software package responsible for coordinating these accesses is
ITM, which can be considered the heart of the FAST/TOOLS
environment. Most of the tools have an interface to this brick, which can
either be a routine interface or a (M)DUR interface. In this chapter we
explain the functionality of ITM as well as its underlying philosophy
FAST/TOOLS In order to gain a better understanding of the FAST/TOOLS
environment environment, a minimum configuration is depicted overleaf, consisting
of the following tools:
1 USER/FAST
2 ITEM/FAST
3 DATABASE/FAST
4 EQUIPMENT/FAST

Introduction What is an item?
USER/FAST
DATABASE/ ITEM/FAST
FAST
EQUIPMENT/
FAST
Process
Figure 1-1 Communication between tools via BUS/FAST
In the coming chapters, reference will be made to this picture and the
tools mentioned.
As shown in the Figure1-1, the process signals enter the FAST/TOOLS

environment via EQUIPMENT/FAST. As described in the
EQUIPMENT/FAST programmer’s guide, the process signals are
Engineering converted from process variables into ‘engineering units’. An
units engineering unit can be regarded as a representation of the value of a
process variable. Let us suppose that the process variable was derived
from a thermometer in a boiler, giving the temperature of the water
inside. Suppose also that the process variable is represented by a value
in the range of 0 to 1024, indicating a temperature between 20 and 100
degrees. The conversion from ‘0’ to the engineering unit ‘20’ and from
‘1024’ to engineering unit ‘100’ is carried out in EQUIPMENT/FAST.
The engineering units are the values which all tools use in calculations.
In order to make these values available to all tools or applications, all
engineering units are stored in a memory resident table: the item table
(also known as the common data area ITMCOM).
Items, as we have said, are representations of process variables, but not

Environment of ITEM/FAST Introduction
only by means of their value. Items contain additional information about

the process variable in order to give a more detailed description of the
process variable itself.
As an example of additional information, consider the status of the water
temperature in the previous example. Suppose you want the status of the
water to be called NORMAL if the temperature lies between 60 and 80
degrees, HIGH if the temperature rises to above 80 degrees and LOW
when it drops below 60 degrees.
In this case, you have added significant information, giving a more
detailed picture of the process variable. This combination of information
is called an ‘item’. However, as will become clear in subsequent
sections, an item comprises much more than simply status and value
alone.
1.2 Environment of ITEM/FAST
1.2.1 The basic tools
As shown in figure 1-1, the basic FAST/TOOLS environment comprises

the following 5 tools:
ITEM/FAST
EQUIPMENT/FAST
USER/FAST
DATABASE/FAST
BUS/FAST
The functionality of the tools is as follows: ITEM/FAST creates an

image of the process in the item table, each item representing a process
variable. EQUIPMENT/FAST takes care of the communication with the
process. USER/FAST takes care of the interface on the user side: it
provides for a forms-based Man Machine Interface. This interface is
used to enable a system operator to define items. This definition not only
affects items in the item table, but also defines links between items and
other tools, for example ALARM/FAST. For more information about
the item definition we refer you to the User Manual. DATABASE/FAST
is necessary to store the additional information about items on disk. As
an example: we added the temperature limits (60 and 80 degrees) and the
corresponding statuses LOW, NORMAL and HIGH to the item. This
information is said to be part of the item definition, and should as such
not only be present in the memory resident item table, but should also be
stored on disk. This allows for a cold system-restart without the loss of

Introduction Environment of ITEM/FAST
item definition information.

Last but not least: BUS/FAST takes care of the interprocess
communication, and is therefore not represented in the figure as a tool.
1.2.2 Interfaces with ITM
All items reside in the memory resident item table and are available to
all other tools or application programs. That means that application
programs are capable of manipulating items by accessing the item table.
Two means of access are available:
• Via a routine interface.

This interface is the quickest and will always be used when higher
performance is required. An example is the interface between
EQUIPMENT/FAST and ITEM/FAST where the process variables
are stored in the item table.
• Via the BUS/FAST interface.
This interface has the advantage of modularity: bricks can be added
to an existing application without needing to rebuild existing
processes.
An example is the interface with USER/FAST.
Note that the routine interface is only a subset of the BUS/FAST

interface and that the BUS/FAST interface is taken care of by the
process called ITM.

Basic principles ITEM/FAST mechanism
2 ITEM/FAST mechanism
2.1 Basic principles
2.1.1 Item structure
An item can be divided into a number of parts:
1 General attributes.
2 Value/status/quality code.
3 Limits, deadband.
4 Criterion info (e.g. PIT filter values).
5 Event requests.
General
Attributes
Value/Status/Quality PHASE
UPDATE ONE
Limits, Deadband
Criterion Info PHASE

(PIT filter etc.) TWO
Event Requests PHASE

THREE
Figure 2-1 Item structure

The general information (general attributes) consists, among other
things, of the identification number, the value representation and
possible options. These options will be discussed at a later stage.
The value, status and quality code information consists of the value (in
engineering units), status and quality code of the process variable.

ITEM/FAST mechanism Basic principles
The limits and deadband are used to determine the status at the moment
an item is updated.
Criterion info is used to store information about certain conditions of the
item after an update.
The PIT filter is used to perform data reduction.
The event actions indicate which processes have to be triggered if
certain criterion flags are true.
As can be seen from the diagram, after an update an item is evaluated in

three different ’phases’. An explanation of each of these phases is given
below.
2.1.2 Phase 1
Status Let us suppose that EQUIPMENT/FAST wishes to change a certain

determination item and that the value, is changed as a result. An update takes place
whereby an item with a certain item-id is changed.
As a result, the following actions are performed:
• The old and new value are saved in the item.

• If a new status is indicated in the update, that status is saved.
• If requested, an automatic determination of the status is performed.
• If specified the new quality code is saved in the item.
For automatic determination of the status to take place, the following

information must be available:
• number of limits (0, 2 or 4)

• limit values
• deadband value
With this information, the status corresponding to a particular value can

be calculated. This calculated status will be one of the statuses defined
by Yokogawa. It is, however, always possible to omit this action and to
impose a ’user defined’ status. This mechanism of automatic status
determination is described in detail in the section on item statuses.
2.1.3 Phase 2
In this phase, the conditions of the item compared with the previous
update are evaluated.

Basic principles ITEM/FAST mechanism
Criteria A number of criteria are recognized, each of which may be used as a

evaluation criterion in phase three. The criterion symbols that refer to a certain
condition are indicated in upper case, e.g. ITM_CRI_FIRST. The
following criteria are possible:
• The very first update: ITM_CRI_FIRST.

This criterion is true if the status before the update was equal to
ITM_ST_NOT_INIT and the status after the update is not equal to
ITM_ST_NOT_INIT. If ITM_CRI_FIRST is true, all other
criterions are always false.
• Each update: ITM_CRI_EACH.
This criterion is true after each update and therefore independent of
whether the value/status has changed.
• Value change: ITM_CRI_VAL.
This criterion is true if the value has changed.
• Status change: ITM_CRI_STA.
This criterion is true if the status has changed.
• Value change: ITM_CRI_QC.
This criterion is true if the value of the quality code has changed.
• Item deleted: ITM_CRI_DEL.
This criterion is true if the item has been deleted from the file.
• PIT criterion: ITM_CRI_PIT.
This criterion is dependent on the filter result (TRUE or FALSE)
that corresponds to the item. If no filter is defined for the item, then
this criterion is true if the ITM_CRI_VAL criterion is true.
• One of the option flags has been changed: ITM_CRI_OPT.
In addition to the value-related statuses, there are flags giving
information on the item as a whole (e.g. offline). These flags are not
automatically determined, but imposed by an application program
(see section on item statuses).
• Fast scanning wanted: ITM_CRI_FST_SCN.
When an equipment supports dynamic scanning of field events
(“on-demand” fast scan) then applications can indicate when they
want to use the fast scanning mode of the equipment driver. This
can be useful for operator displays that are only required to show
the most up-to-data information when they are visible and the
scanned data is in use. For applications presenting information
directly such as a HMI this option should always be used when
subscribing to item events.
• Change of dynamic scan: ITM_CRI_CNG_DSC.
This criteria is typically used by equipment drivers that need to
detect when a client application has requested fast scanning and
change read behaviour accordingly. When applications subscribe

ITEM/FAST mechanism Item values
or un-subscribe to item events using the ITM_CRI_FAST_SCN

criteria, then the application subscribed using
ITM_CRI_CNG_DSC to the same item will receive an
ITM_EVT_DSC event when the first application subscribes and
when the last application un-subscribes. This is used to maintain
fast scanning from the field when at least one application has
expressed this preference.
Once all criteria have been evaluated, and the corresponding flags have
been set, the final phase is started.
2.1.4 Phase 3
Send Establishing whether certain processes have to be ’triggered’ takes place

messages during this phase. It is possible for each process to make it known to
ITM that it is interested in a particular item. In other words, it can
’request’ an event action. In this request, the process has to indicate
which criteria have to be met to result in it being triggered. For this
purpose, the process produces a criterion mask.
The process is only triggered if one (or more) of the specified criteria is
met. It is of course possible for more than one process to be triggered by
the same item, each process having a separate criterion mask.
Such a trigger is also called an ’event’. When an event occurs, a BUS/
FAST message is sent to a process. This action is also known as an
’event action’, the message itself is known as an ’event message’.
In view of the fact that ITM has just determined all the criteria (in phase
2), it is now in a position to determine whether the criterion mask
conditions for each interested process has been fulfilled. If this is the
case, an event message is sent to that process. This message consists of
pieces of information (components).
With this request, (i.e. when it announces that it is interested in this item)
the process indicates which information it wishes to receive at the
moment the criterion mask conditions are met.
2.2 Item values

Items are given names corresponding to the way in which a value is
represented, i.e:
TLS_BOOLEAN

Item statuses ITEM/FAST mechanism
TLS_SHORT (16 bits)

TLS_LONG (32 bits)
TLS_FLOAT (32 bits)
TLS_DOUBLE (64 bits)
CHAR (8 bits, only for array items)
STRING (variable length)
This representation is the default representation. This means that an

application that reads the value obtains it in the predefined
representation. However, procedures are provided to convert one type of
representation to another.
This also applies to the updating of values: it is not necessary to update
the item in its default representation.
Depending on the type of default representation chosen, certain options
are available. A TLS_BOOLEAN or STRING item, for example has no
limits.
Array So-called ARRAY items deserve special mention. These items can have
items any of the representation types mentioned above, including CHAR.
These array items possess no limits, deadband or PIT filter. Their value
consists of an array in which each element can be approached
individually. The buffer in which this array is stored is cyclic and its size
is determined by the item definition. Special procedures are available for
these items.
circular
update array of
elements
Figure 2-2 An array item
2.3 Item statuses
2.3.1 Value-related statuses.
It is possible for the updated value of an item to be checked

ITEM/FAST mechanism Item statuses
automatically against any given limits. Depending on the outcome, ITM

will set the status of the item accordingly. If necessary, however, this
automatic function can be disabled, since ITM allows application
programs to impose a (user defined) status.
The user can define up to 155 statuses. 20 statuses have been reserved
User
status for ITM, another 80 for Yokogawa.
Normally the statuses mentioned above are directly related to the value.
If, for example, the user has defined the status OVERFLOW, then this
overflow relates to the value. That is the reason that these are so-called
’value-related’ statuses.
The interpretation of statuses imposed by application programs is free,
in contrast to that of the automatically determined statuses, which is
fixed, and best explained using the example below.
In this example, we take an item with an analog value. This value can
vary between zero and 100.
100
HH
LIMIT ONE 80
H
LIMIT TWO 60
N
LIMIT THREE 40
L
LIMIT FOUR 20
LL
0
Figure 2-3 Value/status relation using limits
Automatic With the aid of limits, we are now in a position to determine the status.
status In the example quoted, the status will be N (Normal) if the value lies
between 40 and 60; H (High) if the value lies between 60 and 80; and
HH (High-High) if the value exceeds 80. Similarly, the status will be L
(Low) if the value lies between 40 and 20; and LL (Low-Low) if the
value is lower than 20.
In order to prevent resonance should small variations around the limit

value occur, a so-called deadband has been introduced.
100
HH
LIMIT ONE 80
H
LIMIT TWO 60
N DEADBAND
LIMIT THREE 40
L
LIMIT FOUR 20
LL
0
Figure 2-4 The deadband
When the value is such that it lies in the deadband itself, no change of
status occurs.
This results in a kind of hysteresis. If the status is H, for example, it will
become HH only if the value is greater than ’limit 1’. If the value (with
an HH status) subsequently drops, it will become H only if the value falls
below ’limit 1 - deadband’. Note that the deadband does not lie
symmetrically opposite the limit but always pointing towards the N
(Normal) situation. The reason for this asymmetric positioning is that
the deadband is not taken into account when the value changes to
’abnormal’, an alarm situation is immediately detected. Returning to
’normal’ is delayed by the deadband.
Automatic status determination is also possible in the case of
TLS_BOOLEAN items. In that case the status indicates whether the
value is FALSE or TRUE.
It is possible to ’over-rule’ the calculated status with an application
specified status. In other words an application program can force the
status of an item.
Also, the application can indicate to leave the item status unchanged.
Note that the value of an item never will pass the outmost limits when
clamping is defined for the item.

ITEM/FAST mechanism Item statuses
2.3.2 Additional statuses
As well as the status corresponding to the value of an item, certain

statuses may be desired that are related to an item as a whole. In fact,
these could over-rule any earlier calculated or fixed value-related
statuses. It is for these special situations that option flags have been
introduced. Some option flags can be set externally, others are set or
reset automatically. All of these flags are accessible by the application
program.
The following flags exist:
Description Value Note
BLOCKED ITM_OPT_BLOCK Programmer’s option

UPDATED BLOCKED ITM_OPT_UPD_BLK Automatic ITM action
OFFLINE ITM_OPT_OFFLINE Programmer’s option
UPDATED OFFLINE ITM_OPT_UPD_OFF Automatic ITM action
ACKNOWLEDGE ITM_OPT_ACKNOW ALARM/FAST option
ALARM TYPE 1 ITM_OPT_ALM_T1 ALARM/FAST option
ALARM TYPE 2 ITM_OPT_ALM_T2 ALARM/FAST option
ALARM FORCE ITM_OPT_ALM_FNS ALARM/FAST option
NORMAL
Apart from the possibility of checking the state of these flags, it is

possible to generate events when one of these option flags is changed.
Note that setting/resetting these flags has no relation to value updates.
They may be accessed at any time.
Blocked Suppose it becomes necessary to fix an item temporarily at a certain

status value. This can occur if a machine is temporarily out of operation (for
maintenance reasons, for example). In such a situation it is possible for
the operator to ’block’ the item, in which case the item will no longer be
updated by the process. The value of the relevant item, however, must
remain defined in order to allow COMPUTE/FAST or other application
programs, to continue working normally. For this reason, a special
procedure is available, to update the item even though it is blocked. This
action could, for example, be performed by the same operator. As a
result the flag UPDATED BLOCKED will be set automatically.
Both the flags BLOCKED and UPDATED BLOCKED can be checked

by application programs. For the programmer, however, this is not a

’friendly’ procedure. Before checking the value-related status he or she
must always first check the option flags to be sure the item was not
blocked. To provide a more ’programmer friendly’ procedure, a ’merge’
option is available. This option merges the value-related status with the
option flags as stated in the merge table shown on the next page.
Consequently, the operator only has to check the merged status.
Note that if a BLOCKED item is over-written it obtains the status
ITM_ST_UPD_BLOCKED. It will maintain this status even if the item
becomes UNBLOCKED. Only when a subsequent update occurs will
the merged status be equal to the value-related status.
Offline Whereas an operator is able to block an item, he can not declare an item
status offline. This can only be done by the process that is responsible for
updating that item (in most cases, this will be EQUIPMENT/FAST). If,
for example, the link to a machine that is being monitored by
EQUIPMENT/FAST is broken, the value that the corresponding item
has is no longer reliable. In that case EQUIPMENT/FAST will declare
the item OFFLINE.
In the same way as for the blocked status, it is possible to update the
value of an item that has been declared OFFLINE. Again there is a
special procedure available to do this. If the value is updated in such a
case, the option flag UPDATED OFFLINE becomes true.
Again these flags can be merged with the actual status as shown in the
merge table below.
Acknowledge The next option flag is the status acknowledge. This flag is not actively
status monitored by ITM. There is a special routine available to set or reset this
type of flag. This flag can be regarded as an extra option flag for
application purposes. A typical program controlling this status flag is
ALARM/FAST. If ALARM/FAST is used in the system, the user may
not change this flag. ALARM/FAST will set this flag if the status of the
item is acknowledged and reset the flag if not.
If this flag is changed, the ITM_CRI_OPT criterion will be set.
Note that the merge option has no relationship to this option flag.
Alarm type These option flags represent the alarm type. These flags are not actively
status monitored by ITM. There is a special routine available to set or reset
these flags. These flags can be regarded as extra option flags for
application purposes. A typical program controlling this status flags is
ALARM/FAST. If ALARM/FAST is used in the system, the user may
not change these flags. ALARM/FAST will put the alarm status in these
flags. The table below shows the bit settings. The meaning of the alarm

ITEM/FAST mechanism Item quality codes
status (NORMAL, DIRECT, ALARM) can be found in the ALARM/

FAST programmers guide.
If the alarm type status flags are changed, the ITM_CRI_OPT criterion
will be set.
Note that the merge option has no relation to this option flag.
ITM_OPT_ALM_T1 ITM_OPT_ALM_T2 Alarm status
0 0 NORMAL
0 1 undefined
1 0 DIRECT
1 1 ALARM
Alarm force This option flag is used by ALARM/FAST. When this option flag is set
normal status then the alarm status for the item is NORMAL under all conditions. It is
used to disable alarm monitoring for the item temporary. The routine
itm_set_gen() is used to set or reset this option flag.
If the option flags is changed, the ITM_CRI_OPT criterion will be set.
Merge In the table below, the status ’A’ indicates a value-related status. The
table ’result status’ shows the result after the merging of the status and the
option flags.
Value
Updated Updated
related Blocked Offline Result status
blocked offline
status
A * YES * * ITM_ST_UPD_BLK
A YES NO * * ITM_ST_BLOCKED
A NO NO YES NO ITM_ST_OFFLINE
A NO NO * YES ITM_ST_UPD_OFF
A NO NO NO NO A
2.4 Item quality codes

Beside the status an item has a quality code. The quality code can be
used to represent the quality of the item value and status.
The quality code is a TLS_ULONG value.

Value clamping ITEM/FAST mechanism
The quality code is not calculated, by the item-handler, in the same way
as the status. Therefore an application must supply a quality code, like
an equipment manager.
2.5 Value clamping

Sometime it is desired that the value of an item or subitem will always
be limited within a certain range even when someone requests for a new
value outside that range. In that case the value will receive the limit of
that range. This mechanism is called value clamping. Value clamping is
not available for TLS_BOOLEAN and STRING items and subitems.
The outmost limits will be used for the value range. Thus, when 2 limits
are specified than the value will always be held between and including
the Low and High limit. When 4 limits are specified then the value is
always held between the Low-Low and High-High limit. Value
clamping can be enabled for each item or subitem individual.
2.6 Relative values

Besides the absolute value, limit or deadband of an item or subitem a
relative representation of these attributes is available in the range 0 to
100 in relation to the outmost limits (% representation). Relative values
are not available for TLS_BOOLEAN and STRING items and subitems.
When 2 limits are specified the Low limit corresponds with 0 % while
the High limit corresponds with 100 %. When 4 limits are specified the
Low-Low limit corresponds with 0 % while the High-High limit
corresponds with 100 %. The following table lists the algorithms used
when an attribute is obtained or modified in %:
0 limits 2 limits 4 limits
obtain val 0 % = (val-l) / (h-l) * 100 % = (val-ll) / (hh-ll) * 100

modify val illegal val = l + (h-l) * % / 100 val = ll + (hh-ll) * % / 100
obtain db illegal % = (db-l) / (h-l) * 100 % = (db-ll) / (hh-ll) * 100
modify db illegal db = l + (h-l) * % / 100 db = ll + (hh-ll) * % / 100
obtain ll limit illegal illegal %=0
modify ll limit illegal illegal ll = ll + (hh-ll) * % / 100

ITEM/FAST mechanism The PIT filter
0 limits 2 limits 4 limits
obtain l limit illegal %=0 % = (l-ll) / (hh-ll) * 100

modify l limit illegal l = l + (h-l) * % / 100 l = ll + (hh-ll) * % / 100
obtain h limit illegal % = 100 % = (h-ll) / (hh-ll) * 100
modify h limit illegal h = l + (h-l) * % / 100 h = ll + (hh-ll) * % / 100
obtain hh limit illegal illegal % = 100
modify hh limit illegal illegal hh = ll + (hh-ll) * % / 100
2.7 The PIT filter

Event actions are performed whenever a certain criterion is met. Apart
from the criteria that are a direct result of an update (e.g. value change,
status change), it is possible to take the history of previous updates into
account. In order to be able to do so, the PIT filter has to be used.
The PIT filter can be seen as a filter made up of three components. The
filter result is unambiguous however. The filter is activated only if a
Reference certain combination of the three components is true. Note also that the
time time at which activation occurs then becomes the new reference time.
That will be the new time from where the history is taken into account.
The three filter components are the P-filter, I-filter and T-filter
2.7.1 P-filter
For the P-filter, the reference value is equal to the item value at the
reference time. The result of the P-filter is true if the newly arrived value
differs from the reference value by more than a set value P. (see example
overleaf)

The PIT filter ITEM/FAST mechanism
suppose P = 1.5
p detected
2
p detected
t0 t1 t2 t3 t4 t5 t6
initial
reference new new
time reference reference
time time
Figure 2-5 P-filter example
If the value at time t2 becomes 3, the difference between it and the initial
reference value is greater than 1.5. The P-filter result is then true. Note,
however, that this does not necessarily mean that the whole PIT filter is
true. If this is indeed the case, then t2 will be taken as the new reference
point for the whole filter!
The P-filter result is therefore:

TRUE if | update value - reference value | > P.
FALSE if | update value - reference value | <= P.

2.7.2 I - filter
The I-filter (mathematically) integrates the incoming update values with

respect to time. If the integrated value is now greater than a
predetermined value I, the filter result is TRUE.
Item Value
4 Analog Sampled
Value Value
Integrated
Value
5
Reset
4
I = 2.5
3
2
t0 t1 t2 t3 t4 t5 t6 t7
ref time ref time ref time
Figure 2-6 I-filter example

The PIT filter ITEM/FAST mechanism
Suppose that at t0, the value is 0 and that t0 is the reference time. Given
the above value changes, the I-filter result will be true if the integrated
value is greater than 2,5. This is the case at time t2. If, as a result of the
I-filter, the whole PIT filter becomes true, then t2 becomes the new
reference point.
The I-filter takes the current instantaneous value as the reference, so that
at time t4, the I-filter is again TRUE.
The I-filter result is
⎛ ⎞
TRUE if ⎜ ∑ 〈 reference_value – new_value〉 * ∆t ⎟ > I
⎝ t
⎠
⎛ ⎞
FALSE if ⎜ ∑ 〈 reference_value – new_value〉 * ∆t ⎟ <=I
⎝ t
⎠
Where: new_value is the current instantaneous value, reference_value is

the value at the reference time and ∆t is the time between the previous
update time and the time of the current instantaneous update.
Note that integration only takes place at the moment of an update. The
integration itself has a resolution of one second. This means that the time
between two updates is truncated to the nearest whole second.
2.7.3 T-filter
The T-filter can be considered as a temporary ’OFF’ switch. Once the

PIT-filter is activated this action will not be able to be repeated within a
time T. Even in the situation where both the P-filter and I-filter are
activated within this time, the filter as a whole will have the result
FALSE.
The T-filter is synchronized with updates: if the time has elapsed, a P or

I- filter result will only be accepted at the moment of an update.

5
4
Value 3
2
1 t1 t2 t3 t4 t5
50 90 110 130 150
True P = 1,5
P
False
T True
T = 25
False
True
Total
Filter
False
New reference
Figure 2-7 T-filter example
Initially, everything is set at t0. The timer goes off after 25 seconds.
However, since there are no updates, the T-filter goes off effectively at
t1. In addition, a P criterion is detected so that the PIT filter result
becomes TRUE. At time t2 another update takes place but the value does
not change and the P-filter is not activated. The T-filter is now FALSE.
At time t3 another update takes place. The P-filter is activated, the T-
filter was FALSE, therefore the PIT filter becomes TRUE and t3
becomes the new reference time. At t4 another update takes place. The
T-filter is still TRUE, however and the PIT filter therefore does not
react. At t5 the T-filter is again FALSE, however the P criterion does not

Event requests ITEM/FAST mechanism
fulfil the conditions: the difference in value with respect to the previous
reference time is smaller than P.
From the above it can be seen that the use of a T-filter makes data
reduction possible. All the above applies for the P or I filter in
combination with a T-filter.
2.8 Event requests

When after an update certain criteria are met, certain event actions are
carried out.
Each application process can request such an event action with regard to
a particular item. This request remains active until it is deleted. An
example is COLOUR/FAST. Let us suppose that an image is shown on
the color display representing the boiler with water from a previous
example. The color of the water has to be red if the temperature status is
HH (between 80° and 100°), orange if H, yellow if N, blue if L and white
if LL.
In view of the fact that COLOUR/FAST is interested in the status of the
temperature item, it requests an event with the corresponding criterion
mask (action if a status change occurs). At the same time, COLOUR/
FAST makes it known that it is interested in the status. As a result, an
event message containing the new status is sent to COLOUR/FAST after
each status change. COLOUR/FAST is itself responsible for the colour/
status relationship. Note that if another color image is selected which
does not feature the boiler, the event request must be deleted.
It goes without saying that more than one process can be interested in the
same item. The temperature item already mentioned can, for example,
also be used in a complete PROCESS/FAST method, in which, for
example, the heating element of the boiler is activated if the temperature
falls below 40° and is switched off if this rises above 60°. Evidently, this
process is interested in the value change as criterion. Similarly, other
processes can exist, each with its own criteria.
A special option concerning the event actions is the ’alias’ function. In
this case, if a process requests an event action to an item, it is possible to
indicate a different address as sender. The event message will then not
be sent to the real sender but to another process.
To sum up, an event request contains three blocks with significant
information:
• The process address to be triggered (with an event message).

• What criteria the message must meet for it to be sent.

ITEM/FAST mechanism Event requests
• What information must be present in the event message.

This information may contain the old/new value the old/new status, a
time tag etc. In addition, there are four ways to pass extra information in
the event messages and these are described in the following subsections
2.8.1 Application information
In addition to the information above, each item has space reserved for
application info.
Main events
General
info Application
Application info info
Event
message
Application
info
Process
Event request Event

message
Stored on
disk
Figure 2-8 Application info
This information can be stored very simply and can, if necessary, be sent
with an event action. Note, however that this information can also be
requested if a main event occurs. The application info may consist of
text, structs or other data types. Internally the application info is aligned
on the TLS_LONG boundary. This information is obtained by
specifying ITM_EVT_APP_INFO in the event request.
2.8.2 Application flags
There is no great difference between application flags and application

info. The flags consist of a TLS_LONG (32 bits). This TLS_LONG can

be sent in the same way, in an event message, for both a normal event
action and a main event. The difference between the application flags
and the application info lies in the way the information is set in the item.
ITM offers the possibility to set or reset the bits (flags) in the
TLS_LONG independent of each other. The TLS_LONG is always sent
in its entirety. Requesting this information is done by specifying
ITM_EVT_APP_FLG.
2.8.3 Update information
In addition to application info and application flags, it is also possible to

send update info.
Item
Update
A Value/status
Value/status
Info
Event request
B
Figure 2-9 Information update
When process A updates the item value/status, a certain amount of

information can be sent. This information is lost after an update.
However, if process B has indicated this in the event request (by
specifying ITM_EVT_UPD_INF), this information can be sent to
process B with the event message. In order to standardize the use of this
buffer, we use the following conventions:
The information in the buffer resembles a clustered (M) DUR message.
Each of the messages starts with a size and a code followed by a body.
For already defined message codes see reference guide.
In order to guarantee consistency, the codes 0-999 are reserved for

ITEM/FAST mechanism Event requests
Yokogawa, the remainder are free. (see also FAST/CONVENTIONS

manual).
ITM will automatically take care of the system type conversion of

Yokogawa defined update information in an architecture with mixed
hardware, but a special provision is necessary for application’s update
information.
Consider the following example:
X item Y item Z
update event
A + ITM + B
update update
info info
Figure 2-10 Hybrid environment
X, Y and Z are nodes of a different type. Process A updates items using

ITM on node Y. Process B has requested the item update events from
ITM, including the update information.
ITM cannot convert the application’s update information from process
A to the representation of node Y, nor can it convert it to the
representation of node Z, since the layout of the application’s update
information is unknown to ITM.
As a result, process B receives the data in the representation of node X
and has to take care of the conversion to its own data representation.
ITM calls a special function when it encounters a non-Yokogawa update

information code. This function can be adapted by the user to define the
codes and layout of the application’s update information in order to
enable ITM to perform the conversion.
Any unknown update information code at this stage is ignored, it is
assumed that the receiving process will take care of the data conversion.
The function is called itmu_cnv_upd; a default version of itmu_cnv_upd
is available on the FAST/TOOLS source directory (itmu_cnv_upd.c).
A number of steps must be executed to add application update

information to this conversion function:
1 Add the definitions of the codes and data descriptions in file

itmu_cnv_upd.c. Add entries in the switch statement.
2 Compile itmu_cnv_upd.c on the FAST/TOOLS source directory
and replace the object file in the ITM object library. For example
on a UNIX system:

cc itmu_cnv_upd.c -c -I/tls/inc
ar rl /tls/lib/itmlib.a itmu_cnv_upd.o
ranlib /tls/lib/itmlib.a (not necessary on every UNIX
system)
3 Stop FAST/TOOLS
4 Rebuild ITEM/FAST. For example on a UNIX system:
item_build
5 Rebuild related tools and application processes
6 Start FAST/TOOLS
2.8.4 Requester information
The last option for passing application information to a process is the

requester info. This information is stored with an event action.
Item
Update
Event request
Req. info
Main events
B
Stored on
disk
Figure 2-11 Function of requester info
The requester info is information that a process (in this case process B)
has specified in the event request. This information is returned in the
event message only if the ITM_EVT_REQ_INF was specified. A
typical use of this requester info is for the storage of internal keys. Let

ITEM/FAST mechanism Main events
us suppose that an application keeps track of a number of items. When

an event occurs, that application has to find the particular item in its own
internal database. By passing, for example, the internal pointer in the
requester info, the application directly finds the related information
when an event message is received. Note that requester info can not be
used for main events.
2.9 Main events

In certain cases a particular event action has to be carried out for many
items. An example of this is alarm activation. Many items will have as
an event action, the triggering of ALARM/FAST, whereby, for example,
value and status must be transmitted. Such event actions will normally
not be changed in run time.
In addition, these actions are always valid, even when the system has
been down. Note, after a restart all items for which alarm activation was
ever specified must have the same event actions as before activation.
That is why the notion ’main event’ has been introduced. A maximum
of 16 main events per system is possible. Such a main event resembles
a normal event action, the major difference being that a main event is
only present once for all items.

Main events ITEM/FAST mechanism
General General
attributes attributes
Main event mask Main event
Main event mask
mask
Criterion
result
Criterion
mask
Event requests Event action

COLOUR/
FAST ------------------
0 1 2 15
Saved on
disk
Figure 2-12 Main event information storage
As shown in the figure above, all fixed information about an item is

stored on disk. This means that this information is again present after a
’warm’ start. The event actions, however, are not stored. This is due to
the fact that these actions are always dependent on the situation at a
given moment.
The general attributes section contains a main event mask in which is

indicated which main event(s) have been requested. This section is
saved on disk and is therefore again present after a ’re-start’. The main
event information itself is also saved on disk. The main events are
assigned numbers between zero and 15. If an item has to generate a main
event, all that is necessary is to indicate that bit number in the main event
mask. The main events already defined can be found in itm_usr.h. This
takes considerably less time than requesting a ’normal event’ action.

ITEM/FAST mechanism Event buffers
2.10 Event buffers

In some systems, communication performance may deteriorate
considerably as a result of sending many event actions per second.
Let us imagine that COLOUR/FAST is operating on different system
from ITEM/FAST.
Node 1 Node 2
Item table link

Colour/Fast
BUS/FAST
Event buffer
Figure 2-13 Use of event buffers in a system
Let us then suppose that there is an image on the color VDU with a
number of rapidly changing items. Each item change results in an event
action that is sent via BUS/FAST. This means that the (admittedly
small) overhead of BUS/FAST over a relatively slow link appears
repeatedly for each item. For this reason event buffers have been
introduced. These buffers enable all events which have to be sent to the
same process to be ’clustered’.
Consider another example. Suppose that the buffer can accommodate 25
items. In that case the overhead will only operate once for all 25 items.
The contents are sent as soon as the buffer is full. However, in order to
be certain that the items are sent within a certain time, a partially filled
event buffer is sent after a time-out has elapsed, irrespective of whether
it is full or not. In the previous COLOUR/FAST example, therefore,
setting the time-out at one second would result in the items being
updated once every second.

Flow control ITEM/FAST mechanism
2.11 Flow control

ITEM/FAST supports a flow control mechanism to give an application
process the possibility to check if events are lost. When flow control is
requested by calling the routine itm_req_flow() (or sending the BUS/
FAST request ITM_COD_REQ_FLOW), at least each selected time
period an event or a flow control message will be sent to the caller. All
events will be numbered and the actual event number will be sent with
the event and flow control messages. The first event will get the number
1 and in the flow control message the number of the last event sent will
be stored. When event buffering is used, the events stored in one buffer
will have increasing event numbers, so one event buffer can contain
more than one event number.
2.12 Subitems
A subitem is fundamentally no different to any other (main) item - it can
be defined, changed, requested etc. The difference lies in its relation to
a main item. For every main item it is possible to define one or more
subitems up to a maximum of 16. Such a subitem is then processed when
the main item is updated. This can be best described by means of an
example.
EXAMPLE
Let us imagine a process variable whose value corresponds to the time a

particular machine has been in operation. If the machine is in operation
the value is ’1’; if not, ’0’. Using PROCESS/FAST , COMPUTE/FAST
or an application program it is possible to read off the item at intervals
of one second. If the value is ’1’, a ’second’ counter is increased by 1.
This is a relatively ’heavy’ operation to deal with a simple problem, i.e.
the integration of a signal.
The subitem is introduced to solve this kind of problem. Starting from a
main item, a relationship is established with a subitem of one of the
following types
1 integrator
2 pulse counter
3 min/max indicator
4 rate of change
5 typeless

ITEM/FAST mechanism Subitems
In the above mentioned example defining an integrator is the

recommended course of action. Such an item integrates the value of the
main item at intervals of a second. If a process is interested in the time a
machine has been operational, only the subitem needs to be read off. The
actions carried out by subitems are by definition simple as it is important
that the overall performance of ITEM/FAST should not be too heavily
influenced.
Let us look at these subitems in more detail:
1 the integrator
The new value is determined by multiplying the time difference (in
seconds) between the last update and the new update with the last
value and then adding this to the previous integration
value.
Value
1 Time now
0
1 2 3 4 5 6 7 8 9 10 11 12
-1
-2
-3
t Last update
Figure 2-14 How the ’integrator’ sub item works
Thus the algorithm becomes:
new_int_value =
(time_now - time_prev) * prev_value + old_int_value
in which:
new_int_value :Calculated integration value
old_int_value :Last calculated integration value
time_now - time_prev :Time between last two updates in

Subitems ITEM/FAST mechanism
seconds
prev_value :Value of the previous update
Two factors are of particular importance here

- Negative values are subtracted
- Integration always occurs at intervals of one second.
In addition, the problem arises that a calculation takes place only
after an update and does not occur automatically every second. This
problem is best described by means of the following example.
EXAMPLE
Let us suppose that at ’time_now’ (see figure) the value of the

subitem is requested. Because a new update has not occurred, the
value is still equal to the value at time t. This is the reason that, at
the same time that a subitem is read off, the subitem is updated with
the current value of the main item and a reliable value can be read
off.
2 the pulse counter.
This subitem counts the number of pulses in a main item (by

definition, this is always a boolean item).
The action can be stated in the following manner:
if new_item_value == 1 && previous_value == 0

then pulse_counter = pulse_counter + 1
3 the min/max indicator.
The subitem continually checks whether the value of the

corresponding main item is greater than the highest value noted to
date (in the case of a maximum indicator).
The monitoring process is set in motion from the instant the
subitem is defined and remains in this state until reset. The counter
is then automatically set at the current main item value.
A subitem can be changed from a maximum indicator to a
minimum indicator when it is reset.
EXAMPLE
The value max_item_value of a maximum indicator:
If new_item_value > max_item_value

then max_item_value = new_item_value

ITEM/FAST mechanism Storage on disk
The minimum indicator works in the same way.
4 the rate of change
The value of the subitem will be calculated as follows:
new value = (MIVn+1 - MIVn) / ((MITn+1 -MITn) / TU)
where:
MIVn+1 is the new value of the main item;
MIVn is the old value of the main item;
MITn+1 is the timestamp of the new value change of the main
item;
MITn is the timestamp of the previous value change of the main
item;
TU is the time unit in seconds.
The time unit is specified during the insert of the item.
2.13 Storage on disk

Item information can be stored in different ways. Some actions are
updated on disk, others can be forced by an application program. Note
that the saving of item information is only supported for the BUS/FAST
interface. None of the available routines is able to have access to the item
database, as the file may only be opened by one process: ITM. A value
update is an exception on this. If the item is configured so that value
updates must be stored on disk, then the disk will be updated even if a
routine interface is used.
In the following situations, information is stored on disk:
• Item definition after an Insert, Modify or Delete.

In this case, the whole item is set on disk.
• Main events.
If a main event has been defined, a copy will be set on disk after the
definition. This is necessary since any main event flags in the item
are also stored on disk.
• Event buffers.
The event buffer parameters are stored on disk.

Storage on disk ITEM/FAST mechanism
• Blocked status.
Each change in the BLOCKED/UNBLOCKED status is stored on
disk. Note that an OFFLINE status change is not stored. The entire
item is saved on disk.
• Main event request.
If a main event is requested, i.e. the corresponding bit is set in the
main event mask, the entire item will be saved on disk only when
the disk save flag is set in the associated main event.
Item
Main event
mask
Disk
Disk save Y
0 Main events 15
Figure 2-15 Disk storage mechanism
• Store items request.

The value and status of each item can be stored on disk using a
special procedure.
• Store all items request.
It is possible to set all items from the whole item table on disk. This
is done in order to obtain a very defined status after a restart. This
action will not normally take place during run-time. This ’save-all’
option makes it possible to leave the ITM common area in a locked
state, thereby making it impossible for a process to carry out an
update after this storage action.
• Application flags/info.
If application flags/info are updated, the possibility exists for
storing the associated item on disk. This option is selected in the
update procedure.
• Value/status/quality code update
If an item is configured so that new values, statuses and/or quality
codes must be stored on disk (by item definition or by ITM’s setup
file) then all value updates will result in an update of the item on

ITEM/FAST mechanism Interfaces with ITM
disk.
• Set general request (ITM_COD_SET_GEN).
When this request has the save flag on, item information will be
saved. The set general request is able to set several parts of the item
information.
• Resetting a subitem
When the function of a minimum/maximum subitem is changed by
a reset, the item information will be stored.
As disk storage is optional, ITM can function without a disk (and

therefore also without DATABASE/FAST). As a result, however, after
every system re-start, ITM carries out a ’cold’ restart, resulting in an
empty item table.
It is important to realize that all the actions mentioned above which lead
to item information being stored result in the whole item being stored
and not just the information significant at that moment. This means that
if a ’save application flags’ is executed after a ’save item value/status’
both the application flags and the old value, status, etc. will be recorded.
2.14 Interfaces with ITM

Two types of interface exist:
• BUS/FAST interface.
• Routine interface.
Of the two, the BUS/FAST interface is by far the most modular and for
this reason we strongly recommend it for use with application programs.
In those cases where performance plays an important role, the routine
interface is usually the better choice. Note that at the present time only
a C-language interface is supported. The routine interface provides only
a subset of the available BUS/FAST functionality.
From the diagram overleaf it can be seen that the BUS/FAST
communication takes place via the main process ITM.

Interfaces with ITM ITEM/FAST mechanism
Application using
BUS/FAST
interface
BUS/FAST
ITM
Item
table Debugger
Disk
Routine
interface
Application using
ITMTIM routine
interface
Figure 2-16 ITEM/FAST interfaces
The communication between an application using BUS/FAST takes

place via messages, i.e. information which has to comply with certain
conditions. The messages are interpreted by ITM and transformed into
routine calls In effect, ITM acts as the routine interface. The advantages
of such an arrangement are obvious, namely:
• An application can be added to a running system making it

unnecessary to ’link’ again.
• The system continues working if the application is in another node.
In that case the data conversion necessary to enable the systems to
communicate with each other takes place in ITM. It is of course
only possible to use the routine interface if both application and
routine interface are in the same node. It goes without saying that
an (admittedly small) amount of overhead is introduced when using
BUS/FAST, particularly when the application software is in
another node.

ITEM/FAST mechanism Item allocation (locking)
As well as ITM, there are two other processes that can be present:
• ITMTIM
This process is responsible for the timing of various actions in ITM,
one of which is the sending of any event buffers at specified
intervals of one second. Note that ITMTIM works on a second basis
and must be permanently active in the system.
• ITMDBG
An additional process that can be present is the debug program
ITMDBG. This process is active only when requested and has a
wide range of possibilities, the most important of which are
explained in chapter 4.
2.15 Item allocation (locking)

For process operations it is often desired that the operator allocates the
setpoint item before he is allowed to change its value. While the operator
has allocated the item, other operators cannot allocate the same item or
change its value or other attributes. This mechanism is protected by an
time-out to avoid that an item is kept allocated forever. Item allocation
is called item locking in the remainder of the document.
An item is locked using the itm_set_gen() routine (or sending the BUS/
FAST request ITM_COD_SET_GEN). This is also the routine that is
used to verify that modification of an item value or other attribute is
allowed. Updates of an item via one of the other routines pass the
locking mechanism unconditionally. To set a lock call itm_set_gen()
with the following information:
set_gen.set_layout Arguments
struct itm_set_gen
ITM_SET_TRM_USR struct itm_set_trm_usr terminal/user info
ITM_SET_LOCK struct itm_set_lock lock information
In struct itm_set_trm_usr the user and terminal of the lock initiator can
be specified.
Field itm_set_lock.lock is set to TRUE and itm_set_lock.lock_id must
be given a unique lock id. In field itm_set_lock.timeout a time-out can
be specified. When this time elapse then the lock is removed. When a
zero for this time-out is specified then the system default is used which
is set in itm.sup.

API Locking ITEM/FAST mechanism
To unlock the item pass the following information:
struct itm_set_gen
The field itm_set_lock.unlock must be set to TRUE and

itm_set_lock.lock_id must be set to the value supplied at the time the
item was locked.
While the item is locked, any update of the item using itm_set_gen()
fails unless the following information is passed:
struct itm_set_gen
ITM_SET_VAL struct itm_set_val new value/status
(others)
The field itm_set_lock.lock_id must contain the same value as supplied

at the moment the item was locked. When the item is updates the lock
time-out is reset to the value supplied in itm_set_lock.timeout. If a zero
is specified then the time-out is reset to the time-out value specified
when the item was locked.
It is possible to update the item and unlock it in one call to
itm_set_gen(). In this case set the field itm_set_lock.unlock to TRUE.
Option flag ITM_OPT2_LOCKED shows whether the item is locked. In

addition to this flag it is possible to obtain additional lock info with
itm_get_itme() and itm_req_evte() using the flag
ITM_EVT_LOCK_INF. Whether the item is locked and if locked, the
user who owns the lock and the terminal where the lock was initiated are
returned in struct itm_lock_inf.
2.16 API Locking

The item table is a ’shared’ memory area (also known as ‘common area’
or item table) that may be used by all attached users. However, any
inconsistency in the data must be avoided at all times.

ITEM/FAST mechanism API Locking
EXAMPLE
Let us suppose that a certain process A reads off an item, and this item
is simultaneously changed by another process B. In that case, it is
possible that, as a result of the scheduler of the operating system, the
item is only changed partially by process B at the moment process A
reads off the item. This results in process A receiving incorrect
information.
In order to overcome this problem a locking mechanism is implemented.

In other words, if a process carries out an action that is related to the item
table the whole common area is locked and no other process can access
the item table. As a result, the whole system is ’dead’ if a process crashes
or is stopped at the moment that it locks the common area. It is up to the
programmer to be aware of this. It should be noted that a debugger is
needed to unlock a locked common area.

General Item and event manipulations
3 Item and event manipulations
3.1 General
The aim of this chapter is to describe the actions the programmer is
required to know in order to be able to perform everything that has been
described in the previous chapters. In the descriptions that follow both
the BUS/FAST interface and the routine interface will be mentioned.
The precise layout of BUS/FAST messages and the routine syntax can
be found in the Reference Guide. BUS/FAST messages will be referred
to by their message code. The following categories of actions can be
distinguished concerning ITM actions:
1 Gaining access to the common data area.

2 Manipulations with items.
3 Manipulations with events.
4 Saving information on disk.
5 Miscellaneous.
All actions that apply to specific items require an item-id to be passed.

The contents of such an item-id are described in the following section.
The subsequent sections describe the action categories mentioned above
but let’s first take a closer look at the item-id.
3.2 The item-id

The item-id is made up of the following components:
• node
• group
• number
• subno
• attno
The item-id together with its members is referred to as "item_id"

"Node" consists of the node number as defined in BUS/FAST. It is
unique within a cluster. In a specific node, all items will have the same
node number.

Item and event manipulations The item-id
The notion "group" will be discussed at a later stage. Let us assume for
the moment that it is 1.
"number" indicates a unique number within, in this case, group 1.
"subno" indicates whether a main item is involved (subno = 0) or a
subitem (subno == 1......16).
The first four components specify an item within a cluster of systems.
The last-mentioned, "attno", specifies the component unambiguously
within an item which is related to the action (this will be explained at a
later stage).
The data mentioned above specify an item unambiguously.
EXAMPLE
Let us suppose that the cluster consists of the following systems, each
with its own item table (see figure below).
NODE 1
Item table
Group 1 Group 2 Group 3
Items Items Items
1 2 34 1 2 34 1 2 34
NODE 2 NODE 3
Item table Item table

Group 2 Group 3
Items Items
1 2 3 4 1 2 3 4
Figure 3-1 Item-id of a system cluster

Each of the systems has its own unique items. In addition, node 1 has a
’shadow’ for items of the underlying nodes. This could have been done

Gaining access to the common data area Item and event manipulations
by defining items within node 1 that can be related to the items of node
2 and node 3 via a conversion table. The disadvantage of this is that it
costs seek time for each item and results therefore in performance loss.
This problem has been solved by introducing the notion ’group’. Let us
suppose that the item table is divided into three groups: group 1, group
2 and group 3. All item numbers can appear in any and all of these
groups.
The items in both nodes are in that group whose number corresponds
with the number in node 1.
Shadowing Let us suppose that a particular process takes care of the shadowing: if
an item X in node 2 is changed, then the same must happen in the item
table of node 1.
The need for conversion tables disappears now that a shadow item can
be simply defined.
Item in node 2 Shadow item in node 1
item_id item_id
node: 2 node: 1
group: 2 group: 2
number: 4 number: 4
subno: 1 subno: 1
attno: 0 attno: 0
Figure 3-2 Item_id example
It is apparent the shadow items are found simply by changing the node
number.
3.3 Gaining access to the common data area

The common data area can be accessed in two ways: via the BUS/FAST
interface or via the routine interface. In the case of the BUS/FAST
interface, there is no need to attach to (or detach from) the common data
area. The ITM process takes care of that. In the case of a routine
interface, however, it is necessary to attach to the common data area
before accessing it.
Attaching is done with routine itm_att(). This routine returns itm
context. This context must be passed to all routines that access the

Item and event manipulations Item manipulations
common data area. In order to free allocated memory again when the
common data area is no longer being used, it is recommended to use
routine itm_det().
3.4 Item manipulations
3.4.1 Creating a main/sub item
Items can only be created via the BUS/FAST interface. Both creation of
a main and a subitem are performed with the procedures
ITM_COD_INS_ITM or ITM_COD_INS_GEN. These procedures
cannot be used to create array items. When creating an item, the
following information is passed:
• Default representation.
This representation applies to the item value as well as to limits,
deadband and PIT filter values.
• Main/subitem indication.
• Number of limits.
• The limit and deadband values (if any).
• The PIT filter values.
• The name of the item (optional).
The subitem indication has two functions:

• specifies if the item is a main or a subitem.
• specifies what kind of a subitem it is.
A main item is indicated with ITM_SUB_MAIN. Subitems are

indicated with ITM_SUB_INTEGRAL (integrator),
ITM_SUB_PULSE (pule counter), ITM_SUB_MINMAX (minimum or
maximum indicator), ITM_SUB_ROC (rate of change) or
ITM_SUB_TPLSS (typeless).
If a subitem is indicated, one of the members of the item-id has a

meaning: If item_id.subno has a value greater than 0, then this number
will be used to identify the subitem. If, however, that member equals 0,
ITM will find the first free number and returns that as the new
item_id.subno. Consequently, if an existing item has item_id.subno ==
0, then it will always be a main item! The descriptions of the other
parameters (i.e. default representation, limits, deadband and PIT values)

Item manipulations Item and event manipulations
are deferred to the following subsections.

Note that after creation, the value of the item will be zero and the status
of the item will be ITM_ST_NOT_INIT, indicating an item that is not
initialized. Changing this status to any other status causes the
ITM_CRI_FIRST criterion to become true.
Items can be deleted by specifying the item-id. The actual deletion is
performed with ITM_COD_DEL_ITM. When a main item is deleted, all
related subitems are deleted also.
For array items another procedure must be used (see ’Array items’).
3.4.2 Defining the default representation
Conversion The default representation of an item, not only affects the item value, but
also the representation of limits, deadband and PIT filter values. It is,
however, always possible to modify these values in any other
representation, as automatic representation conversion takes place.
Conversely, it is also possible to obtain the values in any required
representation. Hence, specification is only important in order to
increase speed of the value updates: when no conversion is necessary
(i.e. the default representation is identical to the update representation)
the performance is improved.
The default representation cannot be modified. It is possible to obtain the

representation type by requesting it with ITM_COD_PAR_ITM.
3.4.3 Value and status
In order to update the value or status of an item ITM_COD_SET_ITM,

ITM_COD_SET_GEN, itm_set_itm() or itm_set_gen() can be used.
Make sure that in the item-id the member item_id.attno == 0 (indicating
the item value rather than limit or deadband). Note that it is not possible
to use these procedures for array items or blocked items. The following
information has to be passed:
• New status.
The new status may be any user-defined status or it may be
ITM_ST_DEF or ITM_ST_OLD. With ITM_ST_DEF the
calculation of the status is left over to ITM, using limits and
deadband. With ITM_ST_OLD the status may not be affected by
this update: it remains unchanged.
• Value representation.

• New value.
• Addition indication.
This parameter allows the new value to be added to the old value,
rather than replacing it. For TLS_BOOLEAN items, the value is
toggled when the new value is TRUE. Note that this allows for
status update without a value change: Simply adding a value of 0 to
the old value.
When the parameter is set for a STRING item, then the new value
is concatenated to the existing value. The status is set to
ITM_ST_OVER (overranged) when the total string size exceeds
the defined string length. The string value will be truncated in this
case (still zero terminated).
• Update information.
The information passed in this parameter is passed transparently to
all event messages that requested this information (also see chapter
2).
• Optional flags.
Optimization Using ITM_COD_GET_ITM or one of the routines itm_get_itm(),

itm_get_val(), itm_get_sta() or itm_val_sta() the status and/or value can
be obtained. The reason for this range of available procedures is to allow
for optimal speed and performance. When ITM is heavily used (i.e.
many accesses to the common data area), a high response rate is
required. The basic routine itm_get_itm() has the most functionality, but
is relatively slow. The other routines have been added to improve
performance when only the status or value is requested (which is most
often the case). The optimized routines only return the first 8 bytes (7
plus trailing zero) of the STRING item value. Routine itm_get_itm()
must be used to retrieve the full size string value.
itm_get_val() only returns the item value.

itm_get_sta() only returns the item status.
itm_val_sta() returns value, status and optional flags.
Changing the value results in a new status calculation only if the ’new
status’ was specified to be ITM_ST_DEF. In other words, this status
requests automatic status determination. This calculation will result in
one of the following statuses:
ITM_ST_LOW_LOW
ITM_ST_LOW
ITM_ST_NORMAL
ITM_ST_HIGH

ITM_ST_HIGH_HIGH
ITM_ST_0
ITM_ST_1
The latter two statuses indicate the status of a TLS_BOOLEAN item.

A calculated STRING item status wil normally result in a status
NORMAL, unless the string size limits are violated (OVERRANGED).
The returned information of ITM_COD_GET_ITM and itm_get_itm()
is identical to the layout of an event message!
This layout is described in detail in the subsection "Layout of an event
message").
In the case of an event message, ITM_COD_GET_ITM or

itm_get_itm(), the old value and the new value can refer to the Item
value, but can also refer to the value of a limit or a deadband, depending
on the item_id.attno.
3.4.4 Quality code
In order to update the quality code of an item ITM_COD_SET_GEN or

itm_set_gen() can be used. Make sure that in the item-id the member
item_id.attno == 0 (indicating the item value rather than limit or
deadband). Note that this routine can also set the value, status,
application flags, application info and update info. It can also overwrite
a blocked item, exclude processes from updates and save information to
disk. Note also that it is not possible to use these procedures for array
items.
The quality code can be obtained using the routine itm_get_qc().
3.4.5 Limit and deadband values
It is possible to modify the limits and deadband using one of the

functions ITM_COD_MOD_ITM, ITM_COD_MOD_GEN,
ITM_COD_SET_ATT, itm_set_att(), ITM_COD_SET_GEN,
itm_set_gen(), ITM_COD_SET_ITM or itm_set_itm(). The internal
representation of these values is identical to the default item
representation.
Obtaining the limit and deadband values can be done using one of the
functions ITM_COD_PAR_ITM, ITM_COD_GET_ITM,
itm_get_itm(), itm_get_val() or itm_val_sta().

With the functions ITM_COD_MOD_ITM, ITM_COD_MOD_GEN

and ITM_COD_PAR_ITM all limits and deadband values together are
changed or retrieved. Also the number of limits defined for the item can
be changed or retrieved. Three possibilities exist: zero, 2 or 4 limits.
Using one of the other functions always only one limit or deadband
value can be changed or retrieved. To specify which limit or deadband
value is meant, the member item_id.attno should be filled in.
Member item_id.attno can be defined to be:
ITM_ATT_DB The deadband.

ITM_ATT_HL High limit.
ITM_ATT_LL Low limit.
ITM_ATT_HHL High-High limit.
ITM_ATT_LLL Low-Low limit.
It is possible to request events on a change of a limit or deadband value.

In that case the member item_id.attno should also be filled in and the
criterion ITM_CRI_VAL should be set. The item_id struct in the event
message will contain the requested attno number and the limit or
deadband value will be in the value element of the itm_val_sta struct.
For the functionality of limits and deadband, reference should be made

to chapter 2.
3.4.6 PIT values
Modifying the PIT values can be done with one of the functions
ITM_COD_MOD_ITM or ITM_COD_MOD_GEN. The internal
representation of the values is identical to the default item
representation.
Obtaining the PIT filter values can be done with one of the functions
ITM_COD_PAR_ITM or itm_par_itm().
For the functionality of the PIT filter, reference should be made to

chapter 2.

3.4.7 Dealing with array items
Array items are a special type. They differ from ’normal’ types in the
following ways:
• They consist of more than one element.

• They have no limits or deadband.
• They have no PIT filter.
An array item consists of a one-dimensional array of elements. Each

element has the same representation as defined at creation time. Creation
is done with ITM_COD_INS_ARR. In addition to the representation,
the number of elements is also specified at creation time, neither of
which can be modified later.
Cyclic array Obtaining these parameters again using ITM_COD_GET_ARR or
itm_get_arr() not only returns the number of elements and
representation, but also the ’last element’. The latter is only significant
when the array is used as a cyclic buffer. It then indicates which element
was the oldest element in the buffer: It will be the first one to be updated.
Each time an element is updated, the next one is pointed to for the
subsequent update.
Note, however, that it is not necessary to use the array cyclically. In that
case the notion ’last element’ has no meaning.
A number of elements can be updated in one update simultaneously,
using ITM_COD_SET_ARR or itm_set_arr(). These procedures require
the following information:
• New status.
• The number of elements to be updated.
• The first element in the array to be updated.
• All new values.
Obtaining the values of the array elements is done with

ITM_COD_GET_ARR or itm_get_arr(), in which the status as well as
the requested number of values are returned. Note that for array items
automatic status calculation always results in ITM_ST_NORMAL.
Deletion of an array item is done with ITM_COD_DEL_ARR.
3.4.8 Dealing with blocked items
An item is blocked with ITM_COD_BLOCK. After this procedure it is

not possible to update the item in the usual manner. Once blocked, the

option flag ITM_OPT_BLOCK is set. The option flags are returned with
functions like ITM_COD_GET_ITM, itm_get_itm() and itm_val_sta().
Overwriting the item is only possible with the messages/routines
ITM_COD_OWR_ITM, ITM_COD_SET_GEN, itm_owr_itm() or
itm_set_gen() (note that this does not apply for array items since these
cannot be overwritten).
Blocking a sub item means that direct updates of the sub item are
blocked. When the main item is updated or, for an integrator sub item,
the sub item value is read, the sub item will be updated internally, even
when it is blocked.
After an overwrite, the option flag ITM_OPT_UPD_BLK is also
automatically set. This will be maintained even when the item is
unblocked. Only when the item is updated, will the flag be reset again.
The optional status only changes after the first ’normal’ update.
The value-related status and the optional status can be merged using
routine itm_merg_opt(). The resulting merged status table can be found
in chapter 2.
3.4.9 Dealing with offline items
In principle, only the process that interfaces with the external equipment
is allowed to declare an item and all its subitems offline (often
EQUIPMENT/FAST). Declaring an item offline is done with
ITM_COD_OFFLINE, itm_offline(), ITM_COD_OFFLINE_X or
itm_offlin_x() and results in the option flag ITM_OPT_OFFLINE being
set. Note that this action will not be recorded on disk, in contrast to
blocking an item. The reason is as follows: suppose there is a manual or
automatic system shutdown. There is no reason to expect that the same
equipment will be offline before and after the shutdown. If some of the
equipment is still offline, then the related items will be declared offline
again by EQUIPMENT/FAST. Blocked items, however, are blocked for
a certain reason (to allow maintenance on a certain machine for
example). These items must still be blocked after a restart.
Items that are offline can normally be updated without special

procedures. The only consequence will be that the option flag
ITM_OPT_UPD_OFF is also automatically set and this is maintained
even when the item becomes on-line again. The flag is only reset after
the next update
The value related status and the optional status can be merged using

Event manipulations Item and event manipulations
routine itm_merg_opt(). The resulting merged status table can be found

in chapter 2.
3.4.10 How to acknowledge items
Acknowledging an item means no more than setting/resetting one of the

option flags. This action is done with ITM_COD_ACKNOW or
itm_acknow().
This action is specially meant for use with

ALARM/FAST. These option flags should
never be used by applications unless ALARM/
FAST is not going to be used.
3.4.11 Using application information and flags
After creating a new item, the part of the item in which application info
and application flags can be stored is ’empty’ i.e. filled with ’0’s. In
order to modify these contents, the following procedures are available:
ITM_COD_INF_APP Modify application info

ITM_COD_FLG_APP Modify application flags
ITM_COD_SET_GEN General set procedure for an item
All procedures require a parameter in which is stated whether or not the

new information should be recorded on disk. Note that the application
info and flags belong to the item. Hence, when saving an item, this
information is also saved!
Obtaining the application information is done with
ITM_COD_GET_ITM or itm_get_itm(). Normally, however, this
information is put in an event message (but only when explicitly
requested).
3.5 Event manipulations
3.5.1 Requesting ’normal’ events
Requesting an event means: asking for a (BUS/FAST) message when a

Item and event manipulations Event manipulations
certain event occurs. Consequently, you have to specify at least the

condition you want the message to be sent under and to whom it is to be
sent. A ’normal’ request - as opposed to a main event - is performed
using ITM_COD_REQ_EVTE or itm_req_evte(). The following
information must be passed:
• The item-id.
• Criterion mask.
• Event message layout.
• Destination address.
• Message-id.
• Event buffer flag.
• Once flag.
• Immediate flag.
• Requester information.
Criteria The criterion mask consists of a 16 bit mask. Each of the significant bits
is represented by a symbol. The mask is built by logically ’OR’-ing these
symbols. The following symbols are available.
• ITM_CRI_DEL
This is true when an item is being deleted. Before deletion, the
event message will be sent.
• ITM_CRI_EACH
This is true each time the item is updated (either value or status).
• ITM_CRI_FIRST
A message is sent only after the very first update since creation of
the item. In fact, this criterion is only true when the old status of the
item was ITM_ST_NOT_INIT (at the update) and the new status is
not. This status is automatically given to an item at creation time.
But if this status was imposed at a later stage the criterion can
become true again.
• ITM_CRI_OPT
This is true if one of the option flags was modified.
• ITM_CRI_OPT2
Same as ITM_CRI_OPT except the offline and updated offline
flags are ignored. Used to avoid receiving large bursts when
communication has been lost with the field.
• ITM_CRI_PIT
This is true when the new update passed the PIT filter.
• ITM_CRI_STA
This is true if the status was actually changed by the update.
• ITM_CRI_VAL

This is true if the value was actually changed by the update.

• ITM_CRI_EVT
Indicates an external item event. See also: section 3.5.5 on page 16.
• ITM_CRI_QC
This is true if the quality code was actually changed by the update.
• ITM_CRI_FST_SCN
This is true when fast-scanning from the field has been requested
for the item (typically for HMI applications).
• ITM_CRI_CNG_DSC
True when the first application subscribes or the last application
stops subscribing to an item using fast scanning criteria.
When the member item_id.attno is set, to indicate that events are

requested for a limit or deadband, only the criterion ITM_CRI_VAL can
be used.
Event message Specify in the event message what kind of information is required to be
present in the event message. The following options are available:
• ITM_EVT_NEW_VAL
The value after the update.
• ITM_EVT_OLD_VAL
The value before the update.
• ITM_EVT_TIM
The time the event occurred.
• ITM_EVT_CRI
Criterion flags.
• ITM_EVT_APP_FLG
The application flags.
• ITM_EVT_REQ_INF
The requester information.
• ITM_EVT_INT_TIM
The integration time. This information is only significant for
integration subitems. It contains the total integration time since the
last reset.
• ITM_EVT_NEW_QC
Quality code after the update.
• ITM_EVT_OLD_QC
Quality code before the update.
• ITM_EVT_FLOW
The flow control number.
• ITM_EVT_NAME
The item name as saved in the item table.

• ITM_EVT_STRING
The previous and current string item value.
• ITM_EVT_APP_INF
The application info.
• ITM_EVT_UPD_INF
The update information passed by the process that updated the item.
• ITM_EVT_MOD_TIM
The most recent time the value, status or quality code of the item
has been changed.
• ITM_EVT_DSC
An application has started subscribing to an item using a fast
scanning request, or the last of the applications has stopped
subscribing. Typically used to switch the behavior of an equipment
manager when retrieving data from the field.
The destination address may be any existing (M)DUR address. In most

cases, however, it will be the address of the requesting process.
In the message-id you specify the message-id you want the event
message to have.
It is possible to buffer event messages before sending them to the
destination (see also hereafter).
The once flag indicates that you want an event message to be sent only
once. As a consequence, the request is deleted directly after the first
occurrence.
The immediate flag acts as an extra criterion: directly after having
requested an event, the event message is sent, regardless of whether
there was an update or not.
3.5.2 Requesting main events
Before a main event can be requested, the main event-action must exist:
the main event must first have been created. Creation is done with
ITM_COD_PAR_MANE, which closely resembles requesting a
’normal event’. The information to be passed:
• Criterion mask.
• Event message layout.
• Message-id.
• Event buffer.
(For a description we refer you to the previous subsection). Two extra

elements of information must be passed:
1 The main event bit.

As described in chapter 2, there are 16 possible main events, each
represented in the main event mask by one specific bit.
2 Save flag.
Whether or not the existence of this main event must be recorded
on disk or not is specified here.
Once the main event has been created, it can be requested simply by
setting the corresponding bit in the main event mask of the required
item. When the item is updated, the main event criteria are evaluated and
if one is true, an event is generated. Note that all of these items for which
the main event is requested cause the same event message layout to be
sent to the same destination.
The once-flag, the immediate-flag and the requester info cannot be
specified for main events.
3.5.3 Deleting event requests
Event requests continue to be active until explicitly deleted. ’Normal

event’ requests are deleted with ITM_COD_DEL_EVT or itm_del_evt.
Only when the ’once flag’ has been specified, is the event automatically
deleted. Deleting the main event itself is done with
ITM_COD_DEL_MAN.
Note that it is also possible to remove all event requests for a requesting
process with ITM_COD_REM_EVTS. Bear in mind however,
especially if many event requests have been made, that this is a heavy
action for ITEM/FAST to undertake.
3.5.4 Using event-message buffers
Clustered Each event results in a BUS/FAST message. These messages can be

message buffered (clustered) in an event-message buffer. The contents of this
buffer are sent periodically or on request to a certain destination. You
can create (allocate) an event buffer with ITM_COD_ALL_BUF, in
which you have to specify:
Address where the message has to be sent to. All messages to be
clustered must have this specific address

• Buffer size.
• Time-out.
Here you specify the period (in seconds) between two consecutive
sends. Note that when the buffer is full, the message is sent
regardless of the elapsed time. The timing starts as soon as the first
message enters the buffer.
• BUS/FAST event flag.
Receiving BUS/FAST messages can be done with or without the
(M)DUR event flag. If an (M)DUR event is desired, it can be
specified here (see also (M)DUR programmer’s guide.
De-allocation of an event-message buffer is done with

ITM_COD_DEA_BUF. Note that this can only be done when no
requests are pending having this buffer specified. In that case an error is
returned. Both allocation and de-allocation are recorded on disk.
Transfer of the contents of an event buffer is done:
• When the buffer is full.

• Periodically with a time-out.
• When it is time for a flow control message.
• When a send action is ’forced’.
This is done with ITM_COD_SND_BUF or itm_snd_buf(). The
contents are sent as a BUS/FAST message.
• When the buffer contents are directly read.
This is done with itm_get_buf(). This routine performs a
destructive read of the event-message buffer and returns the
contents in a parameter.
Specifying an existing buffer in ITM_COD_ALL_BUF will result in the
buffer size and time-out being modified.
3.5.5 The force event mechanism
The ‘force event mechanism’ was introduced to generate an item event

without changing the item’s status. This can be useful for applications
that include update information in item events as explained in section
2.8.3. A good example of this is the FAST/TOOLS OPC AE client. In
the case of an event coming from the OPC-AE server the client will pass
on the OPC AE specific information as update information. This will not
necessarily cause a change in the item status. To make it possible to
'trigger' ALARM/FAST without an event status change it must be
possible to force an event on an item. This mechanism is analogue to

Saving item/event information on disk Item and event manipulations
'Force to alarm' and 'Force to normal' mechanism
3.6 Saving item/event information on disk

ITEM/FAST keeps track of all major modifications concerning the item
table. These modifications include:
• Insertion/modification of items.
All significant item information is recorded, including limit,
deadband and PIT filter values. Also current item value, status,
application info and flags are recorded.
• Deletion of items.
The items will also be removed from the disk.
• Creation of main events.
• Creation of event buffers.
• Value update if the item is configured that value updates should be
saved.
• Resetting a minimum/maximum subitem with changing its
minimum/maximum status.
Apart from these actions, other actions are stored, but only if requested
explicitly, namely:
• Requests for main events.

Note that requests for normal events cannot be stored
• Update of application info.
• Update of application flags.
• Set general information with the save flag on.
Finally it is possible to force ITM to save an item on disk.

This is done using ITM_COD_SAV_ITM. All information on that
specific item is recorded, including limits, deadband, PIT values,
application info and flags. Also the main event requests are recorded, not
the normal requests.
It is not possible to save a collection of items simultaneously (e.g. all
items in a group). This must be done ’manually’ one by one.
It is, however, possible to save all items, as well as all main event and
event buffer information, in one procedure. This is often done in order
to ’freeze’ the situation existing at any given moment. The latter
provides the option to leave the common data area in a locked state, This
means that no process can now access the common data area and no

Item and event manipulations Miscellaneous
further updates are performed. Hence, after recording all information,

the system can be shut down manually. After a restart, the system’s state
is identical to that before the shutdown.
Latter action puts a heavy load on the system and should therefore not
be performed on systems in operation.
3.7 Miscellaneous
Two miscellaneous routines exist:
itm_merg_opt()
itm_params()
Routine itm_merg_opt() is used to merge the value-related status with

the optional flags (see Chapter 2).
Generation With routine itm_params() you can obtain some of the generation
parameters parameters. This routine can be used to make application programs
generation independent. The routine returns the value used at generation
time of one of the following parameters:
• ITM_PAR_POOL_KBYTES
This value indicates the maximum size (in Kbytes) of the common
memory area, used for the item table.
• ITM_PAR_MAX_GROUPS
This value gives the maximum number of groups in the item table.
• ITM_PAR_MAX_NUMBER
This value gives the maximum number of items in each group.
• ITM_PAR_MAX_APPL_INFO
This value indicates the size of the application info that is reserved
in each item.
• ITM_PAR_MAX_UPD_INFO
This value indicates the maximum size of update info that may be
passed with an update.
• ITM_PAR_INT_SECS
This value indicates the integration time base used in seconds.
• ITM_PAR_DISK_SAVE
This value indicated whether disk saving is selected or not.

Conventions Reference guide
4 Reference guide
4.1 Conventions
All ITM routines have C-type interfaces. The syntax of all routines as
well as the examples conform to C Language Bindings.
In the routine descriptions the pointer to each parameter -not being a
scalar argument- is declared.
Unless otherwise stated, you have to allocate space for the

parameter itself as well.
The direction of the argument is indicated with (R), (I), (O) or (M).
(R) indicates the return value of the routine, which in most cases is a
TLS_BOOLEAN returning TRUE or FALSE.
(I) indicates that the buffer must contain information which will be
used by the routine.
(O) indicates that information is returned in that argument.
(M) is a combination of both: it means that the contents of the buffer
that is passed as input might be modified when the routine returns.
Example: the syntax of routine itm_par_itm() looks like this:
[status=] itm_par_itm(itm_cont, item_id, r_par_itm)
TLS_BOOLEAN status; /*(R) TRUE (success) or

FALSE (error) */
struct itm_context *itm_cont; /*(M) Buffer for ITM context */
struct itm_id *item_id; /*(I) Requested item */
struct itm_r_par_itm *r_par_itm; /*(O) Item parameters */
Nearly all routines return a TLS_BOOLEAN as the status indicator. In

the syntax this is indicated with [status=]. Normally, however, this
return value will not be put in a variable, but will be tested directly.
if (!itm_routine())
{
..... /* error encountered. Use UMH to log errors */
}

Reference guide Compiling, linking and running programs
The TLS_BOOLEAN type is defined in header file global.h (which is

In some routines, you have to enter symbol definitions. These are
defined in itm.h (which also must always be included in your source).
The symbol definitions are written in CAPITALS, e.g. the itm_get_val()
routine requires a representation to be entered. One of the valid
representation types is:
REP_LONG
All routine names in ITM as well as the data structs and symbol
definitions have a name which starts with the three letters ’itm’ or
’ITM’. Do not use a routine or variable name that start with these letters
in applications.
4.2 Compiling, linking and running programs

Using the routine ITM interface in programs requires the following:
• ITM must be installed.

• itm.h must be included.
• Sources must be linked with the ITM libraries.
The BUS/FAST interface also requires itm.h to be included and ITM to

be installed and running.
4.3 Error handling

Nearly all ITM routines as well as the BUS/FAST interface messages,
use standard error handling with the UMH facilities. The routines
require a buffer to be passed as an argument in which error context is
returned. In the case of a BUS/FAST message, the error message is
returned in the reply instead of the requested information. Using routine
fmc_upk_msg() this error can easily be dealt with (see Programmer’s
Guide BUS/FAST).
The philosophy underlying the error handling is described extensively in
the programmer’s guide of BUS/FAST (brick UMH).

Error handling Reference guide
It is recommended to use the following program body to log ITM errors:
...

...
if (!itm_routine())
{ /* an error has been detected */
umh_log(err_cont); /* use UMH to log error */
...
}
Some of the ITM routines return warnings or errors that the application
programmer might want to test on. All codes that can be returned by
each routine are mentioned in the routine description.
When you want to test the returned codes, you can use the following
body:
...
...
if (!itm_routine())
{ /*ITM error example */
if (umh_error(err_cont) == ITM_E_LONG_UPD)
{
... /* handle error */
}
else
{
umh_log(error); /* log all other errors */
}
}
For more detailed information about error handling the reader is directed
to the UMH Programmer’s Guide.

Reference guide Limits and deadband
4.4 Limits and deadband

The status of an item can be imposed, or can be calculated using limit
values. Depending on the new (updated) value of the item, the status will
be set to a certain value. The following calculations are used (depending
on the number of limits being specified and the representation of the
item value):
• The number of limits == 0.
The status becomes ITM_ST_NORMAL. If however, the default
representation of the item is REP_BOOLEAN, then the status
becomes ITM_ST_0 if the item value == 0. If this value != 0, then
ITM_ST_1 is returned as status.
• The number of limits == 2.
In this case it depends on whether the current status of the item is
ITM_ST_NORMAL or not. If the status == ITM_ST_NORMAL,
then the deadband is not taken into account. The status that is
returned depends on the item value compared to both limits. If
new_value > h_limit, then the status becomes ITM_ST_HIGH. If
new_val < than l_limit, then the status becomes ITM_ST_LOW.
If, however, the status was ITM_ST_HIGH, then the status will
only change to ITM_ST_NORMAL when new_val < h_limit -
deadband. Accordingly, the status will change from
ITM_ST_LOW to ITM_ST_NORMAL is new_val > l_limit +
deadband.
To sum up: The deadband lies asymmetrically with respect to the
limits, always pointing towards the normal situation.
• The number of limits == 4
For hh_limit and ll_limit the rules apply as described for limits in
chapter 2.
HH
hh_limit
H
h_limit
N
l_limit
L
ll_limit
LL Deadband
Figure 4-1 Limits and deadband

General data structs Reference guide
4.5 General data structs

In order to have a reference to the structs mentioned in this section,
variables have been introduced. These variable names are referred to in
the remainder of this manual. For example: reference is made to struct
itm_id as well as to item_id (see below).
4.5.1 struct itm_id
Items are referred to with their itm_id. This id is unique within the whole
(distributed) system. Member attno indicates information within the
item and only has significance when values are requested.
struct itm_id /* general item identification */

{
TLS_USHORT node; /* Node where item table resides */
TLS_UBYTE group; /* Group number in item table */
TLS_UBYTE nu1; /* Not used */
TLS_USHORT number;/*Actual item number */
TLS_UBYTE subno; /* 1-16 subitems. 0 == main item */
TLS_UBYTE attno; /* ITM_ATT_HL high limit
ITM_ATT_LL low limit
ITM_ATT_HHL high high limit
ITM_ATT_LLL low low limit
ITM_ATT_DB deadband
0 = value*/
} item_id;
4.5.2 struct dur_adr
This struct is used whenever a BUS/FAST address is to be used in a

procedure. The variable adr is used to represent this structure. See
Section 0.4, ref 2 for more information on this structure.
4.5.3 struct itm_context
The contents of this struct should never be altered.

Reference guide General data structs
struct itm_context /* General item context */

{
struct umh_context *umh_p; /* UMH context */
struct dur_context *dur_p; /* DUR context */
... /* System dependent info */
} itm_cont;
4.5.4 Layout of an event message
The layout of an event message depends on the information that was

requested with the event request. Which information is desired was
passed as argument event_layout in the event request (see for example
itm_req_evte()).
The first part of the event message is identical for all event messages. It
consists of a struct itm_event_gene. Member itm_event_gene.itm_id
indicates to which item the information that follows applies. Member
itm_event_gene.evt_layout is a bit mask, each bit represented by a
symbol. It is identical to the evt_layout specified by the requester. By
AND-ing itm_event_gene.evt_layout with one of the possible symbols,
you can find out whether or not certain information is present in the
reply.
In the following table all possible symbols are given. If one of the
symbols is present in itm_event_gene.evt_layout the table shows the
type of information that is present. Note that the sequence in which the
information is returned is always the same.
itm_event_gene.evt_layout Reply
struct
itm_event_gene
ITM_EVT_NEW_VAL struct itm_val_sta new value/status
ITM_EVT_OLD_VAL struct itm_val_sta old value/status
ITM_EVT_TIM TLS_ULONG time
ITM_EVT_CRI TLS_USHORT crits
TLS_SHORT dummy = 0
ITM_EVT_APP_FLG TLS_ULONG appl_flags
ITM_EVT_REQ_INF TLS_LONG req_info
ITM_EVT_INT_TIM TLS_LONG integrator_val

itm_event_gene.evt_layout Reply
ITM_EVT_NEW_QC TLS_ULONG new_qc
ITM_EVT_OLD_QC TLS_ULONG old_qc
ITM_EVT_FLOW TLS_ULONG evt_seq
ITM_EVT_NAME struct itm_get_name item_name
ITM_EVT_ADD_INF struct itm_add_inf add_inf
ITM_EVT_MOD_TIM* TLS_ULONG modification time
ITM_EVT_LOCK_INF* itm_lock_inf locking information
ITM_EVT_STRING TLS_SHORT tot_size
TLS_UBYTE new_size
TLS_UBYTE old_size
TLS_LONG str_inf[(tot_size - 4)/4]
ITM_EVT_APP_INF TLS_SHORT tot_size
TLS_SHORT info_size
TLS_LONG appl_inf[(tot_size - 4)/4]
ITM_EVT_UPD_INF TLS_SHORT tot_size
TLS_SHORT info_size
TLS_LONG upd_inf[(tot_size - 4)/4]
*This
symbol is an extended event and can only be usedoptional
with the itm_req_evte(),
ITM_COD_REQ_EVTE, itm_get_itme(), ITM_GET_ITME and
ITM_COD_PAR_MANE interfaces.
If ITM_EVT_NEW_VAL is specified, the value and status of the item

is returned. These are the values after the update. The status is returned
in itm_val_sta.status, while the optional statuses are returned in
itm_val_sta.opt_flags. Note that with the merge routine
itm_merge_opt() these two status types can be merged to one. If the item
was an array item, no value is returned, only the status and option flags.
It is also possible, that not the value of the item itself was requested, but
the value of deadband or limits. In that case the member
itm_event_gene.itm_id.attno indicates which value it relates to. In such
a case, the status that is returned will be ITM_ST_NORMAL.

The following possibilities exist for itm_event_gene.itm_id.attno:
ITM_ATT_HL H Limit
ITM_ATT_LL L Limit
ITM_ATT_HHL HH Limit
ITM_ATT_LLL LL Limit
ITM_ATT_DB Deadband
The value is passed in itm_val_sta.value of which the representation is

found in itm_val_sta.repres.
For ITM_EVT_OLD_VAL the same applies as for

ITM_EVT_NEW_VAL. The values that are returned are the old values:
before the update.
If ITM_EVT_TIM was specified, the time is returned indicating the

moment that the event was generated. This time stamp is in seconds
since 01-Jan-1970 00:00:00 (GMT). The resolution of this time stamp
depends on the scan interval of BUS/FAST.
If ITM_EVT_CRI was specified, the criterion that caused the event is

returned. This criterion can be one for the following:
• ITM_CRI_FIRST
This criterion will only be true when the item status changes from
ITM_ST_NOT_INIT to any other status. This status is always set
when an item is inserted, but it is also possible to impose this status,
hence causing ITM_CRI_FIRST to appear again.
• ITM_CRI_EACH
This criterion is true each time an update is performed. Note that
this criterion works only for value or status updates.
• ITM_CRI_VAL
This criterion is only true if the item value was changed in the
current update.
• ITM_CRI_STA
This criterion is only true if the item status was changed in the
current update.
• ITM_CRI_DEL
This criterion is true when the item will be deleted. Before the
deletion all events with this criterion are generated.
• ITM_CRI_PIT
This criterion is true if an update passes the PIT filter.
• ITM_CRI_OPT
This criterion is true if one of the option flags has changed state.

This is the case when one of the following flags changes state:
Action Related option flag

Blocked ITM_OPT_BLOCK
Blocked Updated ITM_OPT_UPD_BLK
Offline ITM_OPT_OFFLINE
Offline Updated ITM_OPT_UPD_OFF
Acknowledge ITM_OPT_ACKNOW
Alarm type 1 ITM_OPT_ALM_T1
Alarm type 2 ITM_OPT_ALM_T2
Force Normal State ITM_OPT2_ALM_FNS
Force Alarm State ITM_OPT2_ALM_FAS
Locked ITM_OPT2_LOCKED
Note that when an item is acknowledged or one of the alarm types

changes, the (merged) status of the item does not change, but an
event is still generated for event requests with ITM_CRI_OPT as
the criterion.
• ITM_CRI_OPT2
Same as ITM_CRI_OPT, except the ITM_OPT_OFFLINE and
ITM_UPD_OFF flags are ignored. This avoids receiving large
bursts of events when communication with the field is lost.
• ITM_CRI_QC
This criterion is only true if the quality code was changed in the
current update.
• ITM_CRI_EVT
This criterion is only true if the ITM_SET_EVT bit was set in the
current update.
If ITM_EVT_APP_FLG was specified in itm_event_gene.evt_layout,

then the application flags are returned. Application flags are flags stored
in the item itself and can be set/reset independent of one another using
procedure ITM_COD_FLG_APP.
If ITM_EVT_REQ_INF was specified, then the requester info is

returned. Requester info consists of information that was passed in the
event request. Hence, this information is only available for that specific
event. It is not saved in the item itself. Requester information cannot be
obtained in the case of main events: in that case the value 0 will be
returned.
If ITM_EVT_INT_TIM was specified, then the integration time is

returned. This time is only significant in the case of an Integrator sub

item. In that case, the time since the integrator was started (or reset) is
returned. When the item appears not to be an integration item, a 0 is
returned.
If ITM_EVT_NEW_QC is specified, the quality code of the item is

returned. It is the quality code after the update.
If ITM_EVT_OLD_QC is specified, the quality code of the item is

returned. It is the quality code before the update.
Specification of ITM_EVT_FLOW offers the possibility to check if

event messages from ITM were lost. A sequence number is replied that
can be compared with a locally saved sequence number. The first event
generated for a process after a flow control request will have number 1.
If ITM_EVT_NAME is specified then the item’s name as saved in the

item table is returned. If the name is not present in the item table (item
generation option), then an empty string is returned.
If ITM_EVT_ADD_INF is specified then the old and new additional

option flags are returned.
If ITM_EVT_MOD_TIM is specified then the time of the most recent

update of the value, status or quality code is returned. It is represented
as seconds since 1970 in GMT.
If ITM_EVT_LOCK_INF is specified then the locking information is

returned. It contains whether the item is locked and if it is locked, the
name of the user who owns the lock and the name of the terminal where
the lock was initiated.
ITM_EVT_STRING is used to get the (variable length) old and current

value of a string item. The total length of the information block (in bytes)
is specified in tot_size (including the TLS_SHORT tot_size and the
TLS_UBYTEs new_size and old_size). The strings are zero terminated,
always starting at a TLS_LONG boundary. The new_size and old_size
include the padding bytes after the terminating zero. The new_size
element is used to position to the old string value.
If ITM_EVT_APP_INF was specified, then information of a variable

length follows. The size of this information is found in tot_size
(including the two TLS_SHORTS tot_size and info_size). In info_size
the actual length of the application information (in bytes) is found. The

application info is stored in the item itself. This can be done with
procedure ITM_COD_INF_APP.
Finally, ITM_EVT_UPD_INF may be specified. This information is

also variable. Again the total size is given in tot_size (including the two
TLS_SHORTS tot_size and info_size). Info_size specifies the length of
the actual information. This update info is passed transparently from the
updating process (e.g. by an equipment manager or the FAST/TOOLS
OPC AE client) to the receiver of the event message.
NOTES • Using standard FSL routines, the time stamp can easily be
converted to any other time representation.
• If get_itm.item_it.attno !=0 (i.e. one of the attributes is selected)
then the returned status in itm_val_sta.status is always
ITM_ST_NORMAL and itm_val_sta.options == 0.
4.5.5 union itm_val_union
The value, limit, deadband of an item is communicated via the union

itm_val_union. Depending on the representation the value one of the
members of the union contains the value.
union itm_val_union
{
TLS_UBYTE c; /* In case of REP_BYTE or
REP_UBYTE */
TLS_SHORT s; /* In case of REP_SHORT or
REP_USHORT */
TLS_LONG l; /* In case of REP_LONG */
TLS_FLOAT f; /* In case of REP_FLOAT */
TLS_DOUBLE_S d; /* In case of REP_DOUBLE or
REP_PERCENT */
TLS_BOOLEAN b; /* In case of REP_BOOLEAN */
char str[ITM_MAX_STR_VAL];
/* In case of REP_STRING */
};
4.5.6 struct itm_flow_msg
A message with this layout is sent when flow control is requested and
for the specified maximum time between events no event is detected. In

stead of an event this flow control message is sent.
struct itm_flow_msg /* Flow control message */

}
TLS_ULONG evt_seq; /* Event sequence number */
TLS_ULONG flow_seq; /* Flow control message number */
};
The event sequence number is equal to the number sent in the last event
message
4.5.7 Update information layout
The information in the update information buffer resembles a clustered

(M) DUR message. Each of the messages starts with a size and a code
followed by a body. The following message codes have already been
defined:
Code layout Description
ITM_UPD_INF_TIM struct Time information

ftm_time
ITM_UPD_INF_NAM1 String Installation name for diag-
nostic message
ITM_UPD_INF_NAM2 String Unit name for diagnostic
message
ITM_UPD_INF_NAM3 String Tag name for diagnostic mes-
sage
ITM_UPD_INF_NAM4 String Sub item name for diagnostic
message
ITM_UPD_INF_STA_TXT String Status text for diagnostic
message
ITM_UPD_INF_ITM_DSC String Item description for diagnos-
tic message
ITM_UPD_INF_ACKNOW struct ITM_ALM_ACK: Force
itm_ack_inf automatic acknowledgement
ITM_ALM_NOT_ACK: Use
normal acknowledge mecha-
nism.
The following codes where added to support external events sources like the
OPC AE client

Routines and BUS/FAST messages Reference guide
Code layout Description
ITM_UPD_INF_EVT_CLT Struct: Address of external event

dur_adr client
ITM_UPD_INF_EVT_SRC String External event source
ITM_UPD_INF_EVT_CAT String Event category
ITM_UPD_INF_EVT_CND String Event condition
ITM_UPD_INF_EVT_SCND String Event sub-condition
ITM_UPD_INF_EVT_ACTOR String Event Actor id
ITM_UPD_INF_EVT_COOKIE struct Event "cookie"
itm_evt_
cookie_inf
ITM_UPD_INF_EVT_PRIO struct Event priority
itm_evt_prio
ITM_UPD_INF_ACTIV_TIM struct Event activation time.
ftm_time
ITM_UPD_INF_EVT_INFO struct External event info
itm_evt_inf
4.6 Routines and BUS/FAST messages

Reference guide Routines and BUS/FAST messages
4.6.1 Acknowledge item status
SYNTAX [status=] itm_acknow(itm_cont, acknowledge)
ARGUMENTS TLS_BOOLEAN status; /*(R) TRUE (success) or

FALSE (error) */
struct itm_acknow *acknowledge; /*(I) Acknowledge request */
BUS/FAST Message_id: ITM_COD_ACKNOW

MESSAGE Request data: struct itm_acknow
Reply data: struct itm_id
DATA struct itm_acknow

STRUCTS {
struct itm_id item_id /* Item to be acknowledged */
TLS_SHORT status; /* Only if item has this status */
TLS_SHORT acknow; /* Set/reset Acknowledge flag */
} acknowledge;
For general structs reference should be made to section GENERAL

DATA STRUCTS.
SEMANTICS The acknowledge flag (ITM_OPT_ACKNOW) can be set or reset using

this routine. Whether the requested actions are actually performed
depends on the status of the item compared with itm_acknow.status.
Itm_acknow.status indicates which status the item must have in order to
be acknowledged. If this status is equal to the item status, or if it is
ITM_ST_OLD, the option flag ACKNOWLEDGE will be set equal to
the value of itm_acknow.acknow. If the latter is equal to 0, the flag will
be reset, otherwise it will be set.
If the state of the ACKNOWLEDGE flag is changed, all event requests

with ITM_CRI_OPT or ITM_CRI_OPT2 in the criterion mask are
executed.
This change will not be saved on disk (in contrast to block).
NOTES This function is typically used by ALARM/FAST. The user should not
use this function when ALARM/FAST is present in a system.

ERROR • ITM_E_WRONG_SUB
CODES Wrong sub item number specified in item_id.
• ITM_E_NO_MAIN
Main item not found.
• ITM_E_WRONG_NUM
Wrong number in item_id.
• ITM_E_WRONG_GRP
Wrong group number in item_id.
• ITM_E_WRONG_NODE
Wrong node number in item_id.
The following codes can only be returned in the case of a BUS/FAST

procedure.
• ITM_E_COPY_BUF
Error during copying of error buffer.
• ITM_E_DSK_FAIL
Disk file access failed.
• ITM_E_NO_OUT
No space in output buffer.
• ITM_E_UNK_MESS
Received an unknown message code.

4.6.2 Allocate an event buffer
BUS/FAST Message-id: ITM_COD_ALL_BUF

MESSAGE Request data: struct itm_all_buf
Reply data: - (only size and code are returned)
DATA struct itm_all_buf

STRUCTS {
struct dur_adr adr; /* Destination address */
TLS_SHORT buf_len; /* Event buffer size (in bytes) */
TLS_SHORT dur_evt_flag; /* 0: No (M)DUR event */
struct dur_evt_blk dur_evt_id; /* (M)DUR event block */
TLS_USHORT timecount; /* Timeout in seconds */
TLS_USHORT mili_timecount;/* Timeout in milli seconds */
} all_buf;

DATA STRUCTS.
SEMANTICS This function is used to allocate an event buffer in which event messages
will be clustered.
The contents of the buffer will be sent to the process specified in
all_buf.adr.
The buffer will get a size as specified in all_buf.
If desired, an event can be generated as soon as a message is put in the
buffer. In that case all_buf.dur_evt_flag must be equal to 1 and the event
flag to be used is passed in member all_buf.dur_evt_id.
If no event is required all_buf.dur_evt_flag must be equal to zero. The
event flag must have been obtained previously using dur_evt_obt() or
dur_evt_orl().
The contents of the event buffer will only be sent when the buffer is full.
If the buffer has to be sent periodically, even when the buffer is not
completely filled, specify this time period in units of one second in
all_buf.timecount. If a 0 is specified, the time-out is disabled. If 0xFFFF
is specified, the timer value will be read from all_buf.mili_timecount. In
this field the timer can be specified in milliseconds. The allowed
precision is dependent on the start-up parameters of the ITMTIM
process.
If ITM was generated with the ’Disk’ option, this change will be
automatically saved in the item file on disk.
NOTES
The timeout timer is started as soon as the first event is put in the buffer.

ERROR • ITM_E_COPY_BUF
CODES Error during copying of error buffer.
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS
• ITM_F_NO_SPACE
Not enough space in to allocate the event buffer.

4.6.3 Attach to the data area
SYNTAX [status=]itm_att(itm_cont,dur_cont,err_cont)

FALSE (error) */
struct itm_context *itm_cont; /*(O) Buffer for ITM context */
struct dur_context *dur_cont; /*(I) Buffer for DUR context */
struct umh_context *err_cont; /*(I) Buffer for UMH context
used by UMH */
SEMANTICS This function should only be used when the item table is to be accessed
via the routine interface. It attaches the calling process to the common
area ITMCOM. The context that is returned in itm_cont must be passed
in each routine that accesses this common area.

4.6.4 Block an item
BUS/FAST Message-id: ITM_COD_BLOCK

MESSAGE Request data: struct itm_block
DATA struct itm_block

STRUCTS {
struct itm_id item_id;
TLS_BOOLEAN block;
} blck
For general structs, reference should be made to section GENERAL

DATA STRUCTS.
SEMANTICS With this function an item can be blocked or unblocked. The

consequence of this status is, that the item cannot be updated anymore
unless a special procedure is used. This status is stored in the option flag
ITM_OPT_BLOCK. Consequently, all event requests depending on the
criterion ITM_CRI_OPT or ITM_CRI_OPT2 are executed when the
flag changes state.
If blck.block is TRUE, the item is blocked, if FALSE, the item is
unblocked.
An item can be blocked or unblocked by the ’Update general item

information’ function too (see 4.6.53).
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

procedure:

• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.5 Deallocate an event buffer
BUS/FAST Message-id: ITM_COD_DEA_BUF

MESSAGE Request data: struct itm_dea_buf
DATA struct itm_dea_buf

STRUCTS {
struct dur_adr adr; /* Destination address */
} dea_buf;

DATA STRUCTS.
SEMANTICS This function is used to deallocate an existing event buffer. The buffer
may only be deallocated if it is no longer in use: no item uses this buffer
to put event messages in. If the buffer is still in use, an error is returned.
The buffer which has to be deleted is specified by the process address to
which the buffer is related. This process is specified in dea_buf.adr.
ERROR • ITM_E_USED_BUF
CODES Buffer still in use. Not allowed to deallocate.
• ITM_E_COPY_BUF
Error during copying of error buffer (for system conversion).
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.6 Delete an array item
BUS/FAST Message-id: ITM_COD_DEL_ARR

MESSAGE Request data: struct itm_del_arr
DATA struct itm_del_arr

STRUCTS {
struct itm_id item_id; /* Item to be deleted */
} del_arr;

DATA STRUCTS.
SEMANTICS This function searches for the item as specified in del_arr.item_id and
checks if the item is an array item. If not, an error is returned. Before
deleting the item the criterion masks of all event requests are checked.
Event requests with ITM_CRI_DEL as a condition are executed.
Afterwards all event requests linked to this item are deleted. Finally, the
item itself is deleted.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

procedure:
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.7 Delete an event request
SYNTAX [status=] itm_del_evt(itm_cont, del_evt)

FALSE (error) */
struct itm_del_evt *del_evt; /*(I) Event information */
BUS/FAST Message_id: ITM_COD_DEL_EVT

MESSAGE Request data: struct itm_del_evt
DATA struct itm_del_evt

STRUCTS {
struct itm_id item_id; /* Specifies item */
struct dur_adr adr; /* Specifies event request */
} del_evt;

DATA STRUCTS.
SEMANTICS This function is used to delete an event request. This function first
searches for the item as specified in del_evt.item_id. When found, all
event requests are checked for process address. Only the event requests
having a process address equal to the one specified in del_evt.adr are
deleted.
NOTES • Deletion of an event request is not recorded on disk.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP


procedure:
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.8 Delete an event request with flags
SYNTAX [status=] itm_del_evtf(itm_cont, del_evt)

FALSE (error) */
struct itm_del_evtf *del_evtf; /*(I) Event information */
BUS/FAST Message_id: ITM_COD_DEL_EVTF

MESSAGE Request data: struct itm_del_evtf
DATA struct itm_del_evtf

STRUCTS {
struct itm_id item_id; /* Specifies item */
struct dur_adr adr; /* Specifies event request */
TLS_SHORT flags; /* Additional flags */
TLS_SHORT spare;
} del_evtf;

DATA STRUCTS.
SEMANTICS This function is used to delete an event request. This function first
searches for the item as specified in del_evtf.item_id. When found, all
event requests are checked for process address and
ITM_EFLG_PERCENT in del_evtf.flags. Only the event requests
having a process address equal to the one specified in del_evtf.adr and
both have set or cleared ITM_EFLG_PERCENT are deleted.
NOTES • Deletion of an event request is not recorded on disk.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP


procedure:
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.9 Delete an item
BUS/FAST Message_id: ITM_COD_DEL_ITM

MESSAGE Request data: struct itm_del_itm
DATA struct itm_del_itm

STRUCTS {
} del_itm;

DATA STRUCTS.
SEMANTICS First, a search is made for the item as specified by del_itm.item_id. If not
found, the routine returns TRUE immediately. If the item appears to be
an array item, the routine returns FALSE without deleting the item.
The routine checks if the item is a subitem. If so, the link between the
main item and the subitem is removed and all event requests having
ITM_CRI_DEL as criterion are executed. Afterwards the subitem is
deleted.
If the item is a main item, the item is deleted as well as all connected
subitems. Before deletion of each of these items, all event requests
having ITM_CRI_DEL as condition are executed.
ERROR • ITM_E_ISARR
CODES Item is an array item.
• ITM_E_WRONG_SUB
Wrong sub item number specified in item_id.
• ITM_E_NO_MAIN
Main item not found
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT


• ITM_E_UNK_MESS

4.6.10 Delete main event
BUS/FAST Message_id: ITM_COD_DEL_MAN

MESSAGE Request data: struct itm_del_man
DATA struct itm_del_man

STRUCTS {
TLS_SHORT main_evt_bit; /* Main event to delete */
TLS_SHORT dummy;
} del_man;

DATA STRUCTS.
SEMANTICS First the main event as specified by del_man.main_evt_bit is searched.

If not found, the function returns an error. If found, the main event info
is deleted.
ERROR • ITM_E_NO_MEVT_BIT
CODES No event bit specified.
• ITM_E_NO_MEVT_DEF
Specified main event not found.
• ITM_E_MEVT_USED
Main event still in use.

4.6.11 Detach from the data area
SYNTAX [status=]itm_det(itm_cont)

FALSE (error) */
SEMANTICS This function detaches the process from the common area ITMCOM.
ERROR None
CODES

4.6.12 Update application flags
BUS/FAST Message_id: ITM_COD_FLG_APP

MESSAGE Request data: struct itm_flg_app
DATA struct itm_flg_app

STRUCTS {
struct itm_id item_id; /* Item to affect */
TLS_LONG update_mask; /* Application flags to affect */
TLS_LONG set_mask; /* New application flags */
TLS_SHORT save_flag; /* Save on disk if TRUE */
TLS_SHORT dummy;
} flg_app;

DATA STRUCTS.
SEMANTICS Using this function each bit of the application flags can be set or reset
individually. The item to which the requests applies is specified in
flg_app.item_id. In order to change one or more flags, two masks have
to be supplied:
• Update mask (flg_app.update_mask).

This mask indicates the bits of interest.
• Set/reset mask (flg_app.set_mask).
This mask indicates how the bits specified in the update mask
must be set/reset.
In the update mask, the bits of interest are indicated with a ’1’. All bits
that should not be altered are indicated with a ’0’ (zero).
The value of the bits of interest are set equal to the value as specified in
the set/reset mask.
If the new value of the application flags has to be stored on disk, specify
a 1 in flg_app.save_flag. If this member is zero, the change will not be
recorded on disk.
NOTES • The application flags will be recorded on disk only when ITM was
generated with the ’Disk’ option.
• When the application flags are saved on disk, the whole item is
saved, including value, status, main events etc. Existing values are
overwritten.

• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.13 Get value/status of array item
SYNTAX [status=] itm_get_arr(itm_cont, get_arr, r_get_arr, outlen)

FALSE (error) */
struct itm_get_arr *get_arr;
/*(M) Contents of array item */
struct itm_r_get_arr *r_get_arr;
/*(O) Returned information */
TLS_SHORT *outlen; /*(M) Size of r_get_arr */
BUS/FAST Message_id: ITM_COD_GET_ARR

MESSAGE Request data: struct itm_get_arr
Reply data: struct itm_r_get_arr
DATA struct itm_get_arr

STRUCTS {
struct itm_id item_id; /* Item of interest */
TLS_SHORT first_ele; /* Number of first wanted element*/
TLS_SHORT repres; /* Wanted representation */
TLS_SHORT nr_of_ele; /* Number of elements to read */
TLS_SHORT dummy;
} get_arr;
struct itm_r_get_arr
{
struct itm_id item_id; /* Item read */
TLS_SHORT status; /* Status of item */
TLS_SHORT first_ele; /* Number of first element read */
TLS_SHORT repres; /* Representation used */
TLS_SHORT nr_of_ele; /* Number of elements read */
TLS_LONG first_value; /* Start pos. of array with values */
} r_get_arr;
DATA STRUCTS.
SEMANTICS This function is used to get one or more of the elements of an array item.
The information regarding which element(s) of the array are to be
returned is specified in get_arr.

First, first a search is made for the indicated item in get_arr.item_id. If

not found, or if the item appears not to be an array item, an error is
returned. When the item is found, the requested number of elements
(specified in get_arr.nr_of_ele) starting with the one indicated in
get_arr.first_elem are returned. In the case get_arr.first_elem was
specified to be -1, the returned elements start with the oldest element.
Furthermore, the status of the item is returned in r_get_arr.status.
The members r_get_arr.first_elem and r_get_arr.nr_of_ele are copies of
the corresponding members of get_arr.
When REP_DEF was specified as the get_arr elements is performed and
the representation type of the elements is returned in r_get_arr.repres. In
all other cases the representation of the returned elements is converted
to the representation as specified in get_arr.repres. This representation is
then copied into r_get_arr.repres.
The element r_get_arr.first_value indicates the start position of the
values read. The user should cast the address of this element to an array
of elements of the used representation.
Possible representation types are:
REP_DEF
REP_BOOLEAN
REP_BYTE
REP_UBYTE
REP_SHORT
REP_USHORT
REP_FLOAT
REP_LONG
REP_DOUBLE
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_NOTABITM
Item is not an array item.
• ITM_E_ELE_NR
Illegal element number.


procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.14 Get event buffer information
SYNTAX [status=] itm_get_buf(itm_cont,adr,outbuf,outlen)

FALSE (error) */
struct dur_adr *adr; /*(I) Destination for event
message */
char *outbuf; /*(O) Buffer to fill */
TLS_SHORT *outlen; /*(M) Size/filled-size of outbuf */
DATA struct itm_event_gene

STRUCTS {
struct itm_id itm_id; /* Item of interest */
TLS_SHORT evt_msk;
char spare;
char flags;
TLS_LONG evt_layout;/* Event layout */
} event_gene;
struct itm_val_sta
{
char status; /* Status of item */
char opt_flags; /* Option flags of item */
TLS_SHORT repres; /* Used representation */
union itm_val_unionvalue; /* Value of item */
} val_sta;

DATA STRUCTS.
SEMANTICS This routine is used to obtain the event buffer without requesting it using
itm_snd_buf(), but directly into a buffer, passed as argument.
The (M)DUR address, to which the event buffer would be sent to in
normal situations must be passed in adr.
The event buffer is returned as if it were a clustered message received by
(M)DUR, except for the size and code: these are not added. The event
buffer is returned in outbuf. The length of outbuf must be specified in
outlen and the size filled will be returned in outlen.
Each of the clustered messages has a certain layout. This layout is
described in detail in section "Layout of an event message".

ERROR • ITM_E_NO_EVTBUF
CODES Specified event buffer was not found.
• ITM_E_SMALL_BUF
The output buffer to store the event buffer in is too small.

4.6.15 Get item information
This routine and BUS/FAST message is

described for compatibility reasons only. It is
strongly recommended to use the
itm_get_itme() and ITM_COD_GET_ITME
interfaces.
SYNTAX [status=] itm_get_itm(itm_cont, get_itm, outbuf, outlen)

FALSE (error) */
struct itm_get_itm *get_itm; /*(M) Contents of item table */
TLS_SHORT *outlen; /*(M) Filled size of outbuf */
BUS/FAST Message_id: ITM_COD_GET_ITM

MESSAGE Request data: struct itm_get_itm
Reply data: see below
DATA struct itm_get_itm

STRUCTS {
TLS_SHORT reset_flag; /* Reset needed flag */
TLS_SHORT reset_type; /* Method of reset */
TLS_SHORT evt_layout;/* Wanted event layout */
} get_itm;
struct itm_event_gen
{
TLS_SHORT evt_layout;/* Wanted event layout */
char spare;
char flags; /* Option flags */
} event_gen;
struct itm_val_sta
{


} val_sta;
struct itm_str_info
{
TLS_SHORT tot_size; /* Total size of string info block */
TLS_UBYTE new_size; /* Size of current string value */
TLS_UBYTE old_size; /* Size of old string value */
TLS_LONG info[1]; /* New and old string value */
} str_inf;

DATA STRUCTS.
SEMANTICS This function is used to obtain item information. Both value and status
of the item or information about a limit or deadband can be returned. The
function needs information to be passed in get_itm. The item_id is
passed in get_itm.item_id.
In bits ‘evt_layout’, the same bits can be set as at "event request" (see
4.6.32). For example, the quality code can be asked for.
Note that this member is of type struct itm_id. One of the members of
this struct is attno. If this member equals 0, then the actual item value is
indicated. In all other cases the member specifies to which attribute the
item value pertains. The possible options which can be selected for this
member (i.e. get_itm.item_id.attno) are:
ITM_ATT_HL /* value of high limit */

ITM_ATT_LL /* value low limit */
ITM_ATT_HHL /* value of high high limit */
ITM_ATT_LLL /* value of low low limit */
ITM_ATT_DB /* value of deadband */
Members get_itm.flag_reset and get_itm.reset_type are only significant

in the case of subitems.
If member get_itm.reset_flag != 0 then it indicates that the routine must
reset the subitem after having read its value. In the case, the subitem is
a min/max indicator, the state to which it has to reset the subitem is
specified in get_itm.reset_type. Three types are defined:
ITM_RST_DEF /* only reset the subitem */

ITM_RST_MIN /* reset and change to min indicator */

ITM_RST_MAX /* reset and change to max indicator */
In member get_itm.repres the representation in which the value must be

returned is indicated. Note that this may be the value of the item itself or
the value of one of the limits or deadband, depending on what was
specified in get_itm.item_id.attno.
The value may be converted to one of the following representation
types:
REP_DEF
REP_BOOLEAN
REP_BYTE
REP_SHORT
REP_FLOAT
REP_LONG
REP_DOUBLE
REP_STRING
REP_PERCENT
Member outlen must contain the length of the output buffer. The routine
fills the actual number of transferred bytes.
Finally, the additional information that must be returned is specified in
get_itm.evt_layout. This member is a bit mask, each bit indicating
certain information. How the event message is built up is found in
section "Event message layout".
NOTES The PIT values can be obtained using ITM_COD_PAR_ITM or

itm_par_itm()
RELATED • itm_par_itm
ROUTINES This routine returns the whole item definition.
RELATED • ITM_COD_PAR_ITM
MESSAGES This procedure returns the whole item definition.
CODES The specified item is an array item.
• ITM_E_SMALL_BUF
The buffer to copy information is too small.
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN

• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_ILLPERC
The value can not be converted to %.

procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.16 Get item information extended
SYNTAX [status=] itm_get_itme(itm_cont, get_itme, outbuf, outlen)

FALSE (error) */
struct itm_get_itme *get_itme; /*(M) Contents of item table */
TLS_SHORT *outlen; /*(M) Filled size of outbuf */
BUS/FAST Message_id: ITM_COD_GET_ITME

MESSAGE Request data: struct itm_get_itme
Reply data: see below
DATA struct itm_get_itme

STRUCTS {
TLS_ULONG evt_layout;/* Wanted event layout */
TLS_ULONG flags; /* Modifier flags */
TLS_SHORT spare;
} get_itme;
struct itm_event_gene
{
TLS_SHORT evt_msk; /* Bit ITM_EVT_USE_MSK2 set */
char spare;
char flags;
TLS_ULONG evt_layout;/* Event layout */
} event_gene;
struct itm_val_sta
{
} val_sta;
struct itm_str_info

{
TLS_SHORT tot_size; /* Total size of string info block */
TLS_UBYTE new_size; /* Size of current string value */
TLS_UBYTE old_size; /* Size of old string value */
TLS_LONG info[1]; /* New and old string value */
} str_inf;

DATA STRUCTS.
SEMANTICS This function is used to obtain item information. Both value and status
of the item or information about a limit or deadband can be returned. The
function needs information to be passed in get_itme. The item_id is
passed in get_itme.item_id.
In bits ‘evt_layout’, the same bits can be set as at "event request" (see
4.6.32). For example, the quality code can be asked for.
Note that this member is of type struct itm_id. One of the members of
this struct is attno. If this member equals 0, then the actual item value is
member (i.e. get_itme.item_id.attno) are:

For subitems a number of flags in get_itme.flags are significant. When

bit ITM_EFLG_RST is set then it indicates that the routine must reset
the subitem after having read its value. In the case, the subitem is a min/
max indicator, the state to which it has to reset the subitem is specified
in get_itme.flags. Two types are defined:
ITM_EFLG_RST_MIN /* reset and change to min indicator */

ITM_EFLG_RST_MAX /* reset and change to max indicator */
When both are not specified then the subitem is only reset.
In member get_itme.repres the representation in which the value must be

returned is indicated. Note that this may be the value of the item itself or
the value of one of the limits or deadband, depending on what was

specified in get_itme.item_id.attno.
The value may be converted to one of the following representation
types:
REP_DEF
REP_BOOLEAN
REP_BYTE
REP_SHORT
REP_FLOAT
REP_LONG
REP_DOUBLE
REP_STRING
REP_PERCENT
Member outlen must contain the length of the output buffer. The routine
fills the actual number of transferred bytes.
Finally, the additional information that must be returned is specified in
get_itme.evt_layout. This member is a bit mask, each bit indicating
certain information. How the event message is built up is found in
section "Event message layout".
NOTES The PIT values can be obtained using ITM_COD_PAR_ITM or

itm_par_itm()
RELATED • itm_par_itm
ROUTINES This routine returns the whole item definition.
RELATED • ITM_COD_PAR_ITM
MESSAGES This procedure returns the whole item definition.
• ITM_E_SMALL_BUF
The buffer to copy information is too small.
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

• ITM_E_ILLPERC

procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.17 Get item name
SYNTAX [status=] itm_get_nam(itm_cont, item_id, itm_name)

FALSE (error) */
struct itm_id *item_id; /*(M) Requested item */
struct itm_get_name *itm_name; /*(O) Buffer to fill */
BUS/FAST Message_id: ITM_COD_GET_NAME

MESSAGE Request data: struct itm_id
Reply data: struct itm_get_name
DATA struct itm_get_name

STRUCTS {
char name[ITM_GET_NAME_SIZ];
} itm_name;

DATA STRUCTS.
SEMANTICS As an option the item name can be stored in the memory-resident item
table. This function returns either the name or an empty string when the
name is not stored in memory.
The user must supply a buffer large enough to hold the full item name,
the buffer size is not checked.
The item name will be returned in the form:
<installation>.<unit>.<tag>[.<sub name>]
NOTES This function is fundamentally different from the GIN functions that
retrieve the item name from the item database on disk.
Even the BUS/FAST procedure is faster than the GIN interface since no
disk access is implied.
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM


• ITM_E_WRONG_GRP

procedure
• ITM_E_COPY_BUF
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.18 Get item quality code
SYNTAX [status=] itm_get_qc(itm_cont, item_id, qc)

FALSE (error) */
TLS_ULONG *qc; /*(O) Value related quality code */
DATA For general structs reference should be made to section GENERAL

STRUCTS DATA STRUCTS.
SEMANTICS This function is used to obtain the quality code of an item. The routine
returns the quality code in an optimized way; faster than would be the
case with itm_get_itm().
In contrast to the latter, this routine cannot return values for the item nor
for the status, limits and deadband.
The routine first checks whether the item exists. If it does not, the
corresponding error is returned.
NOTES • None.
RELATED • itm_get_itm()
ROUTINES This routine also returns the value of the item, status, deadband or
one of the limits.
• itm_val_sta()
This routine returns both value and status in an optimal way.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

4.6.19 Get item status
SYNTAX [status=] itm_get_sta(itm_cont,item_id, stat)

FALSE (error) */
TLS_SHORT *stat /*(O) Value-related status */

SEMANTICS This function is used to obtain the status of an item. The routine returns
the status in an optimized way: faster than would be the case with
itm_get_itm().
In contrast to the latter, this routine cannot return values for the item nor
for the limits and deadband.
The routine first checks whether the item exists. If it does not, the
NOTES • If the item is an integrator item, this function has the following side
effect. The function will first update the item, in order to be able to
receive the status belonging to the current integration value. Event
criteria are evaluated again and, consequently, corresponding event
requests will be performed.
ROUTINES This routine also returns the value of the item, deadband or one of
the limits.
• itm_val_sta()
This routine returns both value and status in an optimal way.
RELATED Message code: ITM_COD_GET_ITM

MESSAGES
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP



4.6.20 Get value of an item
SYNTAX [status=] itm_get_val(itm_cont,item_id,value,repres)

FALSE (error) */
char *value; /*(O) Value of item */
int repres; /*(I) Representation of item */

SEMANTICS
This function is used to obtain the value of an item or the value of limits
or deadband. The routine returns the value in an optimized way: i.e.
faster than would be the case with itm_get_itm().
The representation in which the value must be returned is specified in
repres. If REP_DEF was specified, the default representation is
returned.
The following representation types are valid:
REP_DEF
REP_BOOLEAN
REP_BYTE
REP_SHORT
REP_FLOAT
REP_LONG
REP_DOUBLE
REP_STRING
REP_PERCENT
Note that the item-id is of type struct itm_id. One of the members of this
struct is attno. If this member equals 0, then the actual item value is



The above mentioned attributes only affect the returned value, not the
returned status.
The routine first checks whether the item exists. If not, the
NOTES • If the item is an integrator item, this function has the following side
effect. The function will first update the item, in order to be able to
receive the current integration value. Event criteria are evaluated
again and, consequently, corresponding event requests will be
performed.
• If the item is of type STRING only the first 8 bytes (7 plus trailing
zero) are returned.
ROUTINES This routine also returns the status. It can also return the full value
of a string item.
• itm_val_sta()
This routine returns both status and value in an optimized way.
RELATED ITM_GET_ITM
MESSAGES This procedure also returns the status.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_ILLPERC

4.6.21 Obtain group <-> node relation

Syntax [status=]itm_grps_node(itm_cont,array)
Arguments TLS_BOOLEAN status; /*(R) TRUE:(success) */

char *array; /*(O) Array containing relation
between group
and related node nr. */
Semantics This routine is used to obtain the relation between the item groups and
the node numbers that are related to these item groups.
The argument ‘array’ should point to a character array of 256 elements.
The item group number is the index in this array. By indexing this array
after successful calling this routine, the node number related to a certain
item group number can be found.
The elements in this array corresponding with a item group number that
is currently not allocated, are filled with a zero value.
Errors •
Related routines •

4.6.22 Set application information
BUS/FAST Message_id: ITM_COD_INF_APP

MESSAGE Request data: struct itm_inf_app
DATA struct itm_inf_app /* update application info */

STRUCTS {
struct itm_id item_id; /* Item to affect */
TLS_SHORT info_size; /* Size of info to store */
TLS_SHORT save_flag; /* Save item to disk if TRUE */
TLS_LONG info; /* Start position of info buffer */
} inf_app;

DATA STRUCTS.
SEMANTICS This function modifies the application information. The new

information is passed in inf_app.info. The size of the application info is
specified in inf_app.info_size. Note that the total size of this information
should not exceed ITM_PAR_MAX_APP_INFO, which is defined at
generation time.
If the new information also needs to be stored on disk, inf_app.save_flag

must be made unequal to 0. If inf_app.save_flag == 0, the modification
is not recorded.
NOTES • The application info will be recorded on disk only when ITM was
generated with the ’Disk’ option.
• When the application flags are saved on disk, the whole item is
saved, including value, status, main events etc. Existing values are
overwritten.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

Wrong node number in item_id

procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.23 Insert an array item in the item table
BUS/FAST Message_id: ITM_COD_INS_ARR

MESSAGE Request data: struct itm_ins_arr
DATA struct itm_ins_arr

STRUCTS {
struct itm_id item_id; /* Wanted item id */
TLS_SHORT nr_of_ele; /* Wanted number of elements */
} ins_arr;

DATA STRUCTS.
SEMANTICS An array item may be inserted using this function. It requires the item_id
as input, the number of elements of the array and the default
representation of the elements. Note that only a one- dimensional array
is supported. The representation may be of the following types:
REP_BOOLEAN
REP_BYTE
REP_UBYTE
REP_SHORT
REP_USHORT
REP_FLOAT
REP_LONG
REP_DOUBLE
ITM can generate a free item_id itself or one can be supplied. An

item_id is supplied by filling in the node, group and number. These must
be non-zero values. The node number must be equal to the actual node
number. If the specified item_id is already in use then an error is
returned.
To let ITM generate an item_id, node, group and number must be zero.
ITM will search a free group and number slot and will return these
entries in item_id. Optionally the item can be created in a specific group
by supplying the group (a non-zero value).
In a distributed FAST/TOOLS environment the related node (the node
where the copy of the item exists) has to be specified in item_id.node
during insertion of the item.

NOTES If ITM was generated with the ’Disk’ option, this change will be
ERROR • ITM_E_NO_FREE_NUM
CODES No free item available.
• ITM_E_ITM_EXISTS
The indicated item already exists.
• ITM_F_NO_SPACE
No space left in common area.
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_WRONG_REP
Wrong representation specified.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.24 General insert an item in the item table
BUS/FAST Message_id: ITM_COD_INS_GEN

MESSAGE Request data: see below
DATA struct itm_ins_gen

STRUCTS {
TLS_ULONG ins_layout;
} ins_gen;
struct itm_ins_itm
{
TLS_SHORT repres;
TLS_SHORT limits_count;
TLS_SHORT sub_type;
TLS_SHORT par1;
union itm_val_union deadband;
union itm_val_union l_limit;
union itm_val_union h_limit;
union itm_val_union ll_limit;
union itm_val_union hh_limit;
TLS_SHORT pidt;
TLS_SHORT t_filter;
union itm_val_union p_filter;
union itm_val_union i_filter;
union itm_val_union d_filter;
} ins_itm;
struct itm_set_trm_usr
{
char term[GIN_TERM_NAM_SIZ];
} terminal_user;
struct itm_set_adt_inf
{
char f_inf[ITM_SET_ADT_INF_FSIZ];
char m_inf[ITM_SET_ADT_INF_MSIZ];
} adt_info;

struct itm_set_reason
{
char reason[ITM_SET_REASON_SIZ];
} adt_reason;
struct itm_set_name
{
char name[ITM_SET_NAME_SIZ];
} item_name;

DATA STRUCTS.
SEMANTICS This procedure is used to insert an item in the item table. As an option
there is the possibility to pass audit trail information, so the item
insertion can be traced back to the originator.
Another feature is that the item name can be passed, which is saved in
the memory-resident item table if the flag ITM_PAR1_NAME in the
element ins_itm.par1 is set, to allow fast item name retrieval when the
item_id is known.
The required information is passed in the request data as a number of

structs. The first struct itm_ins_gen contains a bit mask of which the bits
define the remaining structs that are present in the request data.
The request data must at least comprise the structs itm_ins_gen and
itm_ins_itm (which then makes the procedure functionally equal to
ITM_COD_INS_ITM). The other structs are optional and only present
when the corresponding bits are set in itm_ins_gen.
The following bits have been defined for the bit mask:
ITM_INS_ITM /* Item information */

ITM_INS_ADT_SRC /* Audit source code */
ITM_INS_ACT_ADR /* Activator address */
ITM_INS_TRM_USR /* Terminal or user info */
ITM_INS_ADT_INF /* Audit info */
ITM_INS_REASON /* Reason info */
ITM_INS_NAME /* Item name info */
Note that the structs in the request data must appear in the same order as
the definition of the bits.
Refer to the description of the ITM_COD_INS_ITM procedure for the

meaning of the fields in struct itm_ins_itm.
Bit ITM_INS_ADT_SRC is set when AUDIT/FAST information is sent

with the request and it corresponds with the AUDIT/FAST source
indicator which is a number of type TLS_ULONG.
ITM_INS_ACT_ADR is set when the BUS/FAST address of the

originator is present (struct dur_adr).
The presence of the terminal name and user name combination is

flagged with ITM_INS_TRM_USR, the information is stored in struct
itm_set_trm_usr.
When ITM_INS_ADT_INF is set, additional audit info is sent in struct

itm_set_adt_inf. The first part of the struct contains fixed information,
the second part contains audit/fast information that may be modified
later on.
The reason for the item insertion is presented in the itm_set_reason

struct, flagged by the ITM_INS_REASON bit.
Finally the item name can be logged by AUDIT/FAST. It is present in

struct itm_set_name when the ITM_INS_NAME bit is set. The item
name must be delivered in the form:
<installation>.<unit>.<tag>[.<subname>]
The name is saved in the item table if the bit ITM_PAR1_NAME of the
element itm_ins.par1 is also set.
NOTES This procedure can only be used for items that are not array items.
The current implementation does not handle audit trail data (future
release), the item’s name can be stored however.
RELATED • ITM_COD_INS_ARR
MESSAGES This procedure is used to insert an array item.
• ITM_COD_INS_ITM
Insert an item or subitem. No audit trail or item name in the item
table.
CODES Wrong subitem number specified in item_id.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM


• ITM_E_WRONG_GRP
• ITM_E_DUP_SUB
Subitem exists already.
• ITM_E_ITEM_EXISTS
Item exists already.
• ITM_E_NO_FREE_NUM
No free number available in this group.
• ITM_E_NO_FREE_SUB
Max number of subitems was used.
• ITM_E_WRONG_SUBT
Wrong subitem type.
• ITM_F_NO_SPACE
No empty space in itm area.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS
• ITM_E_WRONG_REP
Wrong item representation specified.
• ITM_E_WRONG_LIMIT
Incorrect number of limits specified.
• ITM_E_ITEM2LONG
Total size of item definition is too long. The size of an item
definition can be reduced by using shorter names, application info
and omitting any unnecessary PIT or limit information for example.
• ITM_E_WRONG_REP
Unknown item representation.
Incorrect number of limits defined. In case of a STRING item an
empty or negative string length is defined.
• ITM_F_LIC_PROB2
License problem.

4.6.25 Insert an item in the item table
BUS/FAST Message_id: ITM_COD_INS_ITM

MESSAGE Request data: struct itm_ins_itm
DATA struct itm_ins_itm

STRUCTS {
TLS_SHORT repres;
TLS_SHORT sub_type;
TLS_SHORT par1;
TLS_SHORT pidt;
TLS_SHORT t_filter;
} ins_itm;

DATA STRUCTS.
SEMANTICS This procedure is used to insert items in the item table. The information
about the item to be inserted is passed with struct itm_ins_itm.
ITM allows definition of the complete item_id by the application. There

is one restriction, however: that particular item_id may not yet be in use.
The most common way to fill the ins_itm.item_id is as follows:
item_id.node /*(M) node */

item_id.group /*(I) group */
item_id.number /*(M) number */
item_id.subno /*(I) subno */
item_id.attno /*(I) attno (not used) */
ITM can generate a free item_id itself or one can be supplied. An

item_id is supplied by filling in the node, group and number. These must
be non-zero values. The node number must be equal to the actual node
number. If the specified item_id is already in use then an error is
returned.
To let ITM generate an item_id, node, group and number must be zero.
ITM will search a free group and number slot and will return these
entries in item_id. Optionally the item can be created in a specific group
by supplying the group (a non-zero value).
In a distributed FAST/TOOLS environment the related node (the node
where the copy of the item exists) has to be specified in item_id.node
during insertion of the item.
It depends on what is specified in ins_itm.sub_type (specifying the item

type) what member item_id.subno means. If the item to be inserted is
specified to be a main item, the item_id.subno must always be a 0.
If on the other hand, the item is specified to be a subitem, then it is
allowed to specify a specific subitem number. When that number is
already in use, an error is returned. If, however the number was specified
to be 0, then ITM will return the first free number available (between 1
and 15 subitems may be defined per main item). Thus, if subitems 1,2 3
and 5 have already been defined for a main item, subno will become 4.
Note that if the item to be inserted is a subitem, it is good practice to pass

the item_id of the main item in ins_itm.item_id.
The contents of ins_itm.repres are used to:
• Specify the default representation of the item value.

• Specify the number of limits (e.g. if ins_itm.repres ==
REP_BOOLEAN then no limits are possible).
For a STRING item the limits define the maximum string length.
• Specify the default representation of the deadband value (see
below).
• Specify the default representation of the limit values (see below).
• Specify the default representation of the PIT filter values (see
below).
Valid representation types are:
REP_BOOLEAN /* boolean */
REP_SHORT /* short signed (16 bits) */
REP_FLOAT /* floating point */
REP_DOUBLE /* double floating */
REP_LONG /* long signed (32 bits) */

REP_STRING /* string of variable length */
REP_PERCENT is not a val.id representation for an item. However, the

value of an item can be read or set in %.
Member ins_itm.sub_type may be defined to be one of the following:
ITM_SUB_MAIN /* Item is a main item */

ITM_SUB_INTEGRAL /* Sub item is an integrator */
ITM_SUB_PULSE /* Sub item is a pulse counter */
ITM_SUB_MINMAX /* Sub item is a min/max indicator */
ITM_SUB_ROC /* Sub item is a rate of change */
ITM_SUB_TPLSS /* Sub item is typeless */
If ins_itm.sub_type does not equal ITM_SUB_MAIN then ITM checks

how many subitems had been defined already for that main item
(maximum is 15). If no related main item is found an error is returned.
If a subitem is inserted, a check is performed on the representation: the
representation of the subitem must be identical to the representation of
the main item.
• If the specified subitem is a min/max indicator, then the
representation of the subitem must be the same as of the main item.
Furthermore, that representation may not be REP_BOOLEAN.
• Inserting a pulse counter as subitem is only allowed if the main item
has REP_BOOLEAN as a representation. The representation of the
subitem itself may not be REP_BOOLEAN.
• Inserting an integrator as a subitem is only allowed if the
representation of that subitem is of REP_FLOAT or
REP_DOUBLE. It is recommended, however, to use only
REP_DOUBLE as the accuracy of REP_FLOAT decreases very
quickly when the integration period increases.
• Inserting a rate of change subitem is only allowed if the
representation of that subitem is of REP_DOUBLE.
• Inserting a typeless subitem is only allowed if the representation of
that subitem is of REP_DOUBLE.
If the flag ITM_PAR1_SAVE is set in ins_itm.par1, then the item will

be stored on disk after each value, status or quality code change.
If the flag ITM_PAR1_AUDIT is set each value, status or quality code
change will be logged by AUDIT/FAST.
For rate of change subitems one of flags:
• ITM_PAR1_ROC_DAY Calculate rate of changes per day.
• ITM_PAR1_ROC_HOUR Calculate rate of changes per hour.

• ITM_PAR1_ROC_MIN Calculate rate of changes per

minute.
• ITM_PAR1_ROC_SEC Calculate rate of changes per
second.
will be set in ins_itm.par1 as well.
In ins_itm.limits_count is specified how many limits are to be taken into

account. Three possibilities exist: 0, 2 or 4 limits. Note, that when
ins_itm.repres == REP_BOOLEAN, this member is ignored. For
STRING items it defines the maximum string value length (including
trailing zero).
In ins_itm.deadband the value of the deadband is specified. The
representation of this value is defined by ins_itm.repres.
In ins_itm.l_limit the value of the l-limit is specified. The representation
of this value is also defined by ins_itm.repres. The same applies for the
h-limit, ll-limit and hh-limit. How the limit values are used for
calculations is described in section "Limits and Deadband".
When ITM_PAR1_CLAMP is set in ins_itm.par1 and 2 or 4 limits are
specified then the value of the item will always be forced between and
including the outmost limits. For 2 limits the outmost limits are l-limit
and h-limit. When 4 limits are specified then the outmost limits are the
ll-limit and hh-limit.
In ins_itm.pidt it is indicated if a PIT filter is specified. If this member
== 0 it indicates no filter and the last 5 members of struct ins_itm are
ignored. If this member is not equal to zero, then the filter is initialized
using the values as specified in t_filter, p_filter and i_filter. The
representation of P and I are specified by ins_itm.repres. Note that
member d_filter has no meaning. The differential filter is not supported.
The filter is reset, which means that the time filter and the integration
time are started at the moment of insertion. Furthermore the integration
is activated starting with a zero value. For the use of the PIT filter,
reference should be made to chapter 2 of this manual.
The application info part of the item is reset (i.e. filled with ’0’)
NOTES This procedure can only be used for items that are not array items.
RELATED • ITM_COD_INS_ARR
MESSAGES This procedure is used to insert an array item.

• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_DUP_SUB
Subitem exists already.
• ITM_E_ITEM_EXISTS
Item exists already.
• ITM_E_NO_FREE_NUM
No free number available in this group.
• ITM_E_NO_FREE_SUB
Max number of subitems was used.
Wrong subitem type.
• ITM_F_NO_SPACE
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS
• ITM_E_ITEM2LONG
• ITM_E_WRONG_REP
Unknown item representation.
• ITM_F_LIC_PROB2
License problem.

4.6.26 Add item id error line
SYNTAX itm_log_id (umh_cont, item_id)
ARGUMENTS struct umh_context *umh_cont; /*(M) Error context */

struct itm_id *item_id; /*(I) Item id to log */
BUS/FAST None
MESSAGE

SEMANTICS This procedure is used to add an error line to the error context that
contains the item id.

4.6.27 Merge statuses
SYNTAX opt = itm_merg_opt (status,opt_flags)
ARGUMENTS int opt; /*(R) Merged status */

char status; /*(I) Value-related status */
char opt_flags; /*(I) Option flags */

SEMANTICS This procedure is used to merge value related statuses with option flags.
This procedure is recommended when both the option flags and the
status must be checked.
In the table below, the status ’A’ indicates a value-related status. The
’result status’ shows the result after the merge.
Value- Blocked Updated Offline Updated Result

related blocked offline status
status
A * YES * * ITM_ST_UPD_BLK
A YES NO * * ITM_ST_BLOCKED
A NO NO YES NO ITM_ST_OFFLINE
A NO NO * YES ITM_ST_UPD_OFF
A NO NO NO NO A
Figure 5-2 Merge table

NOTES • When a BLOCKED item is updated, the merge procedure will
result in ITM_ST_UPD_BLOCK. If the item is unblocked again,
the status remains ITM_ST_UPD_BLOCK until a real update takes
place.
• If an offline item was updated, the item obtains the status
ITM_ST_UPD_OFF. When the item comes ONLINE again, the
status immediately changes to status A.
There is no BUS/FAST equivalent for this routine. The reason is, that
this procedure does not require the process to be attached to the common
area.

4.6.28 Modify alarm info
SYNTAX [status =] itm_mod_alm(itm_cont, mod_alm)

FALSE (error) */
struct itm_mod_alm *mod_alm; /*(I) Modification parameters */
BUS/FAST Message_id: ITM_COD_MOD_ALM

MESSAGE Request data: struct itm_mod_alm
DATA struct itm_mod_alm /* modify alarm bits */

STRUCTS {
TLS_SHORT status; /* status to acknowledge */
char cng_acknow; /* change acknow bit if set */
char cng_almtyp; /* change alarm type bits if set */
char options; /* new options mask */
char spare[3];
};
SEMANTICS With this function the alarm info bits in the option flags byte can be
manipulated. This function is typically used by ALARM/FAST. If
ALARM/FAST is present in the system, the user should not use this
function.

4.6.29 Modify alarm info exclusive
SYNTAX [status =] itm_mod_almx(itm_cont, mod_alm, excl_adr)

FALSE (error) */
struct itm_mod_alm *mod_alm; /*(I) Modification parameters */
struct dur_adr *excl_adr; /*(I) Excluded proc. addr. list */
BUS/FAST None
MESSAGE
DATA struct itm_mod_alm /* modify alarm bits */

STRUCTS {
TLS_SHORT status; /* status to acknowledge */
char cng_acknow; /* change acknow bit if set */
char cng_almtyp; /* change alarm type bits if set */
char options; /* new options mask */
char spare[3];
};
SEMANTICS With this function the alarm info bits in the option flags byte can be
manipulated. Its functionality is the same as with itm_mod_alm(). The
difference between the two is the fact that all the processes mentioned in
the excl_adr list will never receive an item event message for the
specified event. Note that no element count for the address list is
included. Therefore the last element of the address list must be set to all
zeroes. If the excl_adr is passed as a NULL pointer then this function is
equivalent to the itm_mod_alm().

4.6.30 General modify an item
BUS/FAST Message_id: ITM_COD_MOD_GEN

MESSAGE Request data: see below
DATA struct itm_ins_gen

STRUCTS {
TLS_ULONG ins_layout;
} ins_gen;
struct itm_ins_itm
{
TLS_SHORT repres;
TLS_SHORT sub_type;
TLS_SHORT par1;
TLS_SHORT pidt;
TLS_SHORT t_filter;
} ins_itm;
{
} terminal-user;
{
} adt_info;

{
} adt_reason;
struct itm_set_name
{
} item_name;

DATA STRUCTS.
SEMANTICS This procedure is used to modify an item in the item table. As an option
there is the possibility to pass audit trail information, so the item
modification can be traced back to the originator.
Another feature is that the item name can be passed, which is then saved
in the memory-resident item table to allow fast item name retrieval when
the item_id is known. The item name will be removed from the item
table when the option is not used.
The required information is passed in the request data as a number of

structs. The first struct itm_ins_gen contains a bit mask of which the bits
define the remaining structs that are present in the request data.
The request data must at least comprise the structs itm_ins_gen and
itm_ins_itm (which then makes the procedure functionally equal to
ITM_COD_MOD_ITM). The other structs are optional and only present
when the corresponding bits are set in itm_ins_gen.
The following bits have been defined for the bit mask:
ITM_INS_ITM /* Item information */

ITM_INS_ADT_SRC /* Audit source code */
ITM_INS_ACT_ADR /* Activator address */
ITM_INS_TRM_USR /* Terminal or user info */
ITM_INS_ADT_INF /* Audit info */
ITM_INS_REASON /* Reason info */
ITM_INS_NAME /* Item name in item table */
Note that the structs in the request data must appear in the same order as
the definition of the bits.

Refer to the description of the ITM_COD_MOD_ITM procedure for the

meaning of the fields in struct itm_ins_itm.
Bit ITM_INS_ADT_SRC is set when AUDIT/FAST information is sent

with the request and it corresponds with the AUDIT/FAST source
indicator which is a number of type TLS_ULONG.
ITM_INS_ACT_ADR is set when the BUS/FAST address of the

originator is present (struct dur_adr).
The presence of the terminal name and user name combination is

flagged with ITM_INS_TRM_USR, the information is stored in struct
itm_set_trm_usr.
When ITM_INS_ADT_INF is set, additional audit info is sent in struct

itm_set_adt_inf. The first part of the struct contains fixed information,
the second part contains audit/fast information that may be modified
later on.
The reason of the item modification is presented in the itm_set_reason

struct, flagged by the ITM_INS_REASON bit.
Finally the item name can be logged by AUDIT/FAST. It is present in

struct itm_set_name when the ITM_INS_NAM bit is set. The item name
should be delivered in the form:
The item name is stored in the item table in memory if the flag
ITM_PAR1_NAME is also set in the element itm_ins.par1.
NOTES If ITM was generated with the ’Disk’ option, this change will be
This procedure can not be used for array items.
RELATED ITM_COD_MOD_ITM
MESSAGE This message modifies information about an item without the possibility
to audit trail the modification, or to save or remove the item name from
the item table.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM


• ITM_E_WRONG_GRP
• ITM_E_ISARR
Item is an array item.
• ITM_E_NO_MAIN
No main item found.
Wrong subitem type.
• ITM_E_WRONG_REP
Wrong representation.
• ITM_F_NO_SPACE
• ITM_E_ITEM2LONG

procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.31 Modify an item
BUS/FAST Message_id: ITM_COD_MOD_ITM

MESSAGE Request data: struct itm_ins_itm
DATA struct itm_ins_itm

STRUCTS {
TLS_SHORT repres;
TLS_SHORT sub_type;
TLS_SHORT par1;
TLS_SHORT pidt;
TLS_SHORT t_filter;
} ins_itm;

DATA STRUCTS.
SEMANTICS This procedure is used to modify an existing item. The new item
information is passed with struct itm_ins_itm.
Member ins_itm.item_id specifies the item to be modified. First this
procedure checks if the item exists and whether the item is an array item.
In both cases an error is returned.
The representation as specified in ins_itm.repres must be identical to the
representation of the item.
telREP_LONG /* long signed (32 bits) */

REP_STRING /* variable string length */
REP_PERCENT is not a val.id representation for an item. However, the

value of an item can be read or set in %.
In the case of a subitem being modified, ins_itm.subtype must be the

same: it is not allowed to alter the subitem type.
Member ins_itm.sub_type may have been defined to be one of the
following

ITM_SUB_INTEGRAL /* Sub item is an integrator */
ITM_SUB_PULSE /* Sub item is a pulse counter */
ITM_SUB_MINMAX /* Subitem is a min/max indicator */
ITM_SUB_ROC /* Sub item keeps rate of change */
ITM_SUB_TPLSS /* Sub item is typeless */
If the flag ITM_PAR1_SAVE is set in ins_itm.par1, then the item will

be stored on disk after each value, status or quality code change.
If the flag ITM_PAR1_AUDIT is set each value, status or quality code
change will be logged by AUDIT/FAST.
For rate of change subitems one of flags:
• ITM_PAR1_ROC_DAY Calculate rate of changes per day.
• ITM_PAR1_ROC_HOUR Calculate rate of changes per hour.
• ITM_PAR1_ROC_MIN Calculate rate of changes per
minute.
• ITM_PAR1_ROC_SEC Calculate rate of changes per
second.
will be set in ins_itm.par1 as well.
In ins_itm.limits_count is specified how many limits are to be taken into

account. This number may be modified. Three possibilities exist: 0, 2 or
4 limits. Note, that when ins_itm.repres == REP_BOOLEAN, this
member is ignored. For a STRING item it represents the string value
length including the trailing zero.
In ins_itm.deadband the new value of the deadband is specified. The
representation of this value is defined by ins_itm.repres.
In ins_itm.l_limit the new value of the l-limit is specified. The
representation of this value is defined by ins_itm.repres. The same
applies for the h-limit, ll-limit and hh-limit. How these limits are used
for calculating the status is described in section "Limits and Deadband".
When ITM_PAR1_CLAMP is set in ins_itm.par1 and 2 or 4 limits are
specified then the value of the item will always be forced between and

including the outmost limits. For 2 limits the outmost limits are l-limit
and h-limit. When 4 limits are specified then the outmost limits are the
ll-limit and hh-limit.
In ins_itm.pidt is indicated if a PIT filter is specified. If this member ==
0 it indicates no filter and the last 5 members of struct ins_itm are
ignored. If this member is not equal to zero, then the filter is initialized
using the new values as specified in t_filter, p_filter and i_filter. The
representation of the P and I are specified by ins_itm.repres. Note that
member d_filter has no meaning. The differential filter is not supported.
The filter is reset, which means that the time filter and the integration
time are started at the moment of insertion. Furthermore the integration
is activated starting with a value zero. For more information about the
use of the PIT filter, reference should be made to chapter 2 of this
manual.
NOTES • If ITM was generated with the ’Disk’ option, this change will be
• This procedure can not be used for array items.
RELATED • ITM_COD_MOD_GEN
MESSAGE This message modifies information about an item.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_ISARR
Item is an array item.
• ITM_E_NO_MAIN
No main item found.
Wrong subitem type.
• ITM_E_WRONG_REP
Wrong representation.
• ITM_F_NO_SPACE

• ITM_E_ITEM2LONG

procedure
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.32 Request a main event
BUS/FAST Message_id: ITM_COD_MSK_MAN

MESSAGE Request data: struct itm_msk_man
DATA struct itm_msk_man

STRUCTS {
TLS_SHORT reset_mask;
TLS_SHORT set_mask;
TLS_SHORT immed;
TLS_SHORT dummy;
} msk_man;

DATA STRUCTS.
SEMANTICS Using this routine the mask bits for the main events can be set in an item.
This mask consist of 16 bits, each representing a specific main event. In
effect, by setting a bit, an event request is made for the corresponding
main event. The procedure first locates the item in the item table. If the
item is not found, an error is returned.
In order to change one or more bits in the main event mask, a reset and
a set mask are used. First the bits in the main event mask are reset using
msk_man.reset_mask. Therefore by using this mask main events can be
turned off. Then the bits of the main event mask as specified in
msk_man.set_mask are set. This mask is therefore used to request main
events.
If the flag msk_man.immed was set unequal to 0, an event is generated
immediately.
Note that if more than one main event was set by this procedure, each of
these main events will be generated.
NOTES If ITM was generated with the ’Disk’ option, this request will be
automatically saved in the item file on disk, but only when in one of the
main event mask bits the "save needed" flg was set.
• ITM_E_NO_MAIN

• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

SYNTAX [status=] itm_mval_sta( itm_cont, item_id_arr, val_sta_arr, count,

err_count, trunc_type, length)
ARGUMENTS TLS_BOOLEAN status; /*(R) TRUE (success) */

struct itm_id *item_id_arr; /*(I) Array of requested items */
struct itm_val_sta *val_sta_arr; /*(0) Value/status of items */
int count; /*(I) The number of items ids
stored in the item_id_arr */
int *err_count; /*(O) Number of errors detected */
int trunc_type; /*(I) Truncation type */
int *length; /*(O) Length of returned
val_sta_arr */
BUS/FAST Message_id: ITM_COD_MUL_GET

MESSAGE Request data: struct itm_mul_get
Reply data: struct itm_r_mul_get
DATA struct itm_val_sta

STRUCTS {
char status; /* item status */
char opt_flags; /* item option flags */
TLS_SHORT repres; /* value representation */
union itm_val_union value; /* item value */
} val_sta;
struct itm_mul_get /* multiple get value/status */

{
TLS_SHORT count; /* number of items to get */
TLS_SHORT trunc_type; /* truncation type */
struct itm_id item_id[1]; /* first item id */
} mul_get;
struct itm_r_mul_get /* multiple get value/status reply */

{
TLS_SHORT count; /* number of items get */
TLS_SHORT err_count; /* number of errors detected */
TLS_SHORT tot_val_siz; /* total value size */

struct itm_val_sta value[1]; /* first value/status */

} r_mul_get;

DATA STRUCTS.
SEMANTICS This routine has been optimized in speed in order to increase

performance when obtaining the status, the optional status, the value, or
the value of limits or deadband of multiple items. This routine has
similar functionality to itm_val_sta().
The items are specified in item_id_arr or mul_get.item_id. The number
of items stored in this array is specified in count.
For each item the routine first searches for the item. If the item is not
found, or if the item appears to be an array item, the error counter
err_count is incremented by one. The corresponding error code is stored
with representation REP_LONG at the corresponding position of the
returned values.
When found, the item is checked to see whether it is an integrator sub
item. If this is the case, the integration value is calculated first.
The value, status and optional status are stored at the corresponding
position of the returned values.
Note that item_id_arr is of type struct itm_id. One of the members of this

These attributes only have an effect on the value. The returned status
will be that of the item.
When trunc_type is ITM_TRUNC_ALL then items with the

representation REP_DOUBLE are converted to values with a
representation REP_FLOAT. ITM_TRUNC_NONE specifies no
conversion of doubles. On return length contains the number of bytes
used in val_sta_arr. The following algorithm is used to unpack data from
val_sta_arr:

struct itm_val_sta *val_sta;

if (trunc_type == ITM_TRUNC_NONE)
val_sta++;
else if ((trunc_type == ITM_TRUNC_ALL) ||
(val_sta->repres != REP_DOUBLE))
val_sta = (struct itm_val_sta *) ((char *)val_sta +
sizeof(struct itm_val_sta) - 4);
else
val_sta++;
NOTES • The status and the optional status can be merged with routine
itm_merg_opt().
• In case of a STRING item only the first 8 bytes (7 plus trailing zero)
of the value are returned when not truncated, otherwise only the
first 4 bytes are returned (3 plus trailing zero).
• Obtaining the values as REP_PERCENT is not supported.
RELATED • itm_val_sta()
ROUTINES This routine returns the value and status of only one item.
• itm_mval_stq()
This routine is the same as itm_mval_sta() but also returns the
quality codes.
• itm_get_itm()
This routine also returns the value of the item, status, deadband or
one of the limits.
• itm_get_qc()
This routine returns the quality code in a optimal way.
RELATED • ITM_COD_MUL_GET2
MESSAGES This message also returns the quality codes.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
Note that these error codes are returned in the corresponding val_sta_arr

position and not returned in the error context of itm_context.


/quality codes
SYNTAX [status=] itm_mval_stq(itm_cont, item_id_arr, val_stq_arr, count,

err_count, trunc_type, length)
ARGUMENTS TLS_BOOLEAN status; /*(R) TRUE (success) */

struct itm_id *item_id_arr; /*(I) Array of requested items */
struct itm_val_stq *val_stq_arr; /*(O) Value/status of items */
int count; /*(I) The number of items ids
stored in the item_id_arr */
int *err_count; /*(O) Number of errors detected */
int trunc_type; /*(I) Truncation type */
int *length; /*(O) Length of returned
val_stq_arr */
BUS/FAST Message_id: ITM_COD_MUL_GET2

MESSAGE Request data: struct itm_mul_get2
Reply data: struct itm_r_mul_get2
DATA struct itm_val_stq

STRUCTS {
TLS_ULONG quality; /* item quality code */
char status; /* item status */
char opt_flags; /* item option flags */
TLS_SHORT repres; /* value representation */
union itm_val_union value; /* item value */
} val_stq;
struct itm_mul_get2 /* multiple get value/status/qual. */

{
TLS_SHORT count; /* number of items to get */
struct itm_id item_id[1]; /* first item id */
} mul_get;
struct itm_r_mul_get2 /* mult. get val./sta./qual. reply */

{
TLS_SHORT count; /* number of items got */
TLS_SHORT err_count; /* number of errors detected */


TLS_SHORT tot_val_siz; /* total value size */
struct itm_val_stq value[1]; /* first value/status/quality */
} r_mul_get;

DATA STRUCTS.

performance when obtaining the status, the optional status, the value, the
quality code, or the value of limits or deadband of multiple items. This
routine has similar functionality to itm_val_itm().
The items are specified in item_id_arr or mul_get.item_id. The number
of items stored in this array is specified in count.
For each item the routine first searches for the item. If the item is not
found, or if the item appears to be an array item, the error counter
err_count is incremented by one. The corresponding error code is stored
with representation REP_LONG at the corresponding position of the
returned values.
The value, status, quality code and optional status are stored at the
corresponding position of the returned values.
Note that item_id_arr is of type struct itm_id. One of the members of this
item value pertains. The possible options which cab be selected for this

ITM_ATT_LL /* value of low limit */
These attributes only have an effect on the value. The returned status and
quality code will be that of the item.
When trunc_type is ITM_TRUNC_ALL then items with the

representation REP_DOUBLE are converted to values with a
representation REP_FLOAT. ITM_TRUNC_NONE specifies no
conversion of doubles. On return length contains the number of bytes
used in val_sta_arr. The following algorithm is used to unpack data from

val_stq_arr:
struct itm_val_stq *val_stq;

if (trunc_type == ITM_TRUNC_NONE)
val_stq++;
else if ((trunc_type == ITM_TRUNC_ALL) ||
(val_stq->repres != REP_DOUBLE))
val_stq = (struct itm_val_stq *) ((char *)val_stq +
sizeof(struct itm_val_stq) - 4);
else
val_stq++;
NOTES • The status and the optional status can be merged with routine
itm_merg_opt().
of the value are returned when not truncated, otherwise only the
first 4 bytes are returned (3 plus trailing zero).
• Obtaining the values as REP_PERCENT is not supported.
RELATED • itm_val_sta()
ROUTINES This routine returns the value and status of only one item.
• itm_mval_sta()
This routine returns the value and status of items.
RELATED • ITM_COD_MUL_GET
MESSAGES This function returns the value and status of items.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_NO_QC
ITEM/FAST does not support quality codes.
Note that these error codes are returned in the corresponding val_stq_arr
position and not returned in the error context of itm_context.

4.6.35 Declare an item offline
SYNTAX [status=] itm_offline(itm_cont, item_id, offline)

FALSE (error) */
TLS_BOOLEAN offline /*(I) Contents of offline item */
BUS/FAST Message_id: ITM_COD_OFFLINE

MESSAGE Request data: struct itm_offline
DATA struct itm_offline

STRUCTS {
TLS_BOOLEAN offline;
} offl;

DATA STRUCTS.
SEMANTICS This procedure is used to declare an item and all its subitems on/off-line.
Normally this action will only be performed by processes that
communicate with the outside world. An example is EQUIPMENT/
FAST.
The routine requires the item_id as a parameter as well as the state in
which the item is to be set: online or offline. In the case of the routine
interface, the offline parameter must not be equal to 0 to set the item
offline. When offline == 0, then the item is declared online again.
In the case of the BUS/FAST interface, this is indicated in the same way
in offl.offline.
The procedure first tries to locate the item. If it does not exist, an error
is returned.
Subsequently, the option flag (ITM_OPT_OFFLINE) is set or reset,
depending on the member offl.offline. In the case of that value being 0
(zero), the flag is reset, if not, the flag is set.
If the state of the option flag changed due to this action, all events having
ITM_CRI_OPT as criterion are generated. Note that no events are
generated if the ITM_CRI_OPT2 criterion is used.
After this procedure the option flag UPDATED OFFLINE will always

be FALSE.
NOTES This action is not recorded on disk.
RELATED ITM_COD_BLOCK
MESSAGES This procedure is often confused with ITM_COD_OFFLINE. The
former, however, is present to manually block the updates of an item,
e.g. when a machine is taken out of operation for maintenance purposes,
all items related to that machine can be blocked. Machines are declared
offline when the link to the machine fails, for example.
ITM_COD_OFFLINE_X
The difference between the two is the fact that all the processes
mentioned in the excl_adr list of ITM_COD_OFFLINE_X will never
receive an item event message for the specified event.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.36 Declare an item offline exclusive
SYNTAX [status=] itm_offlin_x(itm_cont, item_id, offline, excl_adr)

FALSE (error) */
TLS_BOOLEAN offline /*(I) Contents of offline item */
struct dur_adr *excl_adr; /*(I) Excluded proc. address list */
BUS/FAST Message_id: ITM_COD_OFFLINE_X

MESSAGE Request data: struct itm_offline_x
DATA struct itm_offline_x

STRUCTS {
TLS_BOOLEAN offline;
struct dur_adr excl_adr[1];
} offl;

DATA STRUCTS.
SEMANTICS This procedure is used to declare an item and all its subitems on/off-line.
Normally this action will only be performed by processes that
communicate with the outside world. An example is EQUIPMENT/
FAST.
Its functionality is the same as with itm_offline(). The difference
between the two is the fact that all the processes mentioned in the
excl_adr list will never receive an item event message for the specified
event. Note that no element count for the address list is included.
Therefore the last element of the address list must be set to all zeroes. If
the excl_adr is passed as a NULL pointer then this function is equivalent
to the itm_offline()
NOTES This action is not recorded on disk.
RELATED ITM_COD_OFFLINE
MESSAGES The difference between the two is the fact that no excluded address list
can be specified for ITM_COD_OFFLINE.

• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.37 Over-write a blocked item
SYNTAX [status=] itm_owr_itm (itm_cont, owr_itm)

ARGUMENTS TLS_BOOLEAN status; /*(R) TRUE (success) or */
FALSE(error)
struct itm_set_itm *owr_itm; /*(I) Overwrite information */
BUS/FAST Message_id: ITM_COD_OWR_ITM

MESSAGE Request data: struct itm_set_itm
Reply data: struct item_id
DATA struct itm_set_itm

STRUCTS {
TLS_SHORT new_status;
TLS_SHORT repres;
TLS_SHORT add_flag;
TLS_SHORT update_size;
union itm_val_union new_value;
TLS_LONG update_info;
}owr_itm;

DATA STRUCTS.
SEMANTICS This procedure can be used to update items being blocked, which cannot
be done by the normal update procedure.
It is not only possible to update the value of these items, but also
deadband and limit values. This procedure should not be used for array
items.
First, the routine searches for the item. If the item is not found or if the
item appears to be an array item, an error is returned. Even if the item
appears to be unblocked, the item will be updated.
The value in owr_itm.item_id.attno is used to indicate whether the value
passed in this routine applies to the actual item value or to the value of
deadband or limits. In either case, the representation of the value must
be given in owr_itm.repres. The value itself is passed in
owr_itm.new_value. This procedure automatically converts the
representation to the default item representation.
Not only is the main item updated, but also all sub items (if any) even

when they are blocked.

Using the add_flag, it is possible to add a value to the current item value.
This flag is set by specifying owr_itm.add_flag to be not equal to zero.
If the member is zero, the new item value will be made equal to
owr_itm.new_value.
Note that this flag allows items to be updated without their value being
altered: set the add_flag and add a new_value of 0.
The new status of the item can be imposed. In that case, the new status
is indicated in owr_itm.new_status. If, however, this status was
specified to be ITM_ST_OLD, then the old status remains unchanged. It
is also possible to specify ITM_ST_DEF. In that case, the status is
calculated using the limits and deadband value (see section "Limits and
Deadband".
This procedure also allows the update information to be defined. This
information is passed directly to all processes that receive an event due
to this update (only if ITM_EVT_UPD_INFO was specified in the event
layout of the event request). This information must be passed in
owr_itm.update_info. The total size of the update information is passed
in owr_itm_update_size.
All events which match the criterion mask corresponding with the
changes caused by this update are generated, as well as the events
relating to the sub items.
NOTES • This procedure can not be used for array items.

• Blocked and unblocked items can be overwritten.
• Blocked and unblocked sub items of a blocked main item are also
updated.
RELATED • itm_set_itm()
ROUTINES This routine is used to update unblocked items.
RELATED • ITM_COD_SET_ITM
MESSAGES This procedure is used to update unblocked items.
• ITM_E_NO_MAIN
• ITM_E_NO_LIMIT
The requested limit has not been defined in this item.
• ITM_E_UPD2SMALL
The specified update info size is bigger than the internal buffer.

• ITM_E_WRONG_ATT
An unknown code was specified as attribute.
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.38 Return generation parameters
SYNTAX par= itm_params(par_type)
ARGUMENTS TLS_LONG par; /*(R) Value of parameter */

int par_type; /*(I) Requested parameter */
SEMANTICS This routine returns one of the generation parameters of ITM. The
requested parameter must be passed in par_type. The following
parameter types are supported:
• ITM_PAR_POOL_KBYTES
This value indicates the maximum size (in Kilobytes) of the
common memory area, used for the item table.
• ITM_PAR_MAX_GROUPS
This value gives the maximum number of groups in the item table.
• ITM_PAR_MAX_NUMBER
This value gives the maximum number of items in each group.
• ITM_PAR_MAX_APPL_INFO
This value indicates the size of the application info that is reserved
in each item.
• ITM_PAR_MAX_UPD_INFO
This value indicates the maximum size of update info that may be
passed with an update.
• ITM_PAR_INT_SECS
This value indicates the time base for the integrator sub items.
• ITM_PAR_DISK_SAVE
This value indicates if the disk save option is activated or not.
This routine is especially useful for making applications independent of

the generation.
ERROR None.
CODES

4.6.39 Obtain array-item parameters
SYNTAX [status=] itm_par_arr(itm_cont, item_id, r_par_arr)

FALSE (error) */
struct itm_r_par_arr *r_par_arr; /*(O) Array parameters */
BUS/FAST Message_id: ITM_COD_PAR_ARR

MESSAGE Request data: struct itm_par_arr
Reply data: struct itm_r_par_arr
DATA struct itm_par_arr

STRUCTS {
}par_arr;
struct itm_r_par_arr
{
TLS_SHORT repres;
TLS_SHORT nr_of_ele;
TLS_SHORT last_ele;
TLS_SHORT dummy;
}r_par_arr;

DATA STRUCTS.
SEMANTICS This procedure is used to obtain item information, being:

• The default representation
In r_par_arr.repres the default value representation is returned
• The number of elements.
In r_par_arr.nr_of_ele the total number of elements is returned
• The index of the oldest element.
In r_par_arr.last_ele the array index to the element is returned
which is regarded as the first element in the (cyclic) buffer. In
normal situations this element is the oldest one.
The routine first searches for the indicated item. If not found, or if the
item appears not to be an array item, an error is returned.

NOTES • In some cases the last element is not the oldest one. That depends
on how the array item is updated (see itm_set_arr()).
ERROR • ITM_E_NOTABITM
CODES Indicated item is no array item.
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.40 Obtain item parameters
SYNTAX [status=] itm_par_itm(itm_cont,item_id, r_par_itm)

FALSE (error) /*
struct itm_context *itm_cont; /*(M) Buffer for ITM context /*
struct itm_id *item_id; /*(I) Requested item /*
struct itm_r_par_itm *r_par_itm; /*(O) Item parameters /*
BUS/FAST Message_id: ITM_COD_PAR_ITM

MESSAGE Request data: struct itm_par_itm
Reply data: struct itm_r_par_itm
DATA struct itm_par_itm

STRUCTS {
} par_itm;
struct itm_r_par_itm
{
TLS_SHORT repres;
TLS_SHORT sub_type;
TLS_SHORT par1;
TLS_SHORT pidt;
TLS_SHORT t_filter;
} r_par_itm;

DATA STRUCTS.
SEMANTICS This procedure is used to obtain the parameters from an item. The

procedure needs the item_id to find out which item this procedure
applies to and what information is requested. The value requested is
indicated in item_id.attno. If the item is not found, or appears to be an
array item, an error is returned.
This same item_id is returned in par_itm.item_id.
The contents of par_itm.repres indicates the representation of the item.

REP_LONG /* long signed (32 bits) */
REP_STRING /* variable string length */
Member ins_par.sub_type indicates whether or not the item is a sub

item. It may be one of the following:

ITM_SUB_INTEGRAL /* Subitem is an integrator */
ITM_SUB_PULSE /* Subitem is a pulse counter */
ITM_SUB_MINMAX /* Subitem is a min/max indicator */
ITM_SUB_ROC /* Subitem is a rate of change */
ITM_SUB_TPLSS /* Subitem is typeless */
If the flag ITM_PAR1_SAVE is set in par_itm.par1, then the value,

status and quality code of the item will be stored on disk after each
update.
If the flag ITM_PAR1_AUDIT is set in par_itm.par1, then each value,
status or quality change will be logged by AUDIT/FAST.
If the flag ITM_PAR1_CLAMP is set in par_itm.par1, then the value of
the item will be forced between the outmost limits of the item.
For rate of change subitems one of following flags will be set in
ins_itm.par1 as well:
ITM_PAR1_ROC_DAY /* Calculate rate of changes per day */
ITM_PAR1_ROC_HOUR /* Calculate rate of changes per hour */
ITM_PAR1_ROC_MIN /* Calculate rate of changes per minute */
ITM_PAR1_ROC_SEC /* Calculate rate of changes per second */
In par_itm.limits_count it is specified how many limits are taken into

account. Three possibilities exist: 0, 2 or 4 limits.
In par_itm.deadband the value of the deadband is specified. The

representation of this value is defined by par_itm.repres.

In par_itm.l_limit the value of the l-limit is specified. The representation
of this value is also defined by par_itm.repres. The same applies for the
h-limit, ll-limit and hh-limit.
In par_itm.pidt is indicated if a PIT filter is specified. If this member ==
0 it indicates no filter.
If this member is not equal to zero, then the filter is using the values as
specified in t_filter, p_filter and i_filter. The representation of P and I is
specified by par_itm.repres. Note that member d_filter has no meaning.
The differential filter is not supported.
CODES Indicated item is an array item.
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.41 Create a main event
This BUS/FAST message is described for

compatibility reasons only. It is strongly
recommended to use the
ITM_COD_PAR_MANE interface.
BUS/FAST Message_id: ITM_COD_PAR_MAN

MESSAGE Request data: struct itm_par_man
DATA struct itm_par_man

STRUCTS {
struct dur_adr adr;
TLS_SHORT main_evt_bit;
TLS_SHORT evt_layout;
TLS_SHORT crit_mask;
TLS_SHORT use_buf;
TLS_SHORT msg_id;
TLS_SHORT save_flag;
} par_man;

DATA STRUCTS.
SEMANTICS This procedure is used to define a new main event. In total 16 main
events can be defined per system. The information about the main event
to be created is passed in par_man.
The destination process is specified in par_man.adr the address of: if an
event is generated, the event message will be sent to this process.
A mask of the item for this particular main event is indicated in par_man.
Each main event is indicated with one particular bit. If the indicated bit
already exists, or if already 16 main events have been created an error is
returned.
In use_buf is indicated whether or not an event buffer is used. If an event
buffer is used, use_buf must be equal to 0. The procedure will search for
an event buffer having the specified address. If the buffer is not found,
an error is returned.
In par_man.msg_id is indicated what message id must be returned in the
event message.
In par_man.evt_layout is indicated what information must be returned in
the event message in the case of an event.

This message has a certain layout. This layout depends on the

information that was specified in par_man.evt_layout. For a detailed
description of the layout of the event message reference should be made
to section "Layout of an event message".
The main event itself will be automatically recorded on disk. If,
however, par_man.save_flag is set unequal to zero, then also all items
for which this main event is requested are recorded on disk. Note that
storage on disk is only possible if ITM was generated with the ’Disk’
option.
RELATED • itm_req_evte()
ROUTINES This routine creates a single event request.
RELATED • ITM_COD_REQ_EVTE
MESSAGES This procedure creates a single event request.
ERROR The following codes can only be returned in the case of a BUS/FAST
CODES procedure.
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.42 Create a main event extended
BUS/FAST Message_id: ITM_COD_PAR_MANE

MESSAGE Request data: struct itm_par_mane
DATA struct itm_par_mane

STRUCTS {
TLS_SHORT main_evt_bit;
TLS_SHORT flags;
TLS_SHORT msg_id;
TLS_LONG evt_layout;
struct dur_adr adr;
} par_mane;

DATA STRUCTS.
SEMANTICS This procedure is used to define a new main event. In total 16 main
events can be defined per system. The information about the main event
to be created is passed in par_mane.
The destination process is specified in par_mane.adr the address of: if an
event is generated, the event message will be sent to this process.
A mask of the item for this particular main event is indicated in
par_mane. Each main event is indicated with one particular bit. If the
indicated bit already exists, or if already 16 main events have been
created an error is returned.
If bit ITM_EFLG_USE_BUF in par_mane.flags is set then an event
buffer is used. The procedure will search for an event buffer having the
specified address. If the buffer is not found, an error is returned.
In par_mane.msg_id is indicated what message id must be returned in
the event message.
In par_mane.evt_layout is indicated what information must be returned
in the event message in the case of an event.
This message has a certain layout. This layout depends on the
information that was specified in par_mane.evt_layout. For a detailed
description of the layout of the event message reference should be made
to section "Layout of an event message".
The main event itself will be automatically recorded on disk. If,
however, bit ITM_EFLG_SAVE in par_mane.flags is set, then also all
items for which this main event is requested are recorded on disk. Note

that storage on disk is only possible if ITM was generated with the
’Disk’ option.
RELATED • itm_req_evte()
ROUTINES This routine creates a single event request.
RELATED • ITM_COD_REQ_EVTE
MESSAGES This procedure creates a single event request.
CODES procedure.
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.43 Remove events
SYNTAX [status=] itm_rem_evts(itm_cont, req_adr)

FALSE (error) */
struct dur_adr *req_adr; /*(I) Address of requestor */
BUS/FAST Message_id: ITM_COD_REM_EVTS

MESSAGE Request data: struct itm_rem_evts
DATA struct itm_rem_evts

STRUCTS {
struct dur_adr adr;
} rem_evts;

DATA STRUCTS.
SEMANTICS This routine is used to remove all events requests for a requestor. This
function can typically be used before a process exits.
RELATED • itm_del_evt()
ROUTINES This routine removes a single event request.
RELATED • ITM_COD_DEL_EVT
MESSAGES This procedure removes a single event request.
ERROR No error codes can be returned in the case of a BUS/FAST procedure.

CODES

4.6.44 Request an event

itm_req_evte() and ITM_COD_REQ_EVTE
interfaces.
SYNTAX [status=] itm_req_evt(itm_cont, req_evt)

FALSE (error) */
struct itm_req_evt *req_evt; /*(I) Event information */
BUS/FAST Message_id: ITM_COD_REQ_EVT

MESSAGE Request data: struct itm_req_evt
DATA struct itm_req_evt

STRUCTS {
struct dur_adr adr;
TLS_SHORT use_buf;
TLS_SHORT msg_id;
TLS_SHORT once_flag;
TLS_SHORT immed;
TLS_LONG evt_par;
} req_evt;
DATA STRUCTS.
SEMANTICS This routine is used to request an event. This request is linked to the item
specified in req_evt.item_id. If the item does not exist an error is
returned.
As soon as the item is updated and certain criteria (specified in this
procedure) are fulfilled an event message is sent.
The (M)DUR address, to which the event message must be sent is passed
in req_evt.adr.
The event message has a certain layout. This layout depends on the

information that is requested in req_evt.evt_layout. The information that

can be requested as well as the criteria are explained extensively in
section "Layout of an event message".
In req_evt.use_buf is indicated if an event buffer is to be used. If this

member equals zero, no buffer is in use. If, however, this member is
specified to be not equal to zero this procedure will search for an event
buffer with req_evt.adr as destination address. If that buffer is not found
The message-id which is returned in an event message is specified in
req_evt.msg_id.
The ’once_flag’ indicates that only one event message is to be sent.

Directly after this event, the event request is deleted. The once_flag is
set when req_evt.once_flag is specified to be unequal to zero.
If desired it is possible to force an initial event. Immediately after the
request an event message can be sent, independent of an update being
performed. This is done by specifying req_evt. If this member is
specified to be unequal to zero, an event is generated immediately. The
criterion mask returned in the event message will be 0 (indicating no real
update criteria).
The requester information is passed in member req_evt.evt_par. This
information is stored together with the event request. This information
is transparently returned in the event message if ITM_EVT_REQ_INF
was specified in req_evt.evt_layout (see section "Event message
layout").
NOTES If an event request for the same address, having the same event layout
and the same buffer status, is sent to an item twice, the former will be
deleted.
RELATED • ITM_COD_MSK_MAN
MESSAGES This procedure requests a main event
ERROR • ITM_E_NO_EVT_BUF
CODES Event buffer does not exist.
• ITM_F_NO_SPACE
Not enough space in common area.
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM


• ITM_E_WRONG_GRP
procedure
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.45 Request an extended event
SYNTAX [status=] itm_req_evte(itm_cont, req_evte)

FALSE (error) */
struct itm_req_evte *req_evte; /*(I) Event information */
BUS/FAST Message_id: ITM_COD_REQ_EVTE

MESSAGE Request data: struct itm_req_evte
DATA struct itm_req_evte

STRUCTS {
TLS_LONG evt_layout;
TLS_LONG flags;
TLS_SHORT msg_id;
struct dur_adr adr;
TLS_LONG evt_par;
} req_evte;
DATA STRUCTS.
SEMANTICS This routine is used to request an event. This request is linked to the item
specified in req_evte.item_id. If the item does not exist an error is
returned.
As soon as the item is updated and certain criteria (specified in this
procedure) are fulfilled an event message is sent.
The (M)DUR address, to which the event message must be sent is passed
in req_evte.adr.
The event message has a certain layout. This layout depends on the
information that is requested in req_evte.evt_layout. The information
that can be requested as well as the criteria are explained extensively in
section "Layout of an event message".
If bit ITM_EFLG_USE_BUF is set in req_evte.flags then an event

buffer will be used and the procedure will search for an event buffer with
req_evte.adr as destination address. If that buffer is not found an error is
returned.

The message-id which is returned in an event message is specified in

req_evte.msg_id.
If bit ITM_EFLG_ONCE is set in req_evte.flags then only one event

message is to be sent. Directly after this event, the event request is
deleted.
If desired it is possible to force an initial event. Immediately after the
request an event message can be sent, independent of an update being
performed. This is done by setting bit ITM_EFLG_IMMED in
req_evte.flags. The criterion mask returned in the event message will be
0 (indicating no real update criteria).
The requester information is passed in member req_evte.evt_par. This
information is stored together with the event request. This information
is transparently returned in the event message if ITM_EVT_REQ_INF
was specified in req_evte.evt_layout (see section "Event message
layout").
If bit ITM_EFLG_PERCENT is set in req_evtf.flags then the value will
be returned as a fraction in relation to the outmost limits in percents. It
will be returned with the representation REP_PERCENT. When no
limits are specified then 0 will be returned.
and the same buffer status, is sent to an item twice, the former will be
deleted.
• ITM_F_NO_SPACE
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP


procedure
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.46 Request an event with flags

itm_req_evte() and ITM_COD_REQ_EVTE
interfaces.
SYNTAX [status=] itm_req_evtf(itm_cont, req_evtf)

FALSE (error) */
struct itm_req_evtf *req_evtf; /*(I) Event information */
BUS/FAST Message_id: ITM_COD_REQ_EVTF

MESSAGE Request data: struct itm_req_evtf
DATA struct itm_req_evtf

STRUCTS {
struct dur_adr adr;
TLS_SHORT flags;
TLS_SHORT msg_id;
TLS_SHORT once_flag;
TLS_SHORT immed;
TLS_LONG evt_par;
} req_evtf;
DATA STRUCTS.
SEMANTICS This routine is used to request an event. This routine has the same
functionality asd itm_req_evt(). However, the struct member flags
replaces use_buf.
When ITM_EFLG_USE_BUF is set in req_evtf.flags an event buffer is
to be used.
When ITM_EFLG_PERCENT is set in req_evtf.flags then the value
will be returned as a fraction in relation to the outmost limits in percents.
It will be returned with the representation REP_PERCENT. When no

limits are specified then 0 will be returned.
,the same buffer status and the same percent specification, is sent to an
item twice, the former will be deleted.
• ITM_F_NO_SPACE
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

procedure
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.47 Request flow control
SYNTAX [status=] itm_req_flow(itm_cont, req_flow)

FALSE (error) */
struct itm_req_flow *req_flow; /*(I) Flow control information */
BUS/FAST Message_id: ITM_COD_REQ_FLOW

MESSAGE Request data: struct itm_req_flow
DATA struct itm_req_flow /* flow control request */

STRUCTS {
struct dur_adr adr; /* requestor address */
TLS_LONG interval; /* maximum time between events */
TLS_SHORT msg_id; /* id for flow control messages */
TLS_SHORT nu1; /* spare */
} req_flow;
struct itm_flow_msg /* flow control message */

{
TLS_ULONG evt_seq; /* event sequence number */
TLS_ULONG flow_seq; /* flow control message seq. no */
} flow_msg;

DATA STRUCTS.
SEMANTICS This routine is used to request flow control. When flow control is
requested for a process, all events for that process will be numbered. The
first event after a flow control request will have sequence number 1. The
flow control sequence number can be received as part of the event.
In field req_flow.interval the maximum time between events can be
specified. If this interval is negative, the flow control for this process is
disabled.
When for the time specified in req_flow.interval no events are present
for the process, a flow control message will be sent. In this flow control
message the event sequence number of the last event will be sent again.
The requestor process can detect that possible information is missing by
checking if the sequence numbers are still increasing together with a

timeout on receiving events and flow control messages.
CODES procedure.
• ITM_E_COPY_BUF
• ITM_F_NO_SPACE
No space in item table to store request.

4.6.48 Save all items on disk
BUS/FAST Message_id: ITM_COD_SAV_ALL

MESSAGE Request data: struct itm_sav_all
DATA struct itm_sav_all

STRUCTS {
TLS_SHORT flag;
TLS_SHORT dummy;
} sav_all

DATA STRUCTS.
SEMANTICS This routine records all item data as currently present in the item table
on disk. This procedure will only be effective when ITM was defined
with the ’Disk’ option.
In sav_all.flag is indicated whether or not the item common must be left
in a locked state or not. When this member is unequal to zero, the item
table will be locked disabling all modifications to any item. Afterwards
ITM will exit. This might be useful to freeze a certain situation.
NOTES • This action puts a heavy load on the complete system, and should
therefore only be used in exceptional situations.
CODES procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.49 Save an item on disk
BUS/FAST Message_id: ITM_COD_SAV_ITM

MESSAGE Request data: struct itm_sav_itm
DATA struct itm_sav_itm /* save item on disk again */

STRUCTS {
} sav_itm;

DATA STRUCTS.
SEMANTICS This routine records all information of an item on disk. This procedure
will only be effective when ITM was generated with the ’Disk’ option.
The item to be recorded is indicated in sav_itm.item_id. All information

of the item is recorded, including the current value and status and
application info.
NOTES • The event requests linked to the item are not recorded. The main
event requests, however, are part of the item itself (bit mask) and
are therefore recorded.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT

• ITM_E_UNK_MESS

4.6.50 Update an array item
SYNTAX [status=] itm_set_arr(itm_cont, set_arr)

FALSE (error) */
struct itm_set_arr *set_arr; /*(I) Array information */
BUS/FAST Message_id: ITM_COD_SET_ARR

MESSAGE Request data: struct itm_set_arr
DATA struct itm_set_arr

STRUCTS {
TLS_SHORT new_status
TLS_SHORT first_ele;
TLS_SHORT repres;
TLS_LONG first_value;
} set_arr;

DATA STRUCTS.
SEMANTICS This procedure is used to update an array item. A number of array

elements can be updated in this procedure.
First the routine searches for the item as specified in set_arr.item_id. If
this item is not found, or if it appears to be a non-array item an error is
returned. If the array item is blocked, the routine returns immediately
without error.
Member set_arr.first_ele is an index in the (cyclic) array. Two
possibilities exist. Either this member specifies exactly the index in the
array where the first new value must be placed, or the member equals -
1. In the latter case, the first new value is placed on the ’oldest’ position.
In both cases, the remaining elements are placed in the subsequent
locations.
In set_arr.repres the representation is given of the values as passed in
this procedure. These are automatically converted to the default
representation of the array elements.
The total number of elements being update is indicated in

set_arr.nr_of_ele. The values of the subsequent new elements are

appended to this struct, starting with member set_arr.first_value.
It is possible to impose a status to the array item. This status must be

specified in set_arr.new_status. If, however, the old status must remain
unchanged, this member must be given the value ITM_ST_OLD. If this
member is specified to be ITM_ST_DEF, then the item will get the
status ITM_ST_NORMAL. If the item was Offline, the optional status
flag UPDATED OFFLINE is set.
After the update, all events for which the criterion mask corresponds
with the update are generated.
NOTES If set_arr.first_ele a positive number was specified, then all history of

the array being cyclic are lost: the position following the last new
element is considered to be the ’oldest’ element.
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.6.51 Update an array item exclusive
SYNTAX [status=] itm_set_arrx (itm_cont, set_arr, excl_adr)

ARGUMENTS TLS_BOOLEAN status; /*(R) TRUE (success) of
FALSE (error) */
struct itm_set_arr *set_arr; /*(I) Array information */
struct dur_adr *excl_adr; /*(I) Excluded proc. address list*/
DATA struct itm_set_arr

STRUCTS {
TLS_SHORT new_status
TLS_SHORT first_ele;
TLS_SHORT repres;
TLS_LONG first_value;
} set_arr;
DATA STRUCTS.
SEMANTICS This procedure is used to update the value and status of array items. This
procedure should not be used for non array items or for blocked items.
Its functionality is the same as with itm_set_arr(). The difference
between the two is the fact that all the processes mentioned in the
excl_adr list will never receive an item event message for the specified
event. Note that no element count for the address list is included.
Therefore the last element of the address list must be set to all zeroes. If
the excl_adr is passed as a NULL pointer then this function is equivalent
to the itm_set_arr()
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

4.6.52 Modify deadband or limits
SYNTAX [status=] itm_set_att(itm_cont, set_att)

ARGUMENTS TLS_BOOLEAN status /*(R) TRUE (success) or
FALSE (error) */
struct itm_set_att *set_att; /*(I) New array item information */
BUS/FAST Message_id: ITM_COD_SET_ATT

MESSAGE Request data: struct itm_set_att
DATA struct itm_set_att

STRUCTS {
TLS_SHORT dummy;
TLS_SHORT repres;
} set_att;

DATA STRUCTS.
SEMANTICS This procedure is used to modify the values of deadband or limits. The
item to which this procedure applies is specified in set_att.item_id. In
the attno member of the item_id is specified whether the deadband or
one of the limits is to be modified (also see section DATA
STRUCTURES). This member may contain one of the following
values:
• ITM_ATT_HL
This value specifies the high limit.
• ITM_ATT_LL
This value specifies the low limit.
• ITM_ATT_HHL
This value specifies the high high limit.
• ITM_ATT_LLL
This value specifies the low low limit.
• ITM_ATT_DB
This value specifies the deadband.

The representation of the value that is passed in set_att.new_value is

given in set_att.repres. If an attempt is made to modify a limit when no
limits were defined an error is returned.
RELATED itm_get_itm()
ROUTINES This routine has identical functionality.
RELATED ITM_GET_ITM
MESSAGES This procedure has identical functionality.
CODES procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_NO_LIMIT
• ITM_E_WRONG_ATT
An unknown code was specified as an attribute.
• ITM_E_UNK_MESS

4.6.53 Update general item information
SYNTAX [status=] itm_set_gen(itm_cont, set_gen)

FALSE (error) */
struct itm_set_gen *set_gen; /*(I) Array information */
BUS/FAST Message_id: ITM_COD_SET_GEN

MESSAGE Request data: struct itm_set_gen
DATA struct itm_set_gen

STRUCTS {
TLS_SHORT save_flag;
TLS_SHORT dummy;
TLS_LONG set_layout;
}
struct itm_set_val
{
TLS_SHORT add_flag;
TLS_SHORT dummy;
TLS_SHORT repres;
}
struct itm_set_qc
{
TLS_SHORT add_flag;
TLS_SHORT dummy;
TLS_ULONG qc;
}
struct itm_set_flg_app
{
TLS_LONG update_mask;
TLS_LONG set_mask;
}
{

}
{
}
{
}
struct itm_set_name
{
}
struct itm_set_mod_tim
{
TLS_ULONG mod_tim;
}
struct itm_set_info
{
TLS_SHORT tot_size;
TLS_SHORT info_size;
TLS_LONG info[1];
}
struct itm_set_exc
{
TLS_SHORT tot_size;
TLS_SHORT count;
struct dur_adr adr[1];
}
struct itm_set_alm_fns
{
TLS_BOOLEAN force_normal;
}
struct itm_set_block
{
TLS_BOOLEAN block;
}
struct itm_set_lock
{

TLS_BOOLEAN lock;
TLS_BOOLEAN unlock;
TLS_ULONG lock_id;
TLS_ULONG timeout;
}

DATA STRUCTS.
SEMANTICS With this routine and BUS/FAST message the value, status, quality
code, application flags and application info for an item can be set.
Further extra information can be delivered to be used in case of auditing
this update and for event generation.
The item id can be specified in itm_set_gen.itm_id.
The save flag can only be used in case of the BUS/FAST message
interface. In case of the routine interface the save flag will be ignored.
If the save flag is not zero, the modified item will be saved on disk.
The layout of a set message depends on the information that is requested

to set with the set request. Which information must be set is passed as an
argument in the element ‘set_layout’. The first part of the set message is
identical for all set messages. It consists of a struct itm_set_gen.
Member itm_set_gen.set_layout is a bit mask, each bit represented by a
symbol. By AND-ing itm_set_gen.set_layout with one of the possible
symbols, you can specify whether or not certain information is present
in the request. The following table represents all possible symbols. If
one of the symbols is present in itm_set_gen.set_layout the table shows
the type of information that is required to be present in the request. Note
that the sequence in which the information is requested is always the
same.
struct itm_set_gen
ITM_SET_VAL struct itm_set_val new value/status
ITM_SET_QC struct itm_set_qc new quality code
ITM_SET_APP_FLAG struct itm_st_flg_app new application flags
ITM_SET_OWR none overrule block
ITM_SET_ADT_SRC TLS_ULONG audit source code
ITM_SET_ACT_ADR struct dur_adr activator address

ITM_SET_TRM_USR struct itm_set_trm_usr terminal/user info
ITM_SET_ADT_INF struct itm_set_adt_inf audit info
ITM_SET_REASON struct itm_set_reason reason info
ITM_SET_NAME struct itm_set_name item name
ITM_SET_MOD_TIM struct itm_set_mod_tim modification time
ITM_SET_STRING struct itm_set_info string item value
ITM_SET_INF_APP struct itm_set_info new application info
ITM_SET_EXC_APP struct itm_set_exc DUR address array
ITM_SET_UPD_INF struct itm_set_info update appl. info
ITM_SET_ALM_FNS struct itm_set_alm_fns TRUE or FALSE
ITM_SET_BLOCK struct itm_set_block TRUE or FALSE
ITM_SET_ALM_FAS struct itm_set_alm_fas TRUE or FALSE
ITM_SET_EVT none nome
Figure 4.7 Argument layout itm_set_gen() / ITM_SET_GEN

If ITM_SET_VAL is specified, the new value and status can be
specified. In itm_set_gen.itm_id.attno it is indicated whether the value
passed in this request applies to the actual item value or to the value of
deadband or limits. In either case, the representation of the value must
be given in itm_set_val.repres. The value itself is passed in
itm_set_val.new_value.
A new value for a STRING item can be passed in struct itm_set_val as
long as the total string (including trailing zero) fits in 8 bytes. If not then
the string must be provided as a separate info block
(ITM_SET_STRING).
This procedure automatically converts the representation to the default
item representation. If the value specifies the item value, this procedure
first checks if the item is blocked. If so, the value will not be updated and
no error is returned (see also ITM_SET_OWR). Not only the main item
is updated, also related sub items (if any).
For a STRING item it means that the new string will be concatenated to
the existing string, as long as the maximum length is not exceeded, in
which case the status becomes overranged.
This flag can be set to:

• ITM_ADD_FLG_ABS
Set absolute. Sets the value to an absolute value.
• ITM_ADD_FLG_REL
Set relative. Adds the specified value to the current one.
Note that this flag allows items to be updated without changing its value:
set the add_flag to ITM_ADD_FLG_REL and set the new value to 0.
This might be useful when only the status of an item must be updated,
not its value. The new status of an item can be imposed. In that case, the
new status is indicated in itm_set_val.new_status. If, however, this
status is specified to be ITM_ST_OLD, then the old status remains
unchanged. It is also possible to specify ITM_ST_DEF. In that case, the
status is calculated using the limits and deadband value. For more
information about this calculation, reference should be made to the
ITEM/FAST Programmer’s Guide, section ‘Limits and Deadband’. All
events of which the criterium mask corresponds with the changes caused
by this update are generated, also the events that are related to the
subitem.
If ITM_SET_QC is specified the new quality code can be specified. The

quality code of the item will only be changed if the item is not blocked
(see also ITM_SET_OWR). The add_flag specifies the way to calculate
the new quality code. This flag can be set to:
• ITM_ADD_FLG_ABS
Set absolute. Sets the value to an absolute value.
• ITM_ADD_FLG_REL
Set relative. Adds the specified value to the current one.
• ITM_ADD_FLG_AND
AND the old and new quality code.
• ITM_ADD_FLG_OR
OR the old and new quality code.
All events of which the criterium mask corresponds with the changes
caused by this update are generated, also the events that are related to the
subitem.
If ITM_SET_APP_FLAG is specified the application flags can be

changed. Using this information each bit of the application flags can be
set or reset individually. In order to change one or more flags, two masks
have to be supplied:
• Update mask (itm_set_flg_app.update_mask).
This mask indicates the bits of interest.

• Set/reset mask (itm_set_flg_app.set_mask).

This mask indicates how the bits specified in the update mask must
be set/reset.
In the update mask, the bits of interest are indicated with a ‘1’. All bits
that should not be altered are indicated with a ‘0’ (zero). The value of the
bits of interest are set equal to the value as specified in the set/reset
mask.
If ITM_SET_OWR is specified the changes will be made whether or not

the item is blocked.
If ITM_SET_ADT_SRC is specified and the TLS_ULONG value is not

zero, AUDIT/FAST logging will be done for status and value changes
If ITM_SET_ACT_ADR is specified the activator BUS/FAST address

can be specified. This address will be included in AUDIT/FAST
loggings.
If ITM_SET_TRM_USR is specified the terminal name and the user

name of the activator can be specified. These names will be included in
AUDIT/FAST loggings.
If ITM_SET_ADT_INF is specified additional audit info can be

specified. This info will be included in AUDIT/FAST loggings.
If ITM_SET_REASON is specified update reason info can be specified.

This info will be included in AUDIT/FAST loggings.
If ITM_SET_NAME is specified the item name can be specified. The

layout of the name should be:
The item name will be included in AUDIT/FAST loggings. If the name
is not specified in this set command, the item name stored in the item
table will be used. If that name also not is present, then the item id,
translated to ASCII, will be used.
If ITM_SET_MOD_TIM is specified then a modification time can be

specified. When not specified, the modification time of an item or
subitem is set to the current time whenever the value, status or quality
code is changed via any itm routine or BUS/FAST message. This is also
the case using this routine or BUS/FAST message. However this default
behavior for this routine or BUS/FAST message can be changed by

supplying a modification time here. When one supplied and it has a

value of zero then the modification time of the item is not touched. When
a non-zero value is supplied then this modification time is used instead
of the current time. The modification time is supplied in seconds since
1970 GMT.
If ITM_SET_INF_APP is specified new application information for the

item can be specified. The new information is specified in
itm_set_info.info. The size of the application info is specified in
itm_set_info.info_size, the remaining bytes will be unchanged. Note
that the total size of this information will be truncated to
MAX_APP_INFO, which is defined at installation time (see FAST/
TOOLS Installation Manual).
IF ITM_SET_EXC_APP is specified all related events will be sent to

other applications except for the applications mentioned in application
array. The applications can be specified in the adr[x]. The total size of
this struct is set in tot_size, the number of entries in the array is set in
count.
If ITM_SET_UPD_INF is set update information can be specified. This

information is passed directly to all applications that want to receive this
information. The update information must be specified in
itm_set_info.info. The total size of the update information is passed in
itm_set_info.info_size. Note that the total size of this information should
not exceed MAX_UPD_INFO, which is defined at installation time (see
FAST/TOOLS Installation Manual).
If ITM_SET_ALM_FNS is specified a TLS_BOOLEAN flag can be

specified which value will be stored in the item option flags (bit
ITM_OPT2_ALM_FNS). TRUE causes the bit to be set. When the bit is
set the alarm state of the item will always be "normal". Setting this bit
will automatically reset bit ITM_OPT2_ALM_FAS.
If ITM_SET_BLOCK is specified a TLS_BOOLEAN flag can be

ITM_OPT_BLOCK). TRUE causes the bit to be set. When the bit is set
the item will be blocked (see 4.6.4).
If ITM_SET_ALM_FAS is specified a TLS_BOOLEAN flag can be

ITM_OPT2_ALM_FAS). TRUE causes the bit to be set. When the bit is
set the alarm state of the item will always be "alarm". Setting this bit will

automatically reset bit ITM_OPT2_ALM_FNS.
If ITM_SET_EVT is specified all processes that requested event

notification by setting the ITM_CRI_EVT criterium will be notified.
If ITM_SET_LOCK is specified then lock information in struct

itm_set_lock is passed.
To lock an item, set itm_set_lock.lock to TRUE, specify a unique value
in itm_set_lock.lock_id and optionally specify a timeout in
itm_set_lock.timeout. When the timeout is set to zero then the system
default is used (which is set in itm.sup). The user and terminal of the lock
owner can be supplied by ITM_SET_TRM_USR.
To unlock the item, set itm_set_lock.unlock to TRUE and supply in
itm_set_lock.lock_id the same id that was used to lock the item.
While the item is locked any update to the item using itm_set_gen() fails
unless ITM_SET_LOCK is passed and itm_set_lock.lock_id is given a
value that is the same as used to lock the item. In this case
itm_set_lock.lock and itm_set_lock.unlock are set to FALSE. The
timeout is reset to the value given at the time the item was locked or set
to itm_set_lock.timeout if this field contains a non-zero value.
Whether the item is locked can also be optained via the option flag
ITM_OPT2_LOCKED.
The item will be recorded on disk only when ITM was generated with
the ‘Disk’ option. When the item is saved on disk, the whole item is
saved including value, status, quality code, main events, etc.
CODES Indicated item is an array item and a value/status change was
specified (only valid for ITM_SET_VAL).
• ITM_E_WRONG_SUB
Wrong subitem number specified in itm_id.
• ITM_E_NO_MAIN
• ITM_E_NO_LIMIT
• ITM_E_UPD2SMALL
• ITM_E_WRONG_ATT
• ITM_E_WRONG_NUM
Wrong number in itm_id.
• ITM_E_WRONG_GRP

Wrong group in itm_id.

Wrong node number in itm_id.
• ITM_E_NO_QC
ITEM/FAST does not support quality codes.
• ITM_E_LOCKED
The item is already locked by another user
• ITM_E_LOCKINUSE
The lock id supplied is already in use for a lock on another item
• ITM_E_NOTLOCKED
The item is not locked
The following codes can only be returned in case of a BUS/FAST

message interface:
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.7.54 Update item value/status
SYNTAX [status=] itm_set_itm(itm_cont,set_itm)

FALSE (error) */
struct itm_set_itm *set_itm; /*(I) New item information */
BUS/FAST Message_id: ITM_COD_SET_ITM

MESSAGE Request data: struct itm_set_itm
DATA struct itm_set_itm /* set value/status */

STRUCTS
{
TLS_SHORT repres;
TLS_SHORT add_flag;
} set_itm;

DATA STRUCTS.
SEMANTICS This procedure is used to update the value and status of items. This
procedure should not be used for array items or blocked items.
First the routine searches for the item. If the item is not found or if the
item appears to be an array item, an error is returned.
In set_itm.item_id.attno it is indicated whether the value passed in this
routine applies to the actual item value or to the value of deadband or
limits. In either case, the representation of the value must be given in
set_itm.repres. The value itself is passed in set_itm.new_value.
A new value for a STRING item can be passed in struct itm_set_itm as
long as the total string (including trailing zero) fits in 8 bytes. Otherwise
the related function itm_set_gen must be used.
This procedure automatically converts the representation to the default
item representation.

If the value specifies an item value, the procedure first checks if the item
is blocked. If so, the value will not be updated and no error is returned.
Not only the main item is updated, also all sub items (if any) even if they
are blocked.
For a STRING item it means that the new string will be concatenated to
the existing string, as long as the maximum length is not exceeded, in
which case the item status is set to OVERRANGED.
This flag is set by specifying set_itm.add_flag being one of the
following flags:
• ITM_ADD_FLG_ABS add value
• ITM_ADD_FLG_REL add value relative
If none of these flags is set, the new item value will be made equal to
set_itm.new_value.
Note that this flag allows items to be updated without changing its value:
set the flag to ITM_ADD_FLG_REL and set a new_value of 0. This
might be useful when only the status of an item must be updated, not its
value.
The new status of the item can be imposed. In that case, the new status
is indicated in set_itm.new_status. If, however, this status was specified
to be ITM_ST_OLD, then the old status remains unchanged. It is also
possible to specify ITM_ST_DEF. In that case, the status is calculated
using the limits and deadband value. For more information about this
calculation, reference should be made to section "Limits and
Deadband".
This procedure also allows the update information to be defined. This
information is passed directly to all processes that receive an event due
to this update (only if ITM_EVT_UPD_INFO was specified in the event
layout of the event request). This information must be passed in
set_itm.update_info. The total size of the update information is passed
in set_itm.update_size.
All events of which the criterion mask correspond with the changes
caused by this update are generated, also the events that are related to the
subitems.
RELATED itm_owr_itm()
ROUTINES This routine allows blocked items to be updated.
itm_set_gen()
With this routine the value, status, quality code, application flags,
application info and update info of an item can be set.

RELATED ITM_COD_OWR_ITM
MESSAGES This procedure allows blocked items to be updated.
ITM_COD_SET_GEN
With this BUS/FAST message the value, status, quality code,
application flags, application info and update info of an item can be set.
• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_NO_LIMIT
• ITM_E_UPD2SMALL
• ITM_E_WRONG_ATT
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

procedure.
• ITM_E_COPY_BUF
• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.7.55 Update item value/status exclusive
SYNTAX [status=] itm_set_itmx (itm_cont, set_itm, excl_adr)

FALSE (error) */
struct itm_set_itm *set_itm; /*(I) New item information */
struct dur_adr *excl_adr; /*(I) Excluded proc. address list*/
DATA struct itm_set_itm /* set value/status */

STRUCTS
{
TLS_SHORT repres;
TLS_SHORT add_flag;
} set_itm;

DATA STRUCTS.
SEMANTICS This procedure is used to update the value and status of items. This
procedure should not be used for array items or blocked items. Its
functionality is the same as with itm_set_itm(). The difference between
the two is the fact that all the processes mentioned in the excl_adr list
will never receive an item event message for the specified event. Note
that no element count for the address list is included. Therefore the last
element of the address list must be set to all zeroes. If the excl_adr is
passed as a NULL pointer then this function is equivalent to the
itm_set_itm().
RELATED itm_owr_itm()
ROUTINES This routine allows blocked items to be updated.
itm_set_itm()
This routine is used to update the value and status of items.

• ITM_E_WRONG_SUB
• ITM_E_NO_MAIN
• ITM_E_NO_LIMIT
• ITM_E_UPD2SMALL
• ITM_E_WRONG_ATT
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP

4.7.56 Force event buffer to be sent
SYNTAX [status=] itm_snd_buf(itm_cont,adr)

FALSE (error) */
struct dur_adr *adr; /*(I) Process address to send */
buffer to */
BUS/FAST Message_id: ITM_COD_SND_BUF

MESSAGE Request data: struct itm_snd_buf
Reply data: - (Only size and code are returned).
DATA struct itm_snd_buf

STRUCTS {
struct dur_adr adr;
} snd_buf;

DATA STRUCTS.
SEMANTICS In normal situations, an event buffer will only be sent when the buffer is
full or when a timeout has expired. This procedure is used to force an
event buffer to be sent to its destination immediately.
The procedure first searches for an event buffer having a destination
address as specified in snd_buf.adr. If this buffer is not found, an error
is returned.
When the buffer is found, the size is checked. If the buffer appears to be
empty, no message is sent. If the buffer does contain information, the
contents are sent to the destination process, the buffer is cleared.
RELATED itm_get_buf()
ROUTINES This routine returns the contents of the event buffer as an argument
instead of BUS/FAST message.
ERROR • ITM_E_NO_EVTBUF
CODES Event buffer was not found.
procedure.
• ITM_E_COPY_BUF


• ITM_E_DSK_FAIL
• ITM_E_NO_OUT
• ITM_E_UNK_MESS

4.7.57 Obtain item/value status (optimized)
SYNTAX [status=] itm_val_sta(itm_cont, item_id, val_sta, repres)

FALSE (error) */
struct itm_val_sta *val_sta; /*(O) Value/status of item */
int repres; /*(I) Representation of item */
DATA struct itm_val_sta

STRUCTS {
char status;
char opt_flags;
TLS_SHORT repres;
union itm_val_union value;
} val_sta;

DATA STRUCTS.

performance when obtaining the status, optional status, value of an item
or value of limits or deadband. This routine has less functionality than
itm_get_itm().
The routine first searches the item as specified in item_id. If the item is
not found, or if the item appears to be an array item, an error is returned.
The status of the item is returned in val_sta.status. The flags of the
optional status are stored in val_sta.option.
The representation of the item value is converted to the representation as
requested in repres. This representation is also returned in
val_sta.repres.
Note that item-id is of type struct itm_id. One of the members of this
item value pertains. The possible options to select for this member (i.e.
get_itm.item_id.attno) are:


These attributes only have affect on the value. The returned status will
be that of the item.
NOTES • The status and the optional status can be merged with routine.
itm_merg_opt().
will be returned.
ROUTINES This routine has more functionality than itm_val_sta() but is not
optimized in speed. It will also return the full value of a string item
when it exceeds 8 bytes.
RELATED • ITM_COD_GET_ITM
MESSAGES This procedure is the BUS/FAST equivalent of itm_get_itm().
CODES Wrong sub item number specified in item_id .
• ITM_E_NO_MAIN
• ITM_E_WRONG_NUM
• ITM_E_WRONG_GRP


Compiling, Linking, Running ITM programs on UNIX Using ITM on UNIX
Appendix A: Using ITM on UNIX

A.1 Compiling, Linking, Running ITM
programs on UNIX
Compiling, linking and running a program on UNIX platforms using
ITM requires the following:
All program source files have to include two header files:
#include <tools.h>
#include <itm.h>
These files reside on directory /tls/inc on one of the disks.

usual manner:
cc -I /tls/inc program.c
Linking the object requires the library of BUS/FAST and, when ITEM/
FAST routines are used, the library of ITEM/FAST to link with. These
files reside on directory /tls/lib as buslib.a and itmlib.a.
The link command for a program with name program that uses both
ITEM/FAST routine interface and BUS/FAST interface could look like
this:
cc -o program program.o /tls/lib/itmlib.a /tls/lib/buslib.a
ITM Progammer’s Guide A-1

Using ITM on UNIX Compiling, Linking, Running ITM programs on UNIX
B-2 ITM Progammer’s Guide

Compiling, Linking, Running ITM programs Using ITM on Windows
Appendix B: Using ITM on Win-

dows
B.1 Compiling, Linking, Running ITM
programs
Compiling, linking and running a program on a Windows platforms
using ITM requires the following:
All program source files have to include two header files:
#include <tools.h>
#include <itm.h>
These files reside on directory %TLS_ROOT_PATH%\tls\inc on one of

the disks.
usual manner:
> cl -c -MD -D_WINNT -D_WIN32_WINNT=0x0500 -W1

-Ox -I. -I%TLS_ROOT_PATH%\tls\inc program.c
Linking the object requires the dll of BUS/FAST and, when ITEM/
FAST routines are used, the dll of ITEM/FAST to link with.
The link command for a program with name program that uses both
ITEM/FAST routine interface and BUS/FAST interface could look like
this:
> cl program.obj
%TLS_ROOT_PATH%\tls\lib\busimp.lib
%TLS_ROOT_PATH%\tls\lib\itemimp.lib
mpr.lib kernel32.lib user32.lib advapi32.lib
-o program [...]
ITM Progammer’s Guide B-1

Using ITM on Windows Compiling, Linking, Running ITM programs
B-2 ITM Progammer’s Guide

Index
Index
A criterion mask 3-12

acknowledge
item status 4-14
D
items 3-11 data area
optional statuses 2-9 attach to 4-18
additional statuses 2-8 detach from 4-30
alarm info deadband 2-2, 4-4
modify 4-69 modify 4-122
modify exclusive 4-70 values 3-7
alarm type deallocate event buffer 4-21
optional statuses 2-9 declare item offline 4-88
allocate event buffer 4-16 declare item offline exclusive 4-90
application flags 2-18, 3-11 defining the default representation 3-5
update 4-31 delete
application information 2-18, 3-11 array item 4-22
update 4-54 event request 4-23
array items 2-5, 3-9 event request with flags 4-25
delete 4-22 item 4-27
get parameters 4-96 main event 4-29
get status 4-33 detach from data area 4-30
get value 4-33 disable flow control 4-114
update 4-119
update exclusive 4-121 E
attach to data area 4-18 environment of ITEM/FAST 1-3
error handling 4-2
B event actions 2-2
block an item 4-19 event buffers 2-24
blocked allocate 4-16
optional statuses 2-8 deallocate 4-21
blocked items 3-9 force to be sent 4-138
buffers get information 4-36
event 2-24 event manipulations 3-11
BUS/FAST interface 1-4 event message
buffers 3-15
C layout 4-6
event requests 2-17
common data area 1-2, 3-3 events
compiling programs 4-2 delete 4-23
create main event 4-101, 4-103 delete with flags 4-25
creating remove all 4-105
main item 3-4 request 4-106, 4-109
subitem 3-4 request with flags 4-112
criterion flags 2-2 requesting 3-11
ITM Programmer’s Guide 1

Index
F declare offline exclusive 4-90

delete 4-27
flags get information 4-38, 4-42
application 3-11 get name 4-46
flow control 2-25 get parameters 4-98
disable 4-114 get quality code 4-48
request 4-114 get status 4-49, 4-140
force event buffer to be sent 4-138 get value 4-51, 4-140
insertion 3-17
G modify 4-71, 4-75
general attributes 2-1 offline 3-10
general data structs 4-5 over-write blocked 4-92
generation parameters quality code 2-1
return 4-95 save all on disk 4-116
get array item save on disk 4-117
parameters 4-96 status 2-1
status 4-33 statuses 2-5
value 4-33 structure 2-1
get event buffer information 4-36 update exclusive 4-136
get item update general information 4-124
information 4-38, 4-42 update quality code 3-7, 4-124
multiple get 4-81, 4-85 update status 3-5, 4-133, 4-136
name 4-46 update value 3-5, 4-133, 4-136
parameters 4-98 value 2-1
quality code 4-48 item group 4-53
status 4-48, 4-49, 4-140 item id error line 4-67
value 4-48, 4-51, 4-140 item manipulations 3-4
group 3-2 item quality code 2-10
item statuses 2-5
I item table 1-2
I - filter 2-14 insert array item 4-56
information insert item 4-58, 4-62
application 3-11 item values 2-4
request 2-20 item/event information
update 2-19 saving on disk 3-17
insert array item in item table 4-56 item-id 3-1
insert item in item table 4-58, 4-62 ITM
insertion of items 3-17 interfaces with 2-30
interface itm_acknow() 4-14
BUS/FAST 1-4 itm_att() 4-18
routine 1-4 ITM_COD_ACKNOW 4-14
interfaces with ITM 1-4, 2-30 ITM_COD_ALL_BUF 4-16
item 1-1 ITM_COD_BLOCK 4-19
acknowledge 3-11 ITM_COD_DEA_BUF 4-21
acknowledge status 4-14 ITM_COD_DEL_ARR 4-22
block 4-19 ITM_COD_DEL_EVT 4-23
blocked 3-9 ITM_COD_DEL_EVTF 4-25
creating 3-4 ITM_COD_DEL_ITM 4-27
declare offline 4-88 ITM_COD_DEL_MAN 4-29
2 ITM Programmer’s Guide

Index
ITM_COD_FLG_APP 4-31 itm_mod_alm() 4-69

ITM_COD_GET_ARR 4-33 itm_mod_almx() 4-70
ITM_COD_GET_ITM 4-38 itm_mval_sta() 4-81
ITM_COD_GET_ITME 4-42 itm_mval_stq() 4-85
ITM_COD_GET_NAME 4-46 itm_offlin_x() 3-10, 4-90
ITM_COD_INF_APP 4-54 itm_offline() 3-10, 4-88
ITM_COD_INS_ARR 4-56 ITM_OPT_ACKNOW 2-8
ITM_COD_INS_GEN 4-58 ITM_OPT_ALM_FNS 2-8
ITM_COD_INS_ITM 4-62 ITM_OPT_ALM_T1 2-8, 2-10
ITM_COD_MOD_ALM 4-69 ITM_OPT_ALM_T2 2-8, 2-10
ITM_COD_MOD_GEN 4-71 ITM_OPT_BLOCK 2-8, 4-130
ITM_COD_MOD_ITM 4-75 ITM_OPT_OFFLINE 2-8
ITM_COD_MSK_MAN 4-79 ITM_OPT_UPD_BLK 2-8
ITM_COD_MUL_GET 4-81 ITM_OPT_UPD_OFF 2-8
ITM_COD_MUL_GET2 4-85 ITM_OPT2_ALM_FAS 4-130
ITM_COD_OFFLINE 3-10, 4-88 ITM_OPT2_ALM_FNS 4-130
ITM_COD_OFFLINE_X 3-10, 4-90 itm_owr_itm() 4-92
ITM_COD_OWR_ITM 4-92 itm_par_arr() 4-96
ITM_COD_PAR_ARR 4-96 itm_par_itm() 4-98
ITM_COD_PAR_ITM 4-98 ITM_PAR1_AUDIT 4-64, 4-76, 4-99
ITM_COD_PAR_MAN 4-101 ITM_PAR1_CLAMP 4-65, 4-76, 4-99
ITM_COD_PAR_MANE 4-103 ITM_PAR1_NAME 4-59, 4-60, 4-73
ITM_COD_REM_EVTS 4-105 ITM_PAR1_ROC_DAY 4-64, 4-76, 4-
ITM_COD_REQ_EVT 4-106 99
ITM_COD_REQ_EVTE 4-109 ITM_PAR1_ROC_HOUR 4-64, 4-76,
ITM_COD_REQ_EVTF 4-112 4-99
ITM_COD_REQ_FLOW 4-114 ITM_PAR1_ROC_MIN 4-65, 4-76, 4-
ITM_COD_SAV_ALL 4-116 99
ITM_COD_SAV_ITM 4-117 ITM_PAR1_ROC_SEC 4-65, 4-76, 4-
ITM_COD_SET_ARR 4-119 99
ITM_COD_SET_ATT 4-122 ITM_PAR1_SAVE 4-64, 4-76, 4-99
ITM_COD_SET_GEN 4-124 itm_params() 4-95
ITM_COD_SET_ITM 4-133 itm_rem_evts() 4-105
ITM_COD_SND_BUF 4-138 itm_req_evt() 4-106
itm_del_evt() 4-23 itm_req_evte() 4-109
itm_del_evtf() 4-25 itm_req_evtf() 4-112
itm_det() 4-30 itm_req_flow() 4-114
ITM_EFLG_PERCENT 4-110, 4-112 itm_set_arr() 4-119
ITM_EFLG_USE_BUF 4-112 itm_set_arrx() 4-121
itm_get_arr() 4-33 itm_set_att() 4-122
itm_get_buf() 4-36 itm_set_gen() 2-10, 4-124
itm_get_itm() 4-38 itm_set_itm() 4-133
itm_get_itme() 4-42 itm_set_itmx() 4-136
itm_get_nam() 4-46 itm_snd_buf() 4-138
itm_get_qc() 4-48 itm_val_sta() 4-140
itm_get_sta() 4-49 ITMCOM 1-2
itm_get_val() 4-51
itm_log_id() 4-67 L
itm_merg_opt() 4-68 limit values 3-8

Index
limits 2-2, 4-4 PIT filter 2-12

modify 4-122 PIT values 3-8
values 3-7 programs
linking programs 4-2 compiling 4-2
locking 2-33 linking 4-2
running 4-2
M
main events 2-22 R
create 4-101, 4-103 relative values 2-11
delete 4-29 remove events 4-105
request 4-79 REP_BOOLEAN 4-40, 4-44, 4-51, 4-
requesting 3-14 63, 4-75, 4-99
main item REP_BYTE 4-40, 4-44, 4-51
creating 3-4 REP_DEF 4-40, 4-44, 4-51
manipulations REP_DOUBLE 4-40, 4-44, 4-51, 4-63,
event 3-11 4-75, 4-99
merge statuses 4-68 REP_FLOAT 4-40, 4-44, 4-51, 4-63, 4-
merge table 2-10 75, 4-99
modify REP_LONG 4-40, 4-44, 4-51, 4-63, 4-
alarm info 4-69 75, 4-99
alarm info exclusive 4-70 REP_PERCENT 4-40, 4-44, 4-51, 4-64,
deadband 4-122 4-76
item 4-71, 4-75 REP_SHORT 4-40, 4-44, 4-51, 4-63, 4-
limits 4-122 75, 4-99
multiple get item REP_STRING 4-40, 4-44, 4-51, 4-64,
quality 4-85 4-76, 4-99
status 4-81, 4-85 request
value 4-81, 4-85 event 4-106, 4-109
event with flags 4-112
N flow control 4-114
node 3-1, 4-53 main events 4-79
number 3-2 requester information 2-20
requesting events 3-11
O requesting main events 3-14
return codes
offline testing 4-3
optional statuses 2-9 return generation parameters 4-95
offline items 3-10 routine interface 1-4
optional statuses running programs 4-2
acknowledge 2-9
alarm type 2-9 S
blocked 2-8
offline 2-9 save all items on disk 4-116
updated blocked 2-8 save an item on disk 4-117
updated offline 2-9 statuses
over-write blocked item 4-92 merge 4-68
value-related 2-5
P struct dur_adr 4-5
struct itm_context 4-5
P-Filter 2-12 struct itm_flow_msg 4-11

Index
struct itm_id 4-5

subitems 2-25
creating 3-4
subno 3-2
T
testing return codes 4-3
T-filter 2-15
U
union itm_val_union 4-11
update application flags 4-31, 4-124
update application information 4-54, 4-
125
update array item 4-119
update array item exclusive 4-121
update general item information 4-124
update information 2-19
update item
blocked 4-125
exclusive 4-136
modfication time 4-125
quality code 3-7, 4-124
status 3-5, 4-124, 4-133, 4-136
update alarm force normal status 4-
125
update exclusive 4-125
value 3-5, 4-124, 4-133, 4-136
updated blocked
optional statuses 2-8
updated offline
optional st 2-9
V
value clamping 2-11
value-related statuses 2-5
values
deadband 3-7
limit 3-7, 3-8
PIT 3-8

Index

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction PROCESS/FAST FAST/TOOLS
IM50P02P00-01EN/R10.03

IM50P02P00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction ..........................................................................1-1
1.1 General .......................................................................1-1
1.1.1 Classes ...................................................................... 1-1
1.1.2 Objects ...................................................................... 1-2
1.1.3 Trigger groups ........................................................... 1-2
1.2 OPC ...........................................................................1-3
1.3 Programmers interface ...............................................1-4
1.3.1 Configuration ............................................................ 1-4
1.3.2 Functions ................................................................... 1-4
1.3.3 Quick load ................................................................. 1-5
2 Configuration ........................................................................2-1
2.1 General .......................................................................2-1
2.2 The configuration routines .........................................2-1
2.3 Class maintenance .....................................................2-3
2.3.1 Internal class identification ....................................... 2-3
2.3.2 Creating and compiling a class ................................. 2-4
2.3.3 Obtaining information about classes ......................... 2-6
2.3.4 Classes and trigger groups ........................................ 2-9
2.3.5 Miscellaneous class functions ................................... 2-9
2.4 Object maintenance ...................................................2-9
2.4.1 Internal object identification ..................................... 2-9
2.4.2 Creating an object ................................................... 2-10
2.4.3 Obtaining information about objects ...................... 2-14
2.4.4 Objects and trigger groups ...................................... 2-15
2.4.5 Debugging objects .................................................. 2-15
2.4.6 Miscellaneous object functions ............................... 2-15
2.5 Trigger group maintenance ......................................2-16
2.5.1 Internal trigger group identification ........................ 2-16
2.5.2 Creating a trigger group .......................................... 2-16
2.5.3 Trigger groups, classes and objects ........................ 2-16
2.5.4 Obtaining information about trigger groups ........... 2-17
2.5.5 Miscellaneous trigger group functions ................... 2-17
2.6 Manipulation of attributes .......................................2-17
2.7 Signal information ...................................................2-18
OPC Programmer’s Guide iii

Table of Contents
2.8 Data source monitoring ........................................... 2-19

3 Functions .............................................................................. 3-1
3.1 General ...................................................................... 3-1
3.2 Calling functions ....................................................... 3-1
3.3 Function arguments and result .................................. 3-2
3.4 Function definition .................................................... 3-6
3.5 Function specification ............................................... 3-8
3.5.1 Declaration section .................................................... 3-8
3.5.2 Executable statements ............................................... 3-8
3.6 Function context ...................................................... 3-14
3.7 Updating OPC ......................................................... 3-15
4 Quick load ............................................................................. 4-1
4.1 General ...................................................................... 4-1
5 Reference .............................................................................. 5-1
5.1 General ...................................................................... 5-1
5.2 Conventions .............................................................. 5-1
5.4 Error handling ........................................................... 5-2
5.5 Data Structures .......................................................... 5-3
5.5.1 Attribute update ......................................................... 5-3
5.5.2 Attribute value ........................................................... 5-3
5.5.3 Class attributes .......................................................... 5-5
5.5.4 Class definition ......................................................... 5-5
5.5.5 Included class ............................................................ 5-7
5.5.6 Class prompt ............................................................. 5-7
5.5.7 Class reset ................................................................. 5-7
5.5.8 Class signals .............................................................. 5-8
5.5.9 Class/trigger group relation ....................................... 5-8
5.5.10 OPC context .............................................................. 5-8
5.5.11 Function context ........................................................ 5-9
5.5.12 Function definition .................................................... 5-9
5.5.13 Identification ........................................................... 5-10
5.5.14 Object definition ..................................................... 5-10
5.5.15 Object name ............................................................ 5-12
5.5.16 Object/trigger group relation ................................... 5-13
5.5.17 Signal update ........................................................... 5-13
5.5.18 Trigger group definition .......................................... 5-13
5.5.19 Data source monitoring ........................................... 5-16
5.6.1 Introduction ............................................................. 5-17
5.6.2 Obtain the next active trigger .................................. 5-19
5.6.3 Obtain the value of an attribute ............................... 5-21
5.6.4 Modify the value of an attribute .............................. 5-23
5.6.5 Attach to OPC ......................................................... 5-25
5.6.6 Compile a class ....................................................... 5-26
iv OPC Programmer’s Guide

Table of Contents
5.6.7 Delete a class ........................................................... 5-28

5.6.8 Delete a class from a trigger group ......................... 5-29
5.6.9 Close a data source event monitoring channel ........ 5-30
5.6.10 Obtain attribute of a class ....................................... 5-31
5.6.11 Obtain info about a class ......................................... 5-32
5.6.12 Obtain signal of a class ........................................... 5-33
5.6.13 Insert a class ............................................................ 5-34
5.6.14 Insert a class in a trigger group ............................... 5-36
5.6.15 Lock a class ............................................................. 5-37
5.6.16 Modify a class ......................................................... 5-39
5.6.17 Obtain next attribute of a class ................................ 5-40
5.6.18 Obtain next included class of a class ...................... 5-41
5.6.19 Obtain next object of a class ................................... 5-42
5.6.20 Obtain next prompt of a class ................................. 5-43
5.6.21 Obtain next signal of a class ................................... 5-44
5.6.22 Obtain next trigger group of a class ........................ 5-45
5.6.23 Obtain info about a next class ................................. 5-46
5.6.24 Reset a class ............................................................ 5-47
5.6.25 Trigger a class ......................................................... 5-48
5.6.26 View a class ............................................................ 5-49
5.6.27 Detach from OPC .................................................... 5-50
5.6.28 Enable/disable object debugging ............................ 5-51
5.6.29 Delete an object ....................................................... 5-52
5.6.30 Delete an object from a trigger group ..................... 5-53
5.6.31 Obtain info about an object ..................................... 5-54
5.6.32 Insert an object ........................................................ 5-55
5.6.33 Insert an object in a trigger group ........................... 5-57
5.6.34 Modify an object ..................................................... 5-58
5.6.35 Obtain next trigger group of an object .................... 5-59
5.6.36 Obtain info about a next object ............................... 5-60
5.6.37 Reset an object ........................................................ 5-61
5.6.38 Trigger an object ..................................................... 5-62
5.6.39 Open a data source monitoring channel .................. 5-63
5.6.40 Set/clear events on a monitoring channel ............... 5-64
5.6.41 Obtain the item id of a signal .................................. 5-66
5.6.42 Delete a trigger group ............................................. 5-67
5.6.43 Obtain info about a trigger group ............................ 5-68
5.6.44 Insert a trigger group ............................................... 5-69
5.6.45 Modify a trigger group ............................................ 5-71
5.6.46 Obtain info about a next trigger group .................... 5-72
5.7 Support functions .....................................................5-72
5.7.1 Introduction ............................................................. 5-72
5.7.2 Start the body section of a function specification ... 5-74
5.7.3 Start the declaration section of a function
specification ............................................................ 5-75
5.7.4 Declare a function ................................................... 5-76
5.7.5 Define a function ..................................................... 5-77
5.7.6 Obtain DUR context ............................................... 5-79
5.7.7 End function specification ...................................... 5-80
OPC Programmer’s Guide v

Table of Contents
5.7.8 End function declaration section ............................. 5-81

5.7.9 End function definition section ............................... 5-82
5.7.10 Signal and set an error ............................................. 5-83
5.7.11 Signal error and exit ................................................ 5-84
5.7.12 Exit function ............................................................ 5-85
5.7.13 Start function specification ..................................... 5-86
5.7.14 Start function declaration section ............................ 5-87
5.7.15 Start function definition section .............................. 5-88
5.7.16 Get alarm argument priority .................................... 5-89
5.7.17 Get alarm argument status ....................................... 5-90
5.7.18 Get alarm argument value ....................................... 5-92
5.7.19 Get float argument value ......................................... 5-93
5.7.20 Get float global attribute argument value ............... 5-94
5.7.21 Get float local attribute argument value .................. 5-95
5.7.22 Get integer argument value ..................................... 5-96
5.7.23 Get integer global attribute argument value ............ 5-97
5.7.24 Get integer local attribute argument value .............. 5-98
5.7.25 Get signal argument alarm acknowledge ................ 5-99
5.7.26 Get signal argument alarm type ............................ 5-100
5.7.27 Get signal argument application flag .................... 5-102
5.7.28 Get signal argument application info .................... 5-103
5.7.29 Get signal argument application info size ............. 5-104
5.7.30 Get signal argument control status ........................ 5-105
5.7.31 Get signal argument deadband .............................. 5-106
5.7.32 Get signal argument float array value ................... 5-107
5.7.33 Get signal argument float old value ...................... 5-108
5.7.34 Get signal argument float value ............................ 5-109
5.7.35 Get signal argument high limit .............................. 5-110
5.7.36 Get signal argument high high limit ..................... 5-111
5.7.37 Get signal argument item id .................................. 5-112
5.7.38 Get signal argument item id group ........................ 5-113
5.7.39 Get signal argument item id node ......................... 5-114
5.7.40 Get signal argument item id number ..................... 5-115
5.7.41 Get signal argument item id sub ........................... 5-116
5.7.42 Get signal argument installation name .................. 5-117
5.7.43 Get signal argument integer array value ............... 5-118
5.7.44 Get signal argument integer old value .................. 5-119
5.7.45 Get signal argument integer value ........................ 5-120
5.7.46 Get signal argument locked ................................... 5-121
5.7.47 Get signal argument low limit ............................... 5-122
5.7.48 Get signal argument low low limit ........................ 5-123
5.7.49 Get signal argument merged status ....................... 5-124
5.7.50 Get signal argument option status ......................... 5-125
5.7.51 Get signal argument quality .................................. 5-126
5.7.52 Get signal argument status .................................... 5-127
5.7.53 Get signal argument old string value .................... 5-128
5.7.54 Get signal argument string value .......................... 5-129
5.7.55 Get signal argument sub name .............................. 5-130
5.7.56 Get signal argument tag name ............................... 5-131
vi OPC Programmer’s Guide

Table of Contents
5.7.57 Get signal argument unit name ............................. 5-132

5.7.58 Get signal argument update time .......................... 5-133
5.7.59 Get string argument value ..................................... 5-134
5.7.60 Get string global attribute argument value ............ 5-135
5.7.61 Get string local attribute argument value .............. 5-136
5.7.62 Get timer argument status ..................................... 5-137
5.7.63 Get timer argument value ...................................... 5-138
5.7.64 Print a message ..................................................... 5-139
5.7.65 Set float function return value ............................... 5-140
5.7.66 Set integer function return value ........................... 5-141
5.7.67 Set string function return value ............................. 5-142
5.7.68 Set alarm argument priority .................................. 5-143
5.7.69 Set alarm argument status ..................................... 5-144
5.7.70 Set alarm argument value ...................................... 5-146
5.7.71 Set float argument value ....................................... 5-147
5.7.72 Set float global attribute argument value .............. 5-148
5.7.73 Set float local attribute argument value ................ 5-149
5.7.74 Set integer argument value .................................... 5-150
5.7.75 Set integer global attribute argument value .......... 5-151
5.7.76 Set integer local attribute argument value ............ 5-152
5.7.77 Set an attribute of an item ..................................... 5-153
5.7.78 Set attributes of an item ....................................... 5-154
5.7.79 Set signal argument application flag ..................... 5-156
5.7.80 Set signal argument application info ..................... 5-157
5.7.81 Set signal argument deadband .............................. 5-158
5.7.82 Set signal argument float array value .................... 5-159
5.7.83 Set signal argument float value ............................. 5-160
5.7.84 Set signal argument high limit .............................. 5-161
5.7.85 Set signal argument high high limit ...................... 5-162
5.7.86 Set signal argument integer array value ................ 5-163
5.7.87 Set signal argument integer value ......................... 5-164
5.7.88 Set signal argument low limit ............................... 5-165
5.7.89 Set signal argument low low limit ........................ 5-166
5.7.90 Set signal argument quality ................................... 5-167
5.7.91 Set signal argument status ..................................... 5-168
5.7.92 Set signal argument string value ........................... 5-169
5.7.93 Set string argument value ...................................... 5-170
5.7.94 Set string global attribute argument value ............ 5-171
5.7.95 Set string local attribute argument value .............. 5-172
5.7.96 Set timer argument status ...................................... 5-173
5.7.97 Set timer argument value ...................................... 5-174
5.7.98 Obtain task number context .................................. 5-175
5.7.99 Obtain UMH context ............................................. 5-176
Appendix A:Example of object creation.......................................A-1
A.1 General .....................................................................A-1
A.2 Example ....................................................................A-1
OPC Programmer’s Guide vii

Table of Contents
viii OPC Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives
functionality of the OPC-brick.
• To provide experienced users with a reference when using OPC-
routines and macro’s.

This manual is intended for programmers who are familiar with the ‘C’
language. To understand the concept of OPC, the reader is assumed to
((M)DUR).

This manual is structured as follows;
• Chapter 1 can be regarded as an introduction to the OPC
• Chapter 2 contains a description of the OPC mechanism and
configuration routines.
• Chapter 3 describes how user functions can be added to OPC.
• Chapter 4 introduces the quick load facility.
• Chapter 5 contains reference information for those already familiar
with OPC.
OPC Programmer’s Guide 0-1


1 USER/FAST, User Manual.
This manual provides basic information about the PROCESS/
FAST functionality.
This manual provides a description of the Traditional PROCESS/
FAST language.
3 PROCESS/FAST Java Language Manual
This manual provides a description of the Java PROCESS/FAST
language.
4 PROCESS/FAST System Integrator’s Manual
This manual contains information necessary to change the basic
PROCESS/FAST and OPC functions.
which are used.
software.

CONVENTION MEANING
passed.
optional.
0-2 OPC Programmer’s Guide


DUR_NOWAIT.
input.
returns.
output.
literally.
n.u. not used.
a terminal.
from the user.


General Introduction
1 Introduction
OPC
1.1 General
PROCESS/FAST is a member of the FAST/TOOLS collection
facilitating a high level of process variable manipulation by means of
objects. An object specifies the relation between a number of input and
output process variables. The relation between the process variables is
described by means of the PROCESS/FAST language.
Before an object can be created, its template, the class, must be defined.
A class specifies the behavior of all objects derived from it. An example
of a class is a valve. Many valves (objects) can be derived from the
template valve.
1.1.1 Classes
A class is a template for all objects derived from it. A class contains a
number of parameters. These parameters are:
• The name of the class.
• A one-liner description of the class to provide additional textual
information about the class.
• The language in which the method class is written, Traditional or
Java.
• The priority of the class. When more objects derived from different
classes are executed at the same time, the objects derived from the
class with higher priorities are executed before objects derived
from classes with lower priorities. Note that an object can have a
priority which overrules the priority for its class.

• The behavior, called the method, of the class. The method of a class
is specified in the PROCESS/FAST language. The method
specification is called the class source. It defines the process
variables to which a derived object must be connected and it defines
the behavior of the object when active. Process variables are
accessed by signals from within the method. A signal is connected
to a process variable when the object is derived from the class.
A method may contain a number of attributes whose value may
influence the behavior of the class.
Functions can be called from within the PROCESS/FAST
language. A function can be written in the PROCESS/FAST
language. For the Traditional PROCESS/FAST languages
functions can also be written in the ‘C’ language. A number of
functions written in the ‘C’ language are supplied with the
PROCESS/FAST package.
1.1.2 Objects
An object is derived from its template class. An object has a number of

parameters. These parameters are:
• The name of the object. This name has a similar layout to process
variable names. It contains the installation, unit and tag part. The
installation and unit part are with the process variables.
• A one-liner description of the object to provide additional textual
information about the object.
• The object’s class specifies the class to derive the object from.
• The BUS/FAST node which identifies the node where the object
will run.
• The priority of the object. When specified, this priority is used
instead of the priority of the object’s class.
• The control item for the object (optional). This item (process
variable) can be used to control the behavior of the object.
• The time window the object must be active. Outside this time
window the object is latent.
1.1.3 Trigger groups
When an object is active it is in a certain state. It stays in this state when

it is not triggered. For example, on each trigger, the method of the object
is executed to determine the next state of the object. One of the ways of
triggering an object is by means of trigger groups. An object placed in a

OPC Introduction
trigger group is triggered once or at regular intervals by the trigger

group. A class can also be placed in a trigger group. In this case all
objects within the triggered class are triggered, except the objects which
are placed in a trigger group to their own. Note that an object and class
can be placed in more than one trigger group. A trigger group has the
following parameters:
• The name of the trigger group.
• A one-liner description of the trigger group to provide additional
textual information about the trigger group.
• The time window the trigger group must be active. Outside the time
window the object and classes placed in the trigger group are not
triggered by the trigger group.
• The interval by which the objects and classes placed in the trigger
groups must be triggered.
1.2 OPC
PROCESS/FAST contains the brick OPC. OPC stands for Object
oriented Process Control. OPC contains a number of processes which
are:
• The manager (OPCMAN) maintains classes, objects and trigger
groups. In addition it supplies the programmer’s interface to
manipulate the classes objects and trigger groups.
• The compiler (OPC(J)COM) translates the textual class method
into an intermediary code which is executed by the executor
process. OPCCOM is the compiler for the Traditional language.
OPCJCOM is the compiler for the Java language.
• The activator (OPC(J)ACT) links signals to process variables
during object creation. During object deletion it deletes the links.
OPCACT is the activator for the Traditional language. OPCJACT
is the activator for the Java language.
• The loader (OPCLOA) prepares objects for execution. In a multi
BUS/FAST node environment it transfers data between the nodes
in cooperation with the manager process.
• The executor (OPC(J)EXE) executes the methods of objects when
they are active. OPCEXE is the executor for the Traditional
language. OPCJEXE is the executor for the Java language.

Introduction Programmers interface
1.3 Programmers interface

The programmer’s interface of OPC enables the System Integrator to
maintain classes, objects and trigger groups and to add PROCESS/
FAST language callable functions written in the ‘C’ language.
1.3.1 Configuration
A number of routines are supplied to enable the System Integrator to

write applications which maintain classes, objects and trigger groups.
The routines are divided into several types:
• The general routines enable communication with OPC.
• The class routines supply functions to create, modify, compile and
delete classes. Information about classes can be obtained, classes
can be placed in trigger groups and deleted from trigger groups.
Classes can be reset and triggered.
• The object routines supply functions to create, modify and delete
objects. Information about objects can be obtained, classes can be
placed in trigger groups and deleted from trigger groups. Objects
can be triggered.
• The trigger group routines are used to create, modify and delete
trigger groups. In addition information about trigger groups can be
obtained.
• The attribute routines are used to obtain the value of attributes and
to modify the value of attributes.
• The signal routine returns the identification of the item associated
to a certain signal.
1.3.2 Functions
Functions can be called from within the PROCESS/FAST language. A

function can be written in the PROCESS/FAST language. For the
Traditional language functions can also be written in the ‘C’ language.
A number of ‘C’ language functions are supplied with PROCESS/
FAST. The System Integrator can add functions written in the C
language functions.
For the Java language the System Integrator can add function written in
the Java language.

Programmers interface Introduction
1.3.3 Quick load
Classes and objects can be defined by means of files containing textual

class or object specifications. A BUS/FAST request is defined to process
such a text file resulting in classes or objects being defined.

Introduction Programmers interface

General Configuration
2 Configuration
TRIGGER
GROUP
CLASS
CLASS
OPC
OBJECT
2.1 General
In this chapter the mechanisms are described to configure classes,
objects and trigger groups within OPC. The following items are
discussed:
• Usage of the configuration routines
• Class maintenance.
• Object maintenance.
• Trigger group maintenance.
• Manipulation of attributes.
• Signal information.
2.2 The configuration routines

A number of routines are supplied to configure classes, objects and
trigger groups. These routines interface between the application calling
them and the OPC manager process (OPCMAN). In Figure 2-1 the OPC
routines are depicted within their environment. It is possible to address
the OPC manager process directly via its BUS/FAST address. However,
it is recommended to use the routine interface. The BUS/FAST usage of
OPC is not described in this manual.
An application which requires services from OPC must attach itself to
OPC before any functional OPC routine can be called. The global
sequence of calling OPC routines is:

Configuration The configuration routines
APPLICATION
OPC-routines
BUS/FAST interface
OPC manager process
Figure 2-1 The OPC routine interface and its environment
...
Initialize and attach to DUR and UMH
...
Attach to OPC by the opc_attach() routine
...
Call functional OPC routines
...
Detach from OPC by the opc_detach() routine
...
Detach from DUR
Attaching to OPC sets up a communication link between the application
and the OPC manager process. The OPC manager process administrates
the application as one of its clients. The opc_attach() routine returns
a context which is used as a parameter to all successive routine calls to
OPC.
Once attached, classes, objects and trigger groups can be maintained.
When finished the application closes the communication link. The OPC
manager process removes the application from its client list and deletes
all client oriented temporary information. The OPC manager process
checks, at regular intervals, whether or not all clients connected are still
up and running. An attached client which is no longer running is
automatically detached by OPC itself. However it is a good
programming practice to let the application detach from OPC.
The BUS/FAST node, where the OPC manager process is running, must
be specified when attaching. In most cases it is the same node as where
the application is running. In this case a zero can be specified for the
node.
General information is supplied to OPC, with the attach call, which is
used to audit configuration changes in a future version of PROCESS/
FAST.

Class maintenance Configuration
All routines return error information stored in the UMH context on

failure. Failure is indicated by the routine returning a FALSE or a NULL
pointer. Two general errors can be returned:
• OPC_E_NOTATT ‘The client is not attached’ indicates that the
application did not issue the attach call to OPC prior to the
functional routine call.
• OPC_E_BUSY ‘Request not handled (down loading information to
the remote PROCESS/FAST’ indicates that OPC is busy
communicating with PROCES/FAST running on another BUS/
FAST node. The routine causing this error can be called again after
some time, for example 10 seconds.
2.3 Class maintenance

Before an object can be derived from a class the class must be created
and compiled. Once created, classes can be modified, deleted etc.
2.3.1 Internal class identification
Externally (to the user) a class is identified by its name. Internally a class
is identified by its id. A class id is defined by the struct opc_id:
struct opc_id
{
TLS_ULONG sec;
TLS_USHORT seq;
TLS_USHORT opt;
};
The field sec contains the date and time (seconds since 1970) that the
class was created. The field seq contains the sequence number within
the second because more than one class can be created within a second.
The fields sec and seq uniquely identifies a class. The field opt is
always zero.
When a class is created, OPC generates the id which is returned to the
application. The application can access the class by its name or id in
successive calls. While the class exists the id never changes.

Configuration Class maintenance
2.3.2 Creating and compiling a class
Before objects can be derived from a class it must be created and

compiled:
...
Insert class by the opc_cls_ins() routine
...
Modify class source by the opc_cls_lck() and
opc_cls_mod() routines
...
Compile the class
...
A class is created (inserted) by the opc_cls_ins() routine. This routine
creates the class with the specified parameters. The parameters to
specify are:
• The name for the class.
• The language in which the class source is written, Traditional or
Java.
• The one-liner description.
• The class priority.
• The class source.
The source to use for the class can be specified in three ways:
• A name of an existing class whose source will be copied to create
the class. Note that the copied source must be adapted (by the
opc_cls_lck() and opc_cls_mod() calls) prior to compilation of
the newly created class because there is class dependent
information stored in the class source.
• The name of a ASCII text file can be specified which contains the
source written in the PROCESS/FAST language.
• OPC uses the source specified in the template source file when both
the name of a class and ASCII text file are not specified. This
template source file is an ASCII text file containing PROCESS/
FAST statements. The name of the template source file can be
specified in the OPC set-up file. Note that the source must be
adapted (by the opc_cls_lck() and opc_cls_mod() calls) prior
to compilation of the newly created class because the template
source needs to be adapted to fill in the blanks.
The opc_cls_ins() return the class id on successful creation of the
class.
Prior to the compilation the class source must be modified to fulfill the
classes requirements. A class source and other parameters are modified

by the opc_cls_lck() and opc_cls_mod() routines. The

opc_cls_lck() routine locks the class against modification by other
users of OPC. The routine then returns information (its parameters)
about the class. The source is returned in the file whose name is specified
in the opc_cls_lck() routine. When no name is specified then OPC
creates a temporary file in which the class source is placed. This
temporary file is deleted when the application detaches from OPC.
When the lock is requested and another user has locked the class,
opc_cls_lck() returns the error OPC_E_CLS_LOCKED ‘The class is
locked by an other user’. The lock is freed at any subsequent call to OPC.
The contents of the class source file can now be modified. Once
modified, the OPC must be signalled by the opc_cls_mod() call. The
name of the file containing the modified class source must be specified.
In addition the priority and the one-liner description for the class can be
modified.
When the class is created or modified the class needs to be compiled.
The textual class source is transformed into an intermediary code which
can be interpreted by the OPC executor process. The opc_cls_com()
routine is used to compile the source. Two options can be specified:
• A list file can be generated containing a copy of the source and any
error detected by the compiler. The error detected by the compiler
is inserted in the list file at the statement which caused the
compilation error. When a list file is requested, the name for the list
file can be supplied. When not supplied then OPC creates a
temporary list file which will be deleted when the application
detaches from OPC.
• Additional information will be logged by the OPC executor process
when the class is compiled with the trace option enabled. This
information can be very helpful during development and debugging
of the class source. A class compiled with the trace option enabled
performs a little worse than compiled without the trace option.
The number of errors and warnings found by the compiler is returned by
the opc_cls_com() routine. When the number of errors is zero, objects
can be derived from the class.
When the source of a class with derived objects is modified and
compiled, the derived objects continue to use the previous version until
they are somehow reset. An object is reset by resetting it with the
opc_obj_res() call or all objects in the class are reset by resetting the
class by the opc_cls_res() call. When OPC is restarted then the
objects on the node where OPC is restarted are reset as well.

2.3.3 Obtaining information about classes
The following information can be obtained about an existing class:

• Class parameters.
• The classes included in the class source.
• The signals defined in the class source.
• The attributes defined in the class source.
• The prompts defined in the class source.
Class parameters
With the routines opc_cls_view(), opc_cls_get() and
opc_cls_nxt() the class parameters can be returned. Routine
opc_cls_get() returns the parameters of the class specified by name
or id while opc_cls_nxt() returns the next class. The routine
opc_cls_view() has the same functionality as opc_cls_get() and
returns the class source in addition.
Included classes
A class can contain other classes. This is specified in the class source by
the CONTAINS statement. For example:
CONTAINS inlet_valve valve;
which includes the class ‘valve’ and assigns the identifier ‘inlet_valve’
to it.
An included class may have included classes itself. The routine
opc_cls_ninc() is used to retrieve a list of all included class. Each
included class is identified by a unique id whose layout is also defined
by struct opc_id. The fields sec and seq have the same value as the
class. Field opt identifies the included class within the class.
The returned information is defined by struct opc_cls_inc:
struct opc_cls_inc
{
struct opc_id inc_id;
struct opc_id par_inc_id;
struct opc_id cls_id;
char name[OPC_INC_NAME_SZ];
};
Field inc_id identifies the included class. Field par_inc_id identifies
the included class which included this class. When field opt of
par_inc_id is zero then it identifies the root of all classes which is the

class itself. Field cls_id is the id of the class included. Field name
contains the identifier name (‘inlet_valve’ in the above example).
For example suppose the following classes are defined:
CLASS A;
...
ENDCLASS A;
CLASS B;
...
CONTAINS INC_A A;
...
ENDCLASS B;
CLASS C;
...
CONTAINS INC_A A;
CONTAINS INC_B B;
...
ENDCLASS C;
When all included classes of class ‘C’ are obtained the following
information will be returned:
inc_id par_inc_id cls_id name
sec seq opt sec seq opt sec seq opt
3 0 1 3 0 0 3 0 0 C
3 0 2 3 0 1 1 0 0 INC_A
3 0 3 3 0 1 2 0 0 INC_B
3 0 4 3 0 3 1 0 0 INC_A
Signals
A class can contain references to process variables. This is specified in
the class source by the SIGNAL statement. For example:
SIGNAL ph1 := ”my_installation.my_unit.ph”;
which assigns process variable ‘my_installation.my_unit.ph’ to the
signal identifier ‘ph1’.
The routines opc_cls_gsig() and opc_cls_nsig() is used to retrieve
a list of all signals for a class. Each signal is identified by a unique id
whose layout is also defined by struct opc_id. The fields sec and seq
have the same value as the class. Field opt identifies the signal within
the class.

The returned information contains, besides the id, the path name of the
signal. The path name identifies the signal by name and is preceded by
the hierarchical list of included classes separated by dots.
For example, take the classes defined in the previous sub-section
‘Included classes’. When class ‘A’ was defined as follows:
CLASS A;
...
SIGNAL ph1 := ”my_installation.my_unit.ph”;
...
ENDCLASS A;
Two signals will be returned for class ‘C’:
sig_id path
sec seq opt
3 0 1 INC_A.PH1
3 0 2 INC_B.INC_A.PH1
Attributes
A class may contain a number of attributes which are defined in the class
source by the ATTRIBUTE statement. For example:
ATTRIBUTE my_attribute GLOBAL;
which creates a global attribute identified by ‘my_attribute’.
Attributes can be global or local. Global attributes have a single value
for all the objects derived from the class. Local attributes have distinct
values for all objects derived from the class. An attribute is identified in
a similar way as a signal. From all attributes in a class, the id, path and
type (global or local) can be obtained by the routines opc_cls_gatr()
and opc_cls_natr().
Prompts
Prompts can be defined for attributes within a class source:
ATTRIBUTE my_attribute LOCAL;
PROMPT my_attribute QUERY ”Enter value for my attribute”;
The prompts are introduced to prompt the user to enter values for
attributes prior to deriving one or more objects from the class. With the
routine opc_cls_npmt() the prompts defined in the class source can be
obtained. For each prompt the prompt id, the id of the attribute prompted
for and the query text can be obtained. The fields sec and seq have a

Object maintenance Configuration
value equal to the class id. The field opt identifies the prompts within
the class.
Note that only local attributes can be prompted for.
2.3.4 Classes and trigger groups
Classes can be placed in and deleted from trigger groups. The routine
opc_cls_itrg() inserts a class into a trigger group. Both class and
trigger group must be specified by their id.
The routine opc_cls_dtrg() deletes a class from a trigger group.
Use the opc_cls_ntrg()routine to obtain a list of trigger groups in
which the class is inserted.
2.3.5 Miscellaneous class functions
Some miscellaneous routines are available.

Routine opc_cls_del() is used to delete a class. Only classes with no
objects derived can be deleted. Otherwise an error is returned.
All objects in a class active on a certain BUS/FAST node can be reset by
a call to the opc_cls_res() routine.
All objects in a class can be triggered with the opc_cls_trg() routine.
The trigger occurs independent from other triggers defined for the class
and the objects in the class.
2.4 Object maintenance

When a class is created objects can be derived from it. Derived objects
can be modified, deleted, triggered, etc.
2.4.1 Internal object identification
Externally (to the user) an object is identified by its name. Internally an

object is identified by its id. An object id is also defined by the struct
opc_id. The contents of the fields sec and seq do not have any relation
with the fields of the class id from where the object is derived. When an

Configuration Object maintenance
object is created the contents for the fields sec end seq is determined in
a similar way as for classes.
When an object is created, OPC generates the id which is returned to the
application. The application can access the object by its name or id in
successive calls. While the object exists the id never changes.
2.4.2 Creating an object
Objects can be derived from a class. The steps to derive an object from
a class are:
...
Obtain class info to retrieve class id (opc_cls_get()).
Obtain the classes prompts (opc_cls_npmt()).
Obtain the values of the attributes prompted
(opc_atr_rd()). These values are used as defaults.
Show the user the prompts with their defaults and accept
his response.
Insert the object by the opc_obj_ins() routine.
...
The opc_obj_ins() routine creates the object with the specified
parameters. The parameters to specify are:
• The name for the object.
• The one-liner description.
• The id of its class.
• The BUS/FAST node where the object must be activated.
• The object priority.
• The activity time window.
• Optionally the item id of the object control item.
• Whether the items to be created by the object may already exist.
• Whether items created by the object should be deleted when the
object is deleted.
The layout of this parameter list is specified by struct opc_obj_def:
struct opc_obj_def
{
struct opc_id cls_id;
struct opc_obj_name name;
char desc[OPC_OBJ_DESC_SZ];
struct gin_dii_id dii_id;
struct opc_id obj_id;
char file[OPC_FIL_NAME_SZ]
TLS_SHORT node;
TLS_USHORT priority;

TLS_ULONG start;
TLS_ULONG stop;
TLS_ULONG modified;
TLS_ULONG flags;
TLS_USHORT version;
TLS_USHORT nu1;
struct opc_atr_val atr_val[1];
};
The fields obj_id, file, modified,version have no meaning while
creating an object. On exit of the routine, field obj_id contains the id
assigned by OPC to the object.
If the prolog of the class declares signals that create the related items
automatically then the contents of flags controls this behavior.
If an item has to be created three situations may exist:
• The item does not exist
• The item exists already and it has been created and is used by one
or more objects
• The item exists already and it is not used by any object.
The third situation is controlled by flags. If flags is set to
(OPC_OBJ_ITEMS_MAY_EXIST_FLAG | OPC_OBJ_ITEMS_MAY_EXIST)
then the existing item is used. If flags is set to
OPC_OBJ_ITEMS_MAY_EXIST_FLAG (or non of
OPC_OBJ_ITEMS_MAY_EXIST_FLAG and OPC_OBJ_ITEMS_MAY_EXIST
is specified) then an error is issued and the object is not created.
In any case, if the item already exists then its attributes must correspond
with the attributes as if the items was created. If this is not the case an
error is returned and the object is not created.
If the object is deleted and the prolog of the class declares signals that
create the related items automatically then the contents of flags
controls whether items created by the object are deleted.
If flags is set to (OPC_OBJ_LEAVE_ITEMS_FLAG |
OPC_OBJ_LEAVE_ITEMS) then items are not deleted when the object is
deleted. If flags is set to OPC_OBJ_LEAVE_ITEMS_FLAG (or non of
OPC_OBJ_LEAVE_ITEMS_FLAG and OPC_OBJ_LEAVE_ITEMS is
specified) then an item is deleted if the item was created by an object and
no objects are using the item anymore.
The list of values for the prompted attributes must be supplied starting
at the offset indicated by field atr_val. Define and set an attribute value
with opc_atr_val:

struct opc_atr_val
{
struct opc_id atr_id;
TLS_USHORT nu1;
TLS_USHORT rep;
union opc_val
{
TLS_UBYTE c;
TLS_SHORT s;
TLS_LONG l;
TLS_FLOAT f;
TLS_DOUBLE d;
TLS_BOOLEAN b;
char t[sizeof(TLS_DOUBLE)];
} val;
};
A number of attributes can be set during creation of the object. A
fragment of code is extracted from the example in Appendix A to clarify
the handling of attributes. The explanation follows this fragment:
int atrs; [1]
struct opc_obj_def *obj_def; [2]
struct opc_cls_pmt cls_pmt; [3]
struct opc_atr_upd *atr_upd; [4]
struct opc_atr_val *atr_val; [5]
TLS_LONG buf_def[OPC_OBJ_DEF_SZ/sizeof(TLS_LONG)]; [6]

TLS_LONG buf_upd[(sizeof(*atr_upd)+OPC_MAX_STR_SZ)/ [7]
sizeof(TLS_LONG)];
obj_def = (struct opc_obj_def*)buf_def; [8]

atr_upd = (struct opc_atr_upd*)buf_upd; [9]
atrs = 0; [10]
cls_pmt.pmt_id = obj_def->cls_id; [11]
atr_val = obj_def->atr_val; [12]
while (opc_cls_npmt(opc_c, &cls_pmt)) [13]

{
int len;
atr_upd->obj_id.sec = 0; [14]
atr_upd->atr_val.atr_id = cls_pmt.atr_id; [15]
atr_upd->atr_val.rep = REP_STRING; [16]
if (!opc_atr_rd(opc_c, atr_upd)) [17]

{
/* Handle error */

}
fio_ltd_str(io_buf, atr_upd->atr_val.val.t, [18]
cls_pmt.query,
FIO_RETRY | FIO_DFL | FIO_SPACE,
FIO_MAX_INP);
len = sizeof(*atr_val); [19]

len += (strlen(atr_val->val.t) + 1 - [20]
sizeof(atr_val->val.t));
len = (len + 7) & ~7; [21]
if ((char*)atr_val + len > [22]
(char*)obj_def + OPC_OBJ_DEF_SZ)
{
/* Handle error */
}
atr_val->atr_id = cls_pmt.atr_id; [23]

atr_val->rep = REP_STRING; [24]
strcpy(atr_val->val.t, atr_upd->atr_val.val.t); [25]
atr_val = (struct opc_atr_val *)((char*)atr_val + len);

atrs++; [26]
}
if (umh_error(&umh_c) != OPC_E_CLS_NOTPMT) [27]
{
/* Handle error */
}
if (!opc_obj_ins(opc_c, obj_def, atrs)) [28]

{
/* Handle error */
}
1 Variable atrs counts the number of prompted attributes. The
number of attributes is one of the arguments of the opc_obj_ins()
routine.
2 Only one attribute is defined in the structure opc_obj_def. To
handle more than one attribute, a pointer is declared which will
point to a buffer large enough to hold a number of attributes (see
point [6] and [8] in this list).
3 This variable cls_pmt is used to retrieve the prompts for the
object’s class.
4 The pointer atr_upd is used to retrieve the default values of the
attributes to prompt for. It points to a buffer large enough to handle
strings (see points [7] and [9] in this list).
5 The pointer atr_val advances through the object definition buffer
obj_def to store the values of the successive attributes.

6 The buffer buf_def is the storage area to store the object definition
while constructing it. Its maximum size is OPC_OBJ_DEF_SZ (4000)
bytes.
7 The buffer buf_upd is used to store the value of a retrieved
attribute.
8 The pointer obj_def is initialized to point to its buffer.
9 The pointer atr_upd is initialized to point to its buffer.
10 The number of attributes is initialized to zero.
11 The prompt id is initialized to retrieve the first prompt of the
object’s class.
12 The pointer to store the prompted attribute value is initialized to the
first position.
13 Get the first or next prompt until an error is encountered.
14 Initialize to retrieve the default value of prompted attributes.
15 Set the attribute id to retrieve.
16 The value of the attribute must be returned as a string.
17 Retrieve the attributes value.
18 Ask for the new value, displaying the default.
19 Calculate the size of the attribute to set.
20 Adjust the size with the length of the string to store in it.
21 Adjust on TLS_LONG boundary.
22 When there is not enough space in the buffer, issue an error.
23 Set the attribute id.
24 Set its representation.
25 Copy the new string value to it.
26 Adjust the pointer for the next position and count the number of
attributes.
27 opc_cls_npmt() returns the error OPC_E_CLS_NOTPMT when
no more prompts are found in the class.
28 Insert the object.
2.4.3 Obtaining information about objects
The object parameters can be returned with the routines

opc_obj_get() and opc_obj_nxt(). Routine opc_obj_get()
returns the parameters of the object specified by name or id while
opc_obj_nxt() returns the next object.

2.4.4 Objects and trigger groups
Objects can be placed in trigger groups and can be deleted from trigger
groups. The routine opc_obj_itrg() inserts an object into a trigger
group. Both object and trigger group must be specified by their id.
The routine opc_obj_dtrg() deletes an object from a trigger group.
To obtain a list of trigger groups in which the object is inserted use the
opc_obj_ntrg() routine.
2.4.5 Debugging objects
An object can be enabled for debugging. When debugging is enabled

information about the object is written to a debug output file while the
object is active. The debug information contains, among other
information, when it is triggered and by what source, which attributes
and signals are modified by the object.
Only objects defined for the host node, the node where the OPC manager
process is executing, can be debugged.
The routine opc_obj_dbg() is used to enable or disable debugging of a
certain object. The name of the file to which the debug information will
be output must be specified.
2.4.6 Miscellaneous object functions

Use the opc_obj_mod() routine to modify one of the objects
parameters. Only the one-liner description, priority and time window
can be modified.
Use the opc_obj_del() routine to delete an object.
An object can be reset by a call to the opc_obj_res() routine.
An object can be triggered with the opc_obj_trg() routine. The trigger
occurs independent from other triggers for the object.

Configuration Trigger group maintenance
2.5 Trigger group maintenance

Classes and objects can be triggered at regular intervals by placing them
in one or more trigger groups. A trigger group can be created, modified,
etc.
2.5.1 Internal trigger group identification
Externally (to the user) a trigger group is identified by its name.

Internally a trigger group is identified by its id. A trigger group id is also
defined by the struct opc_id. The contents of the fields sec and seq don
not have any relation with the fields of class and object identifications.
When a trigger group is created, OPC generates the id which is returned
to the application. The application can access the trigger by its name or
id in successive calls. While the trigger group exists the id never
changes.
2.5.2 Creating a trigger group
A trigger group is created by the opc_trg_ins() routine. The name for

the trigger group, the one-liner description, the time window and
interval must be specified. The id for the trigger group is returned.
The interval can be specified in microseconds, however, the
microseconds part is not used. The first trigger is generated when the
trigger group enters the trigger window. All successive triggers are
generated at a time which is the start of the time window increased by a
multiple of the specified interval.
Special intervals are available to trigger once a week, month, 2 months,
etc. To trigger an object once when the object is activated, the special
interval OPC_TRG_01 (once) is available.
2.5.3 Trigger groups, classes and objects
A class is inserted in a trigger group by the opc_cls_itrg() routine.

Both class and trigger group are specified by their id. The class is
removed from a trigger group by the opc_cls_dtrg() routine.
Objects are inserted by the opc_obj_itrg() routine and deleted by the
opc_obj_dtrg() routine.

Manipulation of attributes Configuration
2.5.4 Obtaining information about trigger groups
The trigger group parameters can be returned with the opc_trg_get()

and opc_trg_nxt() routines. opc_trg_get() returns the parameters
of the trigger group specified by name or id, while opc_trg_nxt()
returns the next trigger group.
2.5.5 Miscellaneous trigger group functions

Routine opc_trg_mod() is used to modify one of the trigger group’s
parameters. Only the one-liner description, time window and interval
can be modified.
Routine opc_trg_del() is used to delete a trigger group. Only trigger
groups containing no classes or objects can be deleted.
2.6 Manipulation of attributes

Attributes are defined in the class’s source. An attribute can be global or
local. Each object derived from the class has its private value for a local
attribute. The value of global attributes are shared among the objects.
The next table shows a class with three global attributes and five local
attributes:
Class A
Attribute
Class A Object A Object B Object n
Global A “This is a text”

B 12.45
C 42000
Local M 12 15 99 87
N “high” “high” “low” “high”
O 12.4 12.5 12.4 12.6
P -14 7 8 5
Q 42.1 52.1 42.1 62.1

Configuration Signal information
The attribute “B”, for example, has the value “12.45”. When one of the
object‘s methods changes the value to “15.0” then all the objects derived
from the class will receive this new value. For local attributes, the
attribute in the class also has a value. This value is used as default value
for the attributes prompt when an object is created.
Use the opc_atr_rd() routine to obtain the current value of an
attribute. The value is obtained from the attribute defined by
struct opc_atr_upd.
struct opc_atr_upd
{
struct opc_atr_val atr_val;
};
(struct opc_atr_val is depicted on page 12).
For global attributes field obj_id is ignored. For local attributes, field
obj_id specifies the object whose attribute is to be retrieved. When the
field obj_id is cleared (contains all zeros) then the value of the local
attribute for the class is returned. The id of the attribute is specified in
the field atr_id of atr_val. The representation of the value to return
can be specified in field rep. When REP_DEF is specified then the
value is returned in the attribute’s own representation. In all other cases
OPC converts the attribute value to the requested representation. When
the returned representation is REP_STRING make sure that
opc_atr_upd maps to a buffer large enough to handle the longest string
(see [4], [7] and [9] on page 12).
Routine opc_atr_wr() is used to modify an attribute value. When the
value of a global attribute is modified, the value is distributed to all the
objects derived from the class.
2.7 Signal information

When an object is created, signals defined in the class are attached to
process variables. The routine opc_sig_rd() is used to return the item
id of the process variable attached to a certain signal for an object. The
request is specified by struct opc_sig_upd:
struct opc_sig_upd
{
struct opc_id sig_id;

Data source monitoring Configuration
struct gin_dii_id dii_id;

struct opc_his_info his_info;
};
The id of the object and the id of the signal must be specified. The item
id is returned. The returned history information defines in which storage
groups the item is inserted, what the storage criteria are and what item
attributes (value, status, limits etc.) are stored.
2.8 Data source monitoring

It is possible for an application to monitor OPC data sources and be kept
informed about any changes. An event monitoring channel can be
opened for a specific source and a request made to be informed about
particular actions that take place on that source.
The routine opc_opn_evt() can be used to open a channel on a specific
source. The opc_set_evt() routine allows an application to indicate
which kinds of actions are to be monitored. A call to opc_cls_evt() will
close an existing channel. Furthermore flow control can be applied using
opc_flw_evt(), in order to check for lost messages and that
communications have not been lost.

Configuration Data source monitoring

General Functions
3 Functions
TRIGGER
GROUP
CLASS
CLASS OBJECT
Turbo
OPC
Kit
Note: This chapter is only valid for the

Traditional PROCESS/FAST language.
3.1 General
In this chapter a description is given on how to extend the standard
PROCESS/FAST language by adding PROCESS/FAST language
callable functions. These functions can be written in the
PROCESS/FAST language or in the ‘C’ programming language. The
former method is described in the PROCESS/FAST language manual.
The latter method is described in this chapter.
The following items are discussed in this chapter:
• Functions called in the PROCESS/FAST language
• Function arguments and function result
• Function definition
• Function specification
• Function context
• Updating OPC
3.2 Calling functions

Functions can be referenced within the PROCESS/FAST language in
several ways:

Functions Function arguments and result
• In assignments:
The result of a function can be assigned to a variable, attribute,
signal, etc. For example: A:= my_function().
• In expressions:
The function result can be used in expressions. For example:
(3 + my_function()) * 4.
• As a statement:
The function can be a statement. Its result is not used. For example:
my_function().
A function can have zero or up to ten arguments.
3.3 Function arguments and result

Up to ten arguments can be defined for a function. A function expects
each argument to be of a certain type. These types are:
• OPC_REP_INTEGER
The argument is an integer value.
• OPC_REP_FLOAT
The argument is a float value.
• OPC_REP_STRING
The argument is a zero terminated string.
• OPC_TYPE_TIMER
The argument is a timer.
• OPC_TYPE_GLOBAL_ATTRIBUTE
The argument is a global attribute.
• OPC_TYPE_LOCAL_ATTRIBUTE
The argument is a local attribute.
• OPC_TYPE_SIGNAL
The argument is a signal.
• OPC_TYPE_ALARM
The argument is an alarm
However, the real argument supplied may be of a different type. OPC
tries to convert the argument supplied to the expected argument type.

Function arguments and result Functions
The following rules are taken into account when converting argument
types:
Expected argument type
global attribute
local attribute
Supplied argument type
integer
signal
string
alarm
timer
float
integer expression * *
float expression 1 *
string expression *
integer variable * *
float variable 1 *
string variable *
integer constant * *
float constant 1 *
string constant *
timer 1 * 2
timer’value 1 *
timer’status * *
integer global attribute * * 3
float global attribute 1 * 3
string global attribute * 3
integer local attribute * * 4
float local attribute 1 * 4
string local attribute * 4
signal 1 * * 5
signal’value 1 * *
signal’old_value 1 * *
signal’status * *
signal’control_status * *
signal’option_status * *

Functions Function arguments and result
Expected argument type
global attribute
local attribute
Supplied argument type
integer
signal
string
alarm
timer
float
signal’merged_status * *
signal’alarm_type * *
signal’acknowledged * *
signal’high_high_limit 1 *
signal’high_limit 1 *
signal’low_limit 1 *
signal’low_low_limit 1 *
signal’deadband 1 *
signal’quality * *
signal’update_time 1 *
signal’id_node * *
signal’id_group * *
signal’id_number * *
signal’id_sub * *
signal’installation *
signal’unit *
signal’tag *
signal’sub *
signal’application_info * *
signal’application_size * *
signal’application_flag * *
alarm 6
alarm’value *
alarm’status * *
alarm’priority * *

Function arguments and result Functions
* Valid conversion.
1 OPC tries to convert the float into an integer. However, an error is
issued when the float number is too large to fit in an integer.
2 When only timer identifier is passed to the function and the
function expects a timer identifier then all attributes of the timer are
passed to the function and the timer can be manipulated within the
function in the same way as outside the function.
When the function expects an integer or float then the timer value
is passed to the function. Modification of this value within the
function does not influence the timer outside the function.
3 When a global attribute identifier is passed to the function and the
function expects a global attribute identifier then the attribute can
be manipulated within the function the same way as outside the
function. For example, the value for the global attribute is also
modified for the objects derived from the same class.
When the function expects an integer, float or string then the
attribute value is passed to the function. Modification of this value
within the function does not influence the attribute outside the
function. For example, the value for the global attribute remain the
same for the objects derived from the same class.
4 When a local attribute identifier is passed to the function and the
function expects a local attribute identifier then the attribute can be
manipulated within the function the same way as outside the
function.
When the function expects an integer, float or string then the
attribute value is passed to the function. Modification of this value
within the function does not influence the attribute outside the
function.
5 When a signal identifier only is passed to the function and the
function expects a signal identifier then all attributes of the signal
are passed to the function and the signal can be manipulated within
the function in the same way as outside the function.
When the function expects an integer or float then the signal value
is passed to the function. Modification of this value within the
function does not influence the signal outside the function and does
not update the signal value in the item table.
6 When an alarm identifier only is passed to the function and the
function expects an alarm identifier then all attributes of the alarm
are passed to the function and the alarm can be manipulated within
the function in the same way as outside the function.
When the function expects string then the alarm value is passed to
the function. Modification of this value within the function does not
influence the alarm outside the function.

Functions Function definition
Other conversions are not possible and trapped by the OPC compiler.
When the argument supplied is a variable, modification of the value
within the function modifies the value of the variable outside the
function. This method can be used to return values to the function caller
when more than one value has to be returned. For example:
VAR my_var;
my_var:= 10;
my_function(my_var);
/* here my_var has the value of 20 */
The function my_function is defined as follows (represented in the
PROCESS/FAST language):
FUNCTION my_function
ARG a;
a:= a * 2;
ENDFUNCTION my_function;
The function result has one of the following representations:
• OPC_REP_INTEGER
The function returns an integer value.
• OPC_REP_FLOAT
The function returns a float value.
• OPC_REP_STRING
The function returns a zero terminated string.
• OPC_REP_VOID
The function does not return a value.
3.4 Function definition

A function must be defined in the file ‘opc_usr.inc’ (located in the
FAST/TOOLS include directory). It has the following layout:
+-----------------------------------------------------------------------------+
|
| Description:
| This include file defines PROCESS/FAST language callable function added
| by the system integrator.
+----------------------------------------------------------------------------*/
#ifdef OPC_FNC_DEF_DEC
/*----------------------------------------------------------------------------+
| Function declaration section, functions can be added here.
| For example: OPC_DECLARE(my_function)
+----------------------------------------------------------------------------*/
#endif
#ifdef OPC_FNC_DEF_ARG

Function definition Functions
/*----------------------------------------------------------------------------+
| Function argument list section, argument definitions can be added here.
| For example:
| #define MY_ARG_LIST OPC_REP_FLOAT, OPC_REP_VOID, OPC_REP_VOID, OPC_REP_VOID,\
| OPC_REP_VOID, OPC_REP_VOID, OPC_REP_VOID, OPC_REP_VOID,\
| OPC_REP_VOID, OPC_REP_VOID
+----------------------------------------------------------------------------*/
#endif
#ifdef OPC_FNC_DEF_DEF
/*----------------------------------------------------------------------------+
| Function definition section, functions can be added here.
| Function name must be in upper case!
| For example:
| OPC_DEFINE(“MY_FNC”, my_function, “my_functions”, OPC_REP_FLOAT, MY_ARG_LIST)
+----------------------------------------------------------------------------*/
#endif
It contains three sections.

In the declaration section the ‘C’ entry point of the ‘C’ routine handling
the function must be declared. All standard functions are already in this
list and new ones can be added to it.
In the definition section the function characteristics are defined. All
standard functions are already in this list and new ones can be added to
this list. For each function the following characteristics must be
specified:
• The function name (in uppercase) specifies the name of the function
within the PROCESS/FAST language. It is called within the
language by this name.
• The entry point of the corresponding ‘C’ routine. This entry point
must also be specified in the declaration section.
• The name of the source file where the ‘C’ routine resides. All
standard functions are collected in a single source file ‘opc_bif’.
OPC assumes the extension ‘.c’. It is advised to put new functions
in a different source file. The source files must be located on the
FAST/TOOLS source directory.
• The representation of the function result; OPC_REP_INTEGER,
OPC_REP_FLOAT, OPC_REP_STRING or OPC_REP_VOID.
• The representation of the arguments (10 arguments). Not used
arguments must have the representation of OPC_REP_VOID. Note
that in ‘opc_usr.inc’ shortcuts must be used (for example ARG_F)
for the sake of clearness. These are defined in the third section.

Functions Function specification
3.5 Function specification

When the function is defined its source has to be entered in the source
file defined for the function. All standard functions are specified in the
source ‘opc_bif.c’ located in the FAST/TOOLS source directory.
The global layout of a function specification is:
OPC_FUNCTION(<c entry point>)
OPC_DECLARATION
/* Declaration section */
OPC_BODY
/* Executable statements */
OPC_END_FUNCTION
<c entry point> is the name of the entry point defined for the
function.
All standard functions are supplied as source code (file ‘opc_bif.c’ on
the FAST/TOOLS source directory).
3.5.1 Declaration section
In the declaration section all ‘C’ variables used in the executable

statements section must be declared. All ‘C’ type variables can be used.
In addition there are variable types defined corresponding with the value
representation within the PROCESS/FAST language:
PROCESS/FAST representation C representation
integer OPC_INTEGER (= long)

float OPC_FLOAT (= double)
string OPC_STRING (= char)
3.5.2 Executable statements
The actual function algorithm is specified in the executable statement

section. Any C syntax can be used.
Note: A function may not stall while waiting for
any resource to become available. When it
has to wait it must remember its state. The
next time it is called it checks if the resource
is available. When it is, it can advance to

Function specification Functions
the next state and when not available it has

to return immediately. When the function
stalls, it stalls execution of all objects
handled by the OPC executor process.
Support functions are supplied to manipulate function arguments,
function result, function flow. A number of miscellaneous support
functions are supplied to access OPC data.
Accessing arguments
Data passed by the function arguments can be accessed by a number of
support functions. The data can be obtained and modified. The
following table shows the support functions available and the
relationship to the argument representation:
Argument
Obtain Modify
representation
integer OPC_GET_INTEGER OPC_SET_INTEGER
float OPC_GET_FLOAT OPC_SET_FLOAT
string OPC_GET_STRING OPC_SET_STRING
timer OPC_GET_TIMER_VALUE OPC_SET_TIMER_VALUE
OPC_GET_TIMER_STATUS OPC_SET_TIMER_STATUS
global OPC_GET_INTEGER_ OPC_SET_INTEGER_

attribute GLOBAL_ATTRIBUTE GLOBAL_ATTRIBUTE
OPC_GET_FLOAT_ OPC_SET_FLOAT_
GLOBAL_ATTRIBUTE GLOBAL_ATTRIBUTE
OPC_GET_STRING_ OPC_SET_STRING_
GLOBAL_ATTRIBUTE GLOBAL_ATTRIBUTE
local OPC_GET_INTEGER_ OPC_SET_INTEGER_

attribute LOCAL_ATTRIBUTE LOCAL_ATTRIBUTE
OPC_GET_FLOAT_ OPC_SET_FLOAT_
LOCAL_ATTRIBUTE LOCAL_ATTRIBUTE
OPC_GET_STRING_ OPC_SET_STRING_
LOCAL_ATTRIBUTE LOCAL_ATTRIBUTE
alarm OPC_GET_ALARM_PRIORITY OPC_SET_ALARM_PRIORITY
OPC_GET_ALARM_STATUS OPC_SET_ALARM_STATUS
OPC_GET_ALARM_VALUE OPC_SET_ALARM_VALUE
signal OPC_GET_SIGNAL_ OPC_SET_SIGNAL_

INTEGER_VALUE INTEGER_VALUE

Argument
Obtain Modify
representation

FLOAT_VALUE FLOAT_VALUE
OPC_GET_SIGNAL_
INTEGER_OLD_VALUE
OPC_GET_SIGNAL_
FLOAT_OLD_VALUE
OPC_GET_SIGNAL_ OPC_SET_SIGNAL_
INTEGER_ARRAY INTEGER_ARRAY
FLOAT_ARRAY FLOAT_ARRAY
OPC_GET_SIGNAL_STATUS OPC_SET_SIGNAL_STATUS
OPC_GET_SIGNAL_
CONTROL_STATUS
OPC_GET_SIGNAL_
OPTION_STATUS
OPC_GET_SIGNAL_
MERGED_STATUS
OPC_GET_SIGNAL_
ALARM_TYPE
OPC_GET_SIGNAL_
ACKNOWLEDGED
HIGH_HIGH_LIMIT HIGH_HIGH_LIMIT
HIGH_LIMIT HIGH_LIMIT
OPC_GET_SIGNAL_STRING_ OPC_SET_SIGNAL_STRING_
VALUE VALUE
OPC_GET_SIGNAL_STRING_
OLD_VALUE
LOW_LIMIT LOW_LIMIT
LOW_LOW_LIMIT LOW_LOW_LIMIT
DEADBAND DEADBAND
QUALITY QUALITY
OPC_GET_SIGNAL_
APPLICATION_SIZE

Argument
Obtain Modify
representation

APPLICATION_INFO APPLICATION_INFO
APPLICATION_FLAG APPLICATION_FLAG
OPC_GET_SIGNAL_
UPDATE_TIME
OPC_GET_SIGNAL_
ID
OPC_GET_SIGNAL_
ID_NODE
OPC_GET_SIGNAL_
ID_GROUP
OPC_GET_SIGNAL_
ID_NUMBER
OPC_GET_SIGNAL_
ID_SUB
OPC_GET_SIGNAL_
INSTALLATION
OPC_GET_SIGNAL_
UNIT
OPC_GET_SIGNAL_
TAG
OPC_GET_SIGNAL_
SUB
Most support functions accept two parameters. The first parameter

specifies the function argument to obtain or handle. Counting starts with
zero up to 9. The second parameter is an OPC_INTEGER,
OPC_FLOAT or OPC_STRING which will receive the value when
obtaining info or contains the value to set.
Note: OPC does not check that the correct
argument support function is used for an
argument with a certain representation. It
is the programmer’s responsibility that the
argument support functions used
correspond with the argument
representations specified in the function
definition. The OPC compiler checks that
the arguments supplied to the function
when called match the argument

representation as defined in the function

definition.
For example the function MIDDLE() extracts some characters from a
string (see ‘opc_bif.c’):
/*====================================================+
| Entry point
+-----------------------------------------------------+
|
| Description: MIDDLE()
+----------------------------------------------------*/
OPC_FUNCTION(opc_bi_middle) [1]
OPC_DECLARATION [2]
OPC_STRING *s, r[OPC_MAX_STR_SZ+2]; [3]

OPC_INTEGER i, i2; [4]
OPC_BODY [5]
OPC_GET_STRING(0, s); [6]

OPC_GET_INTEGER(1, i); [7]
OPC_GET_INTEGER(2, i2); [8]
if (i < strlen(s)) [9]
{
strcpy(r, &s[i-1]);
if (i2 < OPC_MAX_STR_SZ) r[i] = ’\0’;
}
else
r[0] = ’\0’;
OPC_RET_STRING(r); [10]
OPC_END_FUNCTION [11]
1 The function entry.
2 Start of the declaration section.
3 Two strings are declared. *s is a pointer to string which will point
to the string supplied as the first argument to MIDDLE(). The
second string r[OPC_MAX_STR_SZ+2] will receive the result of the
operation.
4 Two integers are declared. i receives the second argument to
MID() and i2 receives the third argument to MIDDLE().
5 Start of the executable statements section.
6 The first argument to the MIDDLE() function is placed in *s.
7 The second argument is placed in i.
8 The last argument is placed in i2.
9 The operation.

10 The string result of the function is set.

11 The function exit.
Setting function result

The function result is set by one of the following support routines:
• OPC_RET_INTEGER returns an integer.
• OPC_RET_FLOAT returns a float.
• OPC_RET_STRING returns a string (see [10] in the previous
example).
Controlling function flow

A number of flow control support functions are available:
OPC_EXIT exits the function. It can be used to exit the function while
executing an if statement for example:
if ...
{
OPC_EXIT;
}
else
{
...
}
The function also exits when OPC_END_FUNCTION is encountered.
OPC_ERROR_EXIT signals an error condition and exits the function.
Miscellaneous
A number of miscellaneous support functions are available:
OPC_UMH_CONTEXT returns the UMH context to be used in calls to
UMH. For example:
if ...
{
umh_set_code(OPC_UMH_CONTEXT, my_error_code);
OPC_ERROR_EXIT;
}
OPC_DUR_CONTEXT returns the DUR context to be used in calls to
DUR. For example:
if (!dur_snd_rep(OPC_DUR_CONTEXT, OPC_UMH_CONTEXT,
&par_snd)
{

Functions Function context
umh_add_code(OPC_UMH_CONTEXT, my_error_code);
OPC_ERROR_EXIT;
}
OPC_TASK_NUMBER returns a unique number which must by used in
the task id when sending and receiving BUS/FAST messages to
distinguish replies from those addressed to other functions.
OPC_ERROR signals an error condition without going exit. An error
text can be supplied.
OPC_PRINT prints the specified text on the UMH error logger.
3.6 Function context

All information is passed to the function by the OPC function context.
The support functions described in the previous section access this
function context to obtain information. For completeness the function
context is described.
struct opc_fnc_cont
{
struct opc_fnc_def *fnc_def;
struct dur_context *dur_c;
struct umh_context *umh_c;
TLS_BOOLEAN status;
TLS_BOOLEAN exe;
int task;
TLS_BOOLEAN trace;
int trace_line;
char *trace_inc_name;
char *trace_obj_name;
void *cls;
void *obj;
void *dbg;
void *var;
void *a1;
void *a2;
void *a3;
void *a4;
OPC_FLOAT *f;
OPC_INTEGER *i;
OPC_STRING *s;
int *arg;
} *opc_c;
struct opc_fnc_def

Updating OPC Functions
{
char *name;
OPC_FNC fnc;
char *src;
int rep;
int arg_rep[OPC_MAX_FNC_ARGS];
};
The contents can not be modified. The following members can be useful:
exe is TRUE when the object is executing its body. When the prolog is
executed it is FALSE.
trace is TRUE when the object’s class is compiled with the trace option
set. In this case trace_line contains the line number within the class
source being executed and trace_inc_name contains the name of the
included class being executed.
trace_obj_name contains the name of the object.
name contains the name of the current function.
rep contains the representation of the result.
arg_rep contains the representation of the arguments.
These members are addressed in the following way, for example:
if (opc_c->trace) ...
3.7 Updating OPC

A number of steps must be executed to add a function to the standard list
of functions:
1 Add the function declaration and definition to the file ‘opc_usr.inc’
(located in %TLS_ROOT_PATH%\tls\inc).
2 Add the function to ‘opc_usr.c’ (located in
%TLS_ROOT_PATH%\tls\ins).
3 Compile ‘opc_usr.c’. For example on Window systems:
cd %TLS_ROOT_PATH%\tls\com
process_compile
4 Stop PROCESS/FAST.
5 Rebuild PROCESS/FAST. For example on Windows systems:
cd %TLS_ROOT_PATH%\tls\com
process_build
6 Start PROCESS/FAST.
7 Check the execution of the function.

Functions Updating OPC

General Quick load
4 Quick load
TRIGGER OBJECT
GROUP
CLASS
CLASS OBJECT
OPC
4.1 General
Classes and objects can be inserted via the OPC routine set. In addition
the DSS quick load utility can be used to insert classes and objects which
are specified in an ASCII delimited format in a text file. This utility can
be used interactively or the utility can be started in the background
mode. In the latter case a BUS/FAST request can be sent to the utility
containing the name of the file to process.

Quick load General

General Reference
5 Reference
??
? ?
CLASS
OPC
OBJECT
CLASS
TRIGGER
GROUP
5.1 General
In this chapter a reference of the OPC usage is supplied. Described are:
• Conventions
• Compiling, linking, and running applications
• Data structures
• Error handling
• Routines and support functions
5.2 Conventions
All OPC routines have ‘C’-type interfaces. The syntax of all routines as
well as the examples comply with ‘C’ language conventions.
All parameters which are passed by reference may be assumed to be
modifiable by the routine to which they are passed. All parameters
passed by value may be assumed to be input only.
Example: the syntax of the routine opc_obj_ins():
[status=] opc_obj_ins(opc_c,obj_def, attrs)

Reference Compiling, linking, and running applications
struct opc_context *opc_c; /* The OPC context */

struct opc_obj_def *obj_def; /* Object to create */
int attrs; /* Number of attributes */
Most of the OPC routines return a TLS_BOOLEAN as the status

indicator. This is shown in the syntax descriptions as [status=].
Normally this returned value would be tested directly rather than being
assigned to a variable, as follows:
if (!opc_obj_ins())
{
/* error - use UMH context to log the error(s) */
}
The header file opc.h contains definitions that should be used when
calling OPC routines. For this reason, opc.h must always be included in
any source that is to utilize OPC.
The names of routines, data structures, and defined constants that are
part of OPC all start with the three letters ‘opc’.
letters.

applications
In order that the OPC routines can be used in your applications, it is
necessary to ensure that the following are true:
• PROCESS/FAST is installed
• ‘opc.h’ has been included in the source
• the source has been linked with the BUS and OPC libraries
5.4 Error handling

All the OPC routines use the standard FAST/TOOLS error handling
facilities provided by UMH.

When a routine returns TRUE, the contents of the error buffer remain
unchanged.
5.5 Data Structures

The following data structures are important for the application
programmer. They are given in alphabetical order.
5.5.1 Attribute update
The attribute update is used to obtain or modify the value of an attribute.

struct opc_atr_upd
{
struct opc_id obj_id; /* Object id */
struct opc_atr_val atr_val; /* Attribute id and value
*/
};
Global attributes can be modified for classes only. Local attributes can
be modified or obtained for the class and the objects derived from the
class. When the attribute, specified by attribute id, is a global attribute
then the object id is ignored. For local attributes the object is used unless
the obj_id.sec is zero. In the latter case the class is taken.
The attribute id must be obtained previously by a call to opc_cls_npmt(),
opc_cls_gatr() or opc_cls_natr().
5.5.2 Attribute value
The attribute value is also used to obtain or specify the value of an

attribute.

struct opc_atr_val
{
struct opc_id atr_id; /* Attribute id */
TLS_USHORT nu1;
TLS_USHORT rep; /* Representation, REP_ */
union opc_val /* Value */
{
TLS_UBYTE c;
TLS_SHORT s;
TLS_LONG l;
TLS_FLOAT f;
TLS_DOUBLE d;
TLS_BOOLEAN b;
char t[sizeof(TLS_DOUBLE_S)];
} val;
};
When obtaining an attribute value the required presentation must be

specified. On return of the call the field rep contains the returned
representation of the value:
Representation
In field
wanted attribute returned
REP_DEF INTEGER REP_LONG l

REP_DEF REAL REP_DOUBLE d
REP_DEF STRING REP_STRING t
REP_BOOLEAN * REP_BOOLEAN b
REP_UBYTE * REP_UBYTE c
REP_BYTE * REP_BYTE c
REP_SHORT * REP_SHORT s
REP_USHORT * REP_USHORT s
REP_FLOAT * REP_FLOAT f
REP_DOUBLE * REP_DOUBLE d
REP_LONG * REP_LONG l
REP_STRING * REP_STRING t
When handling strings make sure that the attribute value maps to a
buffer large enough to handle strings:

struct opc_atr_val *atr_val;

TLS_LONG buf_val[(sizeof(*atr_val)+OPC_MAX_STR_SZ)/
sizeof(TLS_LONG)];
atr_val = (struct opc_atr_val*)buf_val;
5.5.3 Class attributes
The class attribute is used to obtain the attributes defined in a class.

struct opc_cls_atr
{
char path[OPC_PTH_NAME_SZ]; /* Attribute path */
TLS_USHORT type; /* Attribute type */
TLS_USHORT nu1; /* Not used */
};
The field type returns the attribute type, which is one of:
Value Description
OPC_ATR_CLS global attribute

OPC_ATR_OBJ local attribute
5.5.4 Class definition
The class definition is used for several maintenance purposes.

struct opc_cls_def
{
char name[OPC_CLS_NAME_SZ]; /* Class name */
char desc[OPC_CLS_DESC_SZ]; /* Class description */
char copy[OPC_CLS_NAME_SZ]; /* Class to copy from */
struct opc_id cls_id; /* Class id */
char file[OPC_FIL_NAME_SZ]; /* Source file or
compilation list file*/
TLS_USHORT priority; /* Priority */
TLS_USHORT objects; /* # of objects derived */
TLS_USHORT com_errors; /* Compilation errors */
TLS_USHORT com_warnings; /* Compilation warnings */
TLS_ULONG language; /* Language type, 1:Java
2:Traditional */
TLS_ULONG com_flg; /* Compilation flags */
TLS_ULONG modified; /* Date/time of last
modification */
TLS_ULONG compiled; /* Date/time of last

compilation */
TLS_USHORT version; /* The Deploy version
number */
TLS_USHORT version2; /* The Edit version number
*/
TLS_USHORT objects2; /* # of objects derived
from edit version */
struct opc_attr_prompt attr_prompt_qrs[OPC_QRY_PMTS_SZ];
/* List of attribute
prompt queries (for
Java only) */
};
This struct is the input/output argument for a number of OPC class
manipulation routines. Depending on the routine the fields within the
structure have a meaningful value. This is summarized in the following
table.
opc_cls_view
opc_cls_mod
opc_cls_com
opc_cls_nxt
opc_cls_lck
opc_cls_del
opc_cls_get
opc_cls_ins
Field
I O I O I O I O I O I O I O I O
name * * * * * * * * * * * * * * *
desc * * * * * * * * * * *
copy *
cls_id * * * * * * * * * *
file * * * * * * * *
priority * * * * * * * * *
objects
com_errors *
com_warnings *
com_flg *
modified * * * * * * *
compiled * * * * * * *
The name of a class starts with a letter followed by a number of letters,

digits or underscores. The priority ranges from zero to 999. More
information is found with the description of the routines.

5.5.5 Included class
The included class is used to retrieve information about classes included

by a class.
struct opc_cls_inc
{
struct opc_id inc_id; /* Id for included class*/
struct opc_id par_inc_id; /* Id of parent inc. class
*/
char name[OPC_INC_NAME_SZ]; /* Identifier for included
*/
};
Field inc_id identifies the included class within the class. Field
par_inc_id contains the id for the included class which included this
one. Field cls_id contains the class id of the included class. Field name
contains the name assigned to the included class by the CONTAINS
statement within the class source.
5.5.6 Class prompt
The class prompt is used to obtain information about the prompts

defined in the class source.
struct opc_cls_pmt
{
struct opc_id pmt_id; /* Prompt id */
char query[OPC_QRY_TEXT_SZ]; /* Query text */
};
Field pmt_id identifies the prompt within the class. Field atr_id
identifies the attribute prompted and the field query contains the query
text.
5.5.7 Class reset
The class reset is used to reset all objects of a certain class on the
specified BUS/FAST node.

struct opc_cls_res
{
TLS_SHORT nu1;
};
5.5.8 Class signals
The class signal is used to obtain the signals defined in a class.

struct opc_cls_sig
{
struct opc_id sig_id; /* Signal id */
char path[OPC_PTH_NAME_SZ]; /* Signal path */
};
5.5.9 Class/trigger group relation
The class/trigger group relation specifies a class within a trigger group.

It is used to insert a class in a trigger group (opc_cls_itrg()), to delete a
class from a trigger group (opc_cls_dtrg()) and to obtain information
about a class’s trigger groups (opc_cls_ntrg())
struct opc_cls_trg_id
{
struct opc_id trg_id; /* Trigger group id */
};
5.5.10 OPC context
The OPC context is returned and filled by the OPC attach routine and is
an argument for all successive calls to OPC. It is not allowed to modify
any field in the context.
struct opc_context
{
struct opc_context *chk; /* Internal check */
int timeout; /* MDUR timeout */
struct dur_adr adr; /* BUS/FAST address of the

OPC manager process */

};
5.5.11 Function context
PROCESS/FAST callable functions written in the ‘C’ language are

passed information via the function context. The support functions are
used to access this context.
struct opc_fnc_cont
{
struct opc_fnc_def *fnc_def; /* Function definition */
TLS_BOOLEAN status; /* Error indication */
TLS_BOOLEAN exe; /* TRUE when body excuting
*/
int task; /* Unique task number */
TLS_BOOLEAN trace; /* TRUE when tracing is
enabled */
int trace_line; /* Current source line
number */
char *trace_inc_name; /* Current included class
name */
char *trace_obj_name; /* Current object name */
void *cls; /* Current class info */
void *obj; /* Current object info */
void *dbg; /* Debug info */
void *var; /* Variable table */
void *a1;
void *a2;
void *a3;
void *a4;
OPC_FLOAT *f; /* Return values */
OPC_INTEGER *i;
OPC_STRING *s;
int *arg; /* Arguments */
};
5.5.12 Function definition
PROCESS/FAST callable function written in the ‘C’ language are

defined in the file ‘opc_usr.c’ (on the FAST/TOOLS source directory).

struct opc_fnc_def
{
char name; /* Function name */
OPC_FNC fnc; /* Function entry point */
char *src; /* Source file */
int rep; /* Function result */
int arg_rep[OPC_MAX_FNC_ARGS];
/* Function arguments */
};
5.5.13 Identification
Classes, trigger groups, objects, signals, etc. are externally represented

by their names. Internally they have a unique identification:
struct opc_id
{
TLS_ULONG sec; /* Creation time */
TLS_USHORT seq; /* Sequence within a
second */
TLS_USHORT opt; /* Optional field */
};
An internal identification can not be modified.
5.5.14 Object definition
The object definition is used for several maintenance purposes.

struct opc_obj_def
{
struct opc_obj_name name; /* Object name */
char desc[OPC_OBJ_DESC_SZ]; /* Object Description */
struct gin_dii_id dii_id; /* Id of control item */
char file[OPC_FIL_NAME_SZ]; /* Name of the debug output
file */
TLS_USHORT priority; /* Priority */
TLS_ULONG start; /* Activation time */
TLS_ULONG stop; /* Deactivation time */

modification */
TLS_ULONG flags; /* Flags */
struct opc_atr_val atr_val[1];
/* List of attributes to
set */
};
This struct is the input/output argument of a number of OPC object
table.
opc_obj_mod
opc_obj_dbg
opc_obj_nxt
opc_obj_del
opc_obj_get
opc_obj_ins
Field
I O I O I O I O I O I O
cls_id * * * * * *
name * * * * * * * * * *
desc * * * * * *
dii_id * * * * * *
obj_id * * * * * * * *
file *
node * * * * * *
priority * * * * * *
start * * * * * *
stop * * * * * *
modified * * * *
flags * * * * * * *
atr_val *
The tag name of an object starts with a letter followed by a number of

letters, digits or the underscore. The priority ranges from zero to 999.
The start and stop time specify the time window the object is active.
Special values are defined for the start and stop time:
Start time Stop time Active
< now <= now

>= now <= now

< now > now *
>= now > now
OPC_OBJ_STARTED <= now
OPC_OBJ_STARTED > now *
< now OPC_OBJ_FOREVER *
>= now OPC_OBJ_FOREVER
OPC_OBJ_STARTED OPC_OBJ_FOREVER *
More information is found with the description of the routines.

For flags the following value are define:
#define OPC_OBJ_DEBUG_ON_FLAG
/* Debug flag specified */
#define OPC_OBJ_DEBUG_ON
/* Flag debug on */
#define OPC_OBJ_ITEMS_MAY_EXIST_FLAG
/* Item may exist flag specified */
#define OPC_OBJ_ITEMS_MAY_EXIST
/* For signal make, items may already exist */
#define OPC_OBJ_LEAVE_ITEMS_FLAG
/* Leave items flag specified */
#define OPC_OBJ_LEAVE_ITEMS
/* For signal make, items are not deleted on object
deletion */
5.5.15 Object name
An object name is specified by struct opc_obj_name.

struct opc_obj_name
{
char name[OPC_ITEM_MAX_FLNM];/* Full name */
TLS_ULONG nsid; /* The name space id */
TLS_ULONG parent_nsid; /* The parent name space id
*/
};
The field name specifies the full name of the object including the section
path. The nsid is the name space id by which the object is known within

the FAST/TOOLS name space. The parent_nsid is the name space id by

which the section of the object is known within the FAST/TOOLS name
space. PROCESS/FAST itself doesn’t do a thing with the name space
ids. It is the responsibility of the OPC API user to place the object in the
FAST/TOOLS name space and supply the ids in this struct.
5.5.16 Object/trigger group relation
The object/trigger group relation specifies an object within a trigger

group. It is used to insert an object in a trigger group (opc_obj_itrg()), to
delete an object from a trigger group (opc_obj_dtrg()) and to obtain
information about object’s trigger groups (opc_obj_ntrg()).
struct opc_obj_trg_id
{
struct opc_id trg_id; /* Trigger group id */
};
5.5.17 Signal update
The signal update is used to obtain the id of a signal’s item.

struct opc_sig_upd
{
struct opc_id sig_id; /* Signal id */
struct dii_id dii_id; /* Item id */
struct opc_his_info his_info;/*Item history info */
};
The signal id must be obtained previously by a call to opc_cls_gsig() or
opc_cls_nsig().
5.5.18 Trigger group definition
The trigger group definition is used for several maintenance purposes.

struct opc_trg_def
{
char name[OPC_TRG_NAME_SZ]; /* Trigger group name */
char desc[OPC_TRG_DESC_SZ]; /* Trigger description */
struct opc_id trg_id; /* Trigger id */
struct ftm_time interval; /* Interval (msec) */
TLS_ULONG start; /* Activation time */
TLS_ULONG stop; /* Deactivation time */
TLS_BOOLEAN gmt; /* GMT/LCT flag */
modification */
};
This struct is the input/output argument of a number of OPC trigger

table.
opc_trg_mod
opc_trg_nxt
opc_trg_del
opc_trg_get
opc_trg_ins
Field
I O I O I O I O I O
name * * * * * * * * *
desc * * * * * *
trg_id * * * * * *
interval * * * *
start * * * *
stop * * * *
gmt * * * *
modified * * * *
The name of a trigger group starts with a letter followed by a number of

letters, digits or underscores.
The interval is specified in seconds and milliseconds. However, the
milliseconds part is stripped by OPC. A trigger interval of zero seconds

triggers once when the start time of the trigger group is reached. Special
values are defined for the seconds part of the interval:
Value Description
OPC_TRG_1W Once a week

OPC_TRG_4W Once in four weeks
OPC_TRG_1M Once a month
OPC_TRG_2M Once in two months
OPC_TRG_3M Once in three months
OPC_TRG_4M Once in four months
OPC_TRG_6M Once in six months
OPC_TRG_1Y Once a year
OPC_TRG_01 Once when the object is activated or reset
The once a month intervals take the length of the months in account.
The start and stop time specify the time window the trigger group is
active. Special values are defined for the start and stop time:
< now <= now

>= now <= now
< now > now *
>= now > now
OPC_TRG_STARTED <= now
OPC_TRG_STARTED > now *
< now OPC_TRG_FOREVER *
>= now OPC_TRG_FOREVER
OPC_TRG_STARTED OPC_TRG_FOREVER *
Any when the interval is Any when the interval is *
OPC_TRG_01 OPC_TRG_01
The first trigger is generated at the time the start time is reached.
Additional triggers are generated at multiples of the specified trigger
interval added to the start time.

When the GMT field is set to TRUE, intervals are absolute and summer
and winter time changes are ignored. When FALSE, summer and winter
time changes are taken into account.
More information is found with the description of the routines.
5.5.19 Data source monitoring
The following structures are used in combination with the data source
monitoring functions.
When a data source channel is first opened with opc_opn_evt(), a
context structure is returned to identify the session. This structure must
be used in all subsequent calls to the data source monitoring routines.
The members of this structure are of no direct use to the application and
should not be modified.
struct opc_evt_context
{
struct opc_context *opc_c;
TLS_ULONG flags;
TLS_ULONG msg_ref_id;
TLS_ULONG interval;
struct opc_id evt_id;
struct opc_id rec_id;
char rec_name[OPC_REC_NAME_SZ];
};
When data source monitoring has been set up, the application will
receive a structure containing information about the action that occurred
on the data source:
struct opc_evt /* The event */
{
TLS_ULONG evt_seq; /* Event sequence */
TLS_ULONG ref_id; /* Reference id */
TLS_ULONG evt_layout; /* Layout of the event

Routines and BUS/FAST messages Reference
message*/
TLS_ULONG evt_time; /* Time of the event */
TLS_ULONG data_source; /* Data source changed */
TLS_ULONG evt_crit; /* Event criteria */
};
struct opc_evt_src /* Who did it */
{
struct dur_adr src_adr;
};
struct opc_evt_id /* The record id */
{
struct opc_id rec_id;
};
struct opc_evt_name /* The record name */
{
char name[OPC_REC_NAME_SZ];
};
More information about the members of this structure is provided in the
description of the opc_set_evt().
If flow control has been requested, messages containing the following
information will be received by the application. The evt_seq field
contains the same sequence number as the last event that was sent. The
flow_seq field contains indicates the sequence number of this flow
control message. This makes it possible for the application to determine
if any events have been lost, by keeping track of these sequence
numbers.
struct opc_flow /* Flow control message */
{
TLS_ULONG evt_seq; /* Last event sequence */
TLS_ULONG flow_seq; /* Flow sequence */
};
5.6.1 Introduction
In this section the OPC routine set and BUS/FAST messages are
described.
For each routine and BUS/FAST message a description is given of the
following:

Reference Routines and BUS/FAST messages
• its syntax or its BUS/FAST message layout

• its parameters
• its semantics
• the error codes that may be returned by it
• other OPC routines or BUS/FAST messages that are related to it

5.6.2 Obtain the next active trigger
Syntax [status=] opc_act_nxt(opc_c, act_trg)

struct opc_context *opc_c; /* OPC context */
struct opc_act_trg *act_trg; /* Trigger/class/object */
Semantics opc_act_nxt() is used to get the next active trigger group, but can also be
used to find the relation between active trigger groups and classes or
objects.
opc_c is the pointer to the OPC context obtained with the
opc_attach() routine.
Depending on the type of search a different key must be specified in
act_trg->key_id:
• Find next active trigger:
Fill act_trg->trg_id and set act_trg->key_id to
OPC_TRGACT_TRG_ID. The first active trigger is found by
filling act_trg->trg_id with zeros.
• Find next object or class that uses a specific trigger group:
Fill act_trg->trg_id and set act_trg->key_id to
OPC_TRGACT_TRG_ID_ID. The first class or object using the
trigger id is found by filling act_trg->id with zeros.
The act_trg->flags must be inspected to see whether a class id
or object id is returned. The contents is either
OPC_CLS_ACT_TRG or OPC_OBJ_ACT_TRG.
• Find next trigger group that is used by a specified class or object:
Fill act_trg->id with the class id or object id and set
act_trg->key_id to OPC_TRGACT_ID_TRG_ID. The first
trigger group that is used by the class or object is found by filling
act_trg->trg_id with zeros.
Errors • OPC_E_NOTATT
Not attached to OPC.
• OPC_E_ACT_NOTEXI
The next active trigger record does not exist for the specified trigger
id, class id, object id in combination with the chosen key.
• OPC_E_ACT_NOTGET
The active trigger can not be obtained due to an internal error.

Related routines • opc_attach()

Allocate and attach to OPC.

5.6.3 Obtain the value of an attribute
Syntax [status=] opc_atr_rd(opc_c, atr_upd)

struct opc_atr_upd *atr_upd; /* Attribute to obtain */
Semantics opc_atr_rd() is used to obtain the value of an attribute.

atr_upd points to a buffer which specifies the attribute to obtain and on
return of the routine contains the attribute value. On entry the field
atr_upd->obj_id contains the object id whose attribute has to be
obtained. OPC ignores the object id when a global attribute is specified.
When atr_upd->obj_id.sec is zero and a local attribute is specified
then the value of the local attribute for the class is returned. Field
atr_upd->atr_val.atr_id contains the attribute id to obtain and field
atr_upd->atr_val.rep the wanted representation. On return of the
routine, field atr_upd->atr_val.rep contains the returned
representation of the value stored in atr_upd->atr_val.val.
Notes atr_upd must map to a buffer large enough to store strings in case a
string (REP_STRING) is returned.
• OPC_E_ATR_NOTCONV
The value of the attribute can not be converted to the requested
representation.
• OPC_E_ATR_NOTEXI
The specified attribute does not exist (for the object).
• OPC_E_ATR_NOTGET
Failed to obtain the value for the attribute.

• opc_cls_gatr() and opc_cls_natr()
Return attribute id in a class.

• opc_atr_wr()
Modify the value of an attribute.

5.6.4 Modify the value of an attribute
Syntax [status=] opc_atr_wr(opc_c, atr_upd)

struct opc_atr_upd *atr_upd; /* Attribute to obtain */
Semantics opc_atr_wr() is used to modify the value of an attribute.

atr_upd points to a buffer which specifies the attribute and its new
value. On entry the field atr_upd->obj_id contains the object id
whose attribute has to be modified. OPC ignores the object id when a
global attribute is specified. When atr_upd->obj_id.sec is zero and
a local attribute is specified then the value of the local attribute for the
class is modified. Field atr_upd->atr_val.atr_id contains the id of
the attribute to modify and field atr_upd->atr_val.rep the
representation of the value stored in atr_upd->atr_val.val. On
return of the routine the value of the attribute is returned in its own
representation, Field atr_upd->atr_val.rep contains the returned
representation and the value is stored in atr_upd->atr_val.val.
Notes atr_upd must map to a buffer large enough to store strings in case a
string (REP_STRING) is specified or returned.
• OPC_E_ATR_NOTCONV
The value of the attribute can not be converted to the attribute’s
representation.
• OPC_E_ATR_NOTEXI
The specified attribute does not exist (for the object).
• OPC_E_ATR_NOTMOD
Failed to modify the value of the attribute.

• opc_cls_gatr() and opc_cls_natr()
Return attribute id in a class.

• opc_atr_rd()
Obtain the value of an attribute.

5.6.5 Attach to OPC
Syntax opc_c = opc_attach(dur_c, umh_c, node, timeout, user,

terminal)
Arguments struct opc_context *opc_c; /* OPC context, NULL if

error */
struct umh_context *umh_c, /* UMH context */
int node; /* Node of OPC host */
int timeout; /* Timeout in seconds */
char user[]; /* User name */
char terminal[]; /* Terminal name */
Semantics opc_attach() is used to attach to OPC.

A pointer (opc_c) is returned to the OPC context allocated and
initialized by OPC. When NULL is returned an error has been
encountered.
dur_c contains the DUR context obtained by attaching to DUR.
umh_c contains the UMH context. Errors are stored in this context by all
successive calls to OPC routines.
node contains the node number of the OPC host. Zero specifies to use
the own node.
timeout specifies the number of seconds a successively called OPC
routine may take to process the information. When this timeout elapses
user and terminal are used to audit modifications to the OPC
configuration via successive calls to OPC routines. The size of the user
name is limited to OPC_USR_NAME_SZ characters and the terminal
name is limited to OPC_TER_NAME_SZ characters.
Errors • OPC_E_NOTVER
Version mismatch between the OPC routine set and OPC processes.
Related routines • opc_detach()

Detach from OPC.

5.6.6 Compile a class
Syntax [status=] opc_cls_com(opc_c, cls_def)

struct opc_cls_def *cls_def; /* Class to compile */
Semantics opc_cls_com() is used to compile the source of a class. The source is

transformed from a textual representation to a fast executable binary
representation. In addition the textual information is checked for errors.
cls_def defines the class to compile. The class can be specified by
name or id. The specified id is used when the name is empty.
Compilation options can be specified In in cls_def->com_flg :
• When bit OPC_CLS_COM_TRACE is set then line number
information is maintained which is output with any detected error
during execution of derived objects.
• When bit OPC_CLS_COM_LIST is set then the compilation
results are stored in a list file. The name of the file to store the
listing is specified in cls_def->file. When empty then OPC
creates a temporary file to store the listing. The name of the
temporary file is returned in cls_def->file. This file is
overwritten on the next compilation and deleted when opc_detach()
is called.
The number of compilation errors and warnings are returned in the fields
cls_def->com_errors and cls_def->com_warnings. When
compilation errors or warnings are detected the routine returns success.
Notes The routine also returns class information in the same way as the
opc_cls_get() and opc_cls_nxt() routines.
• OPC_E_CLS_INVNAM
The class name specified contains invalid characters.
• OPC_E_CLS_NOTEXI
The class specified by name or id does not exist.
• OPC_E_CLS_NOTCOM
The class is not compiled due to an internal error.

• OPC_E_CLS_LOCKED
The class is being modified by another user.

• opc_cls_ins()
Create a class.
• opc_cls_mod()
Modify a class.

5.6.7 Delete a class
Syntax [status=] opc_cls_del(opc_c, cls_def)

struct opc_cls_def *cls_def; /* Class to delete */
Semantics opc_cls_del() is used to delete all information about a class. Classes with
no objects derived and not included by other classes can be deleted.
cls_def specifies the class to delete by name.
Notes To recover a deleted class, first obtain class info and source by giving
the opc_cls_lck() call.
The class does not exist.
• OPC_E_CLS_ACTOBJ
The class has objects.
• OPC_E_CLS_ACTCLS
The class is included by other classes.
• OPC_E_CLS_NOTDEL
The class is not deleted due to an internal error.

• opc_cls_ins()
Insert a class.
• opc_cls_mod()
Modify a class.
• opc_cls_lck()
Lock a class.

5.6.8 Delete a class from a trigger group
Syntax [status=] opc_cls_dtrg(opc_c, cls_trg_id)

struct opc_cls_trg_id *cls_trg_id;
/* Class/trigger group */
Semantics opc_cls_dtrg() is used to delete a class from a trigger group.

cls_trg_id specifies the class and the trigger group.
• OPC_E_TRG_NOTEXI
The class does not exist in the trigger group.
• OPC_E_CLS_NOTDEL
The class is not deleted from the trigger group due to an internal
error.

• opc_cls_itrg()
Insert a class in a trigger group.
• opc_cls_ntrg()
Return classes trigger group.

5.6.9 Close a data source event monitoring channel
Syntax [stat=] opc_cls_evt(evt_ctxt)
Arguments TLS_BOOLEAN stat; /* TRUE on success */

struct opc_evt_context evt_ctxt;/*event channel */
Semantics opc_cls_evt() is used to close a data source event monitoring channel

that has been opened with opc_opn_evt().
evt_ctxt is the event channel that has been obtained by the
opc_opn_evt() routine.
Errors • OPC_E_EVT_NOTEXI
The specified event channel does not exist.

• opc_opn_evt()
Opens an event monitoring channel on a data source.
• opc_set_evt()
Set event requests on an open channel.

5.6.10 Obtain attribute of a class
Syntax [status=] opc_cls_gatr(opc_c, cls_atr)

struct opc_cls_atr *cls_atr; /* Attribute info */
Semantics opc_cls_gatr() is used to obtain an attribute defined in the class source.

The attribute to obtain can be specified by id or path name.
cls_atr specifies the attribute to obtain. When cls_atr->path is
empty cls_atr->atr_id must contain the id of the attribute to obtain.
Otherwise, cls_atr->atr_id must contain the id of the class where the
attribute can be found by path. On exit of the routine, the attribute id,
path and type are returned.
Notes Only attributes for a compiled class can be obtained.
• OPC_E_CLS_NOTATR
The attribute specified by id or path does not exist.
• OPC_E_CLS_NOTGET
The attribute can not be obtained due to an internal error.

• opc_cls_natr()
Obtain info of the next attribute in a class.

5.6.11 Obtain info about a class
Syntax [status=] opc_cls_get(opc_c, cls_def)

struct opc_cls_def *cls_def; /* Class to obtain */
Semantics opc_cls_get() is used to obtain info about a class. The class is specified
by id or name.
cls_def defines the class to obtain info about. The class’s id, name,
one-liner description, priority, and time stamps of the last modification
and compilation are returned. The class source can be obtained by the
opc_cls_lck() or opc_cls_view() routine.
The specified class name contains invalid characters.
No information is returned due to an internal error.

• opc_cls_nxt()
Obtain info about the next class.
• opc_cls_view()
Obtain info about a class including the class source.
• opc_cls_lck()
Lock a class.

5.6.12 Obtain signal of a class
Syntax [status=] opc_cls_gsig(opc_c, cls_sig)

struct opc_cls_sig *cls_sig; /* Signal info */
Semantics opc_cls_gsig() is used to obtain a signal defined in the class source. The
signal to obtain can be specified by id or path name.
cls_sig specifies the signal to obtain. When cls_sig->path is empty
cls_sig->sig_id must contain the id of the signal to obtain.
Otherwise, cls_sig->sig_id must contain the id of the class and the
path where the signal can be found. On exit of the routine, the signal id
and path are returned.
Notes Only the signals of a compiled class can be obtained.
• OPC_E_CLS_NOTSIG
The signal specified by id or path does not exist.
The signal can not be obtained due to an internal error.

• opc_cls_nsig()
Obtain info of the next signal in a class.

5.6.13 Insert a class
Syntax [status=] opc_cls_ins(opc_c, cls_def)

struct opc_cls_def *cls_def; /* Class to insert */
Semantics opc_cls_ins() is used to insert a class.

cls_def defines the class to insert. The following fields must be
specified:
• name
The name of the class to insert.
• desc
The one-liner description.
• copy and file
The source of the class can be copied from an existing class, copied
from a specified file or copied from the OPC standard template.
Specify the class whose source it to be copied in copy. When copy
is empty and a file name is specified in file then the contents of
the specified file is used for the class source. When both are empty,
OPC uses its own template.
• priority
The priority for the class. An object with a priority of zero uses the
priority of the class it was derived from.
When inserted, the class source can be adapted by a sequence of
opc_cls_lck() and opc_cls_mod() routines.
Notes The class must be compiled before objects can be derived.
• OPC_E_CLS_EXIST
The class name already exists.
The class to copy the source from does not exist.

• OPC_E_CLS_NOTINS
The class is not inserted due to an internal error.
• OPC_E_CLS_INVPRIO
The specified priority is out of the range 0 to 999.
The class to copy the source from is being modified by another
user.

• opc_cls_mod()
Modify a class.
• opc_cls_lck()
Lock a class.
• opc_cls_del()
Delete a class.
• opc_cls_com()
Compile a class.

5.6.14 Insert a class in a trigger group
Syntax [status=] opc_cls_itrg(opc_c, cls_trg_id)

Semantics opc_cls_itrg() is used to insert a class in a trigger group.

cls_trg_id specifies the class and the trigger group.
The class specified by id does not exist.
The trigger group specified by id does not exist.
• OPC_E_TRG_EXIST
The class has already been inserted in the trigger group.
• OPC_E_CLS_NOTINS
The class is not inserted in the trigger group due to an internal error.

• opc_cls_dtrg()
Delete a class from a trigger group.
• opc_cls_ntrg()
Return classes trigger group.

5.6.15 Lock a class
Syntax [status=] opc_cls_lck(opc_c, cls_def)

struct opc_cls_def *cls_def; /* Class to lock */
Semantics opc_cls_lck() is used to lock a class while its source is being modified.
While the class is locked no other user is able to lock, modify, compile
or delete the class or to derive objects from the class. With the lock
request, class info is returned and the class source is returned in a
specified or temporary file. The locked class is freed by any other OPC
routine call.
cls_def defines the class to lock. The class to lock is specified by name
or id. When the name is empty then the class id is used.
In cls_def->file a name of a file can be specified. OPC copies the
class source to this file. When the file name is empty, OPC creates a
temporary file and copies the class source to this file. The temporary file
is overwritten at the next call to opc_cls_lck() or opc_cls_view() and
deleted with a call to routine opc_detach(). The name of the temporary
file is returned in cls_def->file. When the source is modified the
opc_cls_mod() routine updates the class with the modified source.
Besides the name of the file containing the class source, the class’s id,
name, one-liner description, priority, and time stamps of the last
modification and compilation are returned.
To obtain the source of a class without locking the class the routine
opc_cls_view() can be used.
• OPC_E_CLS_NOTLCK
The class is not locked due to an internal error.


• opc_cls_view()
To obtain the source of a class without locking the class.
• opc_cls_mod()
Modify a class.

5.6.16 Modify a class
Syntax [status=] opc_cls_mod(opc_c, cls_def)

struct opc_cls_def *cls_def; /* Class to modify */
Semantics opc_cls_mod() is used to modify some parameters in a class and to

modify the class source. The class one-liner description and priority can
be modified.
cls_def defines the class to modify. The class to modify is specified by
name or id. When the name is empty then the class id is used. A file
name can be specified in cls_def->file which contains the modified
source for the class. When specified the class must be locked prior to the
opc_cls_mod() routine with a call to opc_cls_lck() which returns the
name of the file containing the class source.
• OPC_E_CLS_NOTMOD
The class is not modified due to an internal error.
• OPC_E_CLS_NOTLCK
The class is not locked.

• opc_cls_lck()
Lock a class.

5.6.17 Obtain next attribute of a class
Syntax [status=] opc_cls_natr(opc_c, cls_atr)

struct opc_cls_atr *cls_atr; /* Attribute info */
Semantics opc_cls_natr() is used to obtain the next attribute defined in the class
source. The attribute with the next higher id than that specified is
returned.
cls_atr specifies the next attribute to obtain. The attribute with the next
higher id than that specified in cls_atr->atr_id is returned. The first
attribute in a class is specified by filling cls_atr->atr_id with the
class id.
On exit of the routine, the attribute id, path and type are returned.
Notes Only the attributes of a compiled class can be obtained.
A next attribute specified by id does not exist.
The attribute can not be obtained due to an internal error.

• opc_cls_gatr()
Obtain info of the specified attribute in a class.

5.6.18 Obtain next included class of a class
Syntax [status=] opc_cls_ninc(opc_c, cls_inc)

struct opc_cls_inc *cls_inc; /* Included class info */
Semantics opc_cls_ninc() is used to obtain the next included class defined in the
class source. The included class with the next higher id than that
specified is returned.
cls_inc specifies the next included class to obtain. The included class
with the next higher id than that specified in cls_inc->inc_id is
returned. The first included class in a class is specified by filling
cls_inc->inc_id with the class id.
On exit of the routine, the included class id, the id of the class including
it, the class id of the included class and name are returned.
Notes Only the included class of a compiled class can be obtained.
• OPC_E_CLS_NOTINC
A next included class specified by id does not exist.
The included class can not be obtained due to an internal error.


5.6.19 Obtain next object of a class
Syntax [status=] opc_cls_nobj(opc_c, obj_def)

struct opc_obj_def *obj_def; /* Object info */
Semantics opc_cls_nobj() is used to obtain the next object that has been instanced
from the class.
obj_def specifies the next object to obtain. The class id must be filled
in obj_def->cls_id. The object with the next higher id than specified
in obj_def->obj_id is returned. The first object derived from a class
is specified by filling obj_def->cls_id with the class id and filling
obj_def->cls_id with zeros.
On exit of the routine, the object id, object name, start and stop time and
other object characteristics are returned.
Notes Only objects of a compiled class can be obtained.
• OPC_E_OBJ_NOTEXI
A next object specified by id does not exist.
• OPC_E_OBJ_NOTGET
The objects can not be obtained due to an internal error.


5.6.20 Obtain next prompt of a class
Syntax [status=] opc_cls_npmt(opc_c, cls_pmt)

struct opc_cls_pmt *cls_pmt; /* Prompt info */
Semantics opc_cls_npmt() is used to obtain the next prompt defined in the class
source. The prompt with the next higher id than that specified is
returned.
cls_pmt specifies the next prompt to obtain. The prompt with the next
higher id than specified in cls_pmt->pmt_id is returned. The first
prompt in a class is specified by filling cls_pmt->pmt_id with the class
id.
On exit of the routine, the prompt id, the id of the associated attribute and
query text are returned.
Notes Only the prompt of a compiled class can be obtained.
• OPC_E_CLS_NOTPMT
A next prompt specified by id does not exist.
The prompts can not be obtained due to an internal error.


5.6.21 Obtain next signal of a class
Syntax [status=] opc_cls_nsig(opc_c, cls_sig)

struct opc_cls_sig *cls_sig; /* Signal info */
Semantics opc_cls_nsig() is used to obtain the next signal defined in the class
source. The signal with the next higher id than that specified is returned.
cls_sig specifies the next signal to obtain. The signal with the next
higher id than that specified in cls_sig->sig_id is returned. The first
signal in a class is specified by filling cls_sig->sig_id with the class
id.
On exit of the routine, the signal id and path are returned.
Notes Only the signal of a compiled class can be obtained.
• OPC_E_CLS_NOTSIG
A subsequent signal specified by id does not exist.
The signal can not be obtained due to an internal error.

• opc_cls_gsig()
Obtain in for the specified signal in a class.

5.6.22 Obtain next trigger group of a class
Syntax [status=] opc_cls_ntrg(opc_c, cls_trg_id)

Semantics opc_cls_ntrg() is used to obtain the next trigger group where the class is
inserted. The trigger group with the next higher id than that specified is
returned.
cls_trg_id specifies the next trigger to obtain. The id of the class must
be specified. The trigger group with the next higher id than that specified
in cls_trg_id->trg_id is returned. The first trigger group where the
class is inserted is specified by filling cls_trg_id->trg_id with zeros.
A next trigger group specified by id does not exist for the class.
The trigger group can not be obtained due to an internal error.

• opc_cls_itrg()
Insert class in a trigger group.
• opc_cls_dtrg()
Delete class from a trigger group.

5.6.23 Obtain info about a next class
Syntax [status=] opc_cls_nxt(opc_c, cls_def)

struct opc_cls_def *cls_def; /* Class to obtain */
Semantics opc_cls_nxt() is used to obtain info about the next class. The class with
the next higher id than that specified or with the next alphabetically
higher name than that specified is returned
cls_def defines the class from which to obtain info. The classes id,
modification and compilation are returned. Information for the first class
is returned by clearing cls_def->cls_id or filling cls_def->name
with the word “A”.
A class name specified contains invalid characters.

• opc_cls_get()
Obtain info about a class.
• opc_cls_lck()
Lock a class.

5.6.24 Reset a class
Syntax [status=] opc_cls_res(opc_c, cls_res)

struct opc_cls_res *cls_res; /* Class to reset */
Semantics opc_cls_res() is used to reset all objects derived from a class on a

specific BUS/FAST node.
cls_res defines the class and node to reset.
• OPC_E_M_NOCOM
There is currently no communication between the OPC host and the
specified BUS/FAST node.
• OPC_E_CLS_NOTRES
No reset is issued due to an internal error.


5.6.25 Trigger a class
Syntax [status=] opc_cls_trg(opc_c, cls_id)

struct opc_id *cls_id; /* Class to trigger */
Semantics opc_cls_trg() is used to trigger all objects derived from a class.

cls_id defines the class to trigger.
• OPC_E_CLS_NOTTRG
No trigger is issued due to an internal error.


5.6.26 View a class
Syntax [status=] opc_cls_view(opc_c, cls_def)

struct opc_cls_def *cls_def; /* Class to lock */
Semantics opc_cls_view() is used to obtain information about a class including its

source. The class source is returned in a specified or temporary file.
cls_def defines the class to view. The class to view is specified by
name or id. When the name is empty then the class id is used.
In cls_def->file a name of a file can be specified. OPC copies the
class source to this file. When the file name is empty, OPC creates a
temporary file and copies the class source to this file. The temporary file
is overwritten at the next call to opc_cls_lck() or opc_cls_view() and
deleted with a call to routine opc_detach(). The name of the temporary
file is returned in cls_def->file.
Besides the name of the file containing the class source, the class’s id,
modification and compilation are returned.
To obtain the source of a class for modification the routine opc_cls_lck()
can be used.

• opc_cls_lck()
To obtain the source of a class for modification purposes.

5.6.27 Detach from OPC
Syntax [status=] opc_detach(opc_c)

Semantics opc_detach() is used to detach from OPC.

Any temporary source or list file create by OPC will be deleted.
Errors • OPC_W_NOTATT
The client was not attached.

Attach to OPC.

5.6.28 Enable/disable object debugging
Syntax [status=] opc_obj_dbg(opc_c, obj_def)

struct opc_obj_def *obj_def; /* Object to enable-
disable debug*/
Semantics opc_obj_def() is used to enable or disable debugging of an object. When

enabled, trace information gathered during execution of the object is
output to a text file. When debug is disabled, the contents of the debug
output file can be examined.
obj_def defines the object for which debug must be enabled or
disabled. The object is specified by its name or id. The id is used when
obj_def->name.tag is empty. Debugging is enabled by setting the
obj_def->flags to OPC_OBJ_DEBUG_ON and entering in obj_def-
>file the file name, where OPC writes the debug info to. Only objects
executed on the OPC host can be debugged. Debug is disabled by setting
obj_def->flags to 0.
• OPC_E_OBJ_INVNAM
The specified object name contains invalid characters.
The object specified by name or id does not exist.
• OPC_E_OBJ_DBGNODE
The object is not located on the OPC host.
• OPC_E_OBJ_FILCRE
The specified output file can not be created.
• OPC_E_OBJ_NOTDBG
Debugging is not enabled/disabled due to an internal error.


5.6.29 Delete an object
Syntax [status=] opc_obj_del(opc_c, obj_def)

struct opc_obj_def *obj_def; /* Object to delete */
Semantics opc_obj_del() is used to delete all information about an object.

obj_def specifies the object to delete by name.
Notes To be able to recover a deleted object, first obtain object info by using
the opc_obj_get() and opc_atr_rd() calls.
The object does not exist.
• OPC_E_OBJ_NOTDEL
The object is not deleted due to an internal error.
• OPC_E_OBJ_NOTCDEL
The object is not completely deleted.

• opc_obj_ins()
Insert an object.
• opc_obj_mod()
Modify an object.

5.6.30 Delete an object from a trigger group
Syntax [status=] opc_obj_dtrg(opc_c, obj_trg_id)

struct opc_obj_trg_id *obj_trg_id;
/* Object/trigger group */
Semantics opc_obj_dtrg() is used to delete an object from a trigger group.

obj_trg_id specifies the object and the trigger group.
The object does not exist in the trigger group.
• OPC_E_OBJ_NOTDEL
The object is not deleted from the trigger group due to an internal
error.

• opc_obj_itrg()
Insert an object in a trigger group.
• opc_obj_ntrg()
Return object’s trigger group.

5.6.31 Obtain info about an object
Syntax [status=] opc_obj_get(opc_c, obj_def)

struct opc_obj_def *obj_def; /* Object to obtain */
Semantics opc_obj_get() is used to obtain info about an object. The object is

specified by id or name.
obj_def defines the object to obtain info about. The object’s id, name,
one-liner description, class id, node, priority, activation time window,
and time stamp of the last modification are returned.

• opc_obj_nxt()
Obtain info about the next object.

5.6.32 Insert an object
Syntax [status=] opc_obj_ins(opc_c, obj_def, attrs)

struct opc_obj_def *obj_def; /* Object to insert */
int attrs; /* Number of attributes */
Semantics opc_obj_ins() is used to insert an object.

obj_def defines the object to insert. The following fields must be
specified:
• name
The name for the object to insert.
• desc
• cls_id
The identification of the class to derive the object from.
• dii_id
The item id of the control item. Use the routine gin_dii_gidn() to
obtain the id of an item. Set the id to zero (by using the macro
GIN_DII_ID_CLEAR) when no control item is used.
• node
The BUS/FAST node number where the object must be executed.
When node is zero and dii_id is specified then the node of
dii_id is used, otherwise the OPC host is used.
• priority
The priority for the object. When zero is specified then the priority
of the class is used.
• start
The activation time of the activity time window.
• stop
The deactivation time of the activity time window.
• atr_val
A list of local attributes and attribute values to set. Normally the
prompted atrribute values are set here. The number of attributes
specified is one of the opc_obj_ins() arguments.
• flags
Defines whether items may already exist on object creation and
whether items are deleted on object deletion (see SubSection 2.4.2).

attrs contains the number of attributes specified in obj_def.
• OPC_E_OBJ_EXIST
The object name already exists.
• OPC_E_OBJ_NOTITM
The specified control item does not exist.
• OPC_E_OBJ_NOTINS
The object is not inserted due to an internal error.
• OPC_E_OBJ_INVPRIO
The specified priory is out of the range 0 to 999.
• OPC_E_OBJ_INVEND
The specified active window is invalid.
• OPC_E_OBJ_NOTCLS
The specified class does not exist.
The class to derive the object from is being modified by another
user.
• OPC_E_OBJ_NOTCOM
The class to derive the object from has not been compiled.

• opc_obj_mod()
Modify an object.
• opc_obj_del()
Delete an object.

5.6.33 Insert an object in a trigger group
Syntax [status=] opc_obj_itrg(opc_c, obj_trg_id)

Semantics opc_obj_itrg() is used to insert an object in a trigger group.

obj_trg_id specifies the object and the trigger group.
Notes When an object is placed in a trigger group, it is no longer triggered by

its class trigger groups.
The object specified by id does not exist.
The trigger group specified by id does not exist.
• OPC_E_TRG_EXIST
The object has already been inserted in the trigger group.
• OPC_E_OBJ_NOTINS
The object is not inserted in the trigger group due to an internal
error.

• opc_obj_dtrg()
Delete an object from a trigger group.
• opc_obj_ntrg()
Return object’s trigger group.

5.6.34 Modify an object
Syntax [status=] opc_obj_mod(opc_c, obj_def)

struct opc_obj_def *obj_def; /* Object to modify */
Semantics opc_obj_mod() is used to modify some parameters in an object. The

object one-liner description, priority and activity window can be
modified.
obj_def defines the object to modify. The object to modify is specified
by name or id. When obj_def->name.tag is empty then the object id
is used.
The field flags defines whether items are deleted on object deletion
(see SubSection 2.4.2).
The object name specified contains invalid characters.
• OPC_E_OBJ_NOTMOD
The object is not modified due to an internal error.
• OPC_E_OBJ_INVPRIO
The specified priory is out of the range 0 to 999.

• opc_obj_ins()
Insert an object.

5.6.35 Obtain next trigger group of an object
Syntax [status=] opc_obj_ntrg(opc_c, obj_trg_id)

Semantics opc_obj_ntrg() is used to obtain the next trigger group where the object
is inserted. The trigger group with the next higher id than that specified
is returned.
obj_trg_id specifies the next trigger to obtain. The id of the object
must be specified. The trigger group with the next higher id than that
specified in obj_trg_id->trg_id is returned. The first trigger group
where the object is inserted is specified by filling obj_trg_id-
>trg_id with zeros.
The next trigger group specified by id does not exist for the object.
The trigger group can not be obtained due to an internal error.

• opc_obj_itrg()
Insert object in a trigger group.
• opc_obj_dtrg()
Delete object from a trigger group.

5.6.36 Obtain info about a next object
Syntax [status=] opc_obj_nxt(opc_c, obj_def)

struct opc_obj_def *obj_def; /* Object to obtain */
Semantics opc_obj_nxt() is used to obtain info about the next object. The object
with the next higher id than that specified or with the next alphabetically
higher name than that specified is returned
obj_def defines the object to obtain info about. The object’s id, name,
one-liner description, class id, node, priority, activation time window,
and time stamp of the last modification are returned. Information for the
first object is returned by clearing obj_def->obj_id or filling
obj_def->name.tag with the word “A”.

• opc_obj_get()
Obtain info about an object.

5.6.37 Reset an object
Syntax [status=] opc_obj_res(opc_c, obj_id)

struct opc_id *obj_id; /* Class to reset */
Semantics opc_obj_res() is used to reset the object specified by id.

obj_id defines the object to reset.
• OPC_E_M_NOCOM
specified BUS/FAST node where the object is active.
• OPC_E_OBJ_NOTRES
No reset is issued due to an internal error.


5.6.38 Trigger an object
Syntax [status=] opc_obj_trg(opc_c, obj_id)

struct opc_id *obj_id; /* Object to trigger */
Semantics opc_obj_trg() is used to trigger the specified object.

obj_id defines the object to trigger.
• OPC_E_M_NOCOM
specified BUS/FAST node where the object is active.
• OPC_E_OBJ_NOTTRG
No trigger is issued due to an internal error.


5.6.39 Open a data source monitoring channel
Syntax evt_ctxt= opc_opn_evt(opc_c, data_source, msg_id)
Arguments struct opc_evt_context evt_ctxt;/*event channel */

int data_source; /* source to monitor */
int msg_id; /* ID for event message */
Semantics opc_opn_evt() is used to initialize a channel for monitoring a data

source.
data_source identifies which source is to be monitored and can be one
of:
• OPC_EVT_CLS to monitor classes
• OPC_EVT_OBJ to monitor objects
• OPC_EVT_TRG to monitor trigger groups
• OPC_EVT_ATR to monitor attributes
msg_id defines the message ID to be used for the event messages.
The event channel that is returned should be used in calls to all
subsequent data source monitoring routines for this source.
Once a channel has been opened, opc_set_evt() should be used to define
the actions on the source that the application is interested in receiving.
Errors • Returns NULL pointer in case the event channel could not be
allocated.

• opc_set_evt()
Set event requests on an open channel.
• opc_cls_evt()
Close an open channel.

5.6.40 Set/clear events on a monitoring channel
Syntax [stat=] opc_set_evt(evt_ctxt, mode, ref_id, rec_id,

rec_name)
Arguments TLS_BOOLEAN stat; /* TRUE on success */

struct opc_evt_context *evt_ctxt;/* Event channel */
int mode; /* Subscription mode */
int ref_id; /* Reference number */
struct opc_id *rec_id; /* Record to monitor */
char *rec_name; /* Record to monitor */
Semantics opc_set_evt() is used to indicate which events on the specified channel
the application is interested in receiving. Events can be requested on the
data source in general or for a specific record
evt_ctxt is the event channel obtained from a call to the
opc_opn_evt() routine.
mode indicates which events on the data source to subscribe to and is a
combination of one or more of the following flags:
• OPC_CRI_GET
A record has been read from the data source.
• OPC_CRI_INS
A record has been inserted into the data source.
• OPC_CRI_MOD
A record has been modified.
• OPC_CRI_DEL
A record has been deleted.
• OPC_CRI_GET_RECORD
Monitor if a specific record has been read.
• OPC_CRI_MOD_RECORD
Monitor if a specific record has been modified.
• OPC_CRI_DEL_RECORD
Monitor if a specific record has been deleted.
• OPC_INF_INITIATOR
Send the initiator of the event along with the event message.
• OPC_INF_IDENTIFIER
Send the record id along with the event message.
ref_id defines a unique number that is returned in the event message to
distinguish it from other events.
rec_id is the record id of an existing record in the data source that has
been obtained by a call to a data source read routine. This is used in

combination with one of the OPC_CRI_*_RECORD mode flags in

order to monitor a specific record.
rec_name performs the same function as rec_id, only the record to
monitor is specified by name. If rec_id is used then rec_name should
be NULL.
Events are set by indicating the necessary flags in mode. To set events
on a particular record, the record must be indicated by either rec_id or
rec_name. To unsubscribe, call this routine and clear the necessary flags
in mode. To unsubscribe to a particular record, the record must also be
specified in either rec_id or rec_name.
Errors • OPC_E_EVT_NOTEXI
The specified event channel does not exist.
• OPC_E_*_INVNAM
Invalid name supplied for record.
• OPC_E_*_NOTEXI
Specified record does not exist.
Specified attribute not found.

• opc_opn_evt()
Open an event monitoring channel on a data source.
• opc_cls_evt()
Close an open channel.

5.6.41 Obtain the item id of a signal
Syntax [status=] opc_sig_rd(opc_c, sig_upd)

struct opc_sig_upd *sig_upd; /* Signal to obtain */
Semantics opc_sig_rd() is used to obtain the id of the item associated with a signal
in an object.
sig_upd specifies the signal to obtain. On entry the field sig_upd-
>obj_id contains the object id whose signal has to be obtained. Field
sig_upd->sig_id contains the signal id to obtain. On return of the
routine, field sig_upd->dii_id contains the id of the associated item.
• OPC_E_SIG_NOTEXI
The specified signal does not exist.
• OPC_E_SIG_NOTGET
Failed to obtain the item id of the signal.

• opc_cls_gsig() and opc_cls_nsig()
Return signal id in a class.

5.6.42 Delete a trigger group
Syntax [status=] opc_trg_del(opc_c, trg_def)

struct opc_trg_def *trg_def; /* Trigger group to delete
*/
Semantics opc_trg_del() is used to delete all information about a trigger group.

Trigger groups not containing objects or classes can be deleted.
trg_def specifies the trigger group to delete by name.
Notes To be able to recover a deleted trigger, first obtain trigger group info by
the opc_trg_get() call.
• OPC_E_TRG_INVNAM
The specified trigger group name contains invalid characters.
The trigger group does not exist.
• OPC_E_TRG_ACTOBJ
Objects are inserted in the trigger group.
• OPC_E_TRG_ACTCLS
Classes are inserted in the trigger group.
• OPC_E_TRG_NOTDEL
The trigger group is not deleted due to an internal error.

• opc_trg_ins()
Insert a trigger group.
• opc_trg_mod()
Modify a trigger group.

5.6.43 Obtain info about a trigger group
Syntax [status=] opc_trg_get(opc_c, trg_def)

struct opc_trg_def *trg_def; /* Trigger group to obtain
*/
Semantics opc_trg_get() is used to obtain info about a trigger group. The trigger
group is specified by id or name.
trg_def defines the trigger group from which to obtain info. The trigger
group’s id, name, one-liner description, active time window, interval,
GMT flag and time stamp of the last modification are returned.
The trigger group specified by name or id does not exist.
• OPC_E_TRG_NOTGET

• opc_trg_nxt()
Obtain info about the next trigger group.

5.6.44 Insert a trigger group
Syntax [status=] opc_trg_ins(opc_c, trg_def)

struct opc_trg_def *trg_def; /* Trigger group to insert
*/
Semantics opc_trg_ins() is used to insert a trigger group.

trg_def defines the trigger group to insert. The following fields must
be specified:
• name
The name of the trigger group to insert.
• desc
• interval
The interval for the trigger group.
• start
The activation time of the activity time window.
• stop
The deactivation time of the activity time window.
• gmt
The GMT/LCT flag.
• OPC_E_TRG_EXIST
The trigger group name already exists.
• OPC_E_TRG_NOTINS
The trigger group is not inserted due to an internal error.
• OPC_E_TRG_INVEND
The specified time window is invalid.

• opc_trg_mod()
Modify a trigger group.

• opc_trg_del()
Delete a trigger group.

5.6.45 Modify a trigger group
Syntax [status=] opc_trg_mod(opc_c, trg_def)

struct opc_trg_def *trg_def; /* Trigger group to modify
*/
Semantics opc_trg_mod() is used to modify some parameters in a trigger group.

The trigger group one-liner description, interval, activity window and
GMT/LCT flag can be modified.
trg_def defines the trigger group to modify. The trigger group to
modify is specified by name or id. When trg_def->name is empty then
the trigger group id is used.
• OPC_E_TRG_NOTMOD
The trigger group is not modified due to an internal error.
• OPC_E_TRG_INVEND
The specified time window is invalid.

• opc_trg_ins()
Insert a trigger group.

Reference Support functions
5.6.46 Obtain info about a next trigger group
Syntax [status=] opc_trg_nxt(opc_c, trg_def)

struct opc_trg_def *trg_def; /* Trigger group to obtain
*/
Semantics opc_trg_nxt() is used to obtain info about the next trigger group. The
trigger group with the next higher id than specified or with the next
alphabetically higher name than that is specified is returned.
trg_def defines the trigger group from which to obtain info. The trigger
group’s id, name, one-liner description, active time window, interval,
GMT flag and time stamp of the last modification are returned.
• OPC_E_TRG_NOTGET

• opc_trg_get()
Obtain info about a trigger group.
5.7 Support functions
5.7.1 Introduction
In this section describes the OPC support functions. The support

functions are used to create PROCESS/FAST language callable
functions written in the ‘C’ language.

Support functions Reference
For each support function a description is given of the following:

• its syntax
• its parameters
• its semantics
• other related support functions

5.7.2 Start the body section of a function specification
Syntax OPC_BODY
Arguments none
Semantics OPC_BODY starts the executable statements section in a function

specification.
Errors none
Related • OPC_FUNCTION
functions Starts a function specification.
• OPC_DECLARATION
Start the declaration section in a function specification.
• OPC_END_FUNCTION
Ends a function specification.

5.7.3 Start the declaration section of a function

specification
Syntax OPC_DECLARATION
Arguments none
Semantics OPC_DECLARATION starts the declaration section in a function

specification.
Errors none
• OPC_BODY
Start the executable statements in a function specification.

5.7.4 Declare a function
Syntax OPC_DECLARE(entry_point)
Arguments OPC_FNC entry_point; /* Function entry point */
Semantics OPC_DECLARE declares the entry point in a function. It is used to

declare the functions within the function declaration section in the file
‘opc_usr.c’.
Errors none
Related • OPC_FUNCTION_DECLARATION
functions Starts the function declaration section.
• OPC_END_FUNCTION_DECLARATION
Ends the function declaration section.

5.7.5 Define a function
Syntax OPC_DEFINE(name, entry_point, source, ret_rep, arg_rep)
Arguments char *name; /* Function name */

OPC_FNC entry_point; /* Function entry point */
char *source; /* Source file name */
int ret_rep; /* Return value
representation */
int arg_rep; /* List of argument
representations */
Semantics OPC_DEFINE defines a function. It is used to define the functions

within the function definition section in the file ‘opc_usr.c’.
name is the name of the function as known in the PROCESS/FAST
language. It must be an uppercase string starting with a letter followed
by letters, digits or underscores.
entry_point is the function’s entry point within the function
specification.
source is the name of the source file (located on the FAST/TOOLS
source directory) where the function specification is stored. More than
one function can be stored in a single source file.
ret_rep defines the representation of function return value. It is one of:
Value Description
OPC_REP_INTEGER Function returns an integer

OPC_REP_TLS_FLO Function returns a float
AT
OPC_REP_STRING Function returns a string
OPC_REP_VOID Function does not return a value
arg_rep defines the representations of the function arguments. Ten

arguments must be specified in the following way:
#define MY_ARGS OPC_REP_STRING, OPC_REP_INTEGER, \
OPC_REP_VOID, OPC_REP_VOID, \
OPC_REP_VOID, OPC_REP_VOID
OPC_DEFINE("MY_FUNCTION", my_function, "my_source",
OPC_REP_INTEGER, MY_ARGS)

This example specifies that the function has two arguments, a string and
an integer. The following argument representations can be used:
Value Description
OPC_REP_INTEGER Argument must be an integer (expression, value)

OPC_REP_FLOAT Argument must be a float (expression, value)
OPC_REP_STRING Argument must be a string (expression, value)
OPC_REP_VOID No argument
OPC_TYPE_TIMER Argument must by a timer identifier
OPC_TYPE_GLOBAL_ Argument must be a global attribute identifier
ATTRIBUTE
OPC_TYPE_LOCAL_ Argument must be a local attribute identifier
ATTRIBUTE
OPC_TYPE_SIGNAL Argument must be a signal identifier
OPC_TYPE_ALARM Argument must be an alarm identifier
Errors none
Related • OPC_FUNCTION_DEFINITION
functions Starts the function definition section.
• OPC_END_FUNCTION_DEFINITION
Ends the function definition section.

5.7.6 Obtain DUR context
Syntax OPC_DUR_CONTEXT
Arguments none
Semantics OPC_DUR_CONTEXT obtains the DUR context which is used in calls

to DUR that send BUS/FAST messages, for example:
dur_snd_rep(OPC_DUR_CONTEXT, OPC_UMH_CONTEXT, &par_snd);
Notes The OPC_DUR_CONTEXT is used within the executable statements

section of the function specification only.
Errors none
Related • OPC_UMH_CONTEXT
functions Obtains the UMH context.

5.7.7 End function specification
Syntax OPC_END_FUNCTION
Arguments none
Semantics OPC_END_FUNCTION ends a function specification. This function

also ends the executable statements. It lets the function exit successfully
when no OPC_ERROR() is called. When OPC_ERROR() is called the
function exits with an error. In the latter case the execution of the object
is terminated and the error is reported to the standard UMH error logger,
when the object’s body is executing, or, returned to user, when the
object’s prolog is executing.
Errors none
• OPC_DECLARATION
Start the declaration section of a function specification.
• OPC_BODY
Start the executable statements of a function specification.

5.7.8 End function declaration section
Syntax OPC_END_FUNCTION_DECLARATION
Arguments none
Semantics OPC_END_FUNCTION_DECLARATION ends the function

declaration section in the file ‘opc_usr.c’.
Errors none
Related • OPC_DECLARE
functions Declares a function.
• OPC_FUNCTION_DECLARATION
Starts the function declaration section.

5.7.9 End function definition section
Syntax OPC_END_FUNCTION_DEFINITION
Arguments none
Semantics OPC_END_FUNCTION_DEFINITION ends the function definition

section in the file ‘opc_usr.c’.
Errors none
Related • OPC_DEFINE
functions Defines a function.
• OPC_FUNCTION_DEFINITION
Starts the function definition section.

5.7.10 Signal and set an error
Syntax OPC_ERROR(error)
Arguments char *error; /* Error text */
Semantics OPC_ERROR signals and sets an error text. The function does not exit.
error is the error text set. A NULL pointer only signals an error without
setting the error. In this case umh_set_code() must be used to set the
error condition.
Notes The OPC_ERROR is used within the executable statements section of

the function specification only.
Errors none
Related • OPC_EXIT
functions Exits the function.

5.7.11 Signal error and exit
Syntax OPC_ERROR_EXIT
Arguments none
Semantics OPC_ERROR_EXIT signals an error and exits the function. It is used to

exit the routine from within if, for, while, etc. statements. Prior to the
OPC_ERROR_EXIT function umh_set_code() must be called to set the
error message causing the error condition.
Notes The OPC_ERROR_EXIT is used within the executable statements

Errors none
Related • OPC_ERROR
functions Signals and sets an error.

5.7.12 Exit function
Syntax OPC_EXIT
Arguments none
Semantics OPC_EXIT exits the function. It is used to exit the routine from within
if, for, while, etc. statements. When no OPC_ERROR function is
executed prior to the OPC_EXIT then success is returned.
Notes The OPC_EXIT is used within the executable statements section of the
function specification only.
Errors none
functions Signals and sets an error.

5.7.13 Start function specification
Syntax OPC_FUNCTION(entry_point)
Arguments OPC_FNC entry_point; /* Function entry point */
Semantics The source file function specification OPC_FUNCTION starts the

function pointed to in the function definition file
A function specification has the following layout:

OPC_FUNCTION(entry_point)
OPC_DECLARATION
/* Declaration section */
OPC_BODY
/* Executable statements */
OPC_END_FUNCTION
Errors none
Related • OPC_DECLARATION
functions Starts the declaration section of a function specification.
• OPC_BODY
Start the executable statements of a function specification.

5.7.14 Start function declaration section
Syntax OPC_FUNCTION_DECLARATION
Arguments none
Semantics OPC_FUNCTION_DECLARATION starts the function declaration

section in the file ‘opc_usr.c’.
Errors none
Related • OPC_DECLARE
functions Declares a function.
• OPC_END_FUNCTION_DECLARATION
Ends the function declaration section.

5.7.15 Start function definition section
Syntax OPC_FUNCTION_DEFINITION
Arguments none
Semantics OPC_FUNCTION_DEFINITION starts the function definition section

in the file ‘opc_usr.c’.
Errors none
Related • OPC_DEFINE
functions Defines a function.
• OPC_END_FUNCTION_DEFINITION
Ends the function definition section.

5.7.16 Get alarm argument priority
Syntax OPC_GET_ALARM_PRIORITY(argument, priority)
Arguments int argument; /* Argument number */

OPC_INTEGER priority; /* Obtained priority */
Semantics OPC_GET_ALARM_PRIORITY obtains the priority of an alarm

argument. Note that this priority must not be confused with the priority
of the alarm in the alarm overviews.
argument specifies the argument whose value is obtained. The
argument index is in the range 0-9 inclusive.
priority receives the alarm argument priority.
Notes • The OPC_GET_ALARM_PRIORITY function must be used for
arguments which have the representation of OPC_TYPE_ALARM.
• The OPC_GET_ALARM_PRIORITY is used within the
executable statements section of the function specification only.
Errors none
Related • OPC_GET_ALARM_VALUE
functions Gets alarm argument value.
• OPC_SET_ALARM_VALUE
Sets alarm argument value.
• OPC_GET_ALARM_STATUS
Gets alarm argument status.
• OPC_SET_ALARM_STATUS
Sets alarm argument status.
• OPC_SET_ALARM_PRIORITY
Sets alarm argument priority.

5.7.17 Get alarm argument status
Syntax OPC_GET_ALARM_STATUS(argument, priority)

OPC_INTEGER status; /* Obtained status */
Semantics OPC_GET_ALARM_STATUS obtains the status of an alarm argument.

argument specifies the argument whose status is obtained. The
status receives the alarm argument status which is one of:
Status Description
NORMAL The alarm is not active and has been removed from
the alarm overview(s) or never been set at all.
A1 The alarm is active (presentation according to A1
definition)
definition)
definition)
ACKNOWLEDGED The alarm is still presented but has been acknowl-
edged by the operator.
Notes • The OPC_GET_ALARM_STATUS function must be used for

• The OPC_GET_ALARM_STATUS is used within the executable
statements section of the function specification only.
Errors none
• OPC_GET_ALARM_PRIORITY
Gets alarm argument priority.


5.7.18 Get alarm argument value
Syntax OPC_GET_ALARM_VALUE(argument, value)

OPC_STRING *value; /* Obtained value */
Semantics OPC_GET_ALARM_VALUE obtains the value of an alarm argument

value.
value receives the pointer to the string. It is not allowed to modify the
string that value is pointing to. When the string has to be modified, a
copy must be made from the string. This copy can be modified:
...
OPC_STRING *value;
OPC_STRING temp[OPC_MAX_STR_SZ+2];
...
OPC_GET_STRING(0, value);
strcpy(temp, value);
...
Notes • The OPC_GET_ALARM_VALUE function must be used for

• The OPC_GET_ALARM_VALUE is used within the executable
Errors none
Related • OPC_SET_ALARM_VALUE
functions Sets alarm argument value.

5.7.19 Get float argument value
Syntax OPC_GET_FLOAT(argument, value)

OPC_FLOAT value; /* Obtained value */
Semantics OPC_GET_FLOAT obtains the value of a float argument.

value receives the float argument value.
Notes • The OPC_GET_FLOAT function must be used for arguments

which have the representation of OPC_REP_FLOAT.
• The OPC_GET_FLOAT is used within the executable statements
Errors none
Related • OPC_GET_INTEGER
functions Gets integer argument value.
• OPC_GET_STRING
Gets string argument value.

5.7.20 Get float global attribute argument value
Syntax OPC_GET_FLOAT_GLOBAL_ATTRIBUTE(argument, value)

Semantics OPC_GET_FLOAT_GLOBAL_ATTRIBUTE obtains the value of a

global attribute with a float representation.
value receives the float global attribute argument value.
Notes • The OPC_GET_FLOAT_GLOBAL_ATTRIBUTE function must

be used for arguments which have the representation of
OPC_TYPE_GLOBAL_ATTRIBUTE.
• The OPC_GET_FLOAT_GLOBAL_ATTRIBUTE is used within
the executable statements section of the function specification only.
Errors none
Related • OPC_GET_INTEGER_GLOBAL_ATTRIBUTE
functions Gets integer global attribute argument value.
• OPC_GET_STRING_GLOBAL_ATTRIBUTE
Gets string global attribute argument value.
• OPC_GET_INTEGER_LOCAL_ATTRIBUTE
Gets integer local attribute argument value.
• OPC_GET_FLOAT_LOCAL_ATTRIBUTE
Gets float local attribute argument value.
• OPC_GET_STRING_LOCAL_ATTRIBUTE
Gets string local attribute argument value.

5.7.21 Get float local attribute argument value
Syntax OPC_GET_FLOAT_LOCAL_ATTRIBUTE(argument, value)

Semantics OPC_GET_FLOAT_LOCAL_ATTRIBUTE obtains the value of a

local attribute with the float representation.
value receives the float local attribute argument value.
Notes • The OPC_GET_FLOAT_LOCAL_ATTRIBUTE function must be

used for arguments which have the representation of
OPC_TYPE_LOCAL_ATTRIBUTE.
• The OPC_GET_FLOAT_LOCAL_ATTRIBUTE is used within
Errors none
Related • OPC_GET_INTEGER_LOCAL_ATTRIBUTE
functions Gets integer local attribute argument value.
• OPC_GET_INTEGER_GLOBAL_ATTRIBUTE
Gets integer global attribute argument value.
• OPC_GET_FLOAT_GLOBAL_ATTRIBUTE
Gets float global attribute argument value.

5.7.22 Get integer argument value
Syntax OPC_GET_INTEGER(argument, value)

OPC_INTEGER value; /* Obtained value */
Semantics OPC_GET_INTEGER obtains the value of an integer argument.

value receives the integer argument value.
Notes • The OPC_GET_INTEGER function must be used for arguments

which have the representation of OPC_REP_INTEGER.
• The OPC_GET_INTEGER is used within the executable
Errors none
Related • OPC_GET_FLOAT
functions Gets float argument value.
• OPC_GET_STRING
Gets string argument value.

5.7.23 Get integer global attribute argument value
Syntax OPC_GET_INTEGER_GLOBAL_ATTRIBUTE(argument, value)

Semantics OPC_GET_INTEGER_GLOBAL_ATTRIBUTE obtains the value of a

global attribute with the integer representation.
value receives the integer global attribute argument value.
Notes • The OPC_GET_INTEGER_GLOBAL_ATTRIBUTE function

must be used for arguments which have the representation of
• The OPC_GET_INTEGER_GLOBAL_ATTRIBUTE is used
within the executable statements section of the function
specification only.
Errors none
Related • OPC_GET_FLOAT_GLOBAL_ATTRIBUTE
functions Gets float global attribute argument value.

5.7.24 Get integer local attribute argument value
Syntax OPC_GET_INTEGER_LOCAL_ATTRIBUTE(argument, value)

Semantics OPC_GET_INTEGER_LOCAL_ATTRIBUTE obtains the value of a

local attribute with the integer representation.
value receives the float local attribute argument value.
Notes • The OPC_GET_INTEGER_LOCAL_ATTRIBUTE function must

• The OPC_GET_INTEGER_LOCAL_ATTRIBUTE is used within
Errors none
Related • OPC_GET_FLOAT_LOCAL_ATTRIBUTE
functions Gets float local attribute argument value.

5.7.25 Get signal argument alarm acknowledge
Syntax OPC_GET_SIGNAL_ACKNOWLEDGED(argument, alarm)

OPC_INTEGER alarm; /* Obtained alarm
acknowledge */
Semantics OPC_GET_SIGNAL_ACKNOWLEDGE obtains the alarm

acknowledge of the item associated with a signal argument.
alarm receives the alarm acknowledge from an item. It returns TRUE
when the alarm has been acknowledged. When the item triggers at least
one object (via a signal) the alarm acknowledge is stored within OPC on
an event basis. In this case the support function is very fast. Otherwise
the support function accesses ITM to retrieve the alarm acknowledge.
Notes • The OPC_GET_SIGNAL_ACKNOWLEDGE function must be

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_ACKNOWLEDGE is used within the
Errors none
Related • OPC_GET_SIGNAL_OPTION_STATUS
functions Gets signal argument option status.
• OPC_GET_SIGNAL_STATUS
Gets signal argument status.
• OPC_GET_SIGNAL_CONTROL_STATUS
Gets signal argument control status.
• OPC_GET_SIGNAL_MERGED_STATUS
Gets signal argument merged status.
• OPC_GET_SIGNAL_ALARM_TYPE
Gets signal argument alarm type.

5.7.26 Get signal argument alarm type
Syntax OPC_GET_SIGNAL_ALARM_TYPE(argument, alarm)

OPC_INTEGER alarm; /* Obtained alarm
type */
Semantics OPC_GET_SIGNAL_ALARM_TYPE obtains the alarm type of the

item associated with a signal argument.
alarm receives the alarm type from the item. When the item triggers at
least one object (via a signal) the alarm is stored within OPC on an event
basis. In this case the support function is very fast. Otherwise the support
function accesses ITM to retrieve the alarm type. The returned alarm
type is one of:
Alarm type Description
OPC_NORMAL Item is not in alarm

OPC_DIRECT Item is in alarm. However, it is not an alarm situation.
OPC_ALARM Item is in alarm.
Notes • The OPC_GET_SIGNAL_ALARM_TYPE function must be used

for arguments which have the representation of
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_ALARM_TYPE is used within the
Errors none

• OPC_GET_SIGNAL_ACKNOWLEDGED
Gets signal argument alarm acknowledge.

5.7.27 Get signal argument application flag
Syntax OPC_GET_SIGNAL_APPLICATION_FLAG(argument, flag)

OPC_INTEGER flag; /* Obtained item
application flag */
Semantics OPC_GET_SIGNAL_APPLICATION_FLAG obtains the application

flag from the item associated with a signal argument.
flag receives the application flag.
Notes • The OPC_GET_SIGNAL_APPLICATION_FLAG function must

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_APPLICATION_FLAG is used within
Errors none
Related none
functions

5.7.28 Get signal argument application info
Syntax OPC_GET_SIGNAL_APPLICATION_INFO(argument, index, value)

int index; /* Array index */
OPC_INTEGER value; /* Obtained item
application info */
Semantics OPC_GET_SIGNAL_APPLICATION_INFO obtains one element

from the application info of the item that is associated with a signal
argument.
index specifies which array index in the application info element to
obtain. When zero is specified the application info is obtained from
ITM, stored within OPC and the first element (element zero) is returned.
When the index is greater than zero, the specified element is obtained
from the information stored within OPC.
value receives the specified application info element of the item.
Notes • The OPC_GET_SIGNAL_APPLICATION_INFO function must

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_APPLICATION_INFO is used within
Errors none
Related • OPC_GET_SIGNAL_APPLICATION_SIZE
functions Gets signal argument application info size.

5.7.29 Get signal argument application info size
Syntax OPC_GET_SIGNAL_APPLICATION_SIZE(argument, size)

OPC_INTEGER size; /* Obtained item
application info size
*/
Semantics OPC_GET_SIGNAL_APPLICATION_SIZE obtains the size of the

application info for the item associated with a signal argument.
argument specifies which argument whose value is obtained. The
size receives the size of the application info (in elements). In addition
the application info itself is also obtained from ITM and stored within
OPC. The application info is accessed by the
OPC_GET_SIGNAL_APPLICATION_INFO support function.
Notes • The OPC_GET_SIGNAL_APPLICATION_SIZE function must

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_APPLICATION_SIZE is used within
Errors none
Related • OPC_GET_SIGNAL_APPLICATION_INFO
functions Gets signal argument application info.

5.7.30 Get signal argument control status
Syntax OPC_GET_SIGNAL_CONTROL_STATUS(argument, status)

OPC_INTEGER status; /* Obtained item
control status */
Semantics OPC_GET_SIGNAL_CONTROL_STATUS obtains the control status

of the item associated with a signal argument.
status receives the control status form the item. The control status is
TRUE when the item is not blocked and FALSE when the item is
blocked. When the item triggers at least one object (via a signal) the
control status is stored within OPC on an event basis. In this case the
support function is very fast. Otherwise the support function accesses
ITM to retrieve the control status.
Notes • The OPC_GET_SIGNAL_CONTROL_STATUS function must be

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_CONTROL_STATUS is used within
Errors none

5.7.31 Get signal argument deadband
Syntax OPC_GET_SIGNAL_DEADBAND(argument, deadband)

OPC_FLOAT deadband; /* Obtained item
deadband */
Semantics OPC_GET_SIGNAL_DEADBAND obtains the deadband from the

argument specifies the argument. The argument index is in the range 0-
9 inclusive.
deadband receives the deadband of the item. When the item triggers at
least one object (via a signal triggered by limit change) the deadband is
stored within OPC on an event basis. In this case the support function is
very fast. Otherwise the support function accesses ITM to retrieve the
deadband.
Notes • The deadband is converted from the item’s representation to

OPC_FLOAT.
• The OPC_GET_SIGNAL_DEADBAND function must be used for
arguments which have the representation of
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_DEADBAND is used within the
Errors none
Related • OPC_GET_SIGNAL_HIGH_HIGH_LIMIT
functions Gets signal argument high high limit.
• OPC_GET_SIGNAL_HIGH_LIMIT
Gets signal argument high limit.
• OPC_GET_SIGNAL_LOW_LIMIT
Gets signal argument low limit.
• OPC_GET_SIGNAL_LOW_LOW_LIMIT
Gets signal argument low low limit.

5.7.32 Get signal argument float array value
Syntax OPC_GET_SIGNAL_FLOAT_ARRAY(argument, index, value)

OPC_FLOAT value; /* Obtained item
value */
Semantics OPC_GET_SIGNAL_FLOAT_ARRAY obtains the value from the

array item associated with a signal argument.
index specifies which array index of the array item to obtain. When -1
is specified, the oldest element is returned.
value receives the array value of the item. The value is obtained by
accessing ITM.
Notes • The value is converted from the item’s representation to

OPC_FLOAT.
• The OPC_GET_SIGNAL_FLOAT_ARRAY function must be
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_FLOAT_ARRAY is used within the
Errors none
Related • OPC_GET_SIGNAL_INTEGER_ARRAY
functions Gets signal argument integer array value.

5.7.33 Get signal argument float old value
Syntax OPC_GET_SIGNAL_FLOAT_OLD_VALUE(argument, value)

value */
Semantics OPC_GET_SIGNAL_FLOAT_OLD_VALUE obtains the previous

value of the item associated with a signal argument.
argument specifies which argument to obtain. The argument index is in
the range 0-9 inclusive.
value receives the previous value of the item when the item triggers at
least one object (via a signal). Otherwise the support function returns the
current value by accessing ITM.

OPC_FLOAT.
• The OPC_GET_SIGNAL_FLOAT_OLD_VALUE function must
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_FLOAT_OLD_VALUE is used within
Errors none
Related • OPC_GET_SIGNAL_INTEGER_OLD_VALUE
functions Gets signal argument integer old value.
• OPC_GET_SIGNAL_STRING_OLD_VALUE
Gets signal argument string old value.

5.7.34 Get signal argument float value
Syntax OPC_GET_SIGNAL_FLOAT_VALUE(argument, value)

value */
Semantics OPC_GET_SIGNAL_FLOAT_VALUE obtains the value of the item

associated with a signal argument.
value receives the value from the item. When the item triggers at least
one object (via a signal) the value is stored within OPC on an event
basis. In this case the support function is very fast. Otherwise the support
function accesses ITM to retrieve the value.

OPC_FLOAT.
• The OPC_GET_SIGNAL_FLOAT_VALUE function must be
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_FLOAT_VALUE is used within the
Errors none
Related • OPC_GET_SIGNAL_INTEGER_VALUE
functions Gets signal argument integer value.
• OPC_GET_SIGNAL_STRING_VALUE
Gets signal argument string value.

5.7.35 Get signal argument high limit
Syntax OPC_GET_SIGNAL_HIGH_LIMIT(argument, limit)

OPC_FLOAT limit; /* Obtained item
limit */
Semantics OPC_GET_SIGNAL_HIGH_LIMIT obtains the high limit of the item

limit receives the limit of the item. When the item triggers at least one
object (via a signal triggered by limit change) the limit is stored within
OPC on an event basis. In this case the support function is very fast.
Otherwise the support function accesses ITM to retrieve the limit.
Notes • The limit is converted from the item’s representation to

OPC_FLOAT.
• The OPC_GET_SIGNAL_HIGH_LIMIT function must be used
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_HIGH_LIMIT is used within the
Errors none
• OPC_GET_SIGNAL_DEADBAND
Gets signal argument deadband.

5.7.36 Get signal argument high high limit
Syntax OPC_GET_SIGNAL_HIGH_HIGH_LIMIT(argument, limit)

limit */
Semantics OPC_GET_SIGNAL_HIGH_HIGH_LIMIT obtains the high high limit


OPC_FLOAT.
• The OPC_GET_SIGNAL_HIGH_HIGH_LIMIT function must be
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_HIGH_HIGH_LIMIT is used within the
Errors none
Related • OPC_GET_SIGNAL_HIGH_LIMIT
functions Gets signal argument high limit.

5.7.37 Get signal argument item id
Syntax OPC_GET_SIGNAL_ID(argument, dii_id)

struct gin_dii_id dii_id; /* Obtained item id */
Semantics OPC_GET_SIGNAL_ID obtains the item_id of the item associated with

a signal argument.
dii_id receives the signal item id.
Notes • The OPC_GET_SIGNAL_ID function must be used for arguments

which have the representation of OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_ID is used within the executable
Errors none
Related • OPC_GET_SIGNAL_ID_NODE
functions Gets signal argument item id node.
• OPC_GET_SIGNAL_ID_GROUP
Gets signal argument item id group.
• OPC_GET_SIGNAL_ID_NUMBER
Gets signal argument item id number.
• OPC_GET_SIGNAL_ID_SUB
Gets signal argument item id sub number.

5.7.38 Get signal argument item id group
Syntax OPC_GET_SIGNAL_ID_GROUP(argument, group)

OPC_INTEGER group; /* Obtained item id
group */
Semantics OPC_GET_SIGNAL_ID_GROUP obtains the group field of the item id

group receives the group field of the signal item id.
Notes • The OPC_GET_SIGNAL_ID_GROUP function must be used for

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_ID_GROUP is used within the
Errors none
Related • OPC_GET_SIGNAL_ID
functions Gets signal argument item id.
• OPC_GET_SIGNAL_ID_NODE
Gets signal argument item id node.

5.7.39 Get signal argument item id node
Syntax OPC_GET_SIGNAL_ID_NODE(argument, node)

OPC_INTEGER node; /* Obtained item id node
*/
Semantics OPC_GET_SIGNAL_ID_NODE obtains the node field of the item id of

the item associated with a signal argument.
node receives the node field of the signal item id.
Notes • The OPC_GET_SIGNAL_ID_NODE function must be used for

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_ID_NODE is used within the executable
Errors none

5.7.40 Get signal argument item id number
Syntax OPC_GET_SIGNAL_ID_NUMBER(argument, number)

OPC_INTEGER number; /* Obtained item id
number */
Semantics OPC_GET_SIGNAL_ID_NUMBER obtains the number field of the

item id of the item associated with a signal argument.
number receives the number field of the signal item id.
Notes • The OPC_GET_SIGNAL_ID_NUMBER function must be used

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_ID_NUMBER is used within the
Errors none

5.7.41 Get signal argument item id sub
Syntax OPC_GET_SIGNAL_ID_SUB(argument, sub)

OPC_INTEGER sub; /* Obtained item id
sub */
Semantics OPC_GET_SIGNAL_ID_SUB obtains the sub number field of the item

id of the item associated with a signal argument.
sub receives the sub number field of the signal item id. For main items
this sub number is zero.
Notes • The OPC_GET_SIGNAL_ID_SUB function must be used for

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_ID_SUB is used within the executable
Errors none

5.7.42 Get signal argument installation name
Syntax OPC_GET_SIGNAL_INSTALLATION(argument, installation)

OPC_STRING *installation; /* Obtained item
installation name*/
Semantics OPC_GET_SIGNAL_INSTALLATION obtains the installation name

of the item associated with a signal argument. From R10.01 this
function will return all first level sections.
installation receives the installation name of the item. It is not
allowed to modify the string that installation is pointing to. When
the string has to be modified, a copy must be made from the string.
Notes • The OPC_GET_SIGNAL_INSTALLATION function must be

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_INSTALLATION is used within the
Errors none
Related • OPC_GET_SIGNAL_UNIT
functions Gets signal argument unit name.
• OPC_GET_SIGNAL_TAG
Gets signal argument tag name.
• OPC_GET_SIGNAL_SUB
Gets signal argument sub name.

5.7.43 Get signal argument integer array value
Syntax OPC_GET_SIGNAL_INTEGER_ARRAY(argument, index, value)

value */
Semantics OPC_GET_SIGNAL_INTEGER_ARRAY obtains the value of the

array item associated with a signal argument.
index specifies the array index of the array item to obtain. When -1 is
specified, the oldest element is returned.
value receives the array value of the item. The value is obtained by
accessing ITM.

OPC_INTEGER.
• The OPC_GET_SIGNAL_INTEGER_ARRAY function must be
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_INTEGER_ARRAY is used within the
Errors none
Related • OPC_GET_SIGNAL_FLOAT_ARRAY
functions Gets signal argument float array value.

5.7.44 Get signal argument integer old value
Syntax OPC_GET_SIGNAL_INTEGER_OLD_VALUE(argument, value)

value */
Semantics OPC_GET_SIGNAL_INTEGER_OLD_VALUE obtains the previous

value receives the previous value of the item when the item triggers at
least one object (via a signal). Otherwise the support function returns the
current value by accessing ITM.

OPC_INTEGER.
• The OPC_GET_SIGNAL_INTEGER_OLD_VALUE function
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_INTEGER_OLD_VALUE is used
specification only.
Errors none
Related • OPC_GET_SIGNAL_FLOAT_OLD_VALUE
functions Gets signal argument float old value.
• OPC_GET_SIGNAL_STRING_OLD_VALUE
Gets signal argument string old value.

5.7.45 Get signal argument integer value
Syntax OPC_GET_SIGNAL_INTEGER_VALUE(argument, value)

value */
Semantics OPC_GET_SIGNAL_INTEGER_VALUE obtains the value of the item

value receives the value of the item. When the item triggers at least one
object (via a signal) the value is stored within OPC on an event basis. In
this case the support function is very fast. Otherwise the support function
accesses ITM to retrieve the value.

OPC_INTEGER.
• The OPC_GET_SIGNAL_INTEGER_VALUE function must be
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_INTEGER_VALUE is used within the
Errors none
Related • OPC_GET_SIGNAL_FLOAT_VALUE
functions Gets signal argument float value.
• OPC_GET_SIGNAL_STRING_VALUE

5.7.46 Get signal argument locked
Syntax OPC_GET_SIGNAL_LOCKED(argument, locked)

OPC_INTEGER locked; /* Obtained lock state
*/
Semantics OPC_GET_SIGNAL_LOCKED obtains the lock state of the item

locked receives the lock state from an item. It returns TRUE when the
item is locked. When the item triggers at least one object (via a signal)
the lock state is stored within OPC on an event basis. In this case the
ITM to retrieve the lock state.
Notes • The OPC_GET_SIGNAL_LOCKED function must be used for

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_LOCKED is used within the executable
Errors none

5.7.47 Get signal argument low limit
Syntax OPC_GET_SIGNAL_LOW_LIMIT(argument, limit)

limit */
Semantics OPC_GET_SIGNAL_LOW_LIMIT obtains the low limit of the item


OPC_FLOAT.
• The OPC_GET_SIGNAL_LOW_LIMIT function must be used for
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_LOW_LIMIT is used within the
Errors none

5.7.48 Get signal argument low low limit
Syntax OPC_GET_SIGNAL_LOW_LOW_LIMIT(argument, limit)

limit */
Semantics OPC_GET_SIGNAL_LOW_LOW_LIMIT obtains the low low limit of


OPC_FLOAT.
• The OPC_GET_SIGNAL_LOW_LOW_LIMIT function must be
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_LOW_LOW_LIMIT is used within the
Errors none

5.7.49 Get signal argument merged status
Syntax OPC_GET_SIGNAL_MERGED_STATUS(argument, status)

OPC_INTEGER status; /* Obtained item merged
status */
Semantics OPC_GET_SIGNAL_MERGED_STATUS obtains the merged status

status receives the merged status of the item. When the item triggers
at least one object (via a signal) the merged status is stored within OPC
on an event basis. In this case the support function is very fast.
Otherwise the support function accesses ITM to retrieve the merged
status.
The merged status returned is one of ITM_ST_*, as defined in ‘itm.h’.
Notes • The OPC_GET_SIGNAL_MERGED_STATUS function must be

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_MERGED_STATUS is used within the
Errors none

5.7.50 Get signal argument option status
Syntax OPC_GET_SIGNAL_OPTION_STATUS(argument, status)

option status */
Semantics OPC_GET_SIGNAL_OPTION_STATUS obtains the option status of

status receives the option status of the item. When the item triggers at
least one object (via a signal) the option status is stored within OPC on
an event basis. In this case the support function is very fast. Otherwise
the support function accesses ITM to retrieve the option status.
The option status returned is one of ITM_OPT_* defined in ‘itm.h’.
Notes • The OPC_GET_SIGNAL_OPTION_STATUS function must be

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_OPTION_STATUS is used within the
Errors none
Related • OPC_GET_SIGNAL_CONTROL_STATUS
functions Gets signal argument control status.

5.7.51 Get signal argument quality
Syntax OPC_GET_SIGNAL_QUALITY(argument, quality)

OPC_INTEGER quality; /* Obtained item
quality code */
Semantics OPC_GET_SIGNAL_QUALITY obtains the quality code of the item

quality receives the quality code of the item. When the item triggers at
least one object (via a signal triggered by quality code change) the
quality code is stored within OPC on an event basis. In this case the
ITM to retrieve the quality code.
Notes • The OPC_GET_SIGNAL_QUALITY function must be used for

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_QUALITY is used within the
Errors none
Related none
functions

5.7.52 Get signal argument status
Syntax OPC_GET_SIGNAL_STATUS(argument, status)

status */
Semantics OPC_GET_SIGNAL_STATUS obtains the status of the item associated

with a signal argument.
status receives the status of the item. When the item triggers at least
one object (via a signal) the status is stored within OPC on an event
bases. In this case the support function is very fast. Otherwise the
support function accesses ITM to retrieve the status.
The status returned is one of ITM_ST_* defined in ‘itm.h’. However in
case of boolean items, status ITM_ST_0 returns a FALSE and status
ITM_ST_1 returns a TRUE.
Notes • The OPC_GET_SIGNAL_STATUS function must be used for

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_STATUS is used within the executable
Errors none

5.7.53 Get signal argument old string value
Syntax OPC_GET_SIGNAL_STRING_OLD_VALUE(argument, value)

OPC_STRING *value; /* Obtained item
old value */
Semantics OPC_GET_SIGNAL_STRING_OLD_VALUE obtains the previous

value receives a pointer to the previous value of the item when the item
triggers at least one object (via a signal). Otherwise the support function
returns the current value by accessing ITM.
It is not allowed to modify the string that value is pointing to. When the
string has to be modified a copy must be made from the string.

OPC_STRING.
• The OPC_GET_SIGNAL_STRING_OLD VALUE function must
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_STRING_OLD_VALUE is used within
Errors none
Related • OPC_GET_SIGNAL_FLOAT_OLD_VALUE
• OPC_GET_SIGNAL_INTEGER_OLD_VALUE

5.7.54 Get signal argument string value
Syntax OPC_GET_SIGNAL_STRING_VALUE(argument, value)

OPC_STRING *value; /* Obtained item
value */
Semantics OPC_GET_SIGNAL_STRING_VALUE obtains the value of the item

value receives a pointer to the value of the item. When the item triggers
at least one object (via a signal) the value is stored within OPC on an
event basis. In this case the support function is very fast. Otherwise the
support function returns the current value by accessing ITM.
It is not allowed to modify the string that value is pointing to. When the
string has to be modified a copy must be made from the string.
OPC_STRING.
• The OPC_GET_SIGNAL_STRING_VALUE function must be
OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_STRING_VALUE is used within the
Errors none
Related • OPC_GET_SIGNAL_FLOAT_VALUE
• OPC_GET_SIGNAL_INTEGER_VALUE

5.7.55 Get signal argument sub name
Syntax OPC_GET_SIGNAL_SUB(argument, sub)

OPC_STRING *sub; /* Obtained item sub
name */
Semantics OPC_GET_SIGNAL_SUB obtains the sub name of the item associated

sub receives the sub name of the item. It is not allowed to modify the
string that sub is pointing to. When the string has to be modified, a copy
must be made from the string. The sub name is an empty string in the
case of main items.
Notes • The OPC_GET_SIGNAL_SUB function must be used for

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_SUB is used within the executable
Errors none
Related • OPC_GET_SIGNAL_INSTALLATION
functions Gets signal argument installation name.
• OPC_GET_SIGNAL_UNIT
Gets signal argument unit name.

5.7.56 Get signal argument tag name
Syntax OPC_GET_SIGNAL_TAG(argument, tag)

OPC_STRING *tag; /* Obtained item tag
name */
Semantics OPC_GET_SIGNAL_TAG obtains the tag name of the item associated

tag receives the tag name of the item. It is not allowed to modify the
string that tag is pointing to. When the string has to be modified, a copy
must be made from the string.
Notes • The OPC_GET_SIGNAL_TAG function must be used for

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_TAG is used within the executable
Errors none
• OPC_GET_SIGNAL_UNIT
Gets signal argument unit name.

5.7.57 Get signal argument unit name
Syntax OPC_GET_SIGNAL_UNIT(argument, unit)

OPC_STRING *unit; /* Obtained item unit
name */
Semantics OPC_GET_SIGNAL_UNIT obtains the unit name of the item

associated with a signal argument. From R10.01 this function will return
all second level sections.
unit receives the unit name of the item. It is not allowed to modify the
string that unit is pointing to. When the string has to be modified, a
copy must be made from the string.
Notes • The OPC_GET_SIGNAL_UNIT function must be used for

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_UNIT is used within the executable
Errors none

5.7.58 Get signal argument update time
Syntax OPC_GET_SIGNAL_UPDATE_TIME(argument, time)

OPC_FLOAT time; /* Obtained item
update time */
Semantics OPC_GET_SIGNAL_UPDATE_TIME obtains the update time of the

time receives the update time of the item. The update time is the time of
the last received event and is only valid when the item triggers at least
one object (via a signal). Otherwise zero is returned. When the initiator
of the item update event, sent to OPC, has inserted an update time stamp
in the event, then this time stamp is used instead of the time of the event
itself.
Notes • The OPC_GET_SIGNAL_UPDATE_TIME function must be used

OPC_TYPE_SIGNAL.
• The OPC_GET_SIGNAL_UPDATE_TIME is used within the
Errors none
Related none
functions

5.7.59 Get string argument value
Syntax OPC_GET_STRING(argument, value)

Semantics OPC_GET_STRING obtains the value of a string argument.

...
OPC_STRING *value;
...
OPC_GET_STRING(0, value);
...
Notes • The OPC_GET_STRING function must be used for arguments

which have the representation of OPC_REP_STRING.
• The OPC_GET_STRING is used within the executable statements
Errors none
Related • OPC_GET_INTEGER
functions Gets integer argument value.
• OPC_GET_FLOAT
Gets float argument value.

5.7.60 Get string global attribute argument value
Syntax OPC_GET_STRING_GLOBAL_ATTRIBUTE(argument, value)

Semantics OPC_GET_STRING_GLOBAL_ATTRIBUTE obtains the value of a

global attribute with the string representation.
argument specifies the argument. The argument index is in the range 0-
9 inclusive.
...
OPC_STRING *value;
...
OPC_GET_STRING_GLOBAL_ATTRIBUTE(0, value);
...
Notes • The OPC_GET_STRING_GLOBAL_ATTRIBUTE function must

• The OPC_GET_STRING_GLOBAL_ATTRIBUTE is used within
Errors none
Related • OPC_GET_FLOAT_GLOBAL_ATTRIBUTE
functions Gets float global attribute argument value.

5.7.61 Get string local attribute argument value
Syntax OPC_GET_STRING_LOCAL_ATTRIBUTE(argument, value)

Semantics OPC_GET_STRING_LOCAL_ATTRIBUTE obtains the value of a

local attribute with the string representation.
...
OPC_STRING *value;
...
OPC_GET_STRING_LOCAL_ATTRIBUTE(0, value);
...
Notes • The OPC_GET_STRING_LOCAL_ATTRIBUTE function must

• The OPC_GET_STRING_LOCAL_ATTRIBUTE is used within
Errors none
Related • OPC_GET_FLOAT_LOCAL_ATTRIBUTE
functions Gets float local attribute argument value.

5.7.62 Get timer argument status
Syntax OPC_GET_TIMER_STATUS(argument, status)

OPC_INTEGER status; /* Obtained status */
Semantics OPC_GET_TIMER_STATUS obtains the status of a timer argument.

status receives the timer argument status which is one of:
Status Description
OPC_EXPIRED The timer is expired

OPC_RUNNING The timer is running
OPC_STOPPED The timer is stopped
Notes • The OPC_GET_TIMER_STATUS function must be used for

arguments which have the representation of OPC_TYPE_TIMER.
• The OPC_GET_TIMER_STATUS is used within the executable
Errors none
Related • OPC_GET_TIMER_VALUE
functions Gets timer argument value.
• OPC_SET_TIMER_VALUE
Sets timer argument value.
• OPC_SET_TIMER_STATUS
Sets timer argument status.

5.7.63 Get timer argument value
Syntax OPC_GET_TIMER_VALUE(argument, value)

Semantics OPC_GET_TIMER_VALUE obtains the value of a timer argument.

value receives the timer argument value. When the timer is expired then
zero is returned otherwise the number of seconds before the timer
expires is returned. Note that the timer can be stopped.
Notes • The OPC_GET_TIMER_VALUE function must be used for

• The OPC_GET_TIMER_VALUE is used within the executable
Errors none
Related • OPC_GET_TIMER_STATUS
functions Gets timer argument status.

5.7.64 Print a message
Syntax OPC_PRINT(text)
Arguments char *text; /* Message text */
Semantics OPC_PRINT prints a text on the standard UMH error logger.

text is the message text to print. When a NULL pointer is supplied then
no action is taken.
Notes The OPC_PRINT is used within the executable statements section of the
function specification only.
Errors none
functions Signals and sets an error text.

5.7.65 Set float function return value
Syntax OPC_RET_FLOAT(value)
Arguments OPC_FLOAT value; /* Return value */
Semantics OPC_RET_FLOAT sets the float return value for a function. The
function does not exit.
Notes • The OPC_RET_FLOAT function must be used for functions for

which a float representation has been defined for the function’s
return value. When OPC_RET_FLOAT is not used before the
function exits then the return value is undefined.
• The OPC_RET_FLOAT is used within the executable statements
Errors none
Related • OPC_RET_INTEGER
functions Sets integer return value.
• OPC_RET_STRING
Sets string return value.
• OPC_EXIT
Exits the function.

5.7.66 Set integer function return value
Syntax OPC_RET_INTEGER(value)
Arguments OPC_INTEGER value; /* Return value */
Semantics OPC_RET_INTEGER sets the integer return value for a function. The
Notes • The OPC_RET_INTEGER function must be used for functions for

which an integer representation has been defined for the function’s
return value. When OPC_RET_INTEGER is not used before the
• The OPC_RET_INTEGER is used within the executable
Errors none
Related • OPC_RET_FLOAT
functions Sets float return value.
• OPC_RET_STRING
Sets string return value.
• OPC_EXIT
Exits the function.

5.7.67 Set string function return value
Syntax OPC_RET_STRING(value)
Arguments OPC_STRING *value; /* Return value */
Semantics OPC_RET_STRING sets the string return value for a function. The
The string is copied to OPC.
Notes • The OPC_RET_STRING function must be used for functions for

which a string representation has been defined for the function’s
return value. When OPC_RET_STRING is not used before the
• The function exits when a string longer than OPC_MAX_STR_SZ
characters is supplied.
• The OPC_RET_STRING is used within the executable statements
Errors • OPC_E_ILLSTRSZ
String is too long.
Related • OPC_RET_INTEGER
functions Sets integer return value.
• OPC_RET_FLOAT
Sets float return value.
• OPC_EXIT
Exits the function.

5.7.68 Set alarm argument priority
Syntax OPC_SET_ALARM_PRIORITY(argument, priority)

OPC_INTEGER priority; /* Priority to set */
Semantics OPC_SET_ALARM_PRIORITY sets the priority of an alarm argument.

Note that the alarm priority is only accessible within an object and has
no relation to the priority of a displayed alarm in an alarm overview.
argument specifies the argument whose value is to be changed. The
priority contains the alarm argument priority to set
Notes • The OPC_SET_ALARM_PRIORITY function must be used for
• The OPC_SET_ALARM_PRIORITY is used within the
Errors none

5.7.69 Set alarm argument status
Syntax OPC_SET_ALARM_STATUS(argument, priority)

OPC_INTEGER status; /* Status to set */
Semantics OPC_SET_ALARM_STATUS sets the status of an alarm argument.

argument specifies the argument whose status is obtained. The
status contains the alarm argument status to set which is one of:
Status Description
NORMAL The alarm is disabled (removed from the alarm

overview(s))
A1 The alarm is activated (presentation according to A1
definition)
definition)
definition)
An alarm acknowledge request can be set when the alarm is activated.

The alarm status must then be logically ORed with ACKNOWLEDGE
like in the next example.
alarm_1 := "Please acknowledge";
alarm_1’status := A1 | ACKNOWLEDGE;
Notes • The OPC_SET_ALARM_STATUS function must be used for

• The OPC_SET_ALARM_STATUS is used within the executable
Errors none


5.7.70 Set alarm argument value
Syntax OPC_SET_ALARM_VALUE(argument, value)

OPC_STRING *value; /* Value to set */
Semantics OPC_SET_ALARM_VALUE sets the value of an alarm argument

value.
value contains the string value to set. The string pointed to is copied to
OPC.
Notes • The OPC_SET_ALARM_VALUE function must be used for
• The OPC_SET_ALARM_VALUE is used within the executable
Errors none
functions Sets alarm argument value.

5.7.71 Set float argument value
Syntax OPC_SET_FLOAT(argument, value)

OPC_FLOAT value; /* Value to set */
Semantics OPC_SET_FLOAT sets the value of a float argument.

argument specifies the argument whose value is set. The argument
index is in the range 0-9 inclusive.
value contains the float value to set. It is only passed to the calling
method or function when the supplied argument is a float variable
identifier. In all other cases setting a float argument value has no effect.
Notes • The OPC_SET_FLOAT function must be used for arguments

which have the representation of OPC_REP_FLOAT.
• The OPC_SET_FLOAT is used within the executable statements
Errors none
Related • OPC_SET_INTEGER
functions Sets integer argument value.
• OPC_SET_STRING
Sets string argument value.

5.7.72 Set float global attribute argument value
Syntax OPC_SET_FLOAT_GLOBAL_ATTRIBUTE(argument, value)

Semantics OPC_SET_FLOAT_GLOBAL_ATTRIBUTE sets the value of a global

attribute.
value contains the float value to set. All objects derived from the same
class will receive the new value for the attribute.
Notes • The OPC_SET_FLOAT_GLOBAL_ATTRIBUTE function must

• The OPC_SET_FLOAT_GLOBAL_ATTRIBUTE is used within
Errors none
Related • OPC_SET_INTEGER_GLOBAL_ATTRIBUTE
functions Sets integer global attribute argument value.
• OPC_SET_STRING_GLOBAL_ATTRIBUTE
Sets string global attribute argument value.
• OPC_SET_INTEGER_LOCAL_ATTRIBUTE
Sets integer local attribute argument value.
• OPC_SET_FLOAT_LOCAL_ATTRIBUTE
Sets float local attribute argument value.
• OPC_SET_STRING_LOCAL_ATTRIBUTE
Sets string local attribute argument value.

5.7.73 Set float local attribute argument value
Syntax OPC_SET_FLOAT_LOCAL_ATTRIBUTE(argument, value)

Semantics OPC_SET_FLOAT_LOCAL_ATTRIBUTE sets the value of a local

attribute.
value contains the float value to set.
Notes • The OPC_SET_FLOAT_LOCAL_ATTRIBUTE function must be

• The OPC_SET_FLOAT_LOCAL_ATTRIBUTE is used within the
Errors none
Related • OPC_SET_INTEGER_LOCAL_ATTRIBUTE
functions Sets integer local attribute argument value.
• OPC_SET_INTEGER_GLOBAL_ATTRIBUTE
Sets integer global attribute argument value.
• OPC_SET_FLOAT_GLOBAL_ATTRIBUTE
Sets float global attribute argument value.

5.7.74 Set integer argument value
Syntax OPC_SET_INTEGER(argument, value)

OPC_INTEGER value; /* Value to set */
Semantics OPC_SET_INTEGER sets the value of an integer argument.

value contains the integer value to set. It is only passed to the calling
method or function when the supplied argument is an integer variable
identifier. In all other cases setting an integer argument value has no
effect.
Notes • The OPC_SET_INTEGER function must be used for arguments

which have the representation of OPC_REP_INTEGER.
• The OPC_SET_INTEGER is used within the executable statements
Errors none
Related • OPC_SET_FLOAT
functions Sets float argument value.
• OPC_SET_STRING
Sets string argument value.

5.7.75 Set integer global attribute argument value
Syntax OPC_SET_INTEGER_GLOBAL_ATTRIBUTE(argument, value)

Semantics OPC_SET_INTEGER_GLOBAL_ATTRIBUTE sets the value of a

global attribute.
value contains the integer value to set. All objects derived from the
same class will receive the new value for the attribute.
Notes • The OPC_SET_INTEGER_GLOBAL_ATTRIBUTE function

• The OPC_SET_INTEGER_GLOBAL_ATTRIBUTE is used
specification only.
Errors none
Related • OPC_SET_FLOAT_GLOBAL_ATTRIBUTE
functions Sets float global attribute argument value.

5.7.76 Set integer local attribute argument value
Syntax OPC_SET_INTEGER_LOCAL_ATTRIBUTE(argument, value)

Semantics OPC_SET_INTEGER_LOCAL_ATTRIBUTE sets the value of a local

attribute.
value contains the integer value to set.
Notes • The OPC_SET_INTEGER_LOCAL_ATTRIBUTE function must

• The OPC_SET_INTEGER_LOCAL_ATTRIBUTE is used within
Errors none
Related • OPC_SET_FLOAT_LOCAL_ATTRIBUTE
functions Sets float local attribute argument value.

5.7.77 Set an attribute of an item
Syntax OPC_SET_ITEM_VALUE(dii_id, flags, attribute,

representation, value)
Arguments gin_dii_id dii_id; /* The distributed item

id */
OPC_INTEGER flags; /* Flags */
int attribute; /* The item attribute to
set */
int representation; /* The representation of
the attribute value
*/
char *value; /* A pointer to the
value */
Semantics OPC_SET_ITEM_VALUE sets the value of an attribute of an item.
dii_id specifies the item id of the item to set.
flags contains additional flags (see GIN_DII_FLAGS in the GIN
attribute specifies the distribute to set (see the function gin_dii_satr()
in the GIN Programmer’s Guide).
representation specifies representation of the value supplied. A zero
indicates a default representation.
value point at a location where the value to be set is stored.
This function calls gin_dii_satr() after some processing to handle item
locking.
Notes • It is strongly advised to use this function to set item attributes and
never to use gin_dii_satr() directly because it bypassed the item
locking mechanism provided by OPC.
Errors none
Related • OPC_SET_ITEM_VALUES
functions Sets two item attributes in one call.
• OPC_GET_SIGNAL_ID
Obtains the item id of the item related to a signal.

5.7.78 Set attributes of an item
Syntax OPC_SET_ITEM_VALUES(dii_id, flags, attribute1,

representation1, value1, attribute2, representation2,
value2)
Arguments gin_dii_id dii_id; /* The distributed item

id */
OPC_INTEGER flags; /* Flags */
int attribute1; /* The first item
attribute to set */
int representation1; /* The representation of
the first attribute
value */
char *value1; /* A pointer to the
first value */
int attribute2; /* The second item
attribute to set */
int representation2; /* The representation of
the second attribute
value */
char *value2; /* A pointer to the
second value */
Semantics OPC_SET_ITEM_VALUES sets the value of two attribute of an item.
dii_id specifies the item id of the item to set.
flags contains additional flags (see GIN_DII_FLAGS in the GIN
attribute1 and attribute2 specify the distributes to set (see the
function gin_dii_satr() in the GIN Programmer’s Guide).
representation1 and representation2 specify the representation
of the values supplied. A zero indicates a default representation.
value1 and value2 point at a location where the values to be set are
stored.
This function calls gin_dii_satr() after some processing to handle item
locking.
Notes • It is strongly advised to use this function to set item attributes and
never to use gin_dii_satr() directly because it bypassed the item
locking mechanism provided by OPC.
Errors none

Related • OPC_SET_ITEM_VALUE
functions Sets a single item attribute.
• OPC_GET_SIGNAL_ID
Obtains the item id of the item related to a signal.

5.7.79 Set signal argument application flag
Syntax OPC_SET_SIGNAL_APPLICATION_FLAG(argument, flag)

OPC_INTEGER flag; /* Application flag to
set */
Semantics OPC_SET_SIGNAL_APPLICATION_FLAG sets the application flag

flag contains the application flag to set.
Notes • All bits in flag are handled. For example, it is not possible to set
or clear distinct bits.
• The OPC_SET_SIGNAL_APPLICATION_FLAG function must
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_APPLICATION_FLAG is used within
Errors none
Related none
functions

5.7.80 Set signal argument application info
Syntax OPC_SET_SIGNAL_APPLICATION_INFO(argument, index, value)

OPC_INTEGER value; /* Application info to
set */
Semantics OPC_SET_SIGNAL_APPLICATION_INFO sets one element of the

application info of the item associated with a signal argument.
index specifies the array index of the application info element to set.
When zero is specified the application info is updated at ITM. When the
index is greater than zero, the specified element is set within OPC only.
value contains the application info element of the item.
Notes • The OPC_SET_SIGNAL_APPLICATION_INFO function must

OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_APPLICATION_INFO is used within
Errors none
Related • OPC_GET_SIGNAL_APPLICATION_SIZE
functions Gets signal argument application info size.

5.7.81 Set signal argument deadband
Syntax OPC_SET_SIGNAL_DEADBAND(argument, deadband)

OPC_FLOAT deadband; /* Deadband to set */
Semantics OPC_SET_SIGNAL_DEADBAND sets the deadband of the item

deadband contains the deadband for the item. The deadband is set at
ITM only. The deadband in the item definition is not changed.
Notes • The deadband is converted from OPC_FLOAT to the item’s

representation.
• The OPC_SET_SIGNAL_DEADBAND function must be used for
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_DEADBAND is used within the
Errors none
Related • OPC_SET_SIGNAL_HIGH_HIGH_LIMIT
functions Sets signal argument high high limit.
• OPC_SET_SIGNAL_HIGH_LIMIT
Sets signal argument high limit.
• OPC_SET_SIGNAL_LOW_LIMIT
Sets signal argument low limit.
• OPC_SET_SIGNAL_LOW_LOW_LIMIT
Sets signal argument low low limit.

5.7.82 Set signal argument float array value
Syntax OPC_SET_SIGNAL_FLOAT_ARRAY(argument, index, value)

Semantics OPC_SET_SIGNAL_FLOAT_ARRAY sets the value of the array item

index specifies the array index of the array item to set. When -1 is
specified, the oldest element is set.
value contains the array value for the item.
Notes • The value is converted from OPC_FLOAT to the item’s

representation.
• The OPC_SET_SIGNAL_FLOAT_ARRAY function must be
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_FLOAT_ARRAY is used within the
Errors none
Related • OPC_SET_SIGNAL_INTEGER_ARRAY
functions Sets signal argument integer array value.

5.7.83 Set signal argument float value
Syntax OPC_SET_SIGNAL_FLOAT_VALUE(argument, value)

Semantics OPC_SET_SIGNAL_FLOAT_VALUE sets the value of the item

value contains the new value for the item.
Notes • The value is converted from OPC_FLOAT to the item’s

representation.
• The OPC_SET_SIGNAL_FLOAT_VALUE function must be used
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_FLOAT_VALUE is used within the
Errors none
Related • OPC_SET_SIGNAL_INTEGER_VALUE
functions Sets signal argument integer value.
• OPC_SET_SIGNAL_STRING_VALUE
Sets signal argument string value.

5.7.84 Set signal argument high limit
Syntax OPC_SET_SIGNAL_HIGH_LIMIT(argument, limit)

OPC_FLOAT limit; /* Limit to set */
Semantics OPC_SET_SIGNAL_HIGH_LIMIT sets the high limit of the item

limit contains the limit for the item. The limit is set at ITM only. The
limit in the item definition is not changed.
Notes • The limit is converted from OPC_FLOAT to the item’s

representation.
• The OPC_SET_SIGNAL_HIGH_LIMIT function must be used for
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_HIGH_LIMIT is used within the
Errors none
• OPC_SET_SIGNAL_DEADBAND
Sets signal argument deadband.

5.7.85 Set signal argument high high limit
Syntax OPC_SET_SIGNAL_HIGH_HIGH_LIMIT(argument, limit)

Semantics OPC_SET_SIGNAL_HIGH_HIGH_LIMIT sets the high high limit of

Notes • The limit is converted from OPC_FLOAT to the item’s

representation.
• The OPC_SET_SIGNAL_HIGH_HIGH_LIMIT function must be
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_HIGH_HIGH_LIMIT is used within the
Errors none
Related • OPC_SET_SIGNAL_HIGH_LIMIT
functions Sets signal argument high limit.

5.7.86 Set signal argument integer array value
Syntax OPC_SET_SIGNAL_INTEGER_ARRAY(argument, index, value)

Semantics OPC_SET_SIGNAL_INTEGER_ARRAY sets the value of the array

index specifies the array index of the array item to set. When -1 is
specified, the oldest element is set.
value contains the array value for the item.
Notes • The value is converted from OPC_INTEGER to the item’s

representation.
• The OPC_SET_SIGNAL_INTEGER_ARRAY function must be
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_INTEGER_ARRAY is used within the
Errors none
Related • OPC_SET_SIGNAL_FLOAT_ARRAY
functions Sets signal argument float array value.

5.7.87 Set signal argument integer value
Syntax OPC_SET_SIGNAL_INTEGER_VALUE(argument, value)

Semantics OPC_SET_SIGNAL_INTEGER_VALUE sets the value of the item

value contains the new value for the item.
Notes • The value is converted from OPC_INTEGER to the representation

of the item.
• The OPC_SET_SIGNAL_INTEGER_VALUE function must be
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_INTEGER_VALUE is used within the
Errors none
Related • OPC_SET_SIGNAL_FLOAT_VALUE
functions Sets signal argument float value.
• OPC_SET_SIGNAL_STRING_VALUE

5.7.88 Set signal argument low limit
Syntax OPC_SET_SIGNAL_LOW_LIMIT(argument, limit)

Semantics OPC_SET_SIGNAL_LOW_LIMIT sets the low limit of the item

Notes • The limit is converted from OPC_FLOAT to the representation of

the item.
• The OPC_SET_SIGNAL_LOW_LIMIT function must be used for
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_LOW_LIMIT is used within the
Errors none

5.7.89 Set signal argument low low limit
Syntax OPC_SET_SIGNAL_LOW_LOW_LIMIT(argument, limit)

Semantics OPC_SET_SIGNAL_LOW_LOW_LIMIT sets the low low limit of the

limit contains the limit for the item.. The limit is set at ITM only. The
Notes • The limit is converted from OPC_FLOAT to the representation of

the item.
• The OPC_SET_SIGNAL_LOW_LOW_LIMIT function must be
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_LOW_LOW_LIMIT is used within the
Errors none

5.7.90 Set signal argument quality
Syntax OPC_SET_SIGNAL_QUALITY(argument, quality)

OPC_INTEGER quality; /* Quality to set */
Semantics OPC_SET_SIGNAL_QUALITY sets the quality code of the item

quality contains the quality code for the item.
Notes • The OPC_SET_SIGNAL_QUALITY function must be used for

OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_QUALITY is used within the executable
Errors none
Related none
functions

5.7.91 Set signal argument status
Syntax OPC_SET_SIGNAL_STATUS(argument, status)

Semantics OPC_SET_SIGNAL_STATUS sets the status of the item associated

value contains the new status for the item. The status to set is a number
in the range 0 to 255. Some are defined in ‘itm.h’ (ITM_ST_*).
Notes • The OPC_SET_SIGNAL_STATUS function must be used for

OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_STATUS is used within the executable
Errors none
Related none
functions

5.7.92 Set signal argument string value
Syntax OPC_SET_SIGNAL_STRING_VALUE(argument, value)

Semantics OPC_SET_SIGNAL_STRING_VALUE sets the value of the item

value contains a pointer to the new value for the item.
Notes • The value is converted from OPC_STRING to the representation of

the item.
• The OPC_SET_SIGNAL_STRING_VALUE function must be
OPC_TYPE_SIGNAL.
• The OPC_SET_SIGNAL_STRING_VALUE is used within the
Errors none
Related • OPC_SET_SIGNAL_FLOAT_VALUE
functions Sets signal argument float value.
• OPC_SET_SIGNAL_INTEGER_VALUE

5.7.93 Set string argument value
Syntax OPC_SET_STRING(argument, value)

Semantics OPC_SET_STRING sets the value of a string argument.

value contains the string value to set. It is only passed to the calling
method or function when the supplied argument is a string variable
identifier. In all other cases setting a string argument value has no effect.
The string pointed to is copied to OPC.
Notes • The OPC_SET_STRING function must be used for arguments

which have the representation of OPC_REP_STRING.
• The OPC_SET_FLOAT is used within the executable statements
Errors none
Related • OPC_SET_INTEGER
functions Sets integer argument value.
• OPC_SET_FLOAT
Sets float argument value.

5.7.94 Set string global attribute argument value
Syntax OPC_SET_STRING_GLOBAL_ATTRIBUTE(argument, value)

Semantics OPC_SET_STRING_GLOBAL_ATTRIBUTE sets the value of a

global attribute.
OPC. All objects derived from the same class will receive the new value
for the attribute.
Notes • The OPC_SET_STRING_GLOBAL_ATTRIBUTE function must

• The OPC_SET_STRING_GLOBAL_ATTRIBUTE is used within
Errors none
Related • OPC_SET_FLOAT_GLOBAL_ATTRIBUTE
functions Sets float global attribute argument value.

5.7.95 Set string local attribute argument value
Syntax OPC_SET_STRING_LOCAL_ATTRIBUTE(argument, value)

Semantics OPC_SET_STRING_LOCAL_ATTRIBUTE sets the value of a local

attribute.
OPC.
Notes • The OPC_SET_STRING_LOCAL_ATTRIBUTE function must

• The OPC_SET_STRING_LOCAL_ATTRIBUTE is used within
Errors none
Related • OPC_SET_FLOAT_LOCAL_ATTRIBUTE
functions Sets float local attribute argument value.

5.7.96 Set timer argument status
Syntax OPC_SET_TIMER_STATUS(argument, status)

Semantics OPC_SET_TIMER_STATUS sets the status of a timer argument.

status contains the status to set which is one of:
Status Description
OPC_EXPIRED The timer is set to expired

OPC_RUNNING The timer is set to running, the timer value contains the
number of seconds before expiring
OPC_STOPPED The timer is set to stopped
Notes • The OPC_SET_TIMER_STATUS function must be used for

• The OPC_SET_TIMER_STATUS is used within the executable
Errors none
Related • OPC_GET_TIMER_VALUE
functions Gets timer argument value.
• OPC_GET_TIMER_STATUS
Gets timer argument status.

5.7.97 Set timer argument value
Syntax OPC_SET_TIMER_VALUE(argument, value)

Semantics OPC_SET_TIMER_VALUE sets the value of a timer argument.

value contains the number of seconds before the timer expires. The
fractional part is ignored. When set to zero, the timer expires
immediately otherwise the timer starts running and expires when the
number of seconds has elapsed. Note that the timer can be stopped.
Notes • The OPC_SET_TIMER_VALUE function must be used for

• The OPC_SET_TIMER_VALUE is used within the executable
Errors none
Related • OPC_GET_TIMER_STATUS
functions Gets timer argument status.
• OPC_GET_TIMER_VALUE
Gets timer argument value.

5.7.98 Obtain task number context
Syntax OPC_TASK_NUMBER
Arguments none
Semantics OPC_TASK_NUMBER obtains a unique task number to be used by

BUS/FAST send/receive sequences to distinguish messages from
messages sent by other functions. When receiving a reply, a selection
filter on this task number must be used to make sure that the correct reply
is received and not a reply addressed to another function.
Each reference to OPC_TASK_NUMBER returns a unique number.
Notes The OPC_TASK_NUMBER is used within the executable statements

Errors none
Related none
functions

5.7.99 Obtain UMH context
Syntax OPC_UMH_CONTEXT
Arguments none
Semantics OPC_UMH_CONTEXT obtains the UMH context which is used in calls

to UMH to set errors. For example:
umh_set_code(OPC_UMH_CONTEXT, my_error_code);
Notes The OPC_UMH_CONTEXT is used within the executable statements

Errors none
Related • OPC_DUR_CONTEXT
functions Obtains the DUR context.

General Example of object creation
Appendix A: Example of object

creation
A.1 General
This appendix contains an example, in ‘C’ source, showing the usage of
several example OPC routines to create objects.
A.2 Example
/*----------------------------------------------------------------------------+
| |
| / / / / / / O O O O O O O |
| /// ///// /// / / O O O O O O OOO |
| / / / / / / O O O O O O O |
| / / / / / / O O O O O O O |
| |
+-----------------------------------------------------------------------------+
| * Example * |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
Module Name : create_object.c
Version : 1.0
Author : C.Horevoorts
+-----------------------------------------------------------------------------+
| Changes .... |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
HVS Jul-93 e307 First version documented
+-----------------------------------------------------------------------------+
+----------------------------------------------------------------------------*/
#include <opc.h>
/*============================================================================+
| Entry point |
+-----------------------------------------------------------------------------+
|
| Description:
OPC Programmer’s Guide A-1

Example of object creation Example
| This example program shows how to create an object

|
+----------------------------------------------------------------------------*/
main()
{
struct opc_context *opc_c;
char io_buf[FIO_MAX_INP];
char t_buf[FIO_MAX_INP];
TLS_LONG node;
TLS_ULONG t_long;
TLS_BOOLEAN ctrl_id;
int i, atrs;
struct ftm_time time;
struct opc_cls_def cls_def;
struct opc_obj_def *obj_def;
struct opc_cls_pmt cls_pmt;
struct opc_atr_upd *atr_upd;
TLS_LONG buf_def[OPC_OBJ_DEF_SZ/sizeof(TLS_LONG)];
TLS_LONG buf_upd[(sizeof(*atr_upd)+OPC_MAX_STR_SZ)/sizeof(TLS_LONG)];
struct opc_atr_val *atr_val;
/*----------------------------------------------------------------------------+
| Initialize the program
+----------------------------------------------------------------------------*/
dur_umh_init(&dur_c, &umh_c, 10, 0, 512, 512, (char*)NULL);
obj_def = (struct opc_obj_def*)buf_def;

atr_upd = (struct opc_atr_upd*)buf_upd;
memset((char*)&cls_def, 0, sizeof(cls_def));
memset((char*)obj_def, 0, sizeof(obj_def));
io_buf[0] = ‘\0’;
/*----------------------------------------------------------------------------+
| Get the node of the PROCESS/FAST host
+----------------------------------------------------------------------------*/
node = 0;
fio_ltd_long(io_buf, &node, “Enter the OPC host node number :”,
FIO_RETRY | FIO_DFL, (TLS_LONG)0, (TLS_LONG)254);
/*----------------------------------------------------------------------------+
| Attach to PROCESS/FAST
+----------------------------------------------------------------------------*/
if ((opc_c = opc_attach(&dur_c, &umh_c, (int)node, 600, “create_object”,
“create_object”)) == NULL)
{
dur_det(&dur_c, &umh_c);
exit(BAD_EXIT);
}
/*----------------------------------------------------------------------------+
| Ask the name for the object
+----------------------------------------------------------------------------*/
fio_ltd_str(io_buf, obj_def->name.name, “Enter object name :”,
FIO_RETRY | FIO_DFL, sizeof(obj_def->name.name));
/*----------------------------------------------------------------------------+
| Ask the one-liner description
+----------------------------------------------------------------------------*/
fio_ltd_str(io_buf, obj_def->desc, “Enter description :”,
FIO_RETRY | FIO_DFL | FIO_SPACE, sizeof(obj_def->desc));
/*----------------------------------------------------------------------------+
A-2 OPC Programmer’s Guide

Example Example of object creation
| Ask the class name

+----------------------------------------------------------------------------*/
fio_ltd_str(io_buf, cls_def.name, “Enter class name :”,
FIO_RETRY | FIO_DFL, sizeof(cls_def.name));
if (!opc_cls_get(opc_c, &cls_def))
{
opc_detach(opc_c);
exit(GOOD_EXIT);
}
obj_def->cls_id = cls_def.cls_id;
/*----------------------------------------------------------------------------+
| Ask the name for the control item or the node
+----------------------------------------------------------------------------*/
ctrl_id = FALSE;
fio_get_conf(io_buf, &ctrl_id, “Use object control item (Y/N) :”,
FIO_RETRY | FIO_DFL, “Y”, “N”);
if (ctrl_id)
{
struct gin_dii_id *dii_id;
char item_name[200];
item_name[0] = ‘\0’;
fio_ltd_str(io_buf, item_name, “Enter item name :”,

FIO_RETRY | FIO_DFL, sizeof(item_name));
if ((dii_id = gin_dii_gidn(&umh_c, item_name)) == NULL)

{
opc_detach(opc_c);
exit(GOOD_EXIT);
}
obj_def->dii_id = *dii_id;
obj_def->node = 0;
}
else
{
t_long = obj_def->node;
fio_get_long(io_buf, &t_long, “Enter node number :”, FIO_RETRY | FIO_DFL);
obj_def->node = t_long;
GIN_DII_ID_CLEAR(&obj_def->dii_id);
}
/*----------------------------------------------------------------------------+
| Ask the priority
+----------------------------------------------------------------------------*/
t_long = obj_def->priority;
fio_get_long(io_buf, &t_long, “Enter priority :”, FIO_RETRY | FIO_DFL);
obj_def->priority = t_long;
/*----------------------------------------------------------------------------+
| Ask activation time window
+----------------------------------------------------------------------------*/
ftm_format(&obj_def->start, FTM_GEN, t_buf);
fio_ltd_str(io_buf, t_buf, “Enter activation time (GMT) :”,
FIO_RETRY | FIO_DFL | FIO_SPACE, sizeof(t_buf));
if (!ftm_inp_time(&umh_c, t_buf, &time, 0))
{
opc_detach(opc_c);
exit(GOOD_EXIT);
}
obj_def->start = time.ftm_sec;

ftm_format(&obj_def->stop, FTM_GEN, t_buf);

fio_ltd_str(io_buf, t_buf, “Enter deactivation time (GMT) :”,
FIO_RETRY | FIO_DFL | FIO_SPACE, sizeof(t_buf));
if (!ftm_inp_time(&umh_c, t_buf, &time, 0))
{
opc_detach(opc_c);
exit(GOOD_EXIT);
}
obj_def->stop = time.ftm_sec;
/*----------------------------------------------------------------------------+
| Retrieve the prompts and the default values of the attribute prompted for,
| and ask the new value for the attributes prompted for
+----------------------------------------------------------------------------*/
atrs = 0;
cls_pmt.pmt_id = obj_def->cls_id;
atr_val = obj_def->atr_val;
while (opc_cls_npmt(opc_c, &cls_pmt))

{
int len;
atr_upd->obj_id.sec = 0;
atr_upd->atr_val.atr_id = cls_pmt.atr_id;
atr_upd->atr_val.rep = REP_STRING;
if (!opc_atr_rd(opc_c, atr_upd))
{
opc_detach(opc_c);
exit(GOOD_EXIT);
}
fio_ltd_str(io_buf, atr_upd->atr_val.val.t, cls_pmt.query,
FIO_RETRY | FIO_DFL | FIO_SPACE, FIO_MAX_INP);
len = sizeof(*atr_val);
len += (strlen(atr_val->val.t) + 1 - sizeof(atr_val->val.t));
len = (len + 7) & ~7; /* Adjust on TLS_LONG boundary */
if ((char*)atr_val + len > (char*)obj_def + OPC_OBJ_DEF_SZ)
{
umh_set_code(&umh_c, UMH_I_INFO);
umh_set_com(&umh_c, “Total size of attribute values too large”);
opc_detach(opc_c);
exit(GOOD_EXIT);
}
atr_val->atr_id = cls_pmt.atr_id;
atr_val->rep = REP_STRING;
strcpy(atr_val->val.t, atr_upd->atr_val.val.t);
atr_val = (struct opc_atr_val *)((char*)atr_val + len);

atrs++;
}
if (umh_error(&umh_c) != OPC_E_CLS_NOTPMT)
{
opc_detach(opc_c);
exit(GOOD_EXIT);
}

Example Example of object creation
/*----------------------------------------------------------------------------+
| Insert the object
+----------------------------------------------------------------------------*/
if (!opc_obj_ins(opc_c, obj_def, atrs))
/*----------------------------------------------------------------------------+
| Exit
+----------------------------------------------------------------------------*/
opc_detach(opc_c);
exit(GOOD_EXIT);
}


Index
Index
A
activator 1-3
attribute 2-8, 2-17, 3-2, 3-9
B
behavior 1-2
C
class 1-1
class parameters 2-6
compiler 1-3
control item 1-2
E
executor 1-3
F
float 3-2, 3-6, 3-9, 3-13
function 1-4, 3-1
accessing arguments 3-9
arguments 3-2
calling 3-1
context 3-14
controlling function flow 3-13
declaration section 3-8
definition 3-6
executable statements 3-8
miscellaneous 3-13
result 3-2
specification 3-8
support 3-9
updating OPC 3-15
I
included classes 2-6
integer 3-2, 3-6, 3-9, 3-13
internal class identification 2-3
internal object identification 2-9
internal trigger group identification 2-16
interval 1-3
OPC Programmer’s Guide 1

Index
L
loader 1-3
M
manager 1-3
method 1-2
MIDDLE() 3-12
N
name
class 1-1
object 1-2
trigger group 1-3
O
object 1-1, 1-2
OPC 1-3, 5-166
OPC_ATR_CLS 5-5
OPC_ATR_OBJ 5-5
opc_atr_rd() 2-10, 2-18, 5-21
opc_atr_upd 2-18, 5-3
opc_atr_val 2-12, 5-4
opc_atr_wr() 2-18, 5-23
opc_attach( 2-2
opc_attach() 2-2, 5-25
opc_bif.c 3-8, 3-12
OPC_BODY 3-8, 3-12, 5-74
opc_cls_atr 5-5
opc_cls_com() 2-5, 5-26
opc_cls_def 5-5
opc_cls_del() 2-9, 5-28
opc_cls_dtrg() 2-9, 2-16, 5-8, 5-29
opc_cls_evt() 5-30
opc_cls_gatr() 2-8, 5-31
opc_cls_get() 2-6, 2-10, 5-32
opc_cls_gsig() 2-7, 5-13, 5-33
opc_cls_inc 2-6, 5-7
opc_cls_ins() 2-4, 5-34
opc_cls_itrg() 2-9, 2-16, 5-8, 5-36
opc_cls_lck() 2-4, 2-5, 5-32, 5-37, 5-49
opc_cls_mod() 2-4, 2-5, 5-39
opc_cls_natr() 2-8, 5-3, 5-40
opc_cls_ninc() 2-6, 5-41
opc_cls_npmt() 2-8, 2-10, 2-14, 5-3, 5-42, 5-43
opc_cls_nsig() 2-7, 5-13, 5-44
opc_cls_ntrg() 2-9, 5-8, 5-45
opc_cls_nxt() 2-6, 5-46
opc_cls_pmt 5-7
2 OPC Programmer’s Guide

Index
opc_cls_res 5-8
opc_cls_res() 2-5, 2-9, 5-47
opc_cls_sig 5-8
opc_cls_trg() 2-9, 5-48
opc_cls_trg_id 5-8
opc_cls_view() 2-6, 5-32, 5-37, 5-49
opc_context 5-8
OPC_DECLARATION 3-8, 3-12, 5-75
OPC_DECLARE() 5-76
OPC_DEFINE() 5-77
opc_detach() 2-2, 5-50
OPC_DUR_CONTEXT 3-13, 5-79
OPC_END_FUNCTION 3-8, 3-12, 5-80
OPC_END_FUNCTION_DECLARATION 5-81
OPC_END_FUNCTION_DEFINITION 5-82
OPC_ERROR() 3-14, 5-83
OPC_ERROR_EXIT 5-84
OPC_EXIT 3-13, 5-85
opc_fnc_cont 3-14, 5-9
opc_fnc_def 3-14, 5-10
OPC_FUNCTION() 3-8, 3-12, 5-86
OPC_FUNCTION_DECLARATION 5-87
OPC_FUNCTION_DEFINITION 5-88
OPC_GET_FLOAT() 3-9, 5-93
OPC_GET_FLOAT_GLOBAL_ATTRIBUTE() 3-9, 5-94
OPC_GET_FLOAT_LOCAL_ATTRIBUTE() 3-9, 5-95
OPC_GET_INTEGER() 3-9, 3-12, 5-96
OPC_GET_INTEGER_GLOBAL_ATTRIBUTE() 3-9, 5-97
OPC_GET_INTEGER_LOCAL_ATTRIBUTE() 3-9, 5-98
OPC_GET_SIGNAL_ACKNOWLEDGED() 3-10, 5-99
OPC_GET_SIGNAL_ALARM_TYPE() 3-10, 5-100
OPC_GET_SIGNAL_APPLICATION_FLAG() 3-11, 5-102
OPC_GET_SIGNAL_APPLICATION_INFO() 3-11, 5-103
OPC_GET_SIGNAL_APPLICATION_SIZE() 3-10, 5-104
OPC_GET_SIGNAL_CONTROL_STATUS() 3-10, 5-105
OPC_GET_SIGNAL_DEADBAND() 3-10, 5-106
OPC_GET_SIGNAL_FLOAT_ARRAY() 3-10, 5-107
OPC_GET_SIGNAL_FLOAT_OLD_VALUE() 3-10, 5-108
OPC_GET_SIGNAL_FLOAT_VALUE() 3-10, 5-109
OPC_GET_SIGNAL_HIGH_HIGH_LIMIT() 3-10, 5-111
OPC_GET_SIGNAL_HIGH_LIMIT() 3-10, 5-110
OPC_GET_SIGNAL_ID() 3-11, 5-112
OPC_GET_SIGNAL_ID_GROUP() 3-11, 5-113
OPC_GET_SIGNAL_ID_NODE() 3-11, 5-114
OPC_GET_SIGNAL_ID_NUMBER() 3-11, 5-115
OPC_GET_SIGNAL_ID_SUB() 3-11, 5-116
OPC_GET_SIGNAL_INSTALLATION() 3-11, 5-117
OPC_GET_SIGNAL_INTEGER_ARRAY() 3-10, 5-118
OPC_GET_SIGNAL_INTEGER_OLD_VALUE() 3-10, 5-119

Index
OPC_GET_SIGNAL_INTEGER_VALUE() 3-9, 5-120, 5-128, 5-129

OPC_GET_SIGNAL_LOCKED() 5-121
OPC_GET_SIGNAL_LOW_LIMIT() 3-10, 5-122
OPC_GET_SIGNAL_LOW_LOW_LIMIT() 3-10, 5-123
OPC_GET_SIGNAL_MERGED_STATUS() 3-10, 5-124
OPC_GET_SIGNAL_OPTION_STATUS() 3-10, 5-125
OPC_GET_SIGNAL_QUALITY() 3-10, 5-126
OPC_GET_SIGNAL_STATUS() 3-10, 5-127
OPC_GET_SIGNAL_SUB() 3-11, 5-130
OPC_GET_SIGNAL_TAG() 3-11, 5-131
OPC_GET_SIGNAL_UNIT() 3-11, 5-132
OPC_GET_SIGNAL_UPDATE_TIME() 3-11, 5-133
OPC_GET_STRING() 3-9, 3-12, 5-134
OPC_GET_STRING_GLOBAL_ATTRIBUTE() 3-9, 5-135
OPC_GET_STRING_LOCAL_ATTRIBUTE() 3-9, 5-136
OPC_GET_TIMER_STATUS() 3-9, 5-89, 5-90, 5-92, 5-137, 5-143, 5-144, 5-146
OPC_GET_TIMER_VALUE() 3-9, 5-138
opc_id 2-3, 5-10
OPC_INTEGER 3-12
opc_obj_dbg() 2-15, 5-51
opc_obj_def 2-10, 5-10
opc_obj_del() 2-15, 5-52
opc_obj_dtrg() 2-15, 2-16, 5-13, 5-53
OPC_OBJ_FOREVER 5-12
opc_obj_get() 2-14, 5-54
opc_obj_ins() 2-10, 2-13, 5-55
opc_obj_itrg() 2-15, 2-16, 5-13, 5-57
opc_obj_mod() 2-15, 5-58
opc_obj_name 5-12
opc_obj_ntrg() 2-15, 5-13, 5-59
opc_obj_nxt() 2-14, 5-60
opc_obj_res() 2-5, 2-15, 5-61
OPC_OBJ_STARTED 5-12
opc_obj_trg() 2-15, 5-62
opc_obj_trg_id 5-13
opc_opn_evt() 5-63, 5-64
OPC_PRINT() 3-14, 5-139
OPC_REP_FLOAT 3-2, 3-6
OPC_REP_INTEGER 3-2, 3-6
OPC_REP_STRING 3-2, 3-6
OPC_RET_FLOAT() 3-13, 5-140
OPC_RET_INTEGER() 3-13, 5-141
OPC_RET_STRING() 3-12, 3-13, 5-142
OPC_SET_FLOAT() 3-9, 5-147
OPC_SET_FLOAT_GLOBAL_ATTRIBUTE() 3-9, 5-148
OPC_SET_FLOAT_LOCAL_ATTRIBUTE() 3-9, 5-149
OPC_SET_INTEGER() 3-9, 5-150
OPC_SET_INTEGER_GLOBAL_ATTRIBUTE() 3-9, 5-151
OPC_SET_INTEGER_LOCAL_ATTRIBUTE() 3-9, 5-152

Index
OPC_SET_ITEM_VALUE() 5-153
OPC_SET_ITEM_VALUES() 5-154
OPC_SET_SIGNAL_APLLICATION_FLAG() 3-11
OPC_SET_SIGNAL_APPLICATION_FLAG() 5-156
OPC_SET_SIGNAL_APPLICATION_INFO() 3-11, 5-157
OPC_SET_SIGNAL_DEADBAND() 3-10, 5-158
OPC_SET_SIGNAL_FLOAT_ARRAY() 3-10, 5-159
OPC_SET_SIGNAL_FLOAT_VALUE() 3-10, 5-160
OPC_SET_SIGNAL_HIGH_HIGH_LIMIT() 3-10, 5-162
OPC_SET_SIGNAL_HIGH_LIMIT() 3-10, 5-161
OPC_SET_SIGNAL_INTEGER_ARRAY() 3-10, 5-163
OPC_SET_SIGNAL_INTEGER_VALUE() 3-9, 5-164, 5-169
OPC_SET_SIGNAL_LOW_LIMIT() 3-10, 5-165
OPC_SET_SIGNAL_LOW_LOW_LIMIT() 3-10, 5-166
OPC_SET_SIGNAL_QUALITY() 3-10, 5-167
OPC_SET_SIGNAL_STATUS() 3-10, 5-168
OPC_SET_STRING() 3-9, 5-170
OPC_SET_STRING_GLOBAL_ATTRIBUTE() 3-9, 5-171
OPC_SET_STRING_LOCAL_ATTRIBUTE() 3-9, 5-172
OPC_SET_TIMER_STATUS() 3-9, 5-173
OPC_SET_TIMER_VALUE() 3-9, 5-174
opc_sig_rd() 2-18, 5-66
opc_sig_upd 2-18, 5-13
OPC_STRING 3-12
OPC_TASK_NUMBER 3-14, 5-175
OPC_TRG_01 2-16, 5-15
OPC_TRG_1M 5-15
OPC_TRG_1W 5-15
OPC_TRG_1Y 5-15
OPC_TRG_2M 5-15
OPC_TRG_3M 5-15
OPC_TRG_4M 5-15
OPC_TRG_4W 5-15
OPC_TRG_6M 5-15
opc_trg_def 5-14
opc_trg_del() 2-17, 5-67
OPC_TRG_FOREVER 5-15
opc_trg_get() 2-17, 5-68
opc_trg_ins() 2-16, 5-69
opc_trg_mod() 2-17, 5-71
opc_trg_nxt() 2-17, 5-72
OPC_TRG_STARTED 5-15
OPC_TYPE_GLOBAL_ATTRIBUTE 3-2
OPC_TYPE_LOCAL_ATTRIBUTE 3-2
OPC_TYPE_SIGNAL 3-2
OPC_TYPE_TIMER 3-2
OPC_UMH_CONTEXT 3-13, 5-176
opc_usr.c 3-15
opc_usr.inc 3-6

Index
OPCACT 1-3
OPCCOM 1-3
OPCEXE 1-3
OPCJACT 1-3
OPCJCOM 1-3
OPCJEXE 1-3
OPCLOA 1-3
OPCMAN 1-3, 2-1
P
parameters
class 1-1
object 1-2
trigger group 1-3
priority
class 1-1
object 1-2
PROCESS/FAST language 1-1
programmers interface 1-4
configuration 1-4
functions 1-4
quick load 1-5
prompt 2-8
S
signal 1-2, 2-7, 2-18, 3-2, 3-9
string 3-2, 3-6, 3-9, 3-13
support functions 3-9, 5-72
T
time window
object 1-2
trigger group 1-3
timer 3-9
trigger group 1-2

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction REPORT/FAST FAST/TOOLS
IM50Q02Q01-01EN/R10.03

IM50Q02Q01-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
0.5 Conventions ...............................................................0-2
1 Introduction ..........................................................................1-1
1.1 Introduction ...............................................................1-1
1.2 REPORT/FAST .........................................................1-1
1.2.1 Functionality ............................................................. 1-1
1.2.2 Environment .............................................................. 1-2
1.3 RPT ............................................................................1-3
1.4 Programmer’s interface .............................................1-5
2 Report maintenance .............................................................2-1
2.1 Introduction ...............................................................2-1
2.2 Report definition ........................................................2-1
2.4 Creation of a report definition ...................................2-2
2.4.1 Report attributes ........................................................ 2-2
2.4.2 Report description ..................................................... 2-3
2.4.3 Report scheduling ..................................................... 2-4
2.4.4 Report event .............................................................. 2-5
2.4.5 Process areas ............................................................. 2-6
2.5 Modification of a report definition ............................2-7
2.5.1 Report attributes and schedule parameters ............... 2-7
2.5.2 Event parameters ....................................................... 2-7
2.5.3 Report description ..................................................... 2-7
2.5.4 Process areas ............................................................. 2-7
2.6 Deletion of a report definition ...................................2-8
2.7 Obtaining information ...............................................2-8
2.7.1 Report definition information ................................... 2-8
2.7.2 Generated reports ...................................................... 2-9
3 Report generation .................................................................3-1
3.1 Introduction ...............................................................3-1
3.2 Report generation ......................................................3-1
3.4 Ad-hoc generation .....................................................3-2
3.5 Cancel generation ......................................................3-3
RPT Programmer’s Guide iii

Table of Contents
3.6 Non-defined generation ............................................ 3-3

3.6.1 Direct mode ............................................................... 3-4
3.6.1.1 Initiation .................................................................... 3-4
3.6.1.2 RQL statements ......................................................... 3-4
3.6.1.3 Termination ............................................................... 3-6
3.6.2 Indirect mode ............................................................ 3-6
4 Creating new RQL functions .............................................. 4-1
4.1 Introduction ............................................................... 4-1
4.2 Grouping and non-grouping functions ...................... 4-1
4.3 RQL function arguments and function result ............ 4-2
4.4 Defining user functions ............................................. 4-2
4.5 Related C-function arguments .................................. 4-3
4.6 Argument variables ................................................... 4-4
4.7 Non-grouping actions ................................................ 4-5
4.7.1 Check the number of supplied arguments ................. 4-5
4.7.2 Pop the arguments from the function stack ............... 4-6
4.7.3 Perform the calculation ............................................. 4-6
4.7.4 Push the result on the function stack ......................... 4-6
4.8 Grouping actions ....................................................... 4-7
4.8.1 Add non-distinct ........................................................ 4-7
4.8.2 Add distinct ............................................................... 4-8
4.8.3 Return result .............................................................. 4-8
4.9 Steps to implement users functions ........................... 4-8
4.10 A non-grouping function example ............................ 4-9
4.11 A grouping function example ................................. 4-11
5 Reference guide .................................................................... 5-1
5.1 Introduction ............................................................... 5-1
5.2 Compiling, Linking and Running Programs ............. 5-1
5.3 Error Handling .......................................................... 5-1
5.4 General data structures .............................................. 5-2
5.4.1 struct rpt_def ............................................................. 5-2
5.4.2 struct rpt_event_def ................................................... 5-4
5.4.3 struct rpt_adhoc ......................................................... 5-5
5.4.4 struct rpt_adhoc_usr .................................................. 5-6
5.4.5 struct rpt_cancel ........................................................ 5-6
5.4.6 struct rpt_info ............................................................ 5-6
5.4.7 structs rpt_s_dir, rpt_r_dir, rpt_s_dir_rql
and rpt_s_dir_done .................................................... 5-7
5.4.8 structs rpt_s_ind and rpt_r_ind ................................. 5-8
5.4.9 struct rpt_cont ........................................................... 5-9
5.4.10 struct rpt_fnc_def ...................................................... 5-9
5.4.11 struct rpt_var ........................................................... 5-10
5.5.1 Create a report definition ........................................ 5-11
5.5.2 Modify a report definition ....................................... 5-12
5.5.3 Delete a report definition ........................................ 5-13
iv RPT Programmer’s Guide

Table of Contents
5.5.4 Generate a report (AD-HOC) .................................. 5-14

5.5.5 Generate a report with user information (AD-HOC) 5-15
5.5.6 Get a report definition ............................................. 5-16
5.5.7 Edit query text ......................................................... 5-17
5.5.8 Finish or Cancel editing .......................................... 5-18
5.5.9 Get the report event information ............................. 5-19
5.5.10 Modify the report event information ....................... 5-20
5.5.11 Delete the report event information ........................ 5-21
5.5.12 Generate a report (DIRECT) ................................... 5-22
5.5.13 RQL statement ........................................................ 5-23
5.5.14 Terminate a direct generation ................................. 5-24
5.5.15 Generate a report (INDIRECT) .............................. 5-25
5.5.16 Cancel a session ...................................................... 5-26
5.5.17 Pop an argument from the function stack ............... 5-27
5.5.18 Set the return value of the user function ................. 5-28
5.5.19 Allocate an argument variable ................................ 5-29
5.5.20 Release an argument variable ................................. 5-30
RPT Programmer’s Guide v

Table of Contents
vi RPT Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives

functionality of the application interface of RPT.
• To provide experienced users with a reference to the use of the
RPT application interface.

language.The reader is assumed to have knowledge of the BUS/FAST
and HISTORY/FAST tools of the FAST/TOOLS set.

This manual contains 5 chapters.
• Chapter 1 introduces the reader to the RPT application interface.
• Chapter 2 describes the maintenance of report definitions.
• Chapter 3 describes the generation of reports.
• Chapter 4 describes the creation of new RQL functions.
alphabetical order.

• FAST/TOOLS Installation Manual
This manual provides the information necessary to install
REPORT/FAST on your system.
RPT Programmer’s Guide 0-1

Preface Conventions
• REPORT/FAST System Integration Manual

This manual supplies additional information about
REPORT/FAST.
• REPORT/FAST Language Manual
This manual provides information necessary to describe reports.
• BUS/FAST Programmer’s Guide Volumes 1, 2 and 3
The programmer’s interface between REPORT/FAST and your
application in a BUS/FAST interface. The BUS/FAST
Programmer’s Guide supplies the information required to use such
a BUS/FAST interface.
• HISTORY/FAST Programmer’s Guide
REPORT/FAST and HISTORY/FAST interact closely with each
other. Some functions of REPORT/FAST require knowledge of the
programmer’s interface to HISTORY/FAST.
0.5 Conventions
CONVENTIONMEANING
( ) Used in routine syntax to indicate a list of arguments that have to be

passed.
<name>Indicates that <name> has to be replaced by the actual function

or statement argument.
[ ] Indicates that the enclosed item is optional.
[,...]Indicates that the previous item may be repeated one or more times.
{ }..Indicates that the previous enclosed items may be repeated one or

more times.
... Indicates that not all of the items are shown.
UPPERCASEIndicates reserved words and predefined letters names,

e.g. NULL, TRUE, DUR_NOWAIT.
n.u. not used
0-2 RPT Programmer’s Guide

Conventions Preface
outputThis typesetting is used to indicate output on a terminal.
inputThis typesetting is used to indicate input from the user.

Preface Conventions

Introduction Introduction
1 Introduction
1.1 Introduction
This chapter introduces the reader to the functionality of RPT. The
following items are discusses in this chapter:
• Global overview of REPORT/FAST
• Position of RPT within REPORT/FAST
• Programmers interface for RPT
1.2 REPORT/FAST
1.2.1 Functionality
REPORT/FAST is one of the tools in the FAST/TOOLS collection and

facilitates the definition, generation and inspection of reports containing
data from various FAST/TOOLS data sets.
Data from different FAST/TOOLS sets can be combined in a single

report.
The data sets are defined in a data dictionary. Data set definitions can be
added, modified or deleted by using the DATABASE/FAST Data
Dictionary Language (DDL).
To define a report, a system user selects the proper menu entry in the
USER/FASTmenu three. This action activates an interactive editor
allowing edit operations for new or existing report definitions. Reports
are defined using an extension of the well known SQL query language.
Reports which have been defined may be generated on an ad hoc basis

via the appropriate USER/FAST menus. Report selection is done using
the name of the report definition as defined in the definition procedure.
Alternatively, report generation may be scheduled via a report
scheduling mechanism or on an event basis.
Scheduling options are:
• Once only at a future date and time

Introduction REPORT/FAST
• Repeatedly starting at a future date and time

• Generated report lifetime
Generated reports may be routed automatically to named print spoolers.

The user may give these destinations during the report definition
procedure. In addition, they may optionally be changed during the report
generation transaction for ad-hoc generation.
Generated reports can also be inspected using the standard USER/FAST
browser facility.
A USER/FAST menu entry is provided for ad-hoc data set inspection

using the REPORT/FAST SQL language interactively.
Application gateways are provided at report generation time to establish
communication between REPORT/FAST and applications, using the
BUS/FAST message passing facilities.
1.2.2 Environment
Figure 1-1 shows the relation of REPORT/FAST to other

FAST/TOOLS.
USER/
FAST
Report Report
definitions output
Application data
Report scheduling
info REPORT/
Item status & value FAST
item history Current alarms and
report event alarm history
class/object
Data dictionary Database data information
info
PROCESS/ APPLI-
HISTORY/ ITEM/ DATABASE/ ALARM/ CATIONS
FAST FAST FAST FAST FAST
Fig. 1-1 REPORT/FAST within its environment
Communication with other FAST/TOOLS is realized using the

BUS/FAST message passing functions or tool support routines.

RPT Introduction
USER/FAST/ is the user interface to REPORT/FAST allowing the user

to define, schedule, generate and examine reports. Reports can also be
output to printers.
HISTORY/FAST is ‘misused’ to handle the scheduling of reports.
ITEM/FAST generates report events (events which result in a report

being generated) and both real-time data and history data are passed to
REPORT/FAST if required in a report.
DATABASE/FAST supplies the data dictionary info making it possible

for REPORT/FAST to retrieve data. DATABASE/FAST also handles
the data retrieval of standard DATABASE files.
ALARM/FAST supplies current and history alarm info for report

purposes.
PROCESS/FAST gives actual information of the active objects in the

system and the available classes.
REPORT/FAST is not limited to handling FAST/TOOLS data sets.

Describing data sets, application data sets and applications can be added.
1.3 RPT
REPORT/FAST itself is split up into several functional blocks, as shown
in figure 1-2.

Introduction RPT
USER/
FAST
Report Report
definitions output
Ad-hoc
query
RPT brick
Activate generation
Report
definitions Report
quickload manager definitions generator Reports
Set
scheduling &
scheduling
info
Item history
Item data
history RPI brick
chrono.. database server Application
server server data
Current Class,
Database Event alarms & object &
data Data alarm trigger
history group info
dict. event item alarm process appli.

server server server server server server
AUDIT/ ITEM/
HISTORY/ DATABASE/ FAST ALARM/ PROCESS/ APPLI-
FAST FAST FAST FAST
FAST CATIONS
Fig. 1-2 REPORT/FAST components
REPORT/FAST is divided into two bricks:

• RPT
The RPT brick includes the manager and generator. This manual
describes the programmer’s interface for this brick. The RPT brick
is divided into two functional blocks (which are also distinct
processes):
- The manager
The manager is responsible for managing report definition and

Programmer’s interface Introduction
report activation. It communicates with USER/FAST to receive

report definition and scheduling, event and generation info. It
communicates with HISTORY/FAST to define report
scheduling and to receive schedule commands. Report
definitions are stored and when a report has to be generated the
generator is instructed to do so.
- The generator
The generator generates the report and uses the report definition
as input. The generation of a report is started at the command of
the manager. It interprets the report definition, accesses the
dictionary server to get the required data sets info and accesses
data servers to receive the required report data. The report data
is combined to the specified layout and stored in the report file.
Report definitions can be entered ad-hoc, in which case the
report output is returned to the ad-hoc user. Ad-hoc generations
(queries) are handled by generator process copies to relieve
non-ad-hoc generations.
- Quick load
The quick load utility is used to load report definitions which are
specified in an ASCII file. It is a utility started as required.
- Report stopper
A generator can be instructed to stop the generation of the
current report. This is useful when, for example, the query
contains an infinite loop. Note that this function is also available
within USER/FAST.
• RPI
The RPI brick is the data set interface between RPT and the
FAST/TOOLS. Whenever the generator has to access either a data
set or the data dictionary to retrieve information, the information
source is accessed by an RPI data set server.
1.4 Programmer’s interface

The RPT brick interfaces with RPI and several FAST/TOOLS as
described in the previous sections. The interfaces to the various
FAST/TOOLS, with the exception of USER/FAST, are described in the
appropriate Programmer’s Guides for these tools. The interface between
RPT and RPI is described in the RPI Programmer’s Guide. The interface
between RPT and USER/FAST is an open interface and is described in
this manual. This interface enables the application programmer to

Introduction Programmer’s interface
maintain (i.e. create, modify, delete or generate) reports without using

the USER/FAST user interface. The RPT manager is used for this
purpose.
The manager issues generate commands to the generator. This interface
between the manager and the generator is also an open interface and is
also described in this manual.
Note that it is possible to add your own set of RQL functions.
The System Integrator can create his own functions while using the
interface routines (described in a separate chapter) and link these to the
existing report generator.

Introduction Report maintenance
2 Report maintenance
2.1 Introduction
Typically, reports are maintained using the standard FAST/TOOLS user
interface USER/FAST. This user interface enables the REPORT/FAST
user to define, modify and delete report definitions. An application
programmer is allowed to modify this user interface and/or write his
own user interface for REPORT/FAST. This chapter describes how
report definitions are maintained by RPT and describes the application
interface enabling the System Integrator to maintain report definitions.
The following items are discussed in this chapter:
• Report definition
• Programmer’s interface
• Creation of a report definition
• Modification of a report definition
• Deletion of a report definition
• Obtaining information about defined and generated reports
2.2 Report definition

A report definition contains all the information required by RPT to
output reports. Such a report definition contains two types of
information:
1 Attributes:
Report attributes do not influence the appearance of the report. The
attributes specify, amongst others, the name of the report, a short
description, the destination for a generated report, and schedule
information.
2 Description:
The report description is a collection of RQL statements describing
the appearance of the report.
This information is maintained by the RPT manager with the help of

HISTORY/FAST. HISTORY/FAST takes care of maintaining the
names of the reports and the files where the report attributes, report
description and report output are stored by RPT.

Report maintenance Programmer’s interface

The report definition is maintained by the RPT process RPTMAN. The
programmer’s interface to this process is a BUS/FAST message
interface. There is no routine interface available.
All requests for the report definition maintenance should be directed to
the RPT process RPTMAN.
2.4 Creation of a report definition

To create a report definition two basic steps must be followed. These
steps are the creation of the report attributes and the specification of the
report description. Optionally, schedule, event and process area
parameters can be specified.
2.4.1 Report attributes
A report is created by the procedure RPT_CREATE. The following

information has to be passed:
• The name of the report.
No other report or HISTORY/FAST group may have this name. If
such a name already exists, an error is returned by RPT. Note that
report names are case sensitive.
• A short informational description of the report.
This description is accessible within the report description for
output into a report.
• The destination for a report just generated.
Three options are available:
- RPT_FILE_ONLY The report is output to a text file only.
- RPT_PRINTER The report is output to a text file and then
spooled to the systems printer.
- RPT_UMHLOG The report is output to a text file and then
spooled to the systems error logger
(UMHLOG).
• The priority of the report.
When several reports have to be generated at the same time, reports
with a higher priority will be generated before reports with a lower
priority. This is only true when more than one generator is active in
the system which are set up to handle distinct priority ranges. The

Creation of a report definition Report maintenance
‘REPORT/FAST System Integrator’s Manual’ contains more

information on this subject.
• Ad-hoc generation flag.
RPT can be requested to generate a report immediately by the
RPT_ADHOC request. The ad-hoc flag indicates if such a generate
request is allowed for that report. If the flag indicates that the
ad-hoc request is not allowed, the report can only be generated by
specifying scheduling for the report.
• Prompt query text.
A maximum count of RPT_PARAM_CNT prompt texts can be
specified for the report. This prompt text is intended to be used with
the ad-hoc request. However, this information is not interpreted by
RPT and can be used for other purposes.
Upon receiving the create request, RPT creates the report and the
specified information is stored. RPT returns the same information as
specified in the request once the create is realized. From this point on,
the report definition is know by RPT. However, the layout of the report
and the report description have yet to be defined. Optionally, report
scheduling can be defined.
2.4.2 Report description
When a report definition is created by the RPT_CREATE request, the

report description must be specified. The default report description
contains no RQL statements and when the report is generated a blank
report will be output. A report description is entered or modified in three
steps, the edit request, the actual RQL statement specification and the
done request.
Edit request
Before a report description can be entered or modified, the modification

must be granted by RPT to avoid interaction by other active report
description modifications of the same report. This modification
permission is requested by the RPT_EDIT request. The name of the
report description to edit has to be supplied. When the edit permission is
granted the name of the report and the name of the file containing the
current report description are returned. An error is returned if the report
description is not allowed to be modified.

Report maintenance Creation of a report definition
RQL statements
The name of the file containing the current report description is returned
by the create request. This file is a plain text file and contains the RQL
statements for the report. It is the programmer’s responsibility to modify
the contents of this file. One way of doing this is to spawn the system
text editor thereby allowing the user to edit the file.
Done request
When the report description file has been edited or examined, RPT has
to be informed of this event. This is done by the RPT_EDIT_DONE
request. The name of the report being modified and the name of the file
containing the modified report description must be supplied.
If the report has to be generated when an edit session is active, the report
description prior to the create request will be used. The modified report
description will be used when the done request is handled by RPT.
Note: If the done request is omitted after a created

request, the report description can not be
modified any more until REPORT/FAST is
restarted. However, it is still possible to
generate the report.
2.4.3 Report scheduling
Optionally, the report can be scheduled for automatic generation. The

RPT_MODIFY request is used for this purpose. The following
information must be supplied:
• The name of the report to schedule.
• A flag (RPT_SCHEDULE_FLG) indicating that schedule
parameters are specified.
• Scheduled generation. The time of the next generation of the report.
• The generation interval. When this is defined as zero, the report is
generated once when the time of the next generation lies in the
future.
• Interval type (GMT/LCT) indicating how summer/winter time
occurrences must be taken into account with the generation
interval.
• Generated report lifetime. This time specifies how long a generated
report will exist. A zero specifies an eternal lifetime.

Creation of a report definition Report maintenance
The scheduled generation and lifetime must be specified in seconds

since 1970. The generation interval is specified in seconds. The
HISTORY/FAST Programmer’s Guide describes how to specify special
intervals such as monthly, weekly, etc.
When a report is created by the RPT_CREATE request, RPT

automatically defines a report lifetime of 7 days to avoid generated
reports being accumulated.
2.4.4 Report event
Optionally, a process variable can be specified which starts the

generation of the report when its value and/or status changes and the new
value and/or status satisfies a specified filter. The
RPT_MODIFY_EVENT request is used for this purpose. The following
information must be specified:
• The name of the report to specify an event process variable for.
• A flag (RPT_EVENT_FLG) indicating that event parameters are
supplied.
• The item id whose value and/or status must be monitored.
• The relational expression which specifies the filter.
• The delay (in seconds). The report will be generated after a period
of time equal to the number of seconds specified here from the
moment the new value and/or status of the item satisfies the filter.
A delay of zero seconds can be specified.
The relational expression contains some sub-relational expressions

connected to each other by the logical operator. The relational
expression has the following layout:
new_value relational_operator1 constant_value1

[logical_operator new_value relational_operator2 constant_value2]
[OR new_status relational_operator3 constant_status1]
[OR new_status relational_operator4 constant_status2]
The new_value is the new value of the item when its value or status
changed.
The relational_operator(1,2,3,4) can be one of:
• RPT_EVT_EQ, equal to,
• RPT_EVT_NEQ, not equal to,
• RPT_EVT_GRT, greater than,
• RPT_EVT_GRTE, greater than or equal to,

Report maintenance Creation of a report definition
• RPT_EVT_LW, less than,

• RPT_EVT_LWE, less than or equal to,
• 0 (zero), when zero, this relational sub-expression is not used.
The constant_value(1,2) is a string containing an ASCII number.

The logical_operator can be one of:
• RPT_EVT_AND, and,
• RPT_EVT_OR, or.
The new_status is the new status of the item when its value or status
changed.
The constant_status(1,2) can be one of:
• RPT_EVT_LOW,
• RPT_EVT_LOW_LOW,
• RPT_EVT_HIGH,
• RPT_EVT_HIGH_HIGH,
• RPT_EVT_BLOCKED,
• RPT_EVT_NORMAL,
• RPT_EVT_OFFLINE,
• RPT_EVT_UNDER,
• RPT_EVT_OVER.
All the items making up the relational expression, except for new_value
and new_status, must be specified in the filter.
2.4.5 Process areas
Optionally, process areas for the report can be specified. generation of

the report when its value and/or status changes and the new value and/or
status satisfies a specified filter. The RPT_MODIFY_EVENT request is
used for this purpose. The following information must be specified:
• The name of the report to specify process areas for.
• A flag (RPT_PROC_AREA_FLG) indicating that process areas are
supplied.
• Up to 16 process area numbers can be specified.
Note that REPORT/FAST itself does not interpret process areas. It just
stores them with the other report definitions. However accessing the
REPORT_VAL dataset uses this information to verify whether the user
is authorized to generated and print the report.

Modification of a report definition Report maintenance
2.5 Modification of a report definition

All report attributes (including schedule parameters) and the report
description can be modified.
2.5.1 Report attributes and schedule parameters
Report attributes or schedule parameters are modified with the

RPT_MODIFY request. A flag indicates which one of the two must be
modified. RPT_GENERAL_FLG specifies the modification of
attributes. All attributes except the name of the report can be modified.
The following information has to be passed:
• The name of the existing report.
• A short informational description of the report.
• The destination for a report just been generated.
• The priority of the report.
• Ad-hoc generation flag.
• Prompt query text.
The supplied attributes overrule the current attributes for the report.
Sub-section ‘Report scheduling’ describes how to modify the report
schedule parameters.
2.5.2 Event parameters
Event parameters are modified with the RPT_MODIFY_EVENT in the

same way as defining event parameters. Sub-section ‘Report event’
describes how to define and to modify event parameters.
2.5.3 Report description
A report description is modified in the same way as described in section

‘Creation of a report definition’.
2.5.4 Process areas
The process areas of a report are modified in the same way as described
in section ‘Creation of a report definition’.

Report maintenance Deletion of a report definition
2.6 Deletion of a report definition

When a report definition is deleted, all information about the report is
removed from the system, including generated reports. It is not possible
to delete schedule parameters or a report description on its own.
The deletion of a report definition is done by the RPT_DELETE request.

The name of the existing report definition to delete must be supplied.
The event parameters can be deleted by the RPT_DELETE_EVENT

request. The name of the report whose event parameters must be deleted
has to be specified.
2.7 Obtaining information

Two types of information can be obtained, report definition information
and generated reports.
2.7.1 Report definition information
Report definition attributes, excluding the event parameters, of existing

reports can be obtained by the RPT_GET, RPT_NEXT and RPT_INFO
requests. The RPT_GET returns information about the report of the
report name specified in the request. If this report definition does not
exist, information about the next report name, in alphabetical order, is
returned. The RPT_NEXT request always returns information about the
next report.
A flag must be added to the request to specify the information required.
This flag can be RPT_GENERAL_FLG to obtain the attributes such as
informational description, printer destination, file path. All information
about the report (definitions and generated reports) are stored on this
path. The flag can be RPT_SCHEDULE to obtain the schedule
parameters.
The RPT_GET_EVENT and RPT_NEXT_EVENT requests must be

used to retrieve the event parameters of the specified report name
(RPT_GET_EVENT) or the next report definition
(RPT_NEXT_EVENT).

Obtaining information Report maintenance
The RPT_INFO request requires the name of an existing report. The

request returns the informational description and the name of the file
containing the report description. This request is used by the generator
to obtain information about a report being included by the INCLUDE
statement.
2.7.2 Generated reports
A generated report is stored in a plain text file on the disk. The location,
the file path, is defined in the set-up file of the report manager (see the
REPORT/FAST System Integration Manual).
These report files are maintained by the manager in conjunction with
HISTORY/FAST. The name of the report files are defined by
HISTORY/FAST. HISTORY/FAST also takes care of deleting a report
file when its life has expired. Obtaining the file names of the generated
reports requires three steps:
• First the file path where the files are stored must be obtained by the
RPT_GET or RPT_NEXT request.
• Second, the so called unit information has to be obtained by the
HIS_INFO_UNIT request to the HISTORY/FAST HIS process.
This unit information is actually a list of identifications of
generated reports of a certain report in a specific time window. It is
possible that this request will have to be repeated to obtain all units
when many reports are generated. The input for this request is the
name of the report (group name in HISTORY/FAST terms) and the
time window. The request returns the unit information created
during the specified time window. A single unit contains the time
of creation (generation) and the so-called group and unit numbers.
• Finally, the HISTORY/FAST routine his_fname() has to be called.
This routine constructs the name of the file from the path and
group/unit numbers of a certain unit. This file contains the
generated report.
The HISTORY/FAST Programmer’s Guide supplies more information

about obtaining unit information.

Report maintenance Obtaining information

Introduction Report generation
3 Report generation
3.1 Introduction
Typically, generation of reports is initiated by the manager when
schedule conditions are met or when an ad-hoc generated request is
issued via the USER/FAST user interface. This chapter informs the
reader on how to issue an ad-hoc generate request to the manager and
how to generate reports without the intervention of the manager
(non-defined request). This chapter is divided into the following
sections:
• Report generation
• Programmer’s interface
• Ad-hoc generation
• Non-defined generations
3.2 Report generation

Chapter 1 described the RPT brick as consisting of two functional
blocks. The manager maintains report definitions and issues generate
requests of defined reports to the generator. The generator has no
knowledge about report definitions. It simply receives a generate request
from the manager containing basically two file names: the name of the
file containing the report description and the name of the file in which
the report has to be output.
This interface to the generator is open and allows the application
programmer to generate reports without interventions from the manager.
Such generations are called non-defined generations because it allows
the generation of reports which are not defined in the normal manner via
the report manager. However, for non-defined generations a dedicated
generator has to be activated which will not make itself known to the
manager by the RQL LOGIN statement. It is not allowed to issue
requests to a generator which is logged-in at the manager because the
manager has control over it. More information about this subject can be
found in the REPORT/FAST System Integration Manual.
Generation of a defined report can be forced by the so called ad-hoc

generate request to the manager.

Report generation Programmer’s interface

The ad-hoc generate and cancel request have to be issued to the RPT
process RPTMAN.
The non-defined generate requests are issued to a report generator
activated for that purpose.
3.4 Ad-hoc generation

The generation of a defined report can be initiated when the schedule
parameters are met or by issuing the RPT_ADHOC or the
RPT_ADHOC_USR request. The RPT_ADHOC_USR supersedes the
RPT_ADHOC request and enabled you to supply user information in
addition to the information the RPT_ADHOC request requires.
Both the RPT_ADHOC and RPT_ADHOC_USR requests requires the

following information:
• The name of the report to generate.
• An array of RPT_PARAM_CNT report parameters. This is an array
of ASCIZ strings. These strings are not interpreted by the manager
and are available by the RQL variables @P0 to @P7 within the
report description.
• A message code for the ‘generation finished’ request from the
manager to the initiating process when the report generation is
completed. When this message code is 0, the manager will not send
a message when the generation is finished.
• The report destination. Possibilities are RPT_FILE_ONLY,
RPT_PRINTER, RPT_UMHLOG and 0. A zero instructs the
manager to use the destination specified during report definition.
In addition the following information can be passed when you issue the
RPT_ADHOC_USR request (note that this information is stored with
the generated report and is not interpreted by REPORT/FAST):
• The name of the terminal where the request came from.
• The name of the user that issued the request.
• The BUS/FAST address of the invoking process.
• A reason for the adhoc request.
An error is returned if ad-hoc generations are not allowed for the report.

Cancel generation Report generation
The ‘generation finished’ request from the manager contains the name
of the file containing the generated report.
The manager can be instructed not to send the ‘generate finished’

request by the RPT_ADH_CAN request to the manager. No information
has to be passed with the RPT_ADH_CAN request. Note that the
generation itself can not be cancelled.
These requests are normally used in the following sequence:

• Obtain information of the report to generate using the RPT_GET
and RPT_NEXT requests. The reply also contains the prompt query
text specified during report creation. This text can be used to
prompt the user for the report parameters.
• Issue the RPT_ADHOC request specifying that the manager has to
send a request when the generation is finished.
• Wait and perform one of the following:
- The ‘generation finished’ request from the manager is received.
Use the supplied file name to show, for example, the generated
report to the user.
- For example, within USER/FAST the user leaves the form.
Issue the RPT_ADH_CAN request to the manager. However,
the ‘generation finished’ request can still be received because is
could have been sent just before the cancel request was received
by the manager.
3.5 Cancel generation

A report which is being generated or currently queued to be generated
by the manager can be cancelled by issuing the RPT_CANCEL request.
When being generated the generation process is stopped immediately for
the report. When queued then the report is removed from the queue. A
single report can be cancelled or all reports can be cancelled.
3.6 Non-defined generation

Two modes can be distinguished: direct and indirect. In the direct mode,
requests containing RQL statements are issued to the generator. When
such a statement generates output, this output is directed by the

Report generation Non-defined generation
generator to the originator by means of requests.

In the indirect mode, a request is sent to the generator containing the
name of a file containing the report description and the name of the file
to which the generator has to output the report.
3.6.1 Direct mode
Three steps are involved for using the direct mode:

• Initiate the direct session.
• Issue RQL statements and receive results.
• Terminate the direct session.
The generator is able to handle a single direct session at one time.
3.6.1.1 Initiation
A direct session is initiated by the RPT_S_DIR request. This request

requires the following information:
A name for the session.

Result message code. This message code is used by the generator when
it returns the result of issued RQL statements.
An error is returned when the generator is busy with a direct or indirect
generation. A successful action is acknowledged with an identification.
This identification has to be used in all subsequent requests to the
generator until the session is terminated.
From now on requests can be issued containing RQL statements.
3.6.1.2 RQL statements
When the session is initiated, any number of RQL statements can be

issued to the generator. If a statement generated a report output then this
output is sent to the originator using the message code specified in the
session initiation.
The RQL statement is sent to the generator by the RPT_S_DIR_RQL
request. The following information has to be supplied:
Session identification as returned by the RPT_S_DIR request.

An ASCII buffer containing RQL statements.

Non-defined generation Report generation
The ASCII buffer may not contain ASCII NUL and ‘\n’ characters. The
following RQL statements may by issued to the generator in different
ways:
SET @my_var 12;

SELECT install FROM install_df;
request 1 SET @my_var 12;

request 2 SELECT install FROM install_df;
or
request SET @my_var 12;SELECT install FROM install_df;
or
request 1 SET @my

request 2 _var 12;SELE
request 3 CT install FROM install_df;
The reply to the RPT_S_DIR_RQL request contains the current session

identification.
When an RQL statement results in report output then this output is sent
by the generator to the originator by request, having the message code
as specified in the session initiation. Each distinct report line is sent as a
distinct request. Such a request from the generator contains the current
session identification and an ASCII buffer containing the report line.
This line is terminated by an ‘\n’ character. The request containing the
report line, must be replied upon with a reply message containing the
current session identification. The end of the report output is signalled
via a separate request message containing a terminating zero character
in the body of the message.
From the moment on an application has issued the RPT_S_DIR_RQL

request, interaction with the report generator is asynchronously. The
report generator starts sending report output (via separate requests), until
all report output has been transferred (including the terminating zero
character). The application is allowed to send a “termination” message
to the report generator (see below). However this request will be handled
after the generator has transferred all report output.

Report generation Non-defined generation
3.6.1.3 Termination
The current session can be terminated with the RPT_S_DIR_DONE

request which includes the identification of the current session. This
request is taken into account by the generator as soon as all previously
sent RQL statements are processed.
3.6.2 Indirect mode
The indirect mode is accessed by the RPT_S_IND request. The

following information has to be passed:
• A name for the report.
• A short informational description.
• The name of the file containing the report description.
• The name of the file to output the report into.
• The report parameters. These ASCIZ strings are accessible within
the report description by the @P0 to @P7 variables.
• The finish code. When this code is zero, the reply to this request is
returned by the generator when the report generation is finished. In
all other cases, the reply is returned when both specified files are
opened by the generator. A request is sent by the generator having
a message code as specified by the finish code when the report has
been generated completely.
The reply to the request contains the identification of the session and the
number of errors encountered during the generation. This error count is
only valid when a finish code of 0 was specified.
The finish request from the generator contains the session identification
and the number of errors encountered during the generation.

Introduction Creating new RQL functions
4 Creating new RQL functions
4.1 Introduction
This chapter describes how to extend the RQL language by adding your
own RQL callable functions to the list of predefined RQL functions.
RQL functions can be referenced within RQL statements like the
SELECT and IF statements. For example:
SELECT ABS(field_a) FROM test;
A function added by the System Integrator (a user function) can be
referenced in the same way as any predefined RQL function:
SELECT MY_FUNCTION(field_a) from test;
A user function is written by the System Integrator in the C and binded
with the report generator
The following items are discussed:
• Grouping and non-grouping functions
• RQL function arguments and function result
• How to make user functions known to REPORT/FAST
• The arguments of the related C-routine
• Argument variables
• Non-grouping actions
• Grouping actions
• Steps to implement user functions
4.2 Grouping and non-grouping functions

Recall the previous example:
SELECT ABS(field_a) FROM test;
The ABS function is a non-grouping function, e.g. it returns a value for
each row selected. In the following example a grouping function is
referenced:
SELECT AVG(field_a) from test;
The AVG function returns one value for all rows selected, the average

Creating new RQL functions RQL function arguments and function result
of all rows. This means that the AVG function has to maintain a context
to sum all values and to remember the number of values summed. In the
following example the AVG function is referenced twice.
SELECT AVG(field_a), AVG(field_b) from test;
Thus, the AVG function has to maintain a context for field_a and a
context for field_b. Such a context is called the aggregate context. For
each invocation of a grouping function the related C-function has to
maintain an aggregate context. The C-function is instructed to create
such an aggregate context and is instructed to release (to free) a certain
aggregate context.
4.3 RQL function arguments and function

result
The arguments (except for the DISTINC modifier) supplied to the RQL
function are put by REPORT/FAST on the function stack. The related
C-function receives the number of arguments placed on the function
stack. It uses RPT routine calls to pop the arguments from the function
stack and to store them in special variables: the argument variables.
After performing the algorithm, the function result is put back on the
function stack by a special RPT routine call.
The C-function itself returns a TRUE to indicate successful execution.
It returns FALSE if it has detected an error. In the latter case, the UMH
error context must be set to the correct error identification and
REPORT/FAST will take care of logging the error to the report output
or user.
4.4 Defining user functions

The RPT routine ‘rpt_fnc’ (source file ‘rpt_func.c’)contains a list of user
functions. The routine supplied with REPORT/FAST contains an empty
list. To define or add user functions, this routine must be extended and
compiled and REPORT/FAST must be re-built.
The routine contains three sections:
• A list of related C-function declarations. The C-function related to
the user function must be declared as ‘extern TLS_BOOLEAN’.

Related C-function arguments Creating new RQL functions
• A list of user function declarations. This list defines the relation

between the user function and the related C-function. Each entry is
of type ‘struct rpt_fnc_def’ and contains:
- The name of the user function as referenced within RQL.
- A pointer to the related C-function (which is declared in the
previous section.
- Internal administration which must be filled with ‘NULL,
NULL, 0, 0, 0’.
- The number of arguments which must be supplied to the user
function. A number less than zero means that the number of
supplied arguments may vary.
- Grouping or non-grouping function identification. A grouping
function is identified by RPT_FNC_AGG. A non-grouping
function is identified by RPT_FNC_NAG.
- The user function result representation. This can be:
• RPT_VAR_INT - Integer.
• RPT_VAR_REAL - Real.
• RPT_VAR_STR - String.
• RPT_VAR_UNK - Unknown. The type of the
user function result is unknown, e.g. depending
upon the supplied user function arguments.
- The last member must always be one.
• The third section is the actual routine body and may not be
modified.
It is possible to replace predefined RQL functions with user functions by

referencing the predefined function name in the user function
declaration list. REPORT/FAST first searches the user function
declaration list before searching the predefined function list when it
parses a statement.
4.5 Related C-function arguments

When REPORT/FAST executes a user function, it calls the related
C-function with the following arguments:
• struct rpt_cont *rpt_c
This pointer points to the REPORT/FAST context. It is one of the
arguments to RPT routines called within the C-function. Two
members (struct umh_context umh_c and struct dur_context dur_c)

Creating new RQL functions Argument variables
can be used as required. Others may not be referenced and may not
be modified.
• struct rpt_fnc_def *fnc_c
This pointer points to the user function declaration of the called
user function as defined in routine ‘rpt_fnc’ (see ‘Defining user
functions’). The following members may be referenced or used:
- char *name
The name of the user function which can be added as comment
when setting an error.
Other members may not be referenced or modified.
• TLS_UBYTE argn
This argument supplies the C-function with the number of
arguments supplied to the user function, and thereby the number of
arguments to pop from the function stack.
• TLS_UBYTE fnc
This argument tells the C-function which action to perform:
- RPT_FNC_ADD - The C-function has to perform an ‘add
non-distinct’ action on the supplied user function arguments.
- RPT_FNC_DIS - The C-function has to perform an ‘add
distinct’ action on the supplied user function arguments.
- RPT_FNC_DONE - The C-function has to return the result.
In the case of non-grouping functions, fnc will always be
RPT_FNC_DONE.
• char **agg_c
This pointer points to the location where the C-function must store
the pointer to the aggregate context (only grouping functions).
4.6 Argument variables

The user function supplied arguments must be popped from the function
stack. When doing so (using the RPT routine ‘rpt_pop_arg’) the
argument is stored in an argument variable. The argument variable is
defined by struct ‘rpt_var’ and contains the following members:
• int rep
The representation of the argument:
- RPT_VAR_INT - Integer.
- RPT_VAR_REAL - Real.
- RPT_VAR_STR - String.
- RPT_VAR_NULL - Invalid.
When the representation is RPT_VAR_NULL the C-function must
return a NULL value.

Non-grouping actions Creating new RQL functions
• union value
The value of the argument:
- RPT_INT i - Integer value when the representation is
RPT_VAR_INT.
- RPT_REAL d - Real value when the representation is
RPT_VAR_REAL.
- char s[] - String value when the representation is
RPT_VAR_STR. The string can be accessed, for example, in
the following way:
‘strcpy(a, var->value.s)’.
Storage for the argument variable is allocated by REPORT/FAST. The

routine ‘rpt_pop_arg’ allocates the storage and copies the argument
from the function stack to the argument variable. Storage, occupied by
the argument variable, can be released with the RPT routine
‘rpt_fre_var’.
Besides popping user function arguments into the C-function, argument
variables are also used to push the result onto the function stack. The
function result has to be stored in an argument variable by using the RPT
routine ‘rpt_all_var’. Afterwards, the result can be pushed onto the
function stack by the RPT routine ‘rpt_psh_ret’. The routine
‘rpt_var_all’ allocates storage for the argument variable. This storage is
released by the ‘rpt_psh_ret’ routine.
4.7 Non-grouping actions

A C-function has to perform the following steps in case of a
non-grouping user function:
4.7.1 Check the number of supplied arguments
The C-function argument ‘argn’ must be verified to be correct. When

incorrect the error ‘RPT_E_BADARGCNT’ must be set and the
C-function must return FALSE. For example:
if (argn != 2)
{
TLS_LONG num = (TLS_LONG)argn;
umh_set_code(rpt_c->umh_c, RPT_E_BADARGCNT);
umh_set_val(rpt_c->umh_c, "val1", REP_LONG, (char*)&num);
umh_set_val(rpt_c->umh_c, "val2", REP_STRING, fnc_c->name);
return FALSE;
}

Creating new RQL functions Non-grouping actions
4.7.2 Pop the arguments from the function stack
The user function arguments must be popped from the function stack
and must be checked for correctness, in terms of both representation and
value. For example:
struct rpt_var *arg1, *arg2;
arg2 = rpt_pop_arg(rpt_c);
if (arg2 == NULL || arg1 == NULL) return FALSE;
if (arg1->rep == RPT_VAR_NULL || arg2->rep == RPT_VAR_NULL)

{
arg1->rep = RPT_VAR_NULL;
rpt_fre_var(rpt_c, arg2);
rpt_psh_ret(rpt_c, arg1);
return TRUE;
}
if (arg1->rep != RPT_VAR_INT || arg2->rep != RPT_VAR_INT)

{
umh_set_code(rpt_c->umh_c, RPT_E_BADARGTYP);
umh_set_com (rpt_c->umh_c, fnc_c->name);
return FALSE;
}
Note that the first call to routine ‘rpt_pop_arg’ returns the last argument
supplied to the user function.
4.7.3 Perform the calculation
When the user function arguments are popped and checked the
calculation can be performed. For example:
arg1->value.i = arg1->value.i + arg2->value.i;
4.7.4 Push the result on the function stack
The result of the calculation must be pushed on the function stack. For
example:
return TRUE;

Grouping actions Creating new RQL functions
4.8 Grouping actions

The steps a grouping function has to take are similar to the non-grouping
function, except for the calculation to perform, which depends upon the
C-function supplied argument ‘fnc’:
4.8.1 Add non-distinct
When ‘fnc’ is RPT_FNC_ADD, the C-function has to perform the

non-distinct add action. Before doing the action, the C-function has to
check whether or not the aggregate context has been allocated. When the
user function is called for the first row, the C-function argument ‘agg_c’
points to the location where the pointer to the aggregate context should
be stored. When this location contains NULL, it is the first call and the
C-function has to allocate the aggregate context and store it at the
specified location. When the location contains a non-NULL value, this
value must be used for the aggregate context. For example (a user
supplied AVG function):
struct agg_context
{
int count;
RPT_INT total;
RPT_INT last;
};
if (*agg_c == NULL)
{
if ((*agg_c = malloc(sizeof(struct agg_context))) == NULL)
{
TLS_LONG tmp = (TLS_LONG)sizeof(struct agg_context);
umh_set_code(rpt_c->umh_c, RPT_F_NOMEMORY);
umh_set_val(rpt_c->umh_c, "val", REP_LONG, (char*)&tmp);
return FALSE;
}
memset(*agg_c, 0, sizeof(struct agg_context);
}
An example of a non-distinct add is (a user supplied AVG function):
if (fnc == RPT_FNC_ADD)
{
((struct agg_context *)*agg_c)->count++;
((struct agg_context *)*agg_c)->total += arg1->value.i;
}

Creating new RQL functions Steps to implement users functions
4.8.2 Add distinct
The add distinct action is similar to the add non-distinct action. It has to
handle the user function argument only when its value differs from the
previous value. For example (the user-supplied AVG function):
if (fnc == RPT_FNC_DIS)
{
if (((struct agg_context *)*agg_c)->count > 0 &&
((struct agg_context *)*agg_c)->last != arg1->value.i)
{
((struct agg_context *)*agg_c)->count++;
((struct agg_context *)*agg_c)->total += arg1->value.i;
((struct agg_context *)*agg_c)->last = arg1->value.i;
}
}
4.8.3 Return result
When REPORT/FAST has called the C-function for all retrieved rows,
it issues a final call to the C-function instructing it to return the result for
the grouping function. The C-function has to ignore the supplied user
function arguments (they must be popped from the function stack
however), calculate the group result, release the aggregate context and
push the group result on the function stack. For example (the user-
supplied AVG function):
if (fnc == RPT_FNC_DONE)
{
if (((struct agg_context *)*agg_c)->count != 0)
{
arg1->value.i = ((struct agg_context *)*agg_c)->total /
((struct agg_context *)*agg_c)->count;
}
else
arg1->value.i = 0;
arg1->rep = RPT_VAR_INT;
free( *agg_c);
}
4.9 Steps to implement users functions

To extend REPORT/FAST with user functions the following steps must

A non-grouping function example Creating new RQL functions
be done:
• Extend source ‘rpt_fnc.c’ to define the user functions. Remember
to specify whether or not a function is a grouping or non-grouping
function.
• Create the related C-functions, each C-function in a separate source
file. Include ‘rpt.h’ into the source file.
• Compile ‘rpt_fnc.c’ and the C-functions.
• Replace them in or add them to the REPORT/FAST object library
‘rptlib’. Make a backup copy of the object library before modifying
it.
• Stop REPORT/FAST.
• Re-build REPORT/FAST. The REPORT/FAST info-servers need
not be re-compiled or re-built.
• Start REPORT/FAST.
• Test the new user functions.
4.10 A non-grouping function example

To make the creation of a function more clear, we will give an example
of a non-grouping function to add two numbers.
The user function will be named ‘add’ and adds two numbers of the type
RPT_INT or RPT_REAL. The result will be of type RPT_REAL if one
or both of the numbers is of type RPT_REAL.
First we will edit the routine ‘rpt_fnc.c’. Add a declaration to declare the
related C-function and extend the user function definition:
extern TLS_BOOLEAN my_add();
{"ADD", my_add, NULL, NULL, NULL, 0, 0, 0, 2,
RPT_FNC_NAG, RPT_VAR_UNK, 1},
ADD is the keyword for REPORT/FAST, ‘my_add’ is the routine name
of the related C-function.
Then create a source file with an editor called ‘my_add.c’.
/*-------------------------------------------+
+-------------------------------------------*/
#include <rpt.h>
/*-------------------------------------------+
| Entry point
|+------------------------------------------*/

Creating new RQL functions A non-grouping function example
TLS_BOOLEAN my_add(rpt_c, fnc_c, argn, fnc, agg_c)

struct rpt_cont *rpt_c;
struct rpt_fnc_def *fnc_c;
TLS_UBYTE argn;
TLS_UBYTE fnc;
char **agg_c;
{
struct rpt_var *arg1, *arg2;
if (argn != 2)
{
umh_set_val(rpt_c->umh_c, "val2",REP_STRING, fnc_c->name);
return FALSE;
}
if (arg1 == NULL || arg2 == NULL) return FALSE;
if (arg1->rep == RPT_VAR_NULL || arg2->rep == RPT_VAR_NULL)
else if (arg1->rep == RPT_VAR_STR ||
arg2->rep == RPT_VAR_STR)
{
umh_set_code(rpt_c->umh_c, RPT_E_STRTONUM);
umh_set_com(rpt_c->umh_c, fnc_c->name);
return FALSE;
}
else if (arg1->rep == RPT_VAR_REAL ||
arg2->rep == RPT_VAR_REAL)
{
RPT_REAL a,b;
a = arg1->rep == RPT_VAR_REAL ? arg1->value.d :
(RPT_REAL)arg1->value.i;
b = arg2->rep == RPT_VAR_REAL ? arg2->value.d :
arg1->value.d = a + b;
arg1->rep = RPT_VAR_REAL;
}
else
arg1->value.i += arg2->value.i;
return TRUE;
}

A grouping function example Creating new RQL functions
4.11 A grouping function example

This user function will be named ‘avg’ and will return the average of a
column. The returned value will always be of type RPT_REAL. Our
‘avg’ function will overwrite the predefined ‘avg’ function.
First we will edit the routine ‘rpt_fnc.c’. Add a declaration to declare the
related C-function and extend the user function definition:
extern TLS_BOOLEAN my_avg();
{"AVG", my_avg, NULL, NULL, NULL, 0, 0, 0, 1,
RPT_FNC_AGG, RPT_VAR_REAL, 1},
AVG is the keyword for REPORT/FAST, ‘my_avg’ is the routine name
of the related C-function.
Then create a source file with an editor called ‘my_avg.c’.
/*-------------------------------------------+
+-------------------------------------------*/
#include <rpt.h>
extern char *malloc();
struct agg_context
{
int count;
RPT_REAL total;
RPT_REAL last;
};
/*-------------------------------------------+
| Entry point
|+------------------------------------------*/
TLS_BOOLEAN my_avg(rpt_c, fnc_c, argn, fnc, agg_c)
struct rpt_cont *rpt_c;
struct rpt_fnc_def *fnc_c;
TLS_UBYTE argn;
TLS_UBYTE fnc;
char **agg_c;
{
struct rpt_var *arg1;
struct agg_context *agg;
if (argn != 1)
{
umh_set_val(rpt_c->umh_c, "val2", REP_STRING,fnc_c->name);

Creating new RQL functions A grouping function example
return FALSE;
}
if (arg1 == NULL) return FALSE;
if (*agg_c == NULL)
{
if ((*agg_c = malloc(sizeof(struct agg_context))) == NULL)
{
TLS_LONG tmp = (TLS_LONG)sizeof(struct agg_context);
umh_set_code(rpt_c->umh_c, RPT_F_NOMEMORY);
umh_set_val(rpt_c->umh_c, "val", REP_LONG, (char*)&tmp);
rpt_var_fre(rpt_c, arg1);
return FALSE;
}
memset(*agg_c, 0, sizeof(struct agg_context));
}
agg = (struct agg_context *)*agg_c;
if (arg1->rep == RPT_VAR_STR)
{
umh_set_code(rpt_c->umh_c, RPT_E_STRTONUM);
umh_set_com(rpt_c->umh_c, fnc_c->name);
return FALSE;
}
if (fnc != RPT_FNC_DONE)
{
RPT_REAL r;
r = arg1->rep == RPT_VAR_REAL ? arg1->value.d :
if (fnc == RPT_FNC_ADD || r != agg->last)
{
agg->total += r;
agg->last = r;
agg->count++;
}
}
else
{
if (agg->count != 0)
arg1->value.d = agg->total / agg->count;
else
arg1->value.d = 0.0;
arg1->rep = RPT_VAR_REAL;
free((char*)*agg_c);

A grouping function example Creating new RQL functions
*agg_c = NULL;
}
return TRUE;
}

Creating new RQL functions A grouping function example

Introduction Reference guide
5 Reference guide
5.1 Introduction
This chapter supplies the application programmer with reference
information enabling him to write applications interacting with the RPT
brick. This chapter is divided into the following sections:
• Compiling, linking and running programs
• Error handling
• Data structures

Programs
Before you can use RPT in your programs, the following actions have to
be performed:
• REPORT/FAST must be installed
• rpt.h must be included
• Sources must be linked with the BUS libraries
REPORT/FAST can be run on several computer architectures, each

having their own specific characteristics.
5.3 Error Handling

Virtually all the BUS/FAST interface messages use standard error
handling with the UMH facilities. The error message is returned in the
reply instead of the requested information. Using routine
fmc_upk_msg() this error can easily be dealt with (see BUS/FAST
Programmer’s Guide). The philosophy underlying the error handling is
described extensively in the BUS/FAST Programmer’s Guide
(brick UMH).

Reference guide General data structures
5.4 General data structures
5.4.1 struct rpt_def
Reports are generally defined with the struct rpt_def.
struct rpt_def
{
struct rpt_name name; /* Report name and flags */
struct rpt_general gen; /* Report attributes */
struct rpt_schedule schedule; /* Scheduling parameters */
struct rpt_file file; /* File information */
struct rpt_proc_area proc_area; /* Process area info */
};
Struct rpt_name has the following layout:
struct rpt_name
{
char name[RPT_NAME_SZ]; /* The name of the report */
TLS_SHORT flags; /* Information flag. For some
BUS/FAST requests this flag
indicates which information in the
rpt_def struct is valid. It can be:
RPT_GENERAL_FLG to indicate
that the report attributes are filled
in or
RPT_SCHEDULE_FLG to
indicate that the scheduling
parameters are filled in or
RPT_PROC_AREA_FLG to
indicate that the process areas are
filled in */
};
Struct rpt_general contains the report attributes:
struct rpt_general
{
char path[TLS_FSPEC_SZ]; /* File path where all report
information is stored */
char description[RPT_DESCRIP_SZ];

General data structures Reference guide
/* A short informational description

*/
TLS_SHORT destination; /* The destination for generated
reports. The following options are
valid:
RPT_FILE_ONLY, the report is
outputted to a text file or
RPT_PRINTER, the report is
outputted to a text file and then
spooled to the systems printer or
RPT_UMHLOG, the report is
outputted to a text file and then
spooled to the systems error logger
*/
TLS_UBYTE adhoc; /* Ad-hoc generation flag. When
TRUE, it is allowed to generate the
report ad-hoc */
TLS_SHORT pri; /* The priority of the report */
char query[RPT_PARAM_CNT][RPT_PARAM_SZ];
/* The query prompt text */
};
Struct rpt_schedule contains the schedule attributes:
struct rpt_schedule
{
TLS_ULONG next_gen; /* The time of the next generation for
the report */
TLS_ULONG interval; /* The interval time. When zero, the
report will be generated once as
specified by next_gen */
TLS_BOOLEAN int_type; /* The GMT/LCT flag */
TLS_ULONG delete_after; /* The generated report life time.
When zero, all generated reports
will be kept on disk forever */
};
The next_gen and delete_after times are GMT seconds since 1970. The
interval is expressed in seconds. Special defines are available to specify
special intervals such as monthly. The HISTORY/FAST Programmer’s
Guide supplies additional information about scheduling.

The struct rpt_file contains the path and name of a text file containing
the report description.
struct rpt_file
{
char def_file[TLS_FSPEC_SZ];
/* Path and name of report
description file */
};
The struct rpt_proc_area contains the process areas for the report.
struct rpt_proc_area
{
TLS_SHORT process_area[GIN_PROCESS_AREA]; /
* Multiple process areas */
};
5.4.2 struct rpt_event_def
Report events are defined and removed using the following structures:
struct rpt_event_def
{
struct rpt_name name; /* Report name and flags */
struct rpt_general gen; /* Reports attributes */
struct rpt_event event; /* Event information */
}
struct rpt_event
{
struct item_name item_name; /* Name of the item on which the
event is generated */
struct itm_id itm_id; /* Item id of the item on which the
event is generated */
TLS_SHORT changeto_1; /* First relational operator
(relational_operator1) to specify
the range of the item value when
the report has to be generated */
TLS_SHORT changeto_2; /* Second relational operator
(relational_operator2) to specify
the range of the item value when


char value_1[8]; /* First border (constant_value1)of
the range mentioned above */
char value_2[8]; /* Second border (constant value2)
of the range mentioned above, this
value is only used when a range
with two borders is used */
TLS_SHORT andor; /* This logical operator
(logical_operator) is used when
the range for the item value has
two borders. */
TLS_SHORT status_1; /* This is the first status
(contant_status1) of the item when
TLS_SHORT status_2; /* This is the second status
(constant_status2) of the item
when the report has to be
generated */
TLS_SHORT value_rep; /* This is the representation of the
item value */
TLS_ULONG delay; /* This is a ULONG representation
of the delay (in seconds) between
the occurrence of the event and the
generation of the report */
};
5.4.3 struct rpt_adhoc
The struct rpt_adhoc is used for the RPT_ADHOC request to the

manager:
struct rpt_adhoc
{
char name[RPT_NAME_SZ]; /* Name of the report definition to
generate */
char query[RPT_PARAM_CNT][RPT_PARAM_SZ];
/* The array with report parameters
to pass to the report description.
These report parameters are
accessible within the report
description by the @P0 to @P7
variables */

TLS_SHORT id; /* The message code for the

‘generation finished’ request from
the manager. When zero, no
‘generation finished’ message will
be sent by the manager*/
TLS_SHORT destination; /* The destination for the report
overwriting the destination
defined during the report
definition. */
};
5.4.4 struct rpt_adhoc_usr
The struct rpt_adhoc is used for the RPT_ADHOC_USR request to the

manager:
struct rpt_adhoc_usr
{
struct rpt_adhoc adhoc; /* The generic adhoc information */
struct his_usr_inf usr_inf; /* User information. See the
HISTORY/FAST Programmer’s
Guide for a description of this
struct */
};
5.4.5 struct rpt_cancel
The struct rpt_cancel is used for the RPT_CANCEL request to the

manager:
struct rpt_cancel
{
char name[RPT_NAME_SZ]; /* Name of report to cancel. When *
is specified for the name than all
reports are cancelled */
};
5.4.6 struct rpt_info
The struct rpt_info is used for the RPT_INFO request to the manager to

obtain some report definition information:
struct rpt_info
{
char name[RPT_NAME_SZ]; /* Name of the report definition */
/* A short informational description
*/
char def_file[TLS_FSPEC_SIZE];
/* The path and name of the file
containing the report description
*/
};
5.4.7 structs rpt_s_dir, rpt_r_dir, rpt_s_dir_rql

and rpt_s_dir_done
The structs rpt_s_dir, rpt_r_dir, rpt_s_dir_rql and rpt_s_dir_done are

used to issue generate requests in direct mode to the report generator
directly. Struct rpt_s_dir defines the request and rpt_r_ind defines the
reply from the generator. Struct rpt_s_dir_rql is used to issue RQL
statements to the generator and struct rpt_s_dir_done terminates the
direct mode session;
struct rpt_s_dir
{
char name[RPT_NAME_SZ]; /* Name for the report */
TLS_USHORT result_code; /* The message id to be used by the
generator for the result of the RQL
statements */
};
struct rpt_r_dir
{
TLS_SHORT ident; /* The report session identification.
This identification must be used in
the following request to the
generator */
};
struct rpt_s_dir_rql
{
TLS_SHORT ident; /* Identification for the session */

char rql[1]; /* The ASCII RQL statement */

};
struct rpt_s_dir_done
{
TLS_SHORT ident; /* The identification for the session to
terminate */
};
5.4.8 structs rpt_s_ind and rpt_r_ind
The structures rpt_s_ind and rpt_r_ind are used to issue generate

requests in indirect mode to the report generator directly. Struct
rpt_s_ind defines the request and rpt_r_ind defines the reply from the
generator:
struct rpt_s_ind
{
char name[RPT_NAME_SZ]; /* Name for the report */
char descrip[RPT_DESCRIP_SZ];
/* Report informational description
*/
char def_file[TLS_FSPEC_SZ];/* Name of the file containing the
report description */
char des_file[TLS_FSPEC_SZ];/* Name of the file to store the report
output */
TLS_USHORT finished_code; /* If zero, the reply to this request is
returned when the generation is
completed. When not equal to
zero, the reply is returned
immediately and when the
generation is finished a message is
sent by the generator having its
message id equal to the
finished_code. The layout for this
message is defined in struct
rpt_r_ind */
char params[RPT_PARAM_CNT][RPT_PARAM_SZ];
/* The report parameters to be used in
the report description */
TLS_ULONG gen_time; /* Value to be passed to the RQL
@GEN_TIME variable */

};
struct rpt_r_ind
{
TLS_SHORT ident; /* The report session identification */
TLS_USHORT errors; /* The number of errors encountered
during the generation of the report
*/
};
5.4.9 struct rpt_cont
struct rpt_cont /* User function info */

{
long rpt_c; /* Internal usage only */
long ses_c; /* Internal usage only */
};
5.4.10 struct rpt_fnc_def
struct rpt_fnc_def /* Available functions */

{
char *name; /* Name of the function */
RPT_FNC fnc; /* Pointer to the related C-function */
char *agg_c; /* Reserved */
char *agg_f; /* Reserved */
int cls; /* Reserved */
int all; /* Reserved */
int cnt; /* Reserved */
int arg_cnt; /* Number of arguments for function
< 0 is variable */
TLS_UBYTE flg; /* Function type */
TLS_UBYTE rep; /* Function representation */
int user; /* Must be 1 */
};

5.4.11 struct rpt_var
struct rpt_var /* An argument variable */

{
int rep; /* Its representation */
union /* Its value */
{
RPT_INT i; /* Integer value */
RPT_REAL d; /* Real value */
char s[1]; /* Character value */
} value;
};

5.5.1 Create a report definition
SYNTAX
BUS/FAST Message_id: RPT_CREATE
MESSAGE Request data: struct rpt_def
Reply data: struct rpt_def
SEMANTICS This routine is used to create a new report definition. The new report
information is passed with the struct rpt_def. First the routine checks to
see if the report already exists. If this is the case, an error is returned.
Before reports can be generated, the report is set active. In addition, an
empty query file is created (extension ‘.rpt’).
NOTES None
ERROR • RPT_E_INTERN
CODES Internal error in report manager.
It is possible that HIS has not been able to create a new group owing
to a failed request to the history manager.
• RPT_E_ALREXI
The report does already exist, use modify to change it.
• RPT_E_NODEFFILE
The report definition cannot be saved or it is not possible to create
the (empty) report query file.
• RPT_E_NOMESSPC
There is no space in the reply message buffer to send a reply.

5.5.2 Modify a report definition
SYNTAX
BUS/FAST Message_id: RPT_MODIFY
SEMANTICS This routine is used to modify a report definition. The flag

rpt_def.name.flags indicates which part of the report has to be changed.
If the flag is RPT_GENERAL_FLG then the history manager is
requested to modify the group. If successful the new definition is saved.
The query text file (*.rpt) is not changed.
If the flag is RPT_SCHEDULE_FLG then HIS is requested to change
the scheduling information.
NOTES None
CODES The request to the history manager failed. HIS is not able to modify
the requested group.
• RPT_E_NOMODIFY
Not able to change schedule info
• RPT_E_NODEFFILE
The report definition cannot be saved.
• RPT_E_NOMESSPC

5.5.3 Delete a report definition
SYNTAX
BUS/FAST Message_id: RPT_DELETE
Reply data: struct rpt_name
SEMANTICS First a check is done to see if the requested report exists. Then a check
is performed to see if there is any scheduling active. If so, a warning is
returned and the report is not deleted. If there is no scheduling active, the
report is deleted by deleting the query text file and by requesting the
history manager to delete the report group.
NOTES None
ERROR • RPT_E_NOREPORT
CODES The report was not found.
• RPT_E_ACTIVE
The report has active scheduling. So it’s not deleted. First stop
scheduling with the RPT_SCHEDULE request.
• RPT_E_INTERN
The request to the history manager failed. HIS is not able to delete
• RPT_E_NOMESSPC

5.5.4 Generate a report (AD-HOC)
SYNTAX
BUS/FAST Message_id: RPT_ADHOC
MESSAGE Request data: struct rpt_adhoc
Reply data: empty message
SEMANTICS First a check is done to see if the requested report exists. If so, a rollover
is forced. After the report has been generated the generator sends a
request RPT_DONE to the manager. The manager then updates his
administration and sends a request to the sender of the RPT_ADHOC
message (if required). The message code of this request is rpt_adhoc.id.
NOTES None
• RPT_E_INTERN
The request to the history manager failed. HIS is not able to force a
rollover.
• RPT_E_NOMESSPC
There is no space in the message buffer to send a reply.

5.5.5 Generate a report with user information (AD-HOC)
SYNTAX
BUS/FAST Message_id: RPT_ADHOC_USR
MESSAGE Request data: struct rpt_adhoc_usr
Reply data: empty message
SEMANTICS First a check is done to see if the requested report exists. If so, a rollover
is forced. After the report has been generated the generator sends a
request RPT_DONE to the manager. The manager then updates his
administration and sends a request to the sender of the
RPT_ADHOC_USR message (if required). The message code of this
request is rpt_adhoc.adhoc.id.
NOTES None
• RPT_E_INTERN
The request to the history manager failed. HIS is not able to force a
rollover.
• RPT_E_NOMESSPC

5.5.6 Get a report definition
SYNTAX
BUS/FAST Message_id: RPT_GET, RPT_NEXT
SEMANTICS If the message id is RPT_GET, the report with the name equal to or
greater than the name specified is searched. If the message id is
RPT_NEXT, however, the report with the name greater than is searched.
This is equivalent to what HIS does. The reply struct contains the actual
known report information depending on the rpt_def.name.flags flag.
This flag could be: RPT_GENERAL_FLG, RPT_SCHEDULE_FLG.
NOTES None
• RPT_E_INTERN
The request to the history manager failed. HIS is not able to handle
the request.
• RPT_E_NOMESSPC
• RPT_E_DEFFILE
The report definition cannot be read from the definition file.

5.5.7 Edit query text
SYNTAX
BUS/FAST Message_id: RPT_EDIT
Reply data: struct rpti_r_info
struct rpti_r_info
{
char name[RPT_NAME_SZ];
char def_file[TLS_FSPEC_SZ];/* Definition file */
};
SEMANTICS This request is used to edit the query text of a report. Upon input, the
name of the report must be given. Upon output, the name of the ASCII
text file is given. The extension of the query text file is ‘rpt’. To protect
this file (e.g. when the system crashes), the file is copied to a new file
with the extension ‘new’. Then the ‘rpt’ file is locked by the manager. It
is not possible to edit this file again. When editing is finished the user
has to send a RPT_EDIT_DONE request.
NOTES None
ERROR • RPT_F_NOMEMORY
CODES Not able to allocate memory for internal information.
• RPT_E_NOMESSPC
• RPT_E_QUEFILE
Not able to access query text file
Error occurred during copying of files.
• RPT_E_NOREPORT
The report requested does not exist
• RPT_E_FILELOCK
Unable to edit file while this file is locked.

5.5.8 Finish or Cancel editing
SYNTAX
BUS/FAST Message_id: RPT_EDIT_DONE
SEMANTICS This message is used to tell the manager that an edit session is finished.
The input file name rpt_def.file.def_file is the name of the file that has
to be unlocked. This is the file name that was received with the
RPT_EDIT request. After this the edited file is copied to the original file.
NOTES None
ERROR • RPT_E_NOMESSPC
CODES There is no space in the message buffer to send a reply.
• RPT_E_NOFOPEN
Error occurred during copying of files.
• RPT_E_QUEFILE
Not able to access query text file

5.5.9 Get the report event information
SYNTAX
BUS/FAST Message_id: RPT_GET_EVENT, RPT_NEXT_EVENT
MESSAGE Request data: struct rpt_event_def
Reply data: struct rpt_event_def
SEMANTICS If the message id is RPT_GET_EVENT, the report with the name equal
to or greater than the name specified is searched. If the message id is
RPT_NEXT_EVENT, however, the report with the name greater than
the name specified is searched. This is equivalent to what HIS does. The
reply struct contains the actual known report event information
depending on the rpt_def.name.flags flag. If the RPT_EVENT_FLG is
set, then the event information is in the reply struct, otherwise only the
general information in the reply struct is valid if the
RPT_GENERAL_FLG is set.
NOTES None
• RPT_E_INTERN
The request to the history manager failed. HIS is not able to handle
the request.
• RPT_E_NOMESSPC
• RPT_E_DEFFILE
The report definition cannot be read from the definition file.

5.5.10 Modify the report event information
SYNTAX
BUS/FAST Message_id: RPT_MODIFY_EVENT
SEMANTICS This routine is used to modify the report event information. Not only the
event information is modified, but also a probably requested event based
on the old event information is cancelled and a new event based on the
new event information is requested to ITM. If successful, the new event
information is saved and the report is generated when the requested
event occurs.
NOTES None
CODES The request to the history manager failed. HIS is not able to modify
• RPT_E_NOREPORT
The report was not found.
• RPT_E_DEFFILE
The report definition cannot be read or saved.
• RPT_E_NOMESSPC
• RPT_E_NOITEM
The item the event is requested on could not be placed in the report
manager context.
• RPT_E_NOINI
The report in the report manager context is not initialized, so the
report can be generated unexpectedly the first time the event
occurs.
• RPT_E_NOREQ
There is no event requested to ITM as a result of this modify
request.
• RPT_E_NORPT
The report could not be placed in the report manager context.

5.5.11 Delete the report event information
SYNTAX
BUS/FAST Message_id: RPT_DELETE_EVENT
SEMANTICS First a check is done to see if the requested report exists. Then a check
is performed to see if there is any requested event for this report. If so,
this event is cancelled. After this the report event information is deleted
from the report definition file and the flag RPT_EVENT_FLG is reset in
the definition file. This means that the event information is not valid for
this report. The empty struct rpt_event_def is returned to the requester,
only the name being filled in.
NOTES None
• RPT_E_INTERN
The request to the history manager failed. HIS is not able to delete
• RPT_E_DEFFILE
The report definition cannot be read or saved.
• RPT_E_NOMESSPC
• RPT_E_NOREQ
The requested event with ITM is not cancelled
• RPT_E_NORPT
The report could not be deleted from the report manager context.

5.5.12 Generate a report (DIRECT)
SYNTAX
BUS/FAST Message_id: RPT_S_DIR
MESSAGE Request data: struct rpt_s_dir
Reply data: struct rpt_r_dir
SEMANTICS The RPT_S_DIR request is used to start the generation of a report whose
description is sent to the generator by means of BUS/FAST messages
following this request. When the request is successfully processed by the
generator, the generator will wait for a request with a message id of
RPT_S_DIR_RQL or RPT_S_DIR_DONE. Messages of id
RPT_S_DIR_RQL contain RQL statements to be executed by the
generator. The session can be terminated by sending a message with an
id of RPT_S_DIR_DONE.
NOTES None
ERROR • RPT_E_SESSION
CODES The generator is busy serving another session.

5.5.13 RQL statement
SYNTAX
BUS/FAST Message_id: RPT_S_DIR_RQL
MESSAGE Request data: struct rpt_s_dir_rql
Reply data: empty
SEMANTICS The RPT_S_DIR_RQL request is used to send RQL statements to the

generator which is busy with a direct session initiated by the
RPT_S_DIR request.
NOTES The result of the RQL statements is sent to the session requester by
means of a BUS/FAST message having a layout defined in struct
rpt_s_dir_rql and a message identification as defined in the direct
session initiating request.
CODES The generator is busy serving a session initiated by another
requester.
Errors in the RQL statements are reported in the report output.

5.5.14 Terminate a direct generation
SYNTAX
BUS/FAST Message_id: RPT_S_DIR_DONE
MESSAGE Request data: struct rpt_s_dir_done
Reply data: empty
SEMANTICS The RPT_S_DIR_DONE request is used to terminate a direct session

initiated by the RPT_S_DIR request.
NOTES None
CODES The generator is busy serving a session initiated by another
requester.

5.5.15 Generate a report (INDIRECT)
SYNTAX
BUS/FAST Message_id: RPT_S_IND
MESSAGE Request data: struct rpt_s_ind
Reply data: struct rpt_r_ind
SEMANTICS The RPT_S_IND request is used to start the generation of a report whose
source and destination (both file names) are specified in the message.
NOTES Depending on the finished_code in the request, the reply is sent

immediately or when the generation is completed. In the former case, the
generator sends a message with a layout as defined in struct rpt_r_ind
and having a message identification equal to finished_code when the
generation is completed.
CODES The generator is busy serving another session.
• RPT_E_OPNFORREAD
The source file can not be found.
• RPT_E_OPNFORWRITE
The destination file can not be created.

5.5.16 Cancel a session
SYNTAX
BUS/FAST Message_id: RPT_CANCEL
MESSAGE Request data: None or struct rpt_cancel
Reply data: None
SEMANTICS The RPT_CANCEL request is used to cancel any active generation

session. It is useful when the generator has encountered an unconditional
loop statement (the LOOP statement).
When sent to the manager with request data struct rpt_cancel then the
specified report is cancelled or removed from the queued of reports to
generate. When ‘*’ is specified for the name than all reports are
cancelled. When the request is sent to a generator (with no request data)
any active generation session is cancelled.
NOTES None
ERROR None
CODES

5.5.17 Pop an argument from the function stack
SEMANTICS
SYNTAX var = rpt_pop_arg(rpt_c)
ARGUMENTS struct rptg_var *var; /* (R) The popped argument */

struct rptg_cont *rpt_c; /* (M) The RPT context */
DATA For general structs, reference should be made to section ‘General data
STRUCTS structs’.
SEMANTICS This routine is used to return an argument passed to the user function
within RQL. The function allocates storage for the argument, moves it
from the RPT context to the allocated storage and returns a pointer to it.
When the returned pointer is NULL, an error has been detected and the
error has been set in the RPT context. The first call to rpt_pop_arg()
returns the last argument specified for the user function. The returned
argument variable can be released by the rpt_fre_var() and rpt_psh_ret()
calls.
NOTES None
ERROR None
CODES

5.5.18 Set the return value of the user function
SEMANTICS
SYNTAX [status =] rpt_psh_ret(rpt_c, var)
ARGUMENTS TLS_BOOLEAN status; /* (R) TRUE (success) or FALSE

(error) */
struct rptg_var *var; /* (I) The return value to set */
DATA For general structures, reference should be made to section ‘General

STRUCTS data structures’.
SEMANTICS This routine is used to set the value which must be returned by the user
function. The routine released the resources allocated by the argument
variable. Only one rpt_psh_ret() call may be executed.
NOTES None
ERROR None
CODES

5.5.19 Allocate an argument variable
SEMANTICS
SYNTAX var = rpt_all_var(rpt_c, rep, value)
ARGUMENTS struct rptg_var *var; /* (R) The return value to set */

int rep; /* (I) The representation */
char *value; /* (I) The value */

SEMANTICS This routine is used to allocate an argument variable. It allocates

resources for it, sets its representation and stores the supplied value in it.
The value is a pointer pointing to an integer value (RPT_INT), pointing
to a real value (RPT_REAL) or pointing to a character string
(RPT_CHAR*) depending upon the representation supplied. The
argument variable can be released by the rpt_fre_var() and rpt_psh_ret()
calls
NOTES None
ERROR None
CODES

5.5.20 Release an argument variable
SEMANTICS
SYNTAX [status =] rpt_fre_var(rpt_c, var)
ARGUMENTS TLS_BOOLEAN status; /* (R) TRUE (success) or FALSE */

/* (error) */
struct rptg_var *var; /* (I) The variable to release */

SEMANTICS This routine is used to release the resources allocated by an argument

variable which has been previously allocated by the rpt_var_all() or
rpt_pop_arg() routine.
NOTES None
ERROR None
CODES

Index
Index
Symbols C
(UMHLOG) 2-2 cancel
report 3-3
A session 5-26
actions C-function 4-2
grouping function 4-7 constant_status 2-6
non-grouping function 4-5 create
aggregate context 4-2 report definition 2-2, 5-11
ALARM/FAST 1-3
allocate argument variable 5-29 D
application interface data dictionary 1-1
RPT 0-1 Data Dictionary Language 1-1
argument variable 5-10 data set 1-1
allocate 5-29 DATABASE/FAST 1-1, 1-3
release 5-30 delete
argument variables 4-2, 4-4 event information 5-21
report definition 2-8, 5-13
B destination 5-3
brick
report 3-1 E
RPI 1-5 edit
RPT 0-1, 1-1, 1-3, 2-1, 5-1 cancel 5-18
BUS/FAST 0-1, 5-1 finish 5-18
BUS/FAST message query text 5-17
RPT_ADHOC 5-14 error code
RPT_ADHOC_USR 5-15 RPT_E_ACTIVE 5-13
RPT_CANCEL 5-26 RPT_E_ALREXI 5-11
RPT_CREATE 5-11 RPT_E_DEFFILE 5-16, 5-19, 5-20,
RPT_DELETE 5-13 5-21
RPT_DELETE_EVENT 5-21 RPT_E_FILELOCK 5-17
RPT_EDIT_DONE 5-18 RPT_E_INTERN 5-11, 5-12, 5-13,
RPT_GET 5-16 5-14, 5-15, 5-16, 5-19, 5-20,
RPT_GET_EVENT 5-19 5-21
RPT_MODIFY 5-12 RPT_E_NODEFFILE 5-11, 5-12
RPT_NEXT 5-16 RPT_E_NOINI 5-20
RPT_NEXT_EVENT 5-19 RPT_E_NOITEM 5-20
RPT_S_DIR 5-22 RPT_E_NOMESSPC 5-11, 5-12, 5-
RPT_S_DIR_DONE 5-24 13, 5-14, 5-15, 5-16, 5-17, 5-
RPT_S_DIR_RQL 5-23 19, 5-20, 5-21
RPT_S_IND 5-25 RPT_E_NOMODIFY 5-12
RPT_E_NOREPORT 5-13, 5-14, 5-
15, 5-16, 5-17, 5-19, 5-20
RPT Programmer’s Guide 1

Index
RPT_E_NOREQ 5-20, 5-21 function argument

RPT_E_NORPT 5-20, 5-21 pop 4-2, 5-27
RPT_E_OPNFORREAD 5-25 function return value
RPT_E_OPNFORWRITE 5-25 push 4-2, 5-28
RPT_E_QUEFILE 5-17
RPT_E_SESSION 5-22, 5-23, 5-24, G
5-25 generate
RPT_F_NOMEMORY 5-17 report 3-1
event information report (AD-HOC) 5-14, 5-15
delete 5-21 report (ad-hoc) 3-1, 3-2
modify 5-20 report (DIRECT) 5-22
example report (direct) 3-4, 3-6
grouping fiunction 4-11 report (INDIRECT) 5-25
non-grouping function 4-9 report (non-defined) 3-3
generator 3-1, 3-2, 3-4, 4-1, 5-26
F get
flag generated reports 2-9
RPT_EVENT_FLG 5-19, 5-21 report definition 5-16
RPT_FILE_ONLY 5-3 report information 2-8
RPT_FNC_ADD 4-4 GMT/LCT 2-4, 5-3
RPT_FNC_AGG 4-3 grouping
RPT_FNC_DIS 4-4 function 4-1
RPT_FNC_DONE 4-4
RPT_FNC_NAG 4-3 H
RPT_GENERAL_FLG 5-2, 5-12, HIS 2-9, 5-12, 5-16, 5-19
5-16, 5-19 his_fname 2-9
RPT_PRINTER 5-3 HIS_INFO_UNIT 2-9
RPT_PROC_AREA_FLG 5-2 history manager 5-12, 5-13
RPT_SCEDULE_FLG 5-12 HISTORY/FAST 0-1, 1-3, 2-1, 2-9
RPT_SCHEDULE_FLG 5-2, 5-16
RPT_UMHLOG 5-3 I
RPT_VAR_INT 4-3
INCLUDE 2-9
RPT_VAR_REAL 4-3
information flag 5-2
RPT_VAR_STR 4-3
interactive editor 1-1
RPT_VAR_UNK 4-3
interval time 5-3
function
ITEM/FAST 1-3
argument 4-2
ITM 5-20
c 4-2
declaration 4-3
grouping 4-1 L
grouping action 4-7 logical operator
grouping example 4-11 RPT_EVT_AND 2-6
non-grouping 4-1 RPT_EVT_OR 2-6
non-grouping action 4-5 LOGIN 3-1
non-grouping example 4-9 LOOP 5-26
predefined 4-1
result 4-2 M
stack 4-2 manager 2-9, 3-3, 5-14, 5-15, 5-17
user 4-1 modify
2 RPT Programmer’s Guide

Index
event information 2-7, 5-20 generate (INDIRECT) 5-25

process areas 2-7 generate (non-defined) 3-3
query text 2-7 report attributes 2-7
report definition 2-7, 5-12 report definition
attributes 2-1
N create 2-2, 5-11
non-grouping delete 2-8, 5-13
function 4-1 description 2-1, 2-3
event 2-5
O get 5-16
modify 2-7, 5-12
operator process areas 2-6
logical 2-6 scheduling 2-4
relational 2-5 report generator 5-8
report information
P get 2-8
pop report stopper 1-5
function argument 4-2 REPORT/FAST 0-2, 1-1
pop function argument 5-27 routine
process rpt_all_var 5-29
generator 1-5 rpt_fre_var 5-30
HIS 2-9, 5-12, 5-16, 5-19 rpt_psh_ret 5-28
ITM 5-20 RPI
manager 1-4 brick 1-5
RPTMAN 2-2, 3-2 RPT 1-3
push application interface 0-1
function return value 5-28 brick 0-1, 1-1, 1-3, 2-1, 3-1, 5-1
return value 4-2 RPT_ADH_CAN 3-3
RPT_ADHOC 2-3, 3-2
Q reference 5-14
quick load 1-5 rpt_adhoc 5-14, 5-15
layout 5-5, 5-6
R RPT_ADHOC_USR 3-2
reference 5-15
reference 5-25
rpt_all_var
relational operator
reference 5-29
RPT_EVT_EQ 2-5
RPT_CANCEL 3-3
RPT_EVT_GRT 2-5
reference 5-26
RPT_EVT_LW 2-6
rpt_cancel
RPT_EVT_LWE 2-6
layout 5-6
RPT_EVT_NEQ 2-5
rpt_cont
release argument variable 5-30
layout 5-9
report
RPT_CREATE 2-2, 2-3, 2-5
cancel 3-3
reference 5-11
definition 2-1
rpt_def 5-11, 5-12, 5-13, 5-16, 5-17
generate 3-1
layout 5-2
generate (AD-HOC) 5-14, 5-15
RPT_DELETE 2-8
generate (ad-hoc) 3-1, 3-2
reference 5-13
generate (DIRECT) 5-22
RPT_DELETE_EVENT 2-8
generate (direct) 3-4, 3-6

Index
reference 5-21 RPT_PROC_AREA_FLG 2-6, 5-2

RPT_DONE 5-14, 5-15 rpt_psh_re 5-29
RPT_EDIT 2-3 rpt_psh_ret 5-27
BUS/FAST message 5-17 reference 5-28
reference 5-17 rpt_r_dir
RPT_EDIT_DONE 2-4, 5-17 layout 5-7
reference 5-18 rpt_r_ind 5-25
rpt_event layout 5-9
layout 5-4 RPT_REAL 4-5
rpt_event_def 5-19, 5-20, 5-21 RPT_S_DIR 3-4, 5-23
RPT_EVENT_FLG 2-5, 5-19, 5-21 reference 5-22
rpt_file rpt_s_dir 5-22
layout 5-4 layout 5-7
RPT_FILE_ONLY 2-2, 3-2, 5-3 RPT_S_DIR_DONE 3-6, 5-22
RPT_FNC_ADD 4-4, 4-7 reference 5-24
RPT_FNC_AGG 4-3 rpt_s_dir_done 5-24
rpt_fnc_def layout 5-8
layout 5-9 RPT_S_DIR_RQL 3-4, 3-5, 5-22
RPT_FNC_DIS 4-4, 4-8 reference 5-23
RPT_FNC_DONE 4-4 rpt_s_dir_rql 5-23
RPT_FNC_NAG 4-3 layout 5-7
rpt_fre_var 5-27, 5-29, 5-30 RPT_S_IND 3-6, 5-25
rpt_general rpt_s_ind
RPT_GENERAL_FLG 2-7, 2-8, 5-2, 5- reference 5-25
12, 5-16, 5-19 RPT_SCHEDULE 2-8
RPT_GET 2-8, 3-3 rpt_schedule
reference 5-16 layout 5-3
RPT_GET_EVENT 2-8 RPT_SCHEDULE_FLG 2-4, 5-2, 5-12,
reference 5-19 5-16
RPT_INFO 2-8 RPT_UMHLOG 2-2, 3-2, 5-3
rpt_info rpt_var
RPT_INT 4-5 rpt_var_all 5-30
RPT_MODIFY 2-4, 2-7 RPT_VAR_INT 4-3
reference 5-12 RPT_VAR_REAL 4-3
RPT_MODIFY_EVENT 2-5, 2-6, 2-7 RPT_VAR_STR 4-3
rpt_name 5-13 RPT_VAR_UNK 4-3
layout 5-2 rptg_cont 5-27, 5-28, 5-30
RPT_NEXT 2-8, 3-3 rptg_var 5-27, 5-28, 5-30
reference 5-16 rpti_r_info 5-17
RPT_NEXT_EVENT 2-8 layout 5-17
reference 5-19 RPTMAN 2-2, 3-2
rpt_pop_arg 5-30 RQL
reference functions 1-6
rpt_pop_arg 5-27 statement 2-1, 2-3, 3-3, 3-4, 4-1, 5-
RPT_PRINTER 2-2, 3-2, 5-3 8, 5-23
rpt_proc_area RQL statement 5-23
layout 5-4

Index
S ALARM/FAST 1-3
BUS/FAST 0-1, 5-1
schedule parameters 2-7 DATABASE/FAST 1-1, 1-3
session 3-4, 3-6 HISTORY/FAST 0-1, 1-3, 2-1, 2-9
SQL ITEM/FAST 1-3
language 1-1, 1-2 REPORT/FAST 0-2, 1-1
statement USER/FAST 1-1, 1-3, 2-1, 3-1
INCLUDE 2-9
LOGIN 3-1
LOOP 5-26
U
status USER/FAST 1-1, 1-3, 2-1, 3-1
RPT_EVT_BLOCKED 2-6
RPT_EVT_HIGH 2-6
RPT_EVT_HIGH_HIGH 2-6
RPT_EVT_LOW 2-6
RPT_EVT_LOW_LOW 2-6
RPT_EVT_NORMAL 2-6
RPT_EVT_OFFLINE 2-6
RPT_EVT_OVER 2-6
RPT_EVT_UNDER 2-6
struct
rpt_adhoc 5-5, 5-6, 5-14, 5-15
rpt_cancel 5-6
rpt_cont 5-9
rpt_def 5-2, 5-11, 5-12, 5-13, 5-16,
5-17
rpt_event 5-4
rpt_event_def 5-19, 5-20, 5-21
rpt_file 5-4
rpt_fnc_def 5-9
rpt_general 5-2
rpt_info 5-7
rpt_name 5-2, 5-13
rpt_proc_area 5-4
rpt_r_dir 5-7
rpt_r_ind 5-9, 5-25
rpt_s_dir 5-7, 5-22
rpt_s_dir_done 5-8, 5-24
rpt_s_dir_rql 5-7, 5-23
rpt_s_ind 5-8, 5-25
rpt_schedule 5-3
rpt_var 5-10
rptg_cont 5-27, 5-28, 5-30
rptg_var 5-27, 5-28, 5-30
rpti_r_info 5-17
T
terminate
direct generation 5-24
tool

Index

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Manual DBV Programmer’s Guide
IM 50F2F01N-E/R10.03

IM 50F2F01N-E/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction ..........................................................................1-1
1.1 ISAM data files ..........................................................1-1
1.2 Record structure alterations .......................................1-1
1.3 ‘Logical’ records ........................................................1-1
1.4 DBV usage .................................................................1-2
1.5 Prerequisites ...............................................................1-2
2 Data dictionaries ...................................................................2-1
2.1 Introduction ...............................................................2-1
2.2 FAST/TOOLS general DD ........................................2-1
2.3 Data file identification ...............................................2-1
2.4 Updating the DDs ......................................................2-2
2.5 Field and key names ..................................................2-2
2.6 Alias names ................................................................2-3
3 View specification .................................................................3-1
3.1 The ‘view field’ data structure ...................................3-1
3.2 phys_field ..................................................................3-1
3.2.1 Identifying the field ‘instance’ .................................. 3-2
3.2.2 Identifying the field ‘occurrence’ ............................. 3-3
3.3 view_type ...................................................................3-6
3.4 elements .....................................................................3-8
3.5 Changes to the physical file .......................................3-8
4 Error handling ......................................................................4-1
4.1 Introduction ...............................................................4-1
4.2 UMH errors and warnings .........................................4-1
4.3 Error flags ..................................................................4-2
5 General notes ........................................................................5-1
5.1 Keys ...........................................................................5-1
5.1.1 Setting keys ............................................................... 5-1
5.1.2 Key field ‘translation’ ............................................... 5-1
5.2 View buffer ................................................................5-2
DBV Programmer’s Guide iii

Table of Contents
5.3 Usage of FAST/TOOLS facilities ............................. 5-2

6 Reference guide .................................................................... 6-1
6.1 Conventions .............................................................. 6-1
6.3 Error handling ........................................................... 6-2
6.4 Data structures .......................................................... 6-2
6.5 Routines .................................................................... 6-3
6.5.1 Introduction ............................................................... 6-3
6.5.2 Create a view ............................................................. 6-4
6.5.3 Read a record ............................................................ 6-9
6.5.4 Lock/unlock ............................................................ 6-12
6.5.5 Modify a record ....................................................... 6-13
6.5.6 Set the key ............................................................... 6-15
6.5.7 Destroy a view ........................................................ 6-16
Appendix A:Examples ................................................................... A-1
A.1 Creating/Reading/Modifying ................................... A-2
A.2 Changing key/Locking ............................................. A-4
Appendix B:Error messages ..........................................................B-1
B.1 Warnings ...................................................................B-1
B.2 Errors .........................................................................B-1
B.3 Fatal errors ................................................................B-2
Appendix C:System info ................................................................ C-1
C.1 UNIX and Windows .................................................C-1
iv DBV Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives
functionality of the DataBase View facility.
DBV routines.

This manual is intended for programmers who are familiar with the ‘C’
language.
The reader is assumed to have knowledge of the BUS/FAST error
handling facility (the Unsolicited Message Handler, UMH), and also of
the basic concepts of data file manipulation: reading from and writing to
files, sequential and random access, and file & record locking.

This manual contains the following information:
• Chapter 1 is an introduction to the functionality of the DBV facility.
• The DBV facility uses the FAST/TOOLS data dictionary to obtain
information about the data files on which views are to be created.
Chapter 2 is an introduction to the FAST/TOOLS data dictionary.
• Chapter 3 contains a detailed description of how DataBase views
can be specified by the application programmer.
• Chapter 4 contains a description of the error handling philosophy of
the DBV facility.
• Chapter 5 contains some general notes that apply when using the
DBV facility.
• Chapter 6 is a reference guide to the usage of the routines that make
up the DBV facility.
DBV Programmer’s Guide 0-1

• Appendix A contains an example of how an application might use

the DBV facility.
• Appendix B contains a list of all possible UMH error messages that
may be generated by the DBV facility.
• Appendix C contains specific information about using the DBV
facility on the various platforms.

• BUS/FAST Programmer’s Guide - Part UMH.
This manual provides a description of the standard error logging
facilities that are utilised by the DBV routines.
• DATABASE/FAST Language Manual.
This manual is a guide to the use of the ‘DDL’ compiler, some
knowledge of which is necessary to use the DBV facility.

CONVENTION MEANING
UPPERCASE Indicates reserved words and predefined
names, e.g. NULL, TRUE.
“” Used in format descriptions. Double
quotes indicate that the character is to
taken literally.
0-2 DBV Programmer’s Guide

<name> Used in format descriptions. Indicates

a variable.
<file_name>+ Used in format descriptions. One or more
n.u. Not used.
output This typeface indicates output appearing
on a terminal.
input This typeface indicates input from the user.
&& Same as the logical AND function.
|| Same as the logical OR function.


ISAM data files Introduction
1 Introduction
1.1 ISAM data files

Within a FAST/TOOLS environment, database files are created and
manipulated by the use of the ISF brick which is part of the
DATABASE/FAST tool. These files contain information about many
aspects of the environment. Several of the FAST/TOOLS themselves
create and update files, and files may also be created and updated by
application programs. The files themselves conform to the ISAM
(Indexed Sequential Access Method) standard.
1.2 Record structure alterations

When an ISAM file in a FAST/TOOLS environment has to be read from
or written to, the ISF brick of the DATABASE/FAST tool is used. Using
this method, the whole of a record is read/written at once. Therefore, any
applications that need to access that file must have knowledge of the
structure of the records. This is no problem... until the record structure
changes! When that happens, no matter how small the change, all the
applications will need to be altered to accommodate the new structure.
If a file is widely used this could involve much work.
1.3 ‘Logical’ records

The DBV facility has been created to resolve this problem by allowing
an application to define and use ‘logical’ records instead of ‘physical’
ones.
A logical record consists simply of a ‘view’ (hence ‘DataBase View’) of
the physical record, as specified by the user. Only the fields required for
a particular application need be included in the logical record, and they
may be specified in any order.
Apart from the obvious advantage of allowing the effective ‘re-
structuring’ of a physical record to suit a specific situation, the main
benefit of the DBV facility is the ‘de-coupling’ of physical and logical

Introduction DBV usage
records. Therefore, if the physical record structure of a file is changed,

the logical record defined by an application will not be affected (within
certain obvious limitations, such as a field used in the logical record
being removed from the physical record).
Note: Throughout the remainder of this manual,
the term ‘view’ implies ‘logical record’.
1.4 DBV usage

The DBV facility is implemented as a set of routines with a standard ‘C’
language interface. The user specifies the structure of the view and DBV
‘creates’ this view. Once created, the view may then be used to perform
regular file manipulation operations. Specifically;
• reading records
• modifying records
• using different indexes (keys) for random or sequential access
• file and record locking
Conceptually DBV creates ‘virtual’ files, consisting of only the
information required by the user, which are ‘de-coupled’ from the
physical files they are based upon. In the event of the physical file being
altered in some way, it is only necessary to restart any applications
which use views on that file. DBV will then create the views afresh,
taking the new physical structure into account, and from the
applications’ point of view, nothing will have changed and they will use
the same ‘virtual’ files as before.
1.5 Prerequisites
The only prerequisites for the use of the DBV facility is that BUS/FAST
and DATABASE/FAST are available. This is because functions
provided by these tools are used by DBV.

Introduction Data dictionaries
2 Data dictionaries
2.1 Introduction
The DBV facility uses data dictionaries (DDs) to obtain information
about the data files on which views are to be created. DDs contain
detailed descriptions of files, i.e. record layout, indexes (keys) defined,
etc. The user interfaces with the DDs via the file description language
DDL. The description of a single data file is contained within a DDL text
file with the extension “.ddl”. These files are used as input to the DDL
compiler which then creates/updates the DDs. “.ddl” files are referred to
throughout this manual.
The specification and usage of these files is described in the
DATABASE/FAST Language Manual.
2.2 FAST/TOOLS general DD

During the installation of DATABASE/FAST, a general DD (with the
name “tlsdic”) will be created within the FAST/TOOLS environment.
This DD may reside on any node in a multi-node environment, but must
be situated on the ‘data’ directory. It will be used to contain descriptions
of the FAST/TOOLS (and other) data files which are to be used via
DBV. Descriptions of end-user defined data files may be added to this
DD for use via DBV. New DDs may also be created which are then
identified to DBV via routine arguments.
2.3 Data file identification

Data files on which views are to be created can be located anywhere in
a FAST/TOOLS (multi-node) environment. A file is identified by the
node (if applicable), the directory, and the file name.
The DD description is that of a data set rather than a specific data file. It
is a ‘blueprint’ of the fundamental aspects of a set of data, which can be
applied to any number of actual physical files (this is explained more
fully in the DATABASE/FAST Language Manual). The DD description

Data dictionaries Updating the DDs
may include the actual identification of a physical file. DBV routine

arguments are used to indicate how the physical file to be used for a view
is to be identified.
Because of the (M)DUR facilities of DATABASE/FAST, it is possible
for the DBV routines to be located on one node, the DD on another, and
the physical file on a third.
In order to create a view on a file, the only requirement is that the file is
described in a DD; that is, it conforms to a specific data set description.
2.4 Updating the DDs

Whenever a data file is changed in some fundamental way, it is
necessary to update the DD which contains the data set description
pertaining to that data file. ‘Changed’ here means any alteration to the
structure of the records (including data type changes), or the
introduction or removal of keys.
The updating of the DD is achieved by altering the “.ddl” file to reflect
the changes, and then invoking the DDL compiler which performs the
update.
Once the DD has been updated, any applications using views on the data
file must invoke the view creation routine (or simply be re-started) in
order that the views may be re-created.
If DDs are not updated and/or views re-created in this way, then any
attempt to use the DBV facility will invariably fail.
2.5 Field and key names

In order to specify which fields from the physical file are required for a
particular view, the field names as specified in the DD must be known.
These field names are the names as contained within the relevant DD
description (they should be ‘technical’ field names, as opposed to ‘alias’
field names - see Section 2.6 below).
Also, if any key other than the primary key is to be used for file access
(either sequential or random), it is necessary to know the key names as
specified in the DD.

Alias names Data dictionaries
The necessity to use the DDL compiler means that all the required
information is contained within the relevant “.ddl” file. Using this file as
a reference provides a simple way of obtaining the information, and also
helps to ensure a correlation between the way the application
programmer sees the physical file and the way DBV sees it (via the DD).
2.6 Alias names

The DDL compiler allows the use of ‘alias’ field and record names in
“.ddl” files, and thus in DDs (more information is given in the
DATABASE/FAST Language Manual). For data set descriptions that
are to be used by DBV, it is recommended not to use these alias’.
This is because the use of alias’ makes it possible to give all fields in a
record the same name within the DD. This situation would make it
extremely difficult to uniquely identify the fields required for the view.
Although this is obviously an extreme example, it does illustrate the
potential problems with using alias’ in this situation.
The benefit of alias’ is that more ‘meaningful’ names may be given to
fields. If this is also desirable, then the easiest solution is to have two
DDs, one containing alias’ and the other without.

Data dictionaries Alias names

The ‘view field’ data structure View specification
3 View specification
3.1 The ‘view field’ data structure

This chapter contains a detailed description of how the required view is
specified by the application programmer to DBV.
A single field is described in a ‘view field’ data structure:
struct dbv_view_fld
{
char *phys_field;
TLS_LONG view_type;
TLS_LONG elements;
}
The whole view is described by using a table of these structures - the
‘view definition table’ (VDT).
The fields in the structure are described in the following three sections.
3.2 phys_field
This is a string identifying which field in the physical file is to be
mapped on to the view field.
A new concept is introduced at this stage - that of a ‘basic field item’.
This is simply one of two things:
1 a single data item, e.g.
- TLS_SHORT id_number;
2 a one dimensional array, e.g.
- TLS_SHORT id_codes[5];
When specifying which field is required for the view, the “phys_field”
string identifies the basic field item to DBV. When the basic field item
is a 1-D array, then the “elements” field is used to specify how many
elements are required, otherwise “elements” is ‘0’ (zero).
So, if the two physical fields above are wanted in the view (with only 3
elements being required from field “id_codes”) the following should be
specified:

View specification phys_field
1 phys_field = “id_number”
view_type = type required (see Section 3.3 below)
elements = 0
2 phys_field = “id_codes”
view_type = type required
elements = 3
multi dimensional arrays are dealt with below.
Note: In the descriptions that follow the term
‘field’ implies ‘basic field item’.
There are two points to be considered when specifying a field:

1 Identifying the instance of the field.
2 Identifying the occurrence of the field.
3.2.1 Identifying the field ‘instance’
Several fields within a physical record may be given identical names,

providing that they have different ‘parent’ fields. The following figure
contains an arbitrary example of a record structure with the names of the
fields given.
my_record
status
status
status option
Figure 3-1
The name “status” appears three times. If the “phys_field” string

consisted of just “status”, this would not be enough information for
DBV to know which field to include in the view. By ‘default’, DBV
would use the first field with that name at the highest nested level which
it encounters within the DD, in this case the one directly below
“my_record”.
Therefore, with regard to identifying the field instance, two options
exist:
1 Specify only the name, in which case the 1st is taken.

phys_field View specification
2 Specify the full ‘field specification path’. This uses the ‘dot’
operator notation to uniquely identify a particular field within a
record. In the figure above, the three instances of “status” would
thus be specified as:
“my_record.status”
“status.status”
“level.status”
It is also possible to specify the ‘complete’ path, from the lowest nested
level, if so desired. In which case the last example above would become;
“my_record.status.level.status”
DBV would use the same physical field in both cases. This option may
be used if it is foreseen that a possible future change to the physical
record structure could make a field specification become ambiguous,
although it should be noted that there is a very slight payoff in terms of
performance during the creation of the view.
3.2.2 Identifying the field ‘occurrence’
If a physical field is a multi-dimensional array, or if it lies within an

array of structures/unions, or both, then that field will ‘occur’ several
times within the entire record.
Note: Both data arrays and structure/union
arrays are limited to a maximum of 4
dimensions. This is a restriction imposed
by the DDL compiler.
Therefore, in order to identify the required ‘occurrence’ of the field it is
necessary for the user to specify the exact path to the field. This path
specification starts from the parent at the highest nested level which is
itself an array of structures/unions, and ends when the basic field item is
reached. Any array dimensions which lie within the path must have a
value (n) specified for them, this being the ‘nth element - 1’ (array
indexes start numbering at zero) within that particular dimension.
This may sound a little complicated, but the following examples will
demonstrate that the basic concept is very simple to grasp, and that
identifying the fields required is a fairly straightforward task.

View specification phys_field
Example 1: data arrays

Assume that the following physical fields exist at the highest level
within a record (defined in a “.ddl” file):
TLS_LONG field_A;
TLS_LONG field_B[2];
TLS_LONG field_C[2][4];
The basic field items and the number of occurrences of each one are as
follows:
- field_A occurs once
- field_B[2] occurs once
- field_C[4] occurs twice
When a field occurs only once, then is it necessary to specify just the
name in the “phys_field” string. Here, that is “field_A” or “field_B”,
with the required elements specified for field_B.
When a field occurs more than once it is necessary to establish which
occurrence is required and then specify that within the “phys_field”
string. Here, this would be “field_C[0]” for the first occurrence and
“field_C[1]” for the second, also with the required number of elements
being specified (1 to 4).
If all the elements of field_C are required, and in the correct ‘order’, then
two consecutive VDT entries should be specified, as follows:
1 phys_field = “field_C[0]”
elements = 4 (or ‘-1’ - see Section 3.4 below)
2 phys_field = “field_C[1]”
elements = 4
Example 2: data arrays within structure/union arrays

Assume that the following exists as part of a record definition in a “.ddl”
file:
struct
{
struct
{
TLS_LONG field_A[20];
struct
{

phys_field View specification
TLS_LONG field_B;
struct
{
TLS_LONG field_C[2][3][4];
TLS_LONG field_D;
}strct_W[10][5];
}strct_X;
}strct_Y[5];
}strct_Z;
If strct_Z is at the highest level within the record, then the basic field
items and the number of occurrences of each one are as follows:
- field_A[20] occurs 5 times
- field_B occurs 5 times
- field_C[4] occurs 1500 times
- field_D occurs 250 times
The following are examples of what should be specified in the
“phys_field” string when the indicated occurrences are required for the
view (field_A and field_C also require a number of elements to be
specified):
• the first occurrence of field_A[20] is specified by
“strct_Y[0].field_A”
• the third occurrence of field_B is specified by
“strct_Y[2].strct_X.field_B”
• the first occurrence of field_C[4] is specified by
“strct_Y[0].strct_X.strct_W[0][0].field_C[0][0]”
• the last occurrence of field_D is specified by
“strct_Y[4].strct_X.strct_W[9][4].field_D”
When studying this example, the following becomes apparent:

1 Specifying a particular occurrence somewhere within a multi-
dimensional array would take some working out (for example, the
957th occurrence of field_C[4]), and could not be deduced by
simply looking at the structure as in the above examples. However,
it is still a straightforward and logical procedure, which in this case
results in the string:
“strct_Y[3].strct_X.strct_W[1][4].field_C[0][2]”
2 If all the elements in field_C were required, a very large view
definition table would be required. This is also quite possible and
the production of such a table could be automated with a utility.

View specification view_type
With regard to the above two points, it should be noted that this structure
is an extreme example. Its purpose is to illustrate how any occurrence of
a field may be isolated in this manner.
In all of the above field specifications, the structure strct_Z could also
have been included at the start of the string.
3.3 view_type
This is the datatype of the view field. The user specifies what type is
required for the field within the view. The value should be one of those
as specified in the header file “global.h” (example: REP_USHORT).
If the physical field, from which the view field is to be mapped, is of a
different type, then DBV will perform the necessary conversion at run-
time. When such a type conversion is performed (‘FROM’ <type> ‘TO’
<type>), the action may result in one of the following errors:
• overflow
the value of the ‘FROM’ data item is greater than the maximum
allowed value for a data item of the ‘TO’ type
(this may happen when converting, for example: FROM
REP_LONG TO REP_SHORT)
• underflow
the value of the ‘FROM’ data item is less then the minimum
allowed value for a data item of the ‘TO’ type
(this may happen when converting, for example: FROM
REP_SHORT TO REP_USHORT)
• information loss
when converting from a float or double representation to an integer
representation, any value after the decimal point will be lost - also
when converting from REP_DOUBLE to REP_FLOAT, precision
will be lost
When any such error is detected by DBV, the application is informed by
the use of the ‘error flags array’ (see Chapter 4), and in the case of
overflow/underflow the ‘TO’ field is given the maximum/minimum
value for its type.
The following table depicts any errors that may result from all the
possible type conversions that can be performed by DBV. The ‘FROM’
data type is the type of the original data item, and the ‘TO’ data type is
the type of the target data item. The possible error, or otherwise, that

view_type View specification
may occur as the result of a specific conversion is indicated in the

appropriate table cell.
The meanings of the text in the cells are as follows:
--- no conversion is necessary
NE the conversion is performed with no error
OF an overflow error may occur
UF an underflow error may occur
O/U an overflow OR an underflow may occur
IL information loss may occur
ALL underflow/overflow/information loss may all occur
REP_BOOLEAN
REP_DOUBLE
REP_USHORT
REP_SHORT
REP_UBYTE
REP_FLOAT
REP_LONG
REP_BYTE
TO →
FROM
↓
REP_BOOLEAN --- NE NE NE NE NE NE NE
REP_BYTE NE --- UF NE UF NE NE NE
REP_UBYTE NE OF --- NE NE NE NE NE
REP_SHORT NE O/U O/U --- UF NE NE NE
REP_USHORT NE OF OF OF --- NE NE NE
REP_LONG NE O/U O/U O/U O/U --- NE NE
REP_FLOAT NE ALL ALL ALL ALL ALL --- NE
REP_DOUBLE NE ALL ALL ALL ALL ALL IL ---
If the type of the physical field is changed, then DBV will simply
perform a different type conversion.
Two points should be noted here:

1 The type representation REP_LONG is not specified in “global.h”.
If the physical field is of type TLS_LONG then it is treated as a
TLS_LONG, and REP_LONG should be specified in this field.
Also note that no overflow/underflow checking is performed when
converting with a TLS_LONG type.
2 It is assumed that physical fields of type char will be character
arrays, i.e. strings. Therefore, the type REP_STRING should be
specified in the “view_type” field. This also applies if the physical
field is only a single item of type char.

View specification elements
Physical fields of type char cannot be converted to or from any

other type. Therefore, if REP_STRING is not specified then an
error will result.
Finally with regard to the view fields, they must be correctly aligned
within the view record. That is; they must lie on the correct boundaries
for their type with relation to the start of the record. The exception is that
a TLS_DOUBLE may start on a TLS_LONG boundary.
3.4 elements
This is the specification of how many elements are required for the view
field.
In the case where the basic field item is an array, the number of elements
of the array to be included in the view should be specified (including
char arrays). The elements are taken starting with the first element.
If ‘-1’ is specified in this field, then the whole array will be included in
the view; that is, the current number of physical elements.
If the basic field item is a single data item, then this field should contain
the value ‘0’ (zero).
3.5 Changes to the physical file

The essence of the VIEW system is that when the physical record
structure of a file is altered in some way, any view on the file will be the
same after the change - the application is ‘unaware’ of the change.
However, there are certain changes that may be made on a file that will
affect the view produced. These are described as follows:
• if the name of a physical field [which is used in the view] is changed
then the field will not be found and the view not created (unless a
different field exists with the same name, in which case this will be
used in the view)
• if a physical field is given a name and inserted before a field [which
is used in the view] with the same name
then the new field will be used for the view
• if a dimension (an index) is added or subtracted from an array
[which is specified in the view definition table]

Changes to the physical file View specification
then the index references will not match (between the view
definition table and the data dictionary) and the view will not be
created
Each ‘part’ of a “phys_field” string (as separated by the dot operators)
may be affected equally by any of the above changes. With regard to the
first two changes described, the outcome depends on the structure of the
physical record. That is, if any alternative field exists that conforms to
the “phys_field” string specification, then this will be used for the view.
Basically, the user should be very careful when changing the physical
file in any of the ways described.

View specification Changes to the physical file

Introduction Error handling
4 Error handling
4.1 Introduction
DBV uses two methods for communicating errors to the application
which calls its routines. The first is the standard FAST/TOOLS error
handling utility UMH (the Unsolicited Message Handler), which
provides text describing the nature of the error. The second is a DBV
specific method consisting of an array of ‘bit flags’. This provides more
specific information about certain errors and relates them to particular
fields in the view record.
4.2 UMH errors and warnings

UMH message codes of severity “F” (fatal), “E” (error), and “W”
(warning) are used by DBV.
All of the DBV routines return a TLS_BOOLEAN value, which
indicates whether or not any errors have been encountered during the
execution of the routine. Any kind of error detected causes the routine to
return FALSE. The UMH error buffer may then be inspected (and
maybe the “err_flags” array - see Section 4.2 below) to obtain details of
the nature of the error(s).
Although a routine returns FALSE, it is still possible that a ‘positive
outcome’ has been achieved. This is because of the nature of certain
DBV routines.
For example: a positive outcome to the “dbv_read()” routine is that a
physical record has been read and ‘translated’ into the view record -
meaning that the view buffer (passed as an argument to the routine) now
contains the translated record. However, if for example a ‘value
overflow’ occurs during the translation, then that particular field
contains an incorrect value (the maximum for that type). The application
must be informed of this, and therefore the routine returns FALSE, and
the UMH buffer and the “err_flags” array contain details of the
overflow. The view buffer contains the logical record (all other fields are
correct), and so a positive outcome has been achieved.

Error handling Error flags
The achievement of a positive outcome or not is indicated by the severity

of the UMH message code(s) generated during the execution of the
routine.
During processing of the view fields (during creation, reading, or
modifying), several message codes of severity “W” may be generated.
When any such message codes occur, a ‘general’ warning code
(DBV_W_GENERAL) is generated at the highest level of the error
buffer, thus providing a means if checking the existence or otherwise of
such warnings (more detailed information is provided by deeper nested
message codes). If the message code DBV_W_GENERAL is generated,
then a positive outcome has been achieved.
If a message code of severity “F” or “E” is generated, then the routine
will return immediately and a positive outcome has not been achieved.
Thus, the return value of the routine and the severity of the top level
message code provide the information necessary to establish how the
routine performed.
4.3 Error flags

During the process of creating a view or reading/modifying records,
several of the fields within a record could produce an error.
In order that the application may be informed of which fields are in error,
an array of ULONGs is used (called “err_flags”), each element being a
number of bit flags indicating the type of any errors. Each entry in the
view definition table (each ‘basic field item’) results in the declaration
of one element in the “err_flags” array. Therefore, the number of
elements in this array is equal to the number of fields in the view.
Before use, the bits are all reset. When the create view/read record/
modify record routines return, “err_flags” may be inspected to ascertain
the details of certain errors encountered. Any bits which have been set
indicate:
(a) which view field(s) the error(s) occurred in, and;
(b) the nature of the error(s).
The type of errors which may occur vary depending on which DBV
activity is being performed, and therefore some bits are not used for
certain activities.

Error flags Error handling
Because of the use of TLS_LONG types for the bit flags, there is a
potential for 32 types of error. Only the ones described below are used
at present, with possible additions being introduced at a later stage.
The errors are described as follows:
bit 0: BOUNDARY ERROR
View creation only.
bit 0: indicates that the field is not lying on the correct
boundary for its type. The UMH message code
DBV_E_BOUND is generated.
bit 1: FIELD NOT FOUND
View creation only.
bit 1: indicates that the field name specified could not be found
in the field data dictionary. The UMH message code
DBV_E_PHYS_FIELD is generated.
bit 2: PATH ERROR
View creation only.
bit 2: indicates that an error was encountered while processing
the path (when “phys_field” contains more than one ‘part’).
This could mean that fields were specified in the wrong order,
or that a field was missed out, or that a field was not found. The
UMH message code DBV_E_PHYS_FIELD is generated.
bit 3: SYNTAX ERROR
View creation only.
bit 3: indicates that an error was found in the ‘syntax’ of the
“phys_field” string. The UMH message code
bit 4: NUMBER OF INDEXES
View creation only.
bit 4: indicates that, for at least one ‘part’ specified in the
“phys_field” string, there is a discrepancy between the number
of indexes specified and the number of actual indexes (as
specified in the field data dictionary). For example: 3 indexes
were specified for a 2-dimensional array; or vice-versa. This
may apply to any one of the ‘parts’ in the string. (Note: this
also applies if more than 4 indexes are specified.) The UMH
message code DBV_E_PHYS_FIELD is generated.
bit 5: ARRAY INDEX OUT-OF-BOUNDS
View creation only.
bit 5: indicates that, for at least one array index specified in the

“phys_field” string, a number was specified which was out-of-

bounds for that particular index. The UMH message code
bit 6: ILLEGAL CONVERSION
View creation only.
bit 6: indicates that either:
• the types of the physical and view data items is different
and that one of them is of type REP_STRING (conversion
to or from type REP_STRING is not permitted), or;
• the “view_type” field contains an unknown type value,
or;
• the type of the physical data item is not one of the
permitted types (e.g. DDL_STRUCT_TP)
The UMH message code DBV_E_VIEW_TYPE is generated.
bit 7: NON-ARRAY FIELD
View creation only.
bit 7: indicates that a positive value was specified in the
“elements” field (either >0 or -1), but the basic field item is not
an array. The UMH message code DBV_E_ELEMENTS is
generated.
Also, if a value of less than -1 is specified, this flag is set and
DBV_E_ELEMENTS generated.
bit 8: ARRAY FIELD
View creation only.
bit 8: indicates that the value ‘0’ (zero) was specified in the
“elements” field, but the basic field item is an array. The UMH
message code DBV_E_ELEMENTS is generated.
bit 9: DATA TYPE MISMATCH
View creation only.
bit 9: indicates that the types of the physical and logical data
item are different (neither are of type REP_STRING), and that
therefore during reading/modifying operations, conversion is
performed and a possible value overflow/underflow (or
information/precision loss when converting between
REP_FLOAT and REP_DOUBLE) may result. The UMH
message code DBV_W_TYPM is generated.
bit 10: PHYSICAL>LOGICAL ARRAY LENGTH
View creation.
During view creation bit 10: indicates that the number of
elements in the physical field is greater than the number in the

Error flags Error handling
view field (specified with “elements”), and that therefore

when reading records, only ‘view array length’ elements will
be copied. The UMH message code DBV_W_ALM is
generated.
bit 11: PHYSICAL<LOGICAL ARRAY LENGTH
View creation.
During view creation bit 11: indicates that the number of
elements in the physical field is less than the number in the
view field (specified with “elements”), and that therefore
when modifying records, only ‘physical array length’ elements
will be copied. The UMH message code DBV_W_ALM is
generated.
bit 12: ARRAY OVERFLOW
Reading records.
When records are being read bit 12: indicates that an overflow
was detected (only possible with char arrays), and that
(“elements” - 1) characters have been read and then terminated
with ‘\0’. The UMH message code DBV_W_ARR_OVF is
generated.
Modifying records.
When records are being modified bit 12: indicates that the
actual string in the logical field is longer than the physical
field, and therefore that (‘physical field length’ - 1) characters
have been read and then terminated with ‘\0’. The UMH
message code DBV_W_ARR_OVF is generated.
bit 13: VALUE OVERFLOW
Reading records.
During a read operation bit 13: indicates that an overflow error
occurred during conversion from physical to view data item.
The value placed in the view buffer is the maximum allowed
for the view type. The UMH message code
DBV_W_VAL_OVF is generated.
Modifying records.
During a modify operation bit 13: indicates that an overflow
error occurred during conversion from view to physical data
item. The value placed in the record is the maximum allowed
for the physical type. The UMH message code
DBV_W_VAL_OVF is generated.
bit 14: VALUE UNDERFLOW
Reading records.
During a read operation bit 14: indicates that an underflow

error occurred during conversion from physical to view data

item. The value placed in the view buffer is the minimum
allowed for the view type. The UMH message code
DBV_W_VAL_UNF is generated.
Modifying records.
During a modify operation bit 14: indicates that an underflow
error occurred during conversion from view to physical data
item. The value placed in the record is the minimum allowed
for the physical type. The UMH message code
DBV_W_VAL_UNF is generated.

Keys General notes
5 General notes
5.1 Keys
5.1.1 Setting keys
For reasons of system performance, the routine that changes the current
key (index) used by the view (“dbv_key()”) does not actually set the key
but merely makes a ‘note’ of the fact that the key has changed.
The routine that reads a record (“dbv_read()”) checks this and then sets
the key (if necessary) before reading the record.
The routine that modifies a record (“dbv_modify()”) also checks the
current key, and changes it to the primary key if necessary. If this is
done, then after modification the routine again makes a ‘note’ of the key
change, which is then subsequently checked by the “dbv_read()” routine
before a record is next read.
It is necessary that the application programmer is aware of this
functionality so as to appreciate the key related UMH message code
DBV_E_KEY_FAIL that may be produced by the reading and
modifying routines.
5.1.2 Key field ‘translation’
If random access is required when reading records, then the view field(s)
that make up the relevant key must first be translated from the view to
the physical type representations. When modifying records the primary
key field(s) is used to find the correct record to modify, and thus is
always translated.
It is possible that array/value overflow/underflow errors may occur
during this translation. If any such error is detected then the UMH
message code DBV_E_KEY_TRNS is generated and the routine returns
without performing any read or modify actions. The “err_flags” array
will contain information about the nature and location of the errors.
When random access reading is required, the view record buffer passed
as argument will contain a search value(s) in the relevant key field(s). It

General notes View buffer
is important for the application to set the rest of the buffer to ‘zero’
values, enabling correct key translation to take place.
5.2 View buffer

When the “dbv_read()” or “dbv_modify()” routines are called, a buffer
is passed (a char pointer) which is used to put the view record into. It is
necessary that the view fields within this buffer are correctly aligned on
their boundaries.
The way that the buffer would normally be declared and passed as
argument would ensure this. That is; a “struct” with the format of the
view is declared, and then the address of this struct is cast to a (char *)
and passed to the appropriate routine.
Because the view fields must be correctly aligned when specified with
the view definition table (see Section 3.3), it is only necessary to ensure
that the buffer starts on a TLS_LONG boundary.
This point is made only because it is possible to pass a buffer declared
as a char array to the routine, in which case there is no guarantee that
correct alignment would result, and therefore serious system errors
would be very likely to occur.
5.3 Usage of FAST/TOOLS facilities

Various FAST/TOOLS facilities and routines are used by DBV. As is
usual within a FAST/TOOLS environment, when errors are generated
by these routines DBV (usually) adds its own more general error
message on top. When a DBV message is not added, this is because the
message already generated is considered to provide enough information.

Conventions Reference guide
6 Reference guide
6.1 Conventions
All DBV routines have ‘C’-type interfaces. The syntax of all routines as
well as the examples comply with ‘C’ language bindings.
All parameters which are passed by reference may be assumed to be
modifiable by the routine to which they are passed. All parameters
passed by value may be assumed to be input only.
Example: the syntax of the routine dbv_key():
[status=] dbv_key(ptr,umh_c,key)

void *ptr; /* the view pointer */
char *key; /* name of key to set */
All the DBV routines return a TLS_BOOLEAN as the status indicator.

This is shown in the syntax descriptions as [status=]. Normally this
return value would be tested directly rather than being assigned to a
variable, as follows:
if (!dbv_key())
{
/* error - use UMH context to log the error(s) */
}
The header file dbv.h contains definitions that should be used when
calling DBV routines. For this reason, dbv.h must always be included in
any source that it to utilise DBV.
The names of routines, data structures, and defined constants that are
part of DBV all start with the three letter ‘dbv’.

Reference guide Compiling, linking, and running applications
Note: Do not use a routine or variable name in

your application that start with these
letters.

applications
In order that the DBV routines can be used in your applications, it is
necessary to ensure that the following are true:
• BUS/FAST and DATABASE/FAST are installed
• dbv.h has been included in the source
• the source has been linked with the BUS and DBV libraries
6.3 Error handling

All the DBV routines used the standard FAST/TOOLS error handling
facilities provided by UMH.
The following three routines use the error flags array to communication
more detailed information about specific errors:
• dbv_create()
• dbv_read()
• dbv_modify()
Details of the error flags mechanism and the specific of DBV’s use of
UMH can be found in Chapter 4.
When a routine returns TRUE, the contents of the error buffer remain
unchanged.
6.4 Data structures

There is only one data structure used for the DBV facility. This is as
follows:

Routines Reference guide
struct dbv_view_fld
{
char *phys_field; /* the field spec. */
TLS_LONG view_type; /* the view data type */
TLS_LONG elements; /* number of elements */
}
This structure is described in detail in Chapter 3.
6.5 Routines
6.5.1 Introduction
This section describes the DBV routine set.

For each routine a description is given of the following:
• its syntax
• its parameters
• its semantics
• other DBV routines that are related to it

Reference guide Routines
6.5.2 Create a view
Syntax [status=] dbv_create( ptr,dur_c,umh_c,err_flags,sup_nm,

dict_nd,dict_nm,set_nm,f_nd,f_dir,
f_nm,mode,key,timeout,table )

void **ptr; /* view pointer */
TLS_ULONG **err_flags; /* error flags pointer */
char *sup_nm; /* set-up file name */
int dict_nd; /* data dict node number*/
char *dict_nm; /* data dict name */
char *set_nm; /* data set name */
int f_nd; /* file node number */
int f_dir; /* file directory number*/
char *f_nm; /* file name */
int mode; /* locking/access mode */
char *key; /* key to search on */
TLS_ULONG timeout; /* timeout for remote node
file access */
struct dbv_view_fld *table; /* view definition table*/
Semantics dbv_create() is used to create a view on a data file.

ptr is the address of a void pointer (only the pointer need be declared).
If the view is successfully created then this is set to ‘point to the view’.
It should subsequently be used as an argument to any DBV routine when
an action is required for that view. If the view creation is unsuccessful
ptr remains unchanged.
dur_c is used to allow communication with remote nodes.
umh_c contains any error messages generated during view creation.
err_flags is the address of a TLS_LONG pointer (only the pointer need
be declared). The error flags array is created by the routine and if the
routine returns FALSE then some bits in the array may have been set.
sup_nm is the name of the set-up file that is to be used if required. This
file can be used to specify the FAST/TOOLS node number and/or the
name of the data dictionary which contains the information for the data
set (specified in set_nm). Any values specified in a set-up file will
override any values contained in dict_nd and dict_nm. If required, the
name should be specified without the “.sup” extension, and the file must

be located on the FAST/TOOLS set-up directory. If no set-up file is

required then this parameter should be a NULL pointer.
set_nm is the name of the data set as specified in the set data dictionary.
Note: As stated in Chapter 2, a data set definition
can apply to several physical data files. If
the data file specified in the set data
dictionary is not that of the required data
file, then the following 3 parameters (f_nd,
f_dir, and f_nm) should be used to correctly
identify the file.
EITHER the data dictionary OR all 3
parameters below are used to identify the
file - a combination is not possible.
f_nd is the FAST/TOOLS node number on which the data file to be used
for the view is located. If the data dictionary is to be used to obtain the
file identity, then the f_nm parameter should be a NULL pointer, in
which case DBV will ignore this one.
Note: If a ‘0’ (zero) is specified for the node
number of the data file, then the own node
will be used. It is possible to specify the
actual node number of the own node, but
this introduces a run time overhead. It is
therefore advisable to use ‘0’ when the data
file is on the same node as DBV.
f_dir is the FAST/TOOLS number of the directory which contains the
data file. The number should be one of those as defined in the header file
“tools.h”, for example; TLS_DATA_T (being the FAST/TOOLS ‘data’
directory). It is possible to include the directory path in the file name
parameter, f_nm. If this is the case then this parameter (f_dir) should
contain the value TLS_NODIR_T. If the data dictionary is to be used to
obtain the file identity, then the f_nm parameter should be a NULL
pointer, in which case DBV will ignore this one.
f_nm is the name, including any extension, of the data file. This
parameter determines how the data file is to be identified by DBV. If it
is a NULL pointer then the ‘set’ data dictionary is used to obtain all the
details of the file. If it contains a string then all 3 parameters (f_nd,
f_dir, and f_nm) are used and the ‘set’ data dictionary is not used at all.
This parameter may also contain the full directory path. If this is the case
then the f_dir parameter must contain the value TLS_NODIR_T.

Note: The FAST/TOOLS directory numbers

(TLS_<name>_T) must not be used in this
parameter - the full path must be specified.
mode defines the locking and access mode to be used when opening the
data file. The mode is derived by arithmetically adding the locking type
and the access mode required. The values should be chosen from the
following (as defined in the header file “isam.h”):
• for the locking type, one of;
- ISEXCLLOCK
- ISMANULOCK
- ISAUTOLOCK
• for the access type, one of;
- ISINPUT
- ISOUTPUT
- ISINOUT
File and record locking and access is described in detail in the
key is the name of the index which is to used for subsequent file access
operations using the view. The name must be one of those as specified
in the key data dictionary. If this parameter is a NULL pointer, then the
primary key will be used by default.
timeout is the time-out period (specified in seconds) to be used when
accessing a data file located on another node. It indicates the length of
time to wait for a message from the remote node server before
disconnecting and reporting an error. A value of ‘0’ (zero) indicates that
no time-out is to be used, that is; wait forever.
If the data file is located on the same node as the DBV routines then the
time-out value has no significance and this parameter is therefore
ignored.
table is the definition of the view itself. It is a table of “dbv_view_fld”
structures, each table entry defining one of the fields in the view. The
order in which the fields are specified in the table is the order in which
they will be placed in the view. The end of the table must be indicated
to DBV. This is achieved by adding an extra entry with a NULL pointer
placed in the “phys_field” field.
View specification is described in detail in Chapter 3.
Errors The following is a list of the possible errors that may result from a call
to “dbv_create()”. Some of the errors will produce extra information in
the error flags array - this is indicated below as appropriate.

• DBV_F_EXCEPTION
An exceptional circumstance has arisen. Details are included in the
error message.
• DBV_F_REP_TYPES
The REP_<type> types in the header file “global.h” have values
other than those expected by DBV. This will happen if these values
are changed in some way.
• DBV_F_FMT_STR_OVF
The record format string is too large.
• DBV_E_FILE
An error occurred during the opening of the file on which the view
is based. The exact cause of the error is indicated by deeper nested
error information.
• DBV_E_SUP_FILE
An error occurred with the specified set-up file. Extra information
is provided indicating the exact nature of the error.
• DBV_E_DICT
An error occurred during the reading of the data dictionary - this
applies equally to the set, key, and field data dictionaries. The exact
cause of the error is indicated by deeper nested error information.
• DBV_E_NO_SET
The specified data set name is not known in the set data dictionary.
• DBV_E_NO_KEY
The specified key name is not known in the key data dictionary.
• DBV_E_BOUND
The logical field is not lying on the correct boundary for its type.
The error flags array indicates to which view field(s) this applies.
(Note: this is the only “E” severity message code where the whole
view definition table is checked before returning)
• DBV_E_PHYS_FIELD
An error occurred when processing one of the “phys_field” fields
in the view definition table.
The error flags array indicates the nature of the error and the logical
field to which it applies.
• DBV_E_VIEW_TYPE
An error occurred when processing one of the “view_type” fields in
the view definition table.
The error flags array indicates the nature of the error and the view
• DBV_E_ELEMENTS
An error occurred when processing one of the “elements” fields in
the view definition table.

The error flags array indicates the nature of the error and the view
• DBV_W_ALM
At least one array length mismatch was detected. The error flags
array indicates to which view field(s) this applies.
• DBV_W_TYPM
At least one data type mismatch was detected (where neither field
is of type REP_STRING). The error flags array indicates to which
view field(s) this applies.
Note: If either DBV_W_ALM or DBV_W_TYPM
or both occur, then DBV adds the code
DBV_W_GENERAL before returning to
the application. This can be used for testing
purposes by the application.

6.5.3 Read a record
Syntax [status=] dbv_read(ptr,umh_c,err_flags,mode,buf,buf_sz)

void *ptr; /* view pointer */
int mode; /* read mode */
char *buf; /* view buffer */
TLS_LONG buf_sz; /* size of view buffer */
Semantics dbv_read() is used to read a record using the view.

ptr is the view pointer assigned by dbv_create().
umh_c is used for error logging.
be declared). If the routine returns FALSE then some bits may have been
set.
mode defines the read mode for reading from the data file. Either
sequential or random access can be used. The value should be chosen
from the following (as defined in the header file “isam.h”):
• for sequential access;
- ISCURR
- ISFIRST
- ISLAST
- ISNEXT
- ISPREV
• for random access
- ISEQUAL
- ISGREAT
- ISGTEQ
In order to use random access, the following three conditions must be
satisfied:
1 ISEQUAL, ISGREAT, or ISGTEQ must be specified.
2 The key currently in use must be part of the view. The ‘current key’
is defined as one of the following:
- the primary key, chosen by default
- the key specified with the key argument to “dbv_create()”
- the key specified by calling “dbv_key()”

3 the search value(s) must be placed in the relevant position(s) in the

view buffer (all remaining fields of the buffer must be given the
value ‘zero’)
If the record is to be locked before being read, then the mode value
should be arithmetically added with the flag ISLOCK. This is only
appropriate if the ISMANULOCK locking mode was used when the
view was created.
buf is the buffer into which the view record should be put. The buffer
must be at least the size of the view record (it may be larger), and should
be correctly aligned as described in Section 5.2.
buf_sz is the size in bytes of the buffer passed to the routine.
to “dbv_read()”. Some of the errors will produce extra information in the
error flags array - this is indicated below as appropriate.
• DBV_F_EXCEPTION
error message.
• DBV_E_RD_FAIL
An error occurred while reading the record from the file. The exact
• DBV_E_KEY_FAIL
An error was detected while trying to set the key to read on. The
exact cause of the error is indicated by deeper nested error
information.
• DBV_E_BUF_SMALL
The buffer passed as argument is too small to contain the view.
• DBV_E_KEY_NOT_IN
Random access was specified, but the current key is not part of the
view.
• DBV_E_KEY_TRNS
Random access was specified. At least one array overflow (string)
or value overflow/underflow occurred whilst converting the key
field(s) from view to physical records.
• DBV_W_ARR_OVF
At least one array overflow (string) was detected whilst converting
from physical to view records.
• DBV_W_VAL_OVF
At least one value overflow was detected whilst converting from

physical to view records.

• DBV_W_VAL_UNF
At least one value underflow was detected whilst converting from
physical to view records.
Note: If any of the following errors occur:
DBV_W_ARR_OVF
DBV_W_VAL_OVF
DBV_W_VAL_UNF
then DBV adds the code

6.5.4 Lock/unlock
Syntax [status=] dbv_lck_ulck(ptr,umh_c,func)

TLS_LONG func; /* required function */
Semantics dbv_lck_ulck() is used to perform file and record locking operations.

This routine may only be used if the ISMANULOCK locking mode was
used when the view was created.
ptr is the view pointer assigned by “dbv_create()”.
func indicates the type of operation required. The value of this
parameter should be chosen from one of the following (as defined in the
header file “dbv.h”):
• DBV_LOCK_FIL
This will lock the file. Other processes will then have read access
but not write access to the file.
• DBV_UNLK_FIL
This will unlock the file after being locked with the previous option.
• DBV_UNLK_REC
This will unlock all records that have been previously [manually]
locked. Records are locked by using the ISLOCK flag when
“dbv_read()” is called.
Manual file and record locking is described in detail in the DATABASE/
FAST Programmer’s Guide.
to “dbv_lck_ulck()”.
• DBV_E_LCK_FAIL
The locking operation failed for some reason. The exact cause of
• DBV_E_INV_FUNC
The func parameter has an unknown value.

6.5.5 Modify a record
Syntax [status=] dbv_modify(ptr,umh_c,err_flags,buf)

char *buf; /* view buffer */
Semantics dbv_modify() is used to modify a record using the view. Only those
fields contained within the view will be modified - all other fields will
remain the same.
The primary key is used to locate the correct record to modify, and
therefore it is necessary that the primary key is contained within the
view. However, it is not necessary for the ‘current key’ to be the primary
key when this routine is called - DBV will set the primary key and then
revert back to the original key when finished, if necessary. Therefore,
the value of the ‘current key’ is not changed by this routine.
be declared). If the routine returns FALSE then some bits may have been
set.
buf is the buffer containing the modified view record to be written to the
file. The value(s) contained in the primary key field(s) will be used as
search values to locate the correct record.
If only a subset of the view record is to be modified, then the following
actions must be performed:
1 Set the ‘current key’ to the primary, if not already set, by calling
“dbv_key()”.
2 Call “dbv_read()” with the correct search value(s) in the primary
key field(s) of the view buffer.
3 Modify the fields in the returned view buffer as required.
4 Call “dbv_modify()” with the same view buffer.
Note: The primary key value(s) must be unique
and may not be changed.

to “dbv_modify()”. Some of the errors will produce extra information in
the error flags array - this is indicated below as appropriate.
• DBV_F_EXCEPTION
error message.
• DBV_E_MOD_FAIL
The routine reads a record before modifying it. Therefore, this error
may be produced during either the reading or modifying. The
operation that caused the error, and its exact nature, is indicated by
• DBV_E_KEY_FAIL
An error was detected while trying to set the primary key. The exact
• DBV_E_PRIM_NOT_IN
The primary key is not part of the view.
• DBV_E_KEY_TRNS
At least one array overflow of value overflow/underflow occurred
whilst converting the primary key field(s) from view to physical
buffers.
• DBV_W_ARR_OVF
At least one array overflow (string) was detected whilst converting
from view to physical records.
• DBV_W_VAL_OVF
At least one value overflow was detected whilst converting from
view to physical records.
• DBV_W_VAL_UNF
At least one value underflow was detected whilst converting from
view to physical records.
Note: If any of the following errors occur:
DBV_W_ARR_OVF
DBV_W_VAL_OVF
DBV_W_VAL_UNF
then DBV adds the code

6.5.6 Set the key
Syntax [status=] dbv_key(ptr,umh_c,key)

char *key; /* name of key to set */
Semantics dbv_key() is used to set the key for subsequent file access. Calling this
routine sets the value of the ‘current key’.
key is the name of the key required. This must be as specified in the key
data dictionary.
to “dbv_key()”.
• DBV_E_NO_KEY
The key name specified is not known in the key data dictionary.

6.5.7 Destroy a view
Syntax [status=] dbv_destroy(ptr,umh_c)

void **ptr; /* view pointer */
Semantics dbv_destroy() is used to remove a view from the system when it is no

longer required. It is the responsibility of the application programmer to
ensure that this routine is called when a particular view is finished with
in order to release system resources.
Once this routine has been called with a particular view pointer, that
view will be subsequently no longer available, that is; the routine always
removes the view from the system. The only error that can result is one
produced whilst trying to close the data file on which the view was
originally created.
ptr is the address of view pointer assigned by “dbv_create()”.
Errors • DBV_E_DSTR_FAIL
An error occurred whilst trying to close the data file. The exact

Examples
This appendix contains two examples of how an application might use
the DataBase View facility.
The following text file is the “.ddl” file defining the physical record
structure and used as input to the DDL compiler:
set:dbv_set,,,,5,“dbv_file.dat”,;
rec:dbv_record
{
long a;
long b[4][2];
short c;
ushort d;
boolean e;
float f;
double g;
char h[12];
ubyte i[8];
struct
{
long c;
struct
{
char j[12];
long k[2][2];
}l[2];
}m[2][2];
};
key:prm_key = (a) NODUP

key:sec_key = (h) DUP
The examples use a data dictionary called “dbvdic” which is assumed to

contain the description contained in the “.ddl” file.
The physical data file used in the examples is called “dbv_file.dat” and
is located on the FAST/TOOLS ‘data’ directory.
DBV Programmer’s Guide A-1

Examples Creating/Reading/Modifying
A.1 Creating/Reading/Modifying
This example will perform the following actions:
1 create a view
2 read a record using the primary key
3 modify some fields in the record
4 modify the physical record
5 remove the view from the system
#include <tools.h> /* also includes global.h */

#include <dur.h> /* contain the ... */
#include <umh.h> /* ... #defines and ... */
#include <isf.h> /* ... struct definitions */
#include <dbv.h> /* the DataBase View header file */
main()
{
/*-----------------------------------------------------------------------------+
| Define the ‘view definition table’
+-----------------------------------------------------------------------------*/
static struct dbv_view_fld table[] =
{
{ “a”, (TLS_LONG)REP_LONG, 0 },
{ “d”, (TLS_LONG)REP_SHORT, 0 },
{ “c”, (TLS_LONG)REP_USHORT, 0 },
{ “g”, (TLS_LONG)REP_DOUBLE, 0 },
{ “b[3]”, (TLS_LONG)REP_SHORT, (TLS_LONG)2 },
{ “i”, (TLS_LONG)REP_UBYTE, (TLS_LONG)8 },
{ “m[1][1].c”, (TLS_LONG)REP_LONG, 0 },
{ “m[0][0].l[0].j”, (TLS_LONG)REP_STRING, (TLS_LONG)12 },
{ “m[1][0].l[1].k[0]”, (TLS_LONG)REP_LONG, (TLS_LONG)2 },
{ “h”, (TLS_LONG)REP_STRING, (TLS_LONG)8 },
{ (char *) NULL, 0, 0 }
};
/*-----------------------------------------------------------------------------+
| Declare the ‘view buffer’
+-----------------------------------------------------------------------------*/
struct
{
TLS_LONG a;
TLS_SHORT d;
TLS_USHORT c;
TLS_DOUBLE_S g;
TLS_SHORT b[2];
TLS_UBYTE i[8];
TLS_LONG m_c;
char m_l_j[12];
TLS_LONG m_l_k[2];
char h[8];
}view_buffer;
/*-----------------------------------------------------------------------------+
| Declare other variables
+-----------------------------------------------------------------------------*/
struct dur_context dur_cont; /* DUR context buffer */
struct umh_context err_cont; /* Error context buffer */
void *view_ptr = NULL; /* the ‘view pointer’ */
TLS_LONG *err_flags = NULL; /* pointer to the ‘error flags’ */
A-2 DBV Programmer’s Guide

Creating/Reading/Modifying Examples
/*-----------------------------------------------------------------------------+
| Attach to DUR
+-----------------------------------------------------------------------------*/
if (!dur_umh_init(&dur_cont, &err_cont, 10, 100, 512, 512, (char *)NULL))
{
exit(BAD_EXIT);
}
/*-----------------------------------------------------------------------------+
| Create the view
+-----------------------------------------------------------------------------*/
if (!dbv_create(&view_ptr,
&dur_cont,
&err_cont,
&err_flags,
(char *)NULL, /* no set-up file used */
0, /* DD on “own” node */
“dbvdic”, /* name of DD to use */
“dbv_set”, /* name of data set */
0, /* data file on “own” node... */
TLS_DATA_T, /* ...on F/T ‘data’ directory... */
(char *)NULL, /* ...with name as in DD */
ISAUTOLOCK | ISINOUT, /* locking and access modes */
(char *)NULL, /* use the primary key */
(TLS_LONG)0, /* this timeout value is ignored */
table)) /* the view definition table */
{
/*-----------------------------------------------------------------------------+
| if the routine returns FALSE then check the severity of the most recent
| UMH message code
| if only ‘warnings’ have occurred then the details may be examined...
+-----------------------------------------------------------------------------*/
if (umh_error(&err_cont) == DBV_W_GENERAL)
{
... print out the details - both UMH buffer and ‘error flags’ ...
}
/*-----------------------------------------------------------------------------+
| ...otherwise the ‘creation’ has failed
+-----------------------------------------------------------------------------*/
else
{
exit(BAD_EXIT);
}
}
/*-----------------------------------------------------------------------------+
| Read the first record from the file using the view
+-----------------------------------------------------------------------------*/
if (!dbv_read(view_ptr,
&err_cont,
&err_flags,
ISFIRST,
(char *)&view_buffer,
sizeof(view_buffer)))
{
{
}
else
{
exit(BAD_EXIT);
}
}

Examples Changing key/Locking
/*-----------------------------------------------------------------------------+
| Modify some fields then modify the record using the view
+-----------------------------------------------------------------------------*/
view_buffer.c = (TLS_USHORT)400;
view_buffer.m_c = (TLS_LONG)10000;
strcpy(view_buffer.h, “field h”);
if (!dbv_modify(view_ptr,
&err_cont,
&err_flags,
(char *)&view_buffer))
{
{
}
else
{
exit(BAD_EXIT);
}
}
/*-----------------------------------------------------------------------------+
| Remove the view from the system
+-----------------------------------------------------------------------------*/
if (!dbv_destroy(&view_ptr, &err_cont))
{
exit(BAD_EXIT);
}
/*-----------------------------------------------------------------------------+
| Detach from DUR and exit
+-----------------------------------------------------------------------------*/
if (!dur_det(&dur_cont, &err_cont))
{
exit(BAD_EXIT);
}
exit(GOOD_EXIT);
}
A.2 Changing key/Locking

This example will perform the following actions:
1 create a view using “manual” locking
2 change the key
3 read two records using the ‘second’ key and manually lock them
while reading
4 unlock the records
5 remove the view from the system
#include <tools.h> /* also includes global.h */

#include <dur.h> /* contain the ... */

Changing key/Locking Examples
#include <umh.h> /* ... #defines and ... */

#include <isf.h> /* ... struct definitions */
#include <dbv.h> /* the DataBase View header file */
main()
{
/*-----------------------------------------------------------------------------+
| Define the ‘view definition table’
+-----------------------------------------------------------------------------*/
static struct dbv_view_fld table[] =
{
{ “a”, (TLS_LONG)REP_LONG, 0 },
{ “d”, (TLS_LONG)REP_SHORT, 0 },
{ “c”, (TLS_LONG)REP_USHORT, 0 },
{ “g”, (TLS_LONG)REP_DOUBLE, 0 },
{ “b[3]”, (TLS_LONG)REP_SHORT, (TLS_LONG)2 },
{ “i”, (TLS_LONG)REP_UBYTE, (TLS_LONG)8 },
{ “m[1][1].c”, (TLS_LONG)REP_LONG, 0 },
{ “m[0][0].l[0].j”, (TLS_LONG)REP_STRING, (TLS_LONG)12 },
{ “m[1][0].l[1].k[0]”, (TLS_LONG)REP_LONG, (TLS_LONG)2 },
{ “h”, (TLS_LONG)REP_STRING, (TLS_LONG)8 },
{ (char *) NULL, 0, 0 }
};
/*-----------------------------------------------------------------------------+
| Declare the ‘view buffer’
+-----------------------------------------------------------------------------*/
struct
{
TLS_LONG a;
TLS_SHORT d;
TLS_USHORT c;
TLS_DOUBLE_S g;
TLS_SHORT b[2];
TLS_UBYTE i[8];
TLS_LONG m_c;
char m_l_j[12];
TLS_LONG m_l_k[2];
char h[8];
}view_buffer;
/*-----------------------------------------------------------------------------+
| Declare other variables
+-----------------------------------------------------------------------------*/
struct dur_context dur_cont; /* DUR context buffer */
struct umh_context err_cont; /* Error context buffer */
void *view_ptr = NULL; /* the ‘view pointer’ */
TLS_LONG *err_flags = NULL; /* pointer to the ‘error flags’ */
/*-----------------------------------------------------------------------------+
| Attach to DUR
+-----------------------------------------------------------------------------*/
if (!dur_umh_init(&dur_cont, &err_cont, 10, 100, 512, 512, (char *)NULL))
{
exit(BAD_EXIT);
}
/*-----------------------------------------------------------------------------+
| Create the view using “manual” locking
+-----------------------------------------------------------------------------*/
if (!dbv_create(&view_ptr,
&dur_cont,
&err_cont,
&err_flags,
(char *)NULL, /* no set-up file used */
0, /* DD on “own” node */
“dbvdic”, /* name of DD to use */
“dbv_set”, /* name of data set */

0, /* data file on “own” node... */

TLS_DATA_T, /* ...on F/T ‘data’ directory... */
(char *)NULL, /* ...with name as in DD */
ISMANULOCK | ISINOUT, /* locking and access modes */
(char *)NULL, /* use the primary key */
(TLS_ULONG)0, /* this timeout value is ignored */
table)) /* the view definition table */
{
/*-----------------------------------------------------------------------------+
| if the routine returns FALSE then check the severity of the most recent
| UMH message code
| if only ‘warnings’ have occurred then the details may be examined...
+-----------------------------------------------------------------------------*/
{
}
/*-----------------------------------------------------------------------------+
| ...otherwise the ‘creation’ has failed
+-----------------------------------------------------------------------------*/
else
{
exit(BAD_EXIT);
}
}
/*-----------------------------------------------------------------------------+
| Change the key to the ‘second’ key
+-----------------------------------------------------------------------------*/
if (!dbv_key(view_ptr, &err_cont, “sec_key”))
{
exit(BAD_EXIT);
}
/*-----------------------------------------------------------------------------+
| Read the first two records from the file using the ‘second’ key and lock
| them at the same time
+-----------------------------------------------------------------------------*/
&err_cont,
&err_flags,
ISFIRST | ISLOCK,
{
{
}
else
{
exit(BAD_EXIT);
}
}
&err_cont,
&err_flags,
ISNEXT | ISLOCK,
{

Changing key/Locking Examples
{
}
else
{
exit(BAD_EXIT);
}
}
/*-----------------------------------------------------------------------------+
| Unlock the records
+-----------------------------------------------------------------------------*/
if (!dbv_lck_ulck(view_ptr, &err_cont, DBV_UNLK_REC))
{
exit(BAD_EXIT);
}
/*-----------------------------------------------------------------------------+
| Remove the view from the system
+-----------------------------------------------------------------------------*/
if (!dbv_destroy(&view_ptr, &err_cont))
{
exit(BAD_EXIT);
}
/*-----------------------------------------------------------------------------+
| Detach from DUR and exit
+-----------------------------------------------------------------------------*/
if (!dur_det(&dur_cont, &err_cont))
{
exit(BAD_EXIT);
}
exit(GOOD_EXIT);
}


Warnings Error messages
Appendix B: Error messages

This appendix contains a list of all possible UMH error messages that
may be generated by the DataBase View facility.
Extra information, such as variable values, is given with some of the
messages. This is indicated by the symbol *** in the messages.
B.1 Warnings
• DBV_W_GENERAL
warning(s) occurred - see err_flags
• DBV_W_ALM
array length mismatch between physical and view fields
• DBV_W_TYPM
data type mismatch between physical and view fields
• DBV_W_ARR_OVF
array overflow occurred during translation
• DBV_W_VAL_OVF
value overflow occurred during translation
• DBV_W_VAL_UNF
value underflow occurred during translation
B.2 Errors
• DBV_E_TABLE
view definition table is empty
• DBV_E_FILE
ISF error occurred when opening the data file
• DBV_E_SUP_FILE
error with the specified set-up file
• DBV_E_DICT
ISF error occurred when reading the data dictionary
• DBV_E_NO_SET
set name *** not known in data dictionary
• DBV_E_NO_KEY
key name *** not known in data dictionary
• DBV_E_KEY_NOT_IN
random access not possible - key is not in the view
DBV Programmer’s Guide B-1

Error messages Fatal errors
• DBV_E_BOUND
view definition table boundary error(s) - see err_flags
• DBV_E_PHYS_FIELD
error with ‘phys_field’ field - see err_flags
• DBV_E_VIEW_TYPE
error with ‘view_type’ field - see err_flags
• DBV_E_ELEMENTS
error with ‘elements’ field - see err_flags
• DBV_E_RD_FAIL
ISF error occurred when reading the record
• DBV_E_KEY_FAIL
ISF error occurred when setting the key
• DBV_E_BUF_SMALL
buffer is too small for the view
• DBV_E_KEY_TRNS
error occurred when translating the key field(s)
• DBV_E_LCK_FAIL
ISF error occurred during locking/unlocking
• DBV_E_INV_FUNC
invalid locking function argument
• DBV_E_MOD_FAIL
ISF error occurred when modifying the record
• DBV_E_PRIM_NOT_IN
primary key field(s) are not within the view
• DBV_E_DSTR_FAIL
ISF error occurred when closing the file
B.3 Fatal errors

• DBV_F_EXCEPTION
Exceptional error
• DBV_F_FMT_STR_OVF
format string overflow
• DBV_F_REP_TYPES
‘REP_*’ types in <global.h> have unexpected values
B-2 DBV Programmer’s Guide

UNIX and Windows System info
Appendix C: System info

This appendix contains specific information about using the DataBase
View facility on the various platforms.
C.1 UNIX and Windows

The following features are not supported on the UNIX and Windows
platforms.
Attempting to use these features will result only in a ‘testable’ error
being returned with no action performed - the process will not abort.
• options for the mode parameter to dbv_read()
- ISPREV
- ISLAST
DBV Programmer’s Guide C-1

System info UNIX and Windows
C-2 DBV Programmer’s Guide

Index
Index
A multi-node 2-2
arrays
multi-dimensional 3-3
N
one-dimensional 3-1 node 2-2
structure/union 3-3
O
B one-dimensional arrays 3-1
basic field item 3-1, 3-4, 3-5
P
C physical fields
changing the file structure 2-2, 3-8 default ‘instance’ 3-2
names 2-2, 3-2
D strings 3-7
data dictionaries, see dictionaries
data set 2-1
R
default field ‘instance’ 3-2 random access 2-2
dictionaries return values 4-1, 6-1
alias field names 2-3
DDL compiler 2-1 S
F/T general 2-1 sequential access 2-2
updating 2-2 severity of message codes 4-2
structure/union arrays 3-3
F
field errors 4-2 T
fields type conversion
logical, see view fields possible errors 3-6
physical, see physical fields table 3-7
file structure change 2-2, 3-3, 3-8
U
H UNIX C-1
header files 6-1
V
K view fields
key names 2-2 alignment 3-8
errors 4-2
L
logical fields, see view fields W
Windows C-1
M
message code severity 4-2
multi-dimensional arrays 3-3
DBV Programmer’s Guide 1

Index
2 DBV Programmer’s Guide

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction ITEM/FAST FAST/TOOLS
Manual ITH Programmer’s Guide
IM50J02J00-01EN/R10.03

IM50J02J00-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction ..........................................................................1-1
1.2 About the functionality ..............................................1-1
2 Mechanism ............................................................................2-1
2.1 Terminology from ITH’s point of view .....................2-1
2.2 The method ................................................................2-1
3 Configuration ........................................................................3-1
3.1 Introduction ...............................................................3-1
3.2 Start creation, modification or deletion .....................3-1
3.3 Insertion, deletion or listing items .............................3-2
3.4 Ending or canceling a configuration ..........................3-4
4 Store and Retrieve ................................................................4-1
4.1 Introduction ...............................................................4-1
4.2 (M)DUR store interface .............................................4-1
4.2.1 Direct/Item-based storage ......................................... 4-1
4.2.2 Direct/Event-based storage ....................................... 4-2
4.3 (M)DUR retrieve interface ........................................4-3
4.3.1 Direct item history .................................................... 4-5
4.3.2 Direct event history ................................................... 4-6
4.4 Get-put routine interface ............................................4-7
4.4.1 Modifying existing samples ...................................... 4-7
4.4.2 Inserting new samples ............................................... 4-8
4.4.3 Overwriting a range of samples ................................ 4-8
5 Reference guide .....................................................................5-1
5.1 Compiling, linking and running programs ................5-1
5.2 General data structs ...................................................5-1
5.2.1 struct ith_grp_con ..................................................... 5-1
5.2.2 struct ith_itm_con ..................................................... 5-2
5.2.3 struct ith_retr_msec ................................................... 5-3
5.2.4 struct ith_retr ............................................................. 5-4
5.2.5 Struct ith_store_di ..................................................... 5-6
ITH Programmer’s Guide iii

Table of Contents
5.2.6 Struct ith_store_de .................................................... 5-6

5.2.7 Struct ith_gp_sample ................................................. 5-7
5.3 Routines and BUS/FAST messages .......................... 5-7
5.3.1 Cancel configuration ................................................. 5-8
5.3.2 Create storage group ................................................. 5-9
5.3.3 Delete storage group ............................................... 5-10
5.3.4 End configuration .................................................... 5-11
5.3.5 Group info ............................................................... 5-12
5.3.6 Item info .................................................................. 5-13
5.3.7 Item info next .......................................................... 5-14
5.3.8 Insert item ............................................................... 5-15
5.3.9 Modify storage group .............................................. 5-16
5.3.10 Return generation parameters ................................. 5-17
5.3.11 Set get-put interface to overwrite range mode ........ 5-18
5.3.12 Get sample during get-put session .......................... 5-19
5.3.13 Insert sample during get-put session ....................... 5-20
5.3.14 Put sample during get-put session ........................... 5-21
5.3.15 Start get-put session ................................................ 5-22
5.3.16 Stop get-put session ................................................ 5-23
5.3.17 Delete item .............................................................. 5-24
5.3.18 Retrieve item ........................................................... 5-25
5.3.19 Retrieve item with milli second resolution ............. 5-27
5.3.20 Direct/Item-based storage ....................................... 5-28
5.3.21 Direct/Event-based storage ..................................... 5-29
Appendix A: BUS/FAST examples .............................................. A-1
A.1 Retrieve session with (M)DUR ................................ A-1
A.2 Retrieve session with routine interface .................... A-3
iv ITH Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives
functionality of the ITH-brick.
ITH-routines.

language. To understand the concept of ITH, the reader is assumed to
((M)DUR).

• Chapter 1 can be regarded as an introduction to the ITH
mechanism.
• Chapter 2 contains a description of the ITH mechanism
• Chapter 3 contains a description of the configuration of item history
• Chapter 4 contains a description of the retrieve and put functions
familiar with the concept of ITH.
ITH Programmer’s Guide 0-1


• BUS/FAST Programmer’s Guide, Volumes 1,2 and 3:
which are used.
software.
• DATABASE/FAST Programmer’s Guide (ISM & ISM)
• HISTORY/FAST Programmer’s Guide
• ITEM/FAST ITM Programmer’s Guide

CONVENTION MEANING
DUR_NOWAIT.
input.
returns.
output.
0-2 ITH Programmer’s Guide


literally.
n.u. not used.
a terminal.
from the user.


1 Introduction

ITEM/FAST comprises a number of bricks. Item History (ITH) is one of
these bricks, which deals with the history of process values, as reflected
by items.
1.2 About the functionality

Item History as brick could be used in all that applications where there
exists a need to keep track of process values at some point in the future,
such as for statistical purposes or governmental demands, etc.
In all cases where historical data has to be retrieved, the process values
are referred to as the values/statuses of items. In every request for
retrieving data it will be done on an item-based manner.
Item History is not useful as a brick itself when one is intending to store
for historical purposes; it should be accompanied with the rest of the
ITEM/FAST tool. (e.g. it requires the item table.)
To perform both the storage (and before this the configuration) and
retrieval of data with the aid of ITH, there should be at least a minimum
of three ITH-processes be active:
1 ITHSER, the server process
2 one of ITHSTx, ITHSIx, ITHEEx, ITHSDI, ITHSDE, the gather
and store process
3 one of ITHRTT, ITHRTI, ITHRTE,ITHRDI, ITHRDE the retrieve
process
In this not all combinations are possible, choosing a gather/store process
determines the retrieve process according to the following table:
ITHSTx ITHRTT
ITHSIx ITHRTI
ITHEEx ITHRTE
ITHSDI ITHRDI
ITHSDE ITHRDE

Introduction About the functionality
Apart from these processes interacting with each other, ITH strongly
depends on the availability of the History Manager (HIS) on the one
hand, and, for retrieving, a user-process on the other.
All requests to ITH can be done by means of an (M)DUR interface and
involve configuration of storage groups and retrieval of historical data.
There is one simple routine interface to perform a single retrieve request
and a put-option to put the (updated) retrieved value back again.
Some utilities are provided:
1 ITHDBG, a debug utility to monitor ITH-processes and inspect
files (both item directory and data files)
2 ITHRECOVER, a recover utility
The information that’s stored will be gathered by the item history

processes for the Scan/Time, Scan/Item and Event/Event based storage
groups. The information for the Direct/Item and Direct/Event based
storage groups must be supplied by an application process. The Direct
Application Item handler
Direct/Item Scan/Item
Direct/Event Scan/Time
Event/Event Store
Item History
Retrieve
Application
Figure 1-1 Information gathering and storage
storage groups can only be used if an application is build to store

information in these groups, otherwise the groups will always be empty.

Terminology from ITH’s point of view Mechanism
2 Mechanism
2.1 Terminology from ITH’s point of view

Although the concepts of storage groups and units can be found in the
HISTORY/FAST Programmer’s Guide, a brief description will be given
from ITH’s point of view in this section.
A storage group for ITH is a set of which the members are the items to
be stored and retrieved historically. Such a set of items then has some
characteristics (therefore being member of one group):
1 scan/event gathering
2 scan interval
3 storage orientation
4 etc.
2.2 The method

Once you have defined and scheduled a group (at HIS) and configurated
it (at ITHSER), probably via USER/FAST forms, the gathering/storage
of data for historical purposes will take place with appropriate
parameters according to what was specified.
If a group is known by HIS, this will be sufficient for retrieval, whether
or not the group is active (active means that is currently used for
storage).
To see in more detail how all of this works, one is invited to read the
subsequent chapters.

Mechanism The method

Introduction Configuration
3 Configuration
3.1 Introduction
This chapter describes the configuration of Item History storage groups.
Before an Item History group can be started, it has to be configurated.
Before we can start gathering and storage of a history group, we first
have to create it. An existing group can also be modified or deleted. The
procedure to create or delete a group consists of two steps:
1 Start creation or deletion
2 End or cancel configuration
The procedure to modify a group consists of three steps:
1 Start modification
2 Insert, delete or list items in the group
3 End or cancel configuration
All these steps are done by sending DUR messages to the Item History
server ITHSER. ITHSER may reside on another node.
3.2 Start creation, modification or deletion

A group configuration is initiated by sending a DUR message to
ITHSER including the name of the group. The message code tells
ITHSER what you are planned to do, creation modification or deletion
of a group.
If you are going to create a group you have to specify the following
(struct ith_grp_con):
• Message code ITH_CREATE.
• The name of the group to create.
All other message members are ignored by ITHSER. ITHSER checks if
there is already a storage group with that name. If so, ITHSER returns
an error. If such group does not exist, ITHSER will lock the request at
the History Manager so that no one else is allowed to start also a
configuration for that group.
ITHSER returns the request message with all members set to a default

Configuration Insertion, deletion or listing items
value like history path (which is defined in the ITHSER setup file). Now
you can continue the creation by sending an end message or cancel the
action by sending a cancel.
If you are going to modify or delete a group you must send the following
message (struct ith_grp_con):
• Message code ITH_MODIFY or ITH_DELETE.
• The name of the group to modify or delete.
All other message members are ignored by ITHSER. ITHSER checks
that the group exists and is of type Item History. If not found, ITHSER
returns an error else ITHSER locks the group at the History Manager so
than no one else is allowed to start a configuration on the same group.
ITHSER returns the request with all the members filled in. Now you can
insert, delete or list items if you are modifying the group. If deleting the
group you can only end or cancel the configuration.
It it also possible to request information of an existing group with the
message (struct ith_grp_con):
• Message code ITH_INFO_GRP.
• The name of the group.
All other members of the struct are ignored by ITHSER. ITHSER will
return that request message with all members filled in when the group
exists and when you are not busy configuration an other group. You
don’t need to end or cancel an information request.
Your process may only configure one group at the same time. If you are
configurating a group and you start another configuration, ITHSER will
return an error.
3.3 Insertion, deletion or listing items

When you started a group modification you can insert, delete or list
items in the group. Note that string type items cannot be inserted, due to
the variable string value length.
When you insert an item you have to specify the following (struct
ith_itm_con):
• Message code ITH_INSERT.
• The name of the item you want to insert.
• The attribute of the item you want to store (value, low limit, high
limit, etc.).

Insertion, deletion or listing items Configuration
The status of the item will always be stored. Currently you can only
store the value when the group type is event based gathering and
event oriented storage. The following attributes can be stored:
- 0 - Value
- ITM_ATT_DB - Deadband
- ITM_ATT_LL - Low limit
- ITM_ATT_LLL - Low low limit
- ITM_ATT_HL - High limit
- ITM_ATT_HHL - High high limit
• If the group type is event based gathering and event oriented
storage, you have to specify the event criterion. If the group is of
another type, the criterion will be ignored. The following criterions
can be specified:
- ITM_CRI_FIRST - First update
- ITM_CRI_VAL - Changed value
- ITM_CRI_STA - Changed status
- ITM_CRI_EACH - Each update
- ITM_CRI_PIT - Changed filter result
- ITM_CRI_DEL - Item deleted
- ITM_CRI_OPT - Changed OPT flags
- ITM_CRI_QC - Changed quality code
To select more than one criterion you have to logical-or them. ITHSER
checks the existence of the item and if existing it will be inserted in the
group description.
It is not possible to insert an item more than once if it has the same
attribute.
ITHSER will return the request message if the insert was successful.
When you delete an item you have to specify the following (struct
ith_itm_con):
• Message code ITH_REMOVE.
• The name of the item you want to delete.
All other members of the message struct are ignored. ITHSER checks
the existence of the item in the group and if found it will be deleted from
the group.
ITHSER will return the request message when the delete was successful.
To list items already defined in the group you have to specify the
following (struct ith_itm_con):
• Message code ITH_INFO_ITM or ITH_INFO_ITM_NXT.
• The name of the item to get info about.
• The attribute.

Configuration Ending or canceling a configuration
If the message code is ITH_INFO_ITM, you have only to specify the

item’s name. ITHSER will return info about the item which name is
lexical equal or greater than the name you specified. All other message
members are ignored.
If the message code is ITH_INFO_ITM_NXT, you have to specify the
items’s name or the attribute. If you specify the name and the attribute
is not equal to ITH_NEXT, ITHSER will return info about an item
which name is lexical greater then the one you specified.
If you specify an attribute with the value ITH_NEXT, ITHSER return
info about the next item in the group description. Before you use this
option you must have requested item info using one of the two previous
mentioned requests.
If there is info found, ITHSER will return the request message with
members updated or filled-in. See ‘insertion of an item’ for the meaning
of the message members.
3.4 Ending or canceling a configuration

Ending a group configuration is done by sending a message. This is
normally the reply you received from ITHSER, when you started the
configuration, with some members modified. The layout of this message
(struct ith_grp_con) is:
• Message code ITH_DONE.
• The group name gives the name of the group to refer it in other
actions. It is allowed to change the name. If the new name already
exists, ITHSER will return an error, but the configuration is ended
successful and the group will remain its old name.
• History path tells Item History where to store the group
configuration file and the unit files on the disk. This path must be a
valid disk directory path. If you omit the history path, Item History
stores the data to the current directory which is depending on how
Item History is generated and started. So, always specify the history
path.
• Shadow path tells Item History where to store the unit files also. If
the shadow path is omitted, Item History does not perform the
shadow recording.
When modifying a group and you modify a path, data previously
stored will become unaccessible by Item History. The group
configuration file is copied by ITHSER to the newly specified
directory.

Ending or canceling a configuration Configuration
• The group type includes how the values are gathered and how they
are stored. Three different types can by specified:
- Scan based gathering and time oriented storage. Items in the
group will be gathered by scanning the real-time item database
in a specified interval and the values are stored in a record
which includes all scanned item values of a single scan. When
specifying this type of group, you must also specify the scan
interval.
- Scan based gathering and item oriented storage. Items in the
group will be scanned by scanning the real-time item database
in a specified interval. Values of an item are saved until a
certain time and written in a single record to the unit data file.
When specifying this type of group, you must also specify the
scan interval and the value save time.
- Event based gathering and event oriented storage. Values are
gathered by generating events of ITEM/FAST to Item History.
Every event is saved as a single record.
- Direct event oriented storage. Values must be supplied by an
application process. Events can be send to Item History by a
BUS/FAST message.
- Direct item oriented storage. Values must be supplied by an
application process. The storage of these values is equal to the
direct event oriented storage, with one difference: The time
between the events is a period.
It is not allowed to change the group type when modifying a group. In
that case ITHSER returns an error and the configuration will remain
active.
• The task number of the gather task which will handle the gathering
and storage of the group. Normally there is a process for every
group type. When you have a lot of groups of the same type, you
can install and start more than one process for that type of group.
Such task handles all groups which have specified a task number
which is the same as defined in the setup file for that process.
normally you will have one process with the task number zero and
you specify zero for the group task number.
• The node number specifies the DUR node on which the real-time
item database resides. When specifying your own node, you have
two options, specifying zero or the real own node number. If you
specified zero, the gather and store processes will use the ITEM/
FAST routine interface to scan items, otherwise the DUR interface
will be used. This is only the case when the group type is scan based
gathering.

Configuration Ending or canceling a configuration
When configurating a group with a node number other than your

own node, a connection with that node must exist.
It is not allowed to change the node number when modifying a
group. In that case ITHSER returns an error and the configuration
will remain active.
• Priority tells ITHSER which group to use when you are retrieving
history and the item to retrieve in specified in more than one group
and you also didn’t specify the group to use in the retrieve request.
The higher the number the higher the priority.
• Interval specifies the scan interval for the group when the type is
scan based gathering.
• Save time specifies the maximum time an item value may be saved
in memory before it is written to disk when the group type is item
oriented storage. This value must be larger than the interval time.
• The convert double flag tells the gather and store task to convert
any item with double representation to float. This to save disk
storage space.
When you have checked or modified these parameters you send the end
request to ITHSER. ITHSER checks the data, creates the group
description file on the specified path if you where creating a group.
Finally the group is unlocked at History Manager.
All members of the message are ignored when ending an deletion.
Deletion of a group will also delete all history information.
As mentioned before some errors will not end the configuration. In that
case you have to retry the ending (with adjusted parameters). Other
errors may leave the group description file in an unknown state. Be very
careful when modifying history paths.
Be aware that the modifications of a group will become active the next
rollover or start of the group.
A configuration can be cancelled by sending (struct ith_grp_con):
• Message code ITH_CANCEL.
All other message members are ignored. The group (if existing) is left in
the state as before the configuration start.

Introduction Store and Retrieve
4 Store and Retrieve
4.1 Introduction
The gathering of values for the Direct storage groups must be done by
an application. These applications can send the gathered values to Item
History by using the store interface.
The gathering for the Scan/Item, Scan/Time and Event/Event storage
groups is done by Item History and don’t have a programmers interface.
The retrieval of stored values can be done by an application that uses the
retrieve interface. This interface is identical for all storage group types.
For special applications a possibility is created to modify values that are
stored. This interface is the GET-PUT interface.
4.2 (M)DUR store interface

The recommended way to store data, is to request ITH for it by means
of a (M)DUR request.
4.2.1 Direct/Item-based storage
Item-based storage will store per item the start-time, the interval time
and the samples.
Start-time Interval-time Sample Sample Sample

Store and Retrieve (M)DUR store interface
The application can send collected samples to the item history. When
collected samples contains overlap in time the Direct/Item storage will
remove the old samples for the overlap time period.
Already stored samples
New samples from application

Stored samples
Direct/Item storage will not have a sample in its data unit, directly after
a roll-over, as the collection is done by an application process. So if the
storage process does not retrieve a sample, it will remain empty for ever
4.2.2 Direct/Event-based storage
Event-based storage will store the first sample with the time it occurred,
the second sample with the time it occurred, etc. per item.
Thus Event-based storage must be used when there is no fixed interval
between the samples. When the samples have a fixed interval the Item-
based storage can be used to save disk storage space.
Sample-time Sample Sample-time Sample Sample-time Sample

(M)DUR retrieve interface Store and Retrieve
The application can send collected samples to the item history. When
collected samples contains overlap in time. The Direct/Event storage
will merge the samples to a new set of history.
Already stored samples
New samples from application

Stored samples
Direct/Event storage will not have a sample in its data unit, directly after
a roll-over, as the collection is done by an application process. So if the
storage process does not retrieve a sample, it will remain empty for ever.
4.3 (M)DUR retrieve interface

The recommended way to retrieve historical data, is to request ITH for
it by means of a (M)DUR request. Historical data can be retrieved with
one of the following requests:
ITH_RETRIEVE seconds resolution, optional quality code
ITH_RETR_MSEC milli second resolution, with quality code
With these requests respectively a struct “ith_retr” or “ith_retr_msec”
can be sent to the ITHSER process which will complete the request
where necessary and will take care that a reply will be sent with (in case
no error occurred) the same struct as header of the message body and a
number of ith_val, ith_val_stq or ith_val_msec structures as an array of
returned/retrieved values. So the layout of every request and reply is
independent of the item history storage type.
The things that must be specified or may optionally be specified in the
request are the following:
• item ID or item name. The item name has preference because in the
past the relation item name - item id may have been changed.
• info, only of interest when requesting on item name and other than
value (for example low-limit) is wanted.

Store and Retrieve (M)DUR retrieve interface
• group ID or group name, optional, when omitted ITHSER will

make the choice (based on priority of groups and furthermore
arbitrary).
• start-time, start time of time-window for retrieve request, when
omitted earliest known time stamp for the group is assumed.
• end-time, stop time of time-window for retrieve request, when
omitted retrieve till current time is assumed.
• wanted-representation, the representation to which the values in the
reply are converted to, when omitted representation as stored is
returned.
• interpolation, specifies the use of previous or next value
(chronologically) when the time-raster for retrieve doesn’t match
the raster as stored, when omitted previous is assumed.
• granule, specifies the time-raster on which the values have to be
retrieved, when omitted the raster as stored is assumed.
• max return size, specifies the maximum number of bytes to return
in the reply.
In all of these fields the convention is that a value of zero (or empty in
case of asciz-string variables) means: omitted. Where time values have
to be specified, GMT representation is assumed.
The GRAN parameter for ITH_RETR_MSEC can be used in the
following ways:
• gran.sec == 0 and gran.msec == 0
All available samples in the wanted period are returned.
• gran.sec == 0xFFFFFFFF and gran.msec == 0
An (interpolated) sample for the start time of the wanted period
followed by all available samples in the wanted period are returned.
• All other gran values:
The (interpolated) samples for all times points “start time + n * gran
(where n = 0, 1, 2, ...)” are returned.
The reply is exactly as shown above with the request except for the fact
that now both item ID and item name and both group ID and group name
will be filled as is the wanted representation. Two more things are
returned in the reply:
• more-next, indicates if there is more data available for this item in
the original specified retrieve time window, if so, the start time for
the next request is supplied in this field.
• an array of ith_val, ith_val_stq or ith_val_msec structures. These
structures contain the following information:
- time stamp, the time for this value
- control, indicates reason for invalid value

(M)DUR retrieve interface Store and Retrieve
- option, item handler’s option byte

- status, item handler’s status
- value, value of item
- quality code, item handler’s quality code
Using the above description a single retrieve session will look like:
main()
{
struct ith_retr_msec request, *reply;
.
.
request.item_name = my_item_name;
.
request.interpol = ITH_POL_NEXT;
request.wanrep = REP_DOUBLE;
.
.
stop_it = FALSE;
while (!stop_it)
{
dur_snd();
dur_rcv_rep();
if (!error)
{
.
process values, e.g. display them
.
if (!reply->more_next)
stop_it = TRUE;
else
{
.
request.start = more_next;
.
}
}
}
}
4.3.1 Direct item history
The retrieval of historical value for Direct/Item storage can be done by

any application in the same way as for the other storage methods. The
information that will be retrieved depends on the storage method and on
the information that is stored in the group.

Store and Retrieve (M)DUR retrieve interface
The Direct/Item storage groups will reply with the samples that are
stored. For the periods that no samples are available invalid samples will
be replied.
t
Invalid Invalid
Samples Samples
To check if a period should result in invalid samples, the period time of

the previous record, together with the period time of the next record will
be considered to determine the maximum time gap that will be seen as
“valid”. This has been depicted in the figure below:.
Period a Period b Period c
t
Invalid Valid
(Gap > a + b) (Gap < b + c)
This method is used within one storage unit. At the beginning and at the
end of a storage unit the maximum gap may be twice the period of the
record that is after or before the gap. If a storage unit doesn’t contain a
record for the item, invalid samples will be replied.
4.3.2 Direct event history
The Direct/Event storage groups will reply the samples that are stored.
The value during the time period before the first sample in a data-unit,
depends on the previous data-unit. If a valid last sample is found in the
previous data-unit, that value will be replied. If no valid last sample is
found an invalid sample will be returned If there is no sample in the

Get-put routine interface Store and Retrieve
current data-unit, an invalid sample will be returned. Therefore the

collection application should store a sample in each data-unit.
a b c d e f t
Data-units
Retrieving history from a Direct/Event-based storage group with a

signal as in this example, will result in invalid samples from the
beginning of data-unit c till the first sample in data-unit d.
4.4 Get-put routine interface

With the get-put routine interface it is possible to get all the exact
samples for an item one by one for a selected time period from a history
group. Each sample can be changed if wanted.
For this feature the following routines are available:
• ith_gp_sta start get-put session
• ith_gp_clr set clear mode
• ith_gp_ins insert a new sample
• ith_gp_get get (next) sample
• ith_gp_put rewrite last retrieved sample
• ith_gp_sto stop get-put session
4.4.1 Modifying existing samples
This sequence is used to overwrite an existing sample with a new values,

status and quality code. All history types support overwriting existing
samples.
A typically program using this mechanism may look like this:
main()

Store and Retrieve Get-put routine interface
{
void *ith_cont;
struct ith_gp_sample sample;
.
ith_cont = ith_gp_sta (...);
.
while (ith_gp_get (ith_cont, &sample))
{
.
if (...) ith_gp_put (ith_cont, &sample);
.
}
ith_gp_sto (ith_cont);
}
The exact parameters of the routines are described in the reference
guide.
4.4.2 Inserting new samples
This sequence is used to insert a new sample. Only Event/Event and

Event/Item history types are supported.
main()
{
void *ith_cont;
struct ftm_time time;
.
.
if (ith_gp_get (ith_cont, &sample))
{
.
if (...) ith_gp_ins (ith_cont, &sample, &time);
.
}
}
4.4.3 Overwriting a range of samples
This sequence is used to overwrite all samples within a time range with
the sample value. All history types support overwriting existing
samples.

Get-put routine interface Store and Retrieve
main()
{
void *ith_cont;
.
.
if (ith_gp_clr (ith_cont))
{
.
if (...) ith_gp_put (ith_cont, &sample);
.
}
}
In this sequence ith_gp_get() is not used. Routine ith_gp_clr() sets the

get-put interface to overwrite range mode. The time range to be
overwritten is specified by the ith_gp_sta() routine. After the call to
ith_gp_clr() a sequence of ith_gp_put() calls are used to overwrite the
existing history. For example with the ith_gp_sta() call a time range of
Ts to Te was specified. The first call to ith_gp_put() with a time stamp
T1 will overwrite an existing sample at T1. If for this timestamp no
sample exists then it will be added (for Event/Event and Event/Time
history type only). The next call to ith_gp_put() with timestamp T2 will
overwrite all existing samples in time range T1 to T2 with the value
given by the first call to ith_gp_put(). Then an existing sample at T2 will
be overwritten by the value supplied with T2. If no sample exists at T2
then it will be inserted. This sequence can be repeated as many times as
required. The timestamp supplied with ith_gp_put() must always be
bigger then the one supplied be a previous call to ith_gp_put().
When the ith_gp_sto() is called then all samples in the time period of Tx
supplied with the last call to ith_gp_put() up to Te will be overwritten
with the sample supplied by the last call to ith_gp_put().

Store and Retrieve Get-put routine interface

Compiling, linking and running programs Reference guide
5 Reference guide

Using the BUS/FAST interface of Item History the following is needed:
• Item History must be installed and running.
• ith.h must be included.
Also the following FAST/TOOLS must be installed.
• BUS/FAST.
• DATABASE/FAST.
• ITEM/FAST.
• HISTORY/FAST.
5.2 General data structs

In order to have a reference to structure definitions mentioned in this
section, variables have been introduced. These variable names are
referred to in the remainder of this manual.
5.2.1 struct ith_grp_con
Starting and ending a group configuration is done by sending the

following struct to ITHSER:
struct ith_grp_con
{
char path[TLS_FPATH_SZ]; /* History file path */
char sh_path[TLS_FPATH_SZ];/*Backup path */
char grp_name[HIS_GRP_NAME_SZ];/*Group name */
TLS_ULONG inter; /* Scan interval (sec) if
scan based gathering */
TLS_ULONG save; /* Value save time (sec) if
item oriented storage*/
TLS_BOOLEAN cnv_dbl; /* See below */
TLS_UBYTE gath; /* Gathering type */
TLS_UBYTE stor; /* Storing type */
TLS_UBYTE task; /* Gather task number */
TLS_UBYTE node; /* Item table node numb.*/

TLS_UBYTE priority; /* Group priority */

TLS_USHORT ave_interval; /* Averaging interval */
TLS_BOOLEAN fill_old_rec; /* Fill existing data recs*/
} grp_con;
Member cnv_dbl can have one or more of the following flags set:
• ITH_CNV_DBL - Convert doubles to floats
• ITH_STR_QC - Store quality code
Member gath can have one of the following values:
• ITH_G_SCAN - Scan based gathering.
• ITH_G_EVENT - Event based gathering.
• ITH_G_DIRECT - Application based gathering.
Member stor can have one of the following values:
• ITH_S_TIME - Time oriented storage.
• ITH_S_ITEM - Item oriented storage.
• ITH_S_EVENT - Event oriented storage.
The following gath and stor combinations are valid:
• ITH_G_SCAN with ITH_S_TIME.
• ITH_G_SCAN with ITH_S_ITEM.
• ITH_G_EVENT with ITH_S_EVENT.
• ITH_G_DIRECT with ITH_S_ITEM.
• ITH_G_DIRECT with ITH_S_EVENT.
5.2.2 struct ith_itm_con
When a group modification is active, items can be inserted, deleted and

listed using the following struct:
struct ith_itm_con
{
struct gin_item_flnm item_name; /* Item name */
TLS_SHORT crit_mask; /* Event criterion mask if
event based gathering*/
TLS_UBYTE info; /* Info type attribute */
TLS_UBYTE spare;
} itm_con;
Member crit_mask can be a logical-or of the following:
• ITM_CRI_FIRST - First update
• ITM_CRI_VAL - Changed value
• ITM_CRI_STA - Changed status
• ITM_CRI_EACH - Each update

• ITM_CRI_PIT - Changed filter result

• ITM_CRI_DEL - Item deleted
• ITM_CRI_OPT - Changed OPT flags
• ITM_CRI_QC - Changed quality code
Member info can be one of the following:
• 0 - Value
• ITM_ATT_DB - Deadband
• ITM_ATT_LL - Low limit
• ITM_ATT_LLL - Low low limit
• ITM_ATT_HL - High limit
• ITM_ATT_HLL - High high limit
• ITH_NEXT - Special
• ITH_ATT_QC - Value, status and quality code
Note that ITEM/FAST symbols are used here.
5.2.3 struct ith_retr_msec
When a retrieve with code ITH_RETR_MSEC is done, the following

structs should be used:
struct ith_retr_msec
{
TLS_UBYTE info; /* Info type (att_no) */
TLS_UBYTE wan_rep; /* Wanted representation*/
TLS_UBYTE interpol; /* wanted interpolation */
TLS_UBYTE spare;
struct itm_id item_id; /* Internal item id */
struct his_grp_nr grp_id; /* Group number */
TLS_ULONG ref; /* User reference */
TLS_USHORT ret_size; /* Requestor buffer size*/
TLS_UBYTE spare2[2];
struct ith_tim_seq start; /* Start time window */
struct ith_tim_seq end; /* End time window */
struct ith_tim_seq gran; /* Time granule */
struct ith_tim_seq more_next;/*More data avail from*/
TLS_LONG data[1]; /* Data */
}
Member interpol can be one of the following:
• ITH_POL_PREV (default)
• ITH_POL_NXT
In the reply, an array of ith_val_msec structs is returned starting at the
position of element data[1]:

struct ith_val_msec
{
struct ith_tim_seq stamp; /* timestamp of value */
TLS_UBYTE ctrl; /* ITH control byte */
TLS_UBYTE status; /* ITM item status */
TLS_UBYTE opt_flags; /* ITM item option flags*/
TLS_UBYTE par1; /* par1 */
union itm_val_union value; /* ITM item value */
TLS_ULONG quality; /* ITM item quality */
};
Member ctrl can be zero or a logical-or ITH_ABN_VAL (indicating
abnormal value) and one of the following:
• ITH_INV_VAL - invalid value due to item handler
• ITH_INV_SCAN - gatherer couldn’t scan correctly
• ITH_INV_RTV - retriever couldn’t retrieve correctly
• ITH_CNV_ERR - retriever couldn’t convert value correctly
• ITH_MAN_VAL - manual update of value is performed
• ITH_INI_VAL - initial value indicator
Member par1 can have the following flags set:
• ITH_QC_VALID - quality code is valid (storage done with
quality code storage set)
• ITH_QC_NOTVALID - quality code is not valid (no quality code
was stored)
For time stamps the struct ith_tim_seq is used:
struct ith_tim_seq
{
TLS_ULONG sec; /* Seconds since 1970 */
TLS_USHORT msec; /* Milli seconds */
TLS_USHORT seq; /* Sequence if same time*/
}
5.2.4 struct ith_retr
When a retrieve with code ITH_RETRIEVE is done, the following

structs should be used:
struct ith_retr
{
TLS_UBYTE info; /* Info type (att_no) */
TLS_UBYTE wan_rep; /* Wanted representation*/
TLS_UBYTE spare[2];
struct itm_id item_id; /* Internal item id */


struct his_grp_nr grp_id; /* Group number */
TLS_ULONG ref; /* User reference */
TLS_ULONG start; /* Start time window */
TLS_ULONG end; /* End time window */
TLS_ULONG gran; /* Time granule */
TLS_ULONG interpol; /* wanted interpolation */
TLS_ULONG ret_size; /* Requestor buffer size*/
TLS_ULONG more_next; /* More data avail from */
TLS_LONG data[1]; /* Data */
}
Member interpol can be one of the following:
• ITH_POL_PREV (default)
• ITH_POL_NXT
In the reply, an array of ith_val structs (if info != ITH_ATT_QC) or
ith_val_stq structs (if info == ITH_ATT_QC) is returned starting at the
position of element data[1]:
struct ith_val{
TLS_ULONG stamp; /* time stamp of value */
TLS_UBYTE spare; /* spare */
};
• ITH_INV_VAL invalid value due to item handler
• ITH_INV_SCAN gatherer couldn’t scan correctly
• ITH_INV_RTV retriever couldn’t retrieve correctly
• ITH_CNV_ERR retriever couldn’t convert value correctly
• ITH_MAN_VAL manual update of value is performed
struct ith_val_stq
{
TLS_ULONG stamp; /* timestamp of value */
TLS_UBYTE par1; /* par1 */
TLS_ULONG quality; /* ITM item quality */
};


• ITH_INV_VAL - invalid value due to item handler
• ITH_INV_SCAN - gatherer couldn’t scan correctly
• ITH_INV_RTV - retriever couldn’t retrieve correctly
• ITH_CNV_ERR - retriever couldn’t convert value correctly
• ITH_MAN_VAL - manual update of value is performed
Member par1 can have the following flags set:
• ITH_QC_VALID - quality code is valid (storage done with
quality code storage set)
• ITH_QC_NOTVALID - quality code is not valid (no quality code
was stored)
5.2.5 Struct ith_store_di
In order to store items in the Direct/Item-based storage group a message

of the following lay-out must be sent to ITHSDI.
struct ith_store_di
{
struct itm_id item_id; /* Item identification */
struct his_grp_nr grp_id /* Storage group id */
TLS_ULONG start; /* Time of the first
sample */
TLS_ULONG delta; /* Interval time */
TLS_LONG count; /* Number of samples */
struct itm_val_stq sample[1];/*Samples */
};
5.2.6 Struct ith_store_de
In order to store items in the Direct/Event-based storage group a

message of the following lay-out must be sent to ITHSDE.
struct ith_store_de
{
struct his_grp_nr grp_id; /* Storage group id */
TLS_LONG count; /* Number of samples */
struct ith_de_sample sample[1];/*Samples */
};

struct ith_de_sample
{
struct ftm_time timestamp; /* Sample time */
struct itm_val_stq value; /* Sample value */
};
The programmer never has to change the contents of this struct.
5.2.7 Struct ith_gp_sample
For the get-put interface the struct ith_gp_sample is defined:

struct ith_gp_sample
{
struct ith_val_stq value; /* Sample value */
struct ftm_time timestamp; /* Sample time */
TLS_ULONG sequence; /* Sequence within time */
};
The element value.value will always be of the representation type
REP_DOUBLE.

ITHSER is the user server process for Item History. All messages have
to be sent to this process, except for the store message interface of Direct
storage (message specification).

5.3.1 Cancel configuration
BUS/FAST Message id : ITH_CANCEL

Message Request data: struct ith_grp_con
Reply data : struct ith_grp_con
Data structs For general structs reference should be made to Section 5.2
Semantics This message is used to cancel an active group configuration like

creating, modifying or deleting a group. The group description is left in
the state as it was before the start of configuration. If creating a group,
no creation is done, if modifying a group all insertions and deletions are
cancelled and if deleting a group, the group is not deleted. All members
of the message are ignored.
Notes A cancel of a group creation or deletion is forced by Item History when

there were no configuration commands received within a certain time.
Errors • ITH_E_NACTCONF
No group configuration active.
• ITH_E_GRPCON
Group configuration error.

5.3.2 Create storage group
BUS/FAST Message id : ITH_CREATE

Semantics This message will start a group configuration to create a history group.
The request only has to specify the name of the group to create. All other
Item History returns the same message with members set to default
values.
The actual creation is activated by sending an ITH_DONE message. The
create request can be canceled by an ITH_CANCEL message.
Errors • ITH_E_ACTCONF
Already busy with group configuration.
Group already exists.
• ITH_E_GRPCON

5.3.3 Delete storage group
BUS/FAST Message id : ITH_DELETE

Semantics This message will start a group configuration to delete a history group.
The request only has to specify the name of the group to delete. All other
Item History returns the same message with members set to there current
value.
The actual deletion is activated by sending an ITH_DONE message. The
delete request can be canceled by an ITH_CANCEL message.
Notes Only not active groups can be deleted. An active group is a group
currently gathering and storing history.
Deleting a group includes the deletion of all history information.
Group doesn’t exist.
• HIS_E_GROUPHASUNT
Group has still an active unit connected.
• HIS_E_IS_LOCKED
Someone is working on this group.
• ITH_E_GRPCON

5.3.4 End configuration
BUS/FAST Message id : ITH_DONE

Semantics This message is used to end a group configuration. All members of the
request must be specified.
Notes • When modifying a group it is not allowed to change some

members.
• An end of a group modification is forced by Item History when
there were no configuration commands received within a certain
time.
Group already exists.
• ITH_E_INVGATH
Invalid gather type specified.
• ITH_E_INVSTOR
Invalid storage type specified.
• ITH_E_INVNODECHNG
Not allowed to change node number.
• ITH_E_INVGATHCHNG
Not allowed to change gathering type.
• ITH_E_INVPATH
Invalid paths specified.
• ITH_E_GRPCON

5.3.5 Group info
BUS/FAST Message id : ITH_INFO_GRP

Semantics The message is used to get information about a group without starting a
configuration cycle. The request specifies the name of the group to
retrieve information about.
value.
• ITH_E_GRPCON

5.3.6 Item info
BUS/FAST Message id : ITM_INFO_ITM

Message Request data: struct ith_itm_con
Reply data : struct ith_itm_con
Semantics This message is used to list items defined in a group when modifying the
group. Only the item name has to be specified in the request. Item
History returns information about the item which name is lexical greater
or equal to the name specified in the request.
Reply member crit_mask has no meaning when requesting item info
about a group not based upon event based gathering.
• ITH_E_ITMEXISTNOT
Specified item not found.
• ITH_E_GRPCON

5.3.7 Item info next
BUS/FAST Message id : ITH_INFO_ITM_NXT

Semantics This message is used to list items defined in a group when modifying the
group. If ITH_NEXT is specified in the request member info, Item
History returns information about the next item in the group description.
If you specify a value not equal to ITH_NEXT, Item History returns
information about the item which name is lexical greater to the name
specified in the request.
Reply member crit_mask has no meaning when requesting item info
about a group not based upon event based gathering.
• ITH_E_GRPCON

5.3.8 Insert item
BUS/FAST Message id : ITH_INSERT

Semantics This message is used to insert a new item in a group while modifying the
group.
• ITH_E_ITMNOTALL
Item modification only allowed when modifying group.
• ITH_E_ITMEXIST
Specified item already exists.
• ITH_E_UNKNWNITM
specified item name not defined.
• ITH_E_GRPCON
• ITH_E_STRINS
Not allowed to insert a string item in item history.

5.3.9 Modify storage group
BUS/FAST Message id : ITH_MODIFY

Semantics This message will start a group configuration to modify a history group.
The request only has to specify the name of the group to modify. All
other members are ignored.
value.
The actual modification is activated by sending an ITH_DONE
message. The modify request can be canceled by an ITH_CANCEL
message. In that case all inserted and removed items will be ignored.
• HIS_E_IS_LOCKED
Someone is working on this group.
• ITH_E_GRPCON

5.3.10 Return generation parameters
Syntax par = ith_params(par_type)
Arguments TLS_LONG par; /* (R)Value of parameter */

int par_type; /* (I)Requested parameter */
Semantics This routine returns one of the generation parameters of Item History.
The requested parameter must be passed in par_type. The following
parameter types are supported:
• ITH_LOG_STARTED
This value indicates if logging of Item History started messages is
enabled or disabled. A value of zero means disabled.
Errors None

5.3.11 Set get-put interface to overwrite range mode
Syntax [status =] ith_gp_clr (ith_cont)

void *ith_cont; /* (M)Internal context */
Semantics With this routine the get-put interface is set to ‘Overwriting a range of
samples’ mode.
Errors ITH_E_NODATA Failed to set mode

5.3.12 Get sample during get-put session
Syntax [status =] ith_gp_get (ith_cont, samp)

struct ith_gp_sample *samp; /* (O)Found sample */
Semantics With this routine the first/next value can be requested during a get-put
session. If necessary, the routine will walk over history unit boundaries
until the to_time specified in the ith_gp_sta() routine is reached.
The element samp->value.value will always be of the representation
type REP_DOUBLE.
Errors ITH_E_NODATA No sample found
ITH_E_NOGETPUT The get-put interface is not enabled (see
ithser.sup)

5.3.13 Insert sample during get-put session
Syntax [status =] ith_gp_ins (ith_cont, samp, timestamp)

struct ith_gp_sample *samp; /* (I)New sample */
struct ftm_time *timestamp; /* (I)Timestamp of sample */
Semantics With this routine an sample can be added during a get-put sequence.
Prior a call to ith_gp_ins() a call to ith_gp_get() has to be called.
type REP_DOUBLE.
Errors ITH_E_NODATA No sample inserted

5.3.14 Put sample during get-put session
Syntax [status =] ith_gp_put (ith_cont, samp)

struct ith_gp_sample *samp; /* (I)Changed sample */
Semantics With this routine a sample can be changed during a get-put session.
Elements of the sample struct which may be changed are:
samp->value.value item value
samp->value.status item value status
samp->value.opt_flags item option flags
samp->value.ctrl item history control flags
samp->value.quality item quality code
All other fields of the sample struct are ignored unless the ‘Overwriting
a range of samples’ sequence is used. In this case the samp->timestamp
is use.
type REP_DOUBLE.
The bit ITH_MAN_VAL of element samp->value.ctrl will internally be
set by this function.
Errors ITH_E_NOPUT Put action did not succeed
ITH_E_NOGETPUT The get-put interface is not enabled (see
ithser.sup)

5.3.15 Start get-put session
Syntax ith_cont = ith_gp_sta (dur_c, umh_c, node, group_name,

item, attrib, from_time, to_time)
Arguments void *ith_cont; /* (R)Internal context */

struct dur_context *dur_c; /* (I)Dur context */
struct umh_context *umh_c; /* (M)Umh context */
int node; /* (I)History node number */
char *group_name; /* (I)History group name */
struct gin_item_flnm *item;/* (I)Item name*/
int attrib; /* (I)Item attribute numb. */
struct ftm_time *from_time; /* (I)Start time session */
struct ftm_time *to_time; /* (I)Stop time session */
Semantics With this routine a get-put session can be started. Memory will be
allocated for internal administration. The first ith_gp_get() call after this
start request will return the first sample of the specified item in the
specified history group during the specified time span.
The parameter attrib may have one of the following values:
ITM_ATT_VAL Value, status and quality code
ITM_ATT_DB Deadband
ITM_ATT_LL Low limit
ITM_ATT_HL High limit
ITM_ATT_LLL Low low limit
ITM_ATT_HHL High high limit
Errors ITH_F_NOMEMORY Memory allocation failure

ITH_E_BADATTR Bad attribute number

5.3.16 Stop get-put session
Syntax ith_gp_sto (ith_cont)
Arguments void *ith_cont; /* (I)Internal context */
Semantics With this routine a get-put session can be stopped. Memory allocated for
internal administration will be released.
Errors None

5.3.17 Delete item
BUS/FAST Message id : ITH_REMOVE

Semantics This message is used to delete a new item from a group while modifying
the group.
• ITH_E_ITMNOTALL
Item modification only allowed when modifying group.
• ITH_E_GRPCON

5.3.18 Retrieve item
BUS/FAST Message id : ITH_RETRIEVE

Message Request data: struct ith_retr
Reply data : struct ith_retr
Semantics This message is used to retrieve an item’s historical data with seconds
resolution.
Errors • ITH_E_NO_UDACC
access on unit data not successfully completed
• ITH_E_NO_UDSND
send on unit data not successfully completed
• ITH_E_NODATA
no data retrieved
• ITH_E_NOREPR
couldn’t convert to wanted representation correctly
• ITH_E_NOCNV
couldn’t convert to wanted system-type correctly
• ITH_E_REVSTAMP
no event-data with reversed time stamp key
• ITH_E_NO_ADM_UPD
couldn’t check and/or update internal administration
• ITH_E_NO_ADM_INFO
couldn’t get wanted internal administration info
• ITH_E_NO_RTV_SND
couldn’t send to specific retriever
• ITH_E_ITMNOTADM
item not in external administration
• ITH_E_NOGRPID
no group ID found for specified group name
• ITH_E_NOFNAME
no file name for this (nr, seq) pair
• ITH_E_NO_RTVR
no retrieve process to handle request
• ITH_E_WDWNOUN
group (%node:d,%nr:d): no units found for specified time-window
[%start:d,%stop:d]

• ITH_F_NOMEMORY
memory allocation failure

5.3.19 Retrieve item with milli second resolution
BUS/FAST Message id : ITH_RETR_MSEC

Message Request data: struct ith_retr_msec
Reply data : struct ith_retr_msec
Semantics This message is used to retrieve an item’s historical data with

milliseconds resolution.
Errors • ITH_E_NO_UDACC
access on unit data not successfully completed
• ITH_E_NO_UDSND
send on unit data not successfully completed
• ITH_E_NODATA
no data retrieved
• ITH_E_NOREPR
couldn’t convert to wanted representation correctly
• ITH_E_NOCNV
couldn’t convert to wanted system-type correctly
• ITH_E_REVSTAMP
no event-data with reversed time stamp key
• ITH_E_NO_ADM_UPD
couldn’t check and/or update internal administration
• ITH_E_NO_ADM_INFO
couldn’t get wanted internal administration info
• ITH_E_NO_RTV_SND
couldn’t send to specific retriever
• ITH_E_ITMNOTADM
item not in external administration
• ITH_E_NOGRPID
no group ID found for specified group name
• ITH_E_NOFNAME
no file name for this (nr, seq) pair
• ITH_E_NO_RTVR
no retrieve process to handle request
• ITH_E_WDWNOUN
group (%node:d,%nr:d): no units found for specified time-window
[%start:d,%stop:d]

• ITH_F_NOMEMORY
memory allocation failure
5.3.20 Direct/Item-based storage
Server process: ITHSDI

Message id : ITH_STORE_DI
Request data: struct ith_store_di
Reply data : empty
Semantics Sending this message to the item history will cause samples to be stored
in the Direct/Item-based storage group(s).
The grp_id specifies the storage group into which the samples must be
stored. If the storage group isn’t a Direct/Item-based storage group an
error will be returned. If no group id is specified, the samples will be
stored in all Direct/Item-based storage groups for which the item is
configured.
The start time is the time of the first sample. The delta time is the
interval time between the samples. The samples must be in time order,
oldest sample first.
If the storage group is configured with no quality code, the quality code
in the message will not be used.(It still must be in the message, but it has
no meaning.)
If the storage group is configured for data compression, the data
compression will be done by the item history process.
The maximum number of samples in the message is 100. If the
maximum number of samples in the storage record is less than the
number of samples in the message, the item history process will split the
samples into two or more records.
Warnings
Errors • ITH_W_NO_NOVALUNIT
Message contains samples with an illegal (too old or too new)
timestamp.
Errors • ITH_E_BAD_SAMP
Invalid number of samples in request
• ITH_E_INVORDER
Timestamp of samples out of order

• ITH_E_NOCONFIG
Item is not configured for this/any storage group.
• ITH_E_NOGROUP
Unknown storage group
5.3.21 Direct/Event-based storage
Server process: ITHSDE

Message id : ITH_STORE_DE
Request data: struct ith_store_de
Reply data : empty
Semantics Sending this message to the item history will cause samples to be stored
in the Direct/Event-based storage group(s).
The grp_id specifies the storage group into which the samples must be
stored. If the storage group isn’t a Direct/Event-based storage group an
error will be returned. If no group id is specified, the samples will be
stored in all Direct/Event-based storage groups for which the item is
configured.
The start time is the time of the first sample. The delta time is the
interval time between the samples. The samples must be in time order,
oldest sample first.
If the storage group is configured with no quality code, the quality code
in the message will not be used.(It still must be in the message, but it has
no meaning.)
If the storage group is configured for data compression, the data
compression will be done by the item history process.
The maximum number of samples in the message is 100. If the
maximum number of samples in the storage record is less than the
number of samples in the message, the item history process will split the
samples into two or more records.
Warnings
Errors • ITH_W_NO_NOVALUNIT
Message contains samples with an illegal (too old or too new)
timestamp.
Errors • ITH_E_BAD_SAMP
Invalid number of samples in request

• ITH_E_INVORDER
Timestamp of samples out of order
• ITH_E_NOCONFIG
Item is not configured for this/any storage group.
• ITH_E_NOGROUP
Unknown storage group

Retrieve session with (M)DUR BUS/FAST examples
Appendix A: BUS/FAST examples
A.1 Retrieve session with (M)DUR

In this program an example is given for a retrieve session using the
(M)DUR interface.
#include <ith.h>
#define MAX_RET_SIZE \
2*sizeof(TLS_SHORT )+(sizeof(struct ith_retr) - \
4+10*sizeof(struct ith_val))
#define MAX_SND_BUF 1000

#define MAX_RCV_BUF 1000
main()
{
struct dur_par_rcv dur_par_rcv;
struct dur_par_snd dur_par_snd;
struct dur_adr ith_ser;
struct mess
{
TLS_SHORT size;
TLS_SHORT code;
struct ith_retr ith_retr;
} *req, *repl;
struct ith_retr *in,*out;
struct ith_val *p;
int mess_size;
TLS_BOOLEAN stop_it = FALSE;
/* init dur and umh */

/* allocate receive buffer */
buf = malloc(MAX_RCV_BUF);
/* init recieve parameters */
if (!dur_rcv_ini (&dur_cont,&err_cont,
&dur_par_rcv,buf,MAX_RCV_BUF))
{
umh_log (&err_cont);
exit(BAD_EXIT);
}
if (!dur_adr_ini(&ith_ser,0,"ITHSER",0))
{
exit(BAD_EXIT);
ITH Programmer’s Guide A-1

BUS/FAST examples Retrieve session with (M)DUR
buf = malloc(MAX_SND_BUF); /* allocate send buffer */

if (!dur_snd_ini (&dur_cont,&err_cont,/* init send parameters */
&dur_par_snd,buf,MAX_SND_BUF,NULL))
{
exit(BAD_EXIT);
}
dur_par_snd.rcv_adr = ith_ser;
/* do not wait on replies */

dur_par_snd.sync_type = DUR_SYNC_NOWAIT;
req = (struct mess *)dur_par_snd.msg_buf_pnt;
repl = (struct mess *)dur_par_rcv.msg_buf_pnt;
dur_par_snd.reply_required = TRUE;
dur_par_snd.msg_size = sizeof(struct mess);
dur_par_rcv.time_out = 30;
in = &req->ith_retr;
out = &repl->ith_retr;
strcpy(in->item_name.name,”ITH.ITH.REAL”);
in->info = 0;
strcpy(in->grp_name,"group1");
in->wan_rep = REP_FLOAT;
in->interpol = ITH_POL_NEXT;
in->start = 605000000;
in->end = 605086000;
in->gran = 300;
in->ret_size = MAX_RET_SIZE;
req->size = sizeof(struct mess);
req->code = ITH_RETRIEVE;
while (!stop_it)
{
dur_snd(&dur_cont,&err_cont,&dur_par_snd);
if (!dur_rcv_rep(&dur_cont,&err_cont,&dur_par_rcv) ||
repl->code & FMC_ERR_BIT)
{
exit(BAD_EXIT);
}
mess_size = dur_par_rcv.msg_size-(sizeof(struct mess)-4);
if (out->more_next)
in->start = more_next;
for (p = (struct ith_val *)out->data;
mess_size >= sizeof(struct ith_val);
mess_size -= sizeof(struct ith_val) ,p++)
{
if (p->ctrl)
printf("%d: invalid\n",p->stamp);
else
printf("%d: %d, %d, %f\n",p->stamp,p->status,
p->opt_flags,p->value);
}
}
}
A-2 ITH Programmer’s Guide

Retrieve session with routine interface BUS/FAST examples
A.2 Retrieve session with routine interface

In this program an example is given for a retrieve - change session using
the routine interface.
#include <dur.h>
#include <umh.h>
#include <fsl.h>
#include <itm.h>
#include <ith.h>
main(argc,argv)
int argc;
char *argv[];
{
struct dur_context context;
char io_buf[FIO_MAX_INP];
struct itm_id itm_id;
TLS_LONG val,buf[25];
struct gin_item_flnm item = {0};
TLS_SHORT size;
TLS_LONG node,attrib;
void *ith_cont;
char group[100];
char tim_string1[100];
char tim_string2[100];
struct ftm_time from_time,to_time;
TLS_BOOLEAN put = 0;
/* attach to BUS/FAST and initialize values */

dur_umh_init (&context,&err_cont,4,1000,512,512,”b180”);
node = 0;
group[0] = 0;
attrib = 0;
tim_string1[0] = 0;
tim_string2[0] = 0;
fio_ltd_long (io_buf,&node,“Give history node number”,

FIO_RETRY | FIO_DFL,(TLS_LONG)0,(TLS_LONG)254);
while (1)
{
/* ask for session parameters */
fio_ltd_str (io_buf,group,“Give group name (or exit)”,
FIO_RETRY | FIO_DFL,100);
if (!strcmp (group,”exit”)) break;
fio_ltd_str (io_buf,item.name,“Give item name”,
FIO_RETRY | FIO_DFL,GIN_MAX_ITEM_FLNM);
fio_ltd_long (io_buf,&attrib,“Give attribute number”,

fmf_strup (group);
fmf_strup (item.name);

BUS/FAST examples Retrieve session with routine interface
while (1)
{
fio_get_str (io_buf,tim_string1,
“Give start time (lct, empty is start of day)”,
FIO_DFL | FIO_SPACE);
if (ftm_inp_time(&err_cont,tim_string1,&from_time,FTM_NO_DATE
| FTM_NO_TIME | FTM_DEF_DATE | FTM_OFFSET_DAYS))
break;
umh_log_term (&err_cont);
}
ftm_c_lctgmt (&from_time,&err_cont);
while (1)
{
fio_get_str (io_buf,tim_string2,
“Give stop time (lct, empty is now)”,
FIO_DFL | FIO_SPACE);
if (ftm_inp_time(&err_cont,tim_string2,&to_time,FTM_NO_DATE |
FTM_NO_TIME | FTM_DEF_DATE | FTM_DEF_TIME |
FTM_OFFSET_DAYS))
break;
}
ftm_c_lctgmt (&to_time,&err_cont);
/* start get/put session */

ith_cont = ith_gp_sta (&context,&err_cont,node,group,&item,
attrib,&from_time,&to_time);
if (!ith_cont)
{
dur_det (&context,&err_cont);
return;
}
while (ith_gp_get(ith_cont,&sample)) /* get next sample */

{
printf (“item id: %d,%d,%d,%d,%d\n”,sample.item_id.node,
sample.item_id.group,sample.item_id.number,
sample.item_id.subno,sample.item_id.attno);
printf (“time: %d, %d, %d\n”,sample.timestamp.ftm_sec,
sample.timestamp.ftm_usec,sample.sequence);
printf (“ctrl: 0x%x, opt_flags: 0x%x, par1: 0x%x\n”,
sample.value.ctrl,sample.value.opt_flags,
sample.value.par1);
printf (“status: %d, value: %g, quality: %d\n\n”,
sample.value.status,
tls_get_double(sample.value.value.d),
sample.value.quality);
fio_get_conf (io_buf,&put,”Put action wanted”,
FIO_DFL | FIO_RETRY,“YJyjOo”,”Nn”);
/* ask for change info if a change of the sample is wanted */
if (put)
{
TLS_DOUBLE value;
TLS_LONG lvar;

Retrieve session with routine interface BUS/FAST examples
value = tls_get_double(sample.value.value.d);
fio_get_dbl (io_buf,&value,”Give value”,
FIO_RETRY | FIO_DFL);
tls_put_double(sample.value.value.d,value);
lvar = sample.value.status;
fio_ltd_long (io_buf,&lvar,”Give status”,
sample.value.status = lvar;
lvar = sample.value.quality;
fio_get_long (io_buf,&lvar,”Give quality”,
FIO_RETRY | FIO_DFL);
sample.value.quality = lvar;
lvar = (int)sample.value.ctrl & 0xFF;

fio_ltd_long (io_buf,&lvar,”Give ctrl”,
FIO_RETRY | FIO_DFL |
FIO_HEX,(TLS_LONG)0,(TLS_LONG)255);
sample.value.ctrl = lvar;
lvar = (int)sample.value.opt_flags & 0xFF;

fio_ltd_long (io_buf,&lvar,”Give opt_flags”,
FIO_RETRY | FIO_DFL |
FIO_HEX,(TLS_LONG)0,(TLS_LONG)255);
sample.value.opt_flags = lvar;
if (!ith_gp_put (ith_cont,&sample)) /* do the change */

{
}
}
}
umh_set_com (&err_cont,”on get next sample request”);
ith_gp_sto (ith_cont); /* close session */

}
dur_det (&context,&err_cont);
}

BUS/FAST examples Retrieve session with routine interface

Index
Index
Symbols ITH_CNV_VAL 5-4, 5-5, 5-6

ITH_CREATE 3-1, 5-9
(M)DUR interface A-1 ith_de_sample 5-7
ITH_DELETE 3-2, 5-10
C ITH_DONE 3-4, 5-11
cancel configuration 5-8 ITH_G_DIRECT 5-2
configuration 3-1 ITH_G_EVENT 5-2
create storage group 5-9 ITH_G_SCAN 5-2
crit_mask 5-2 ith_gp_clr() 4-7, 5-18
ith_gp_get() 4-7, 5-19, 5-20
D ith_gp_ins() 4-7, 5-18, 5-20
delete item 5-24 ith_gp_put() 4-7, 5-21
delete storage group 5-10 ith_gp_sample 5-7
direct/event-based storage 4-2, 5-29 ith_gp_sta() 4-7, 5-22
direct/item-based storage 4-1, 5-28 ith_gp_sto() 4-7, 5-23
ith_grp_con 5-1
E ITH_INFO_GRP 3-2, 5-12
ITH_INFO_ITM 3-3
end configuration 5-11
ITH_INFO_ITM_NXT 3-3, 5-14
ITH_INI_VAL 5-4, 5-5, 5-6
F ITH_INSERT 3-2, 5-15
functionality 1-1 ITH_INV_RTV 5-4, 5-5, 5-6
ITH_INV_SCAN 5-4, 5-5, 5-6
G ITH_INV_VAL 5-4, 5-5, 5-6
gather 1-1 ith_itm_con 5-2
gathering 2-1 ITH_LOG_STARTED 5-17
get sample get-put session 5-19 ITH_MAN_VAL 5-4, 5-5, 5-6
group 2-1 ITH_MODIFY 3-2, 5-16
group info 5-12 ITH_NEXT 5-3
ith_params() 5-17
H ITH_POL_NXT 5-3, 5-5
HIS 1-2 ITH_POL_PREV 5-3, 5-5
ITH_QC_NOTVALID 5-4, 5-6
I ITH_QC_VALID 5-4, 5-6
ITH_REMOVE 3-3, 5-24
info 5-3 ith_retr 5-4
insert item 5-15 ITH_RETR_MSEC 4-3
interpol 5-3, 5-5 ith_retr_msec 5-3
item info 5-13 ITH_RETRIEVE 4-3, 5-25, 5-27
item info next 5-14 ITH_S_EVENT 5-2
ITH_ABN_VAL 5-5 ITH_S_ITEM 5-2
ITH_ATT_QC 5-3 ITH_S_TIME 5-2
ITH_CANCEL 3-6, 5-8 ith_store_de 5-6
ITH_CNV_DBL 5-2 ith_store_di 5-6
ITH Programmer’s Guide 1

Index
ITH_STR_QC 5-2 S
ith_tim_seq 5-4
start get-put session 5-22
ith_val 5-5
stop get-put session 5-23
ith_val_msec 5-4
storage 2-1
ith_val_stq 5-5
direct event 4-2, 5-29
ITHDBG 1-2
direct item 4-1, 5-28
ITHEEx 1-1
storage group 2-1
ITHRDE 1-1
ITHRDI 1-1 store 1-1
structs 5-1
ITHRECOVER 1-2
ITHRTE 1-1
ITHRTI 1-1
ITHRTT 1-1
ITHSDE 1-1, 5-29
ITHSDI 1-1, 5-28
ITHSER 1-1
ITHSIx 1-1
ITHSTx 1-1
ITM_ATT_DB 5-3
ITM_ATT_HL 5-3
ITM_ATT_HLL 5-3
ITM_ATT_LL 5-3
ITM_ATT_LLL 5-3
ITM_CRI_DEL 5-3
ITM_CRI_EACH 5-2
ITM_CRI_FIRST 5-2
ITM_CRI_OPT 5-3
ITM_CRI_PIT 5-3
ITM_CRI_QC 5-3
ITM_CRI_STA 5-2
ITM_CRI_VAL 5-2
ITM_INFO_ITM 5-13
M
mechanism 2-1
modify storage group 5-16
P
put sample get-put session 5-21
R
retrieval
direct event 4-6
direct item 4-5
retrieve 1-1, 4-3
retrieve item 5-25, 5-27
retrieve session A-1, A-3
return generation parameters 5-17
routine interface A-3
2 ITH Programmer’s Guide

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Manual DSS Programmer’s Guide
IM 50F2F01N-E/R10.03

IM 50F2F01N-E/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
1 Introduction to DSS ..............................................................1-1
1.1 Global description of functionality ............................1-1
1.2 The data set model .....................................................1-1
1.3 DSS and authorisation ...............................................1-4
1.4 DSS and data replication ...........................................1-4
1.5 Bulk operations ..........................................................1-6
1.6 Field binding mechanism ...........................................1-6
1.7 Data access servers ....................................................1-7
2 The DSS API .........................................................................2-1
2.1 Introduction ...............................................................2-1
2.2 General DSS API functions .......................................2-4
2.2.1 Connect to/Disconnect from DSS ............................. 2-4
2.2.2 Request data set properties ....................................... 2-4
2.2.3 Bind/Unbind fields .................................................... 2-4
2.2.4 Log-on to/Log-off from DSS .................................... 2-5
2.2.5 Define/Delete filter ................................................... 2-5
2.2.6 Check if record matches filter criteria ...................... 2-6
2.2.7 Recover DSS client from dictionary update ............. 2-6
2.2.8 Dump DSS API data structures ................................ 2-7
2.3 Synchronous DSS API functions ...............................2-7
2.3.1 Open/Close data set table .......................................... 2-7
2.3.2 Read data from a data set table ................................. 2-7
2.3.3 Set current index ....................................................... 2-7
2.3.4 Activate/Deactivate filter .......................................... 2-8
2.3.5 Insert record .............................................................. 2-8
2.3.6 Update record ............................................................ 2-8
2.3.7 Delete record ............................................................. 2-9
2.3.8 Open MEMO/UNKNOWN field .............................. 2-9
2.3.9 Lock/Unlock record .................................................. 2-9
2.4 Functions related to the event mechanism ...............2-10
2.4.1 Open/Close an event channel .................................. 2-10
2.4.2 Set/Cancel event request ......................................... 2-10
2.4.3 Read event information ........................................... 2-10
2.4.4 Get flow control information .................................. 2-11
2.5 Sessions ...................................................................2-11
3 Data access servers ...............................................................3-1
3.1 Introduction ...............................................................3-1
3.1.1 The physical mapping layer ...................................... 3-2
DATABASE/FAST DSS Programmer’s Guide iii

Table of Contents
3.1.2 The Data Access Servers .......................................... 3-2

3.1.3 Interaction between PML and DAS .......................... 3-2
3.2 Data access server types ............................................3-3
3.3 General processing ....................................................3-4
3.4 Physical units .............................................................3-5
3.5 Data replication ..........................................................3-5
3.6 Events ........................................................................3-6
3.7 Data access server layout .........................................3-11
3.8 Processing ................................................................3-13
3.8.1 Global processing ................................................... 3-13
3.8.2 Setting the DAS type .............................................. 3-13
3.8.3 PML event processing ............................................ 3-14
3.8.4 Error handling ......................................................... 3-15
3.8.5 Synchronous access ................................................ 3-16
3.8.6 Reading a record ..................................................... 3-17
3.8.7 Inserting a record .................................................... 3-19
3.8.8 Updating a record .................................................... 3-21
3.8.9 Deleting a record ..................................................... 3-23
3.8.10 Conversion .............................................................. 3-24
3.8.11 Asynchronous data access ...................................... 3-25
3.8.12 Subscribe for events ................................................ 3-27
3.8.13 Handle events from the physical unit ..................... 3-29
3.8.14 Handle flow control from the physical unit ............ 3-30
3.8.15 Audit trailing ........................................................... 3-31
3.8.16 Process area authorisation ....................................... 3-31
3.8.17 Accessing other data sets ........................................ 3-32
3.8.18 Regular actions ....................................................... 3-34
3.8.19 Consistency check ................................................... 3-34
3.9 Making a DAS .........................................................3-35
4 Reference DSS API ...............................................................4-1
4.1 Introduction ...............................................................4-1
4.2 Return value/Error indication ....................................4-1
4.3 Arguments .................................................................4-1
4.4 dss.h header file .........................................................4-2
4.5 Structures ...................................................................4-3
4.5.1 dss_conn_sta ............................................................. 4-3
4.5.2 dss_flw_sta ................................................................ 4-3
4.5.3 dss_gen_arr ............................................................... 4-4
4.5.4 dss_user ..................................................................... 4-4
4.5.5 dss_fld_basics ........................................................... 4-5
4.5.6 dss_rec_struct ............................................................ 4-6
4.5.7 dss_str_lst .................................................................. 4-6
4.5.8 dss_str_nr_lst ............................................................ 4-6
4.5.9 dss_idx_basics .......................................................... 4-7
4.5.10 dss_idcs ..................................................................... 4-7
4.5.11 dss_node_info ........................................................... 4-8
4.5.12 dss_node_lst .............................................................. 4-8
DATABASE/FAST DSS Programmer’s Guide iv

Table of Contents
4.5.13 dss_das ...................................................................... 4-8

4.5.14 dss_filespec ............................................................... 4-9
4.5.15 dss_mbstr_lst ............................................................ 4-9
4.5.16 dss_dbl_rng ............................................................... 4-9
4.5.17 dss_def_val ............................................................. 4-10
4.5.18 dss_fld_operation .................................................... 4-10
4.5.19 dss_fld_transform_lst .............................................. 4-11
4.5.20 dss_fld_relation ....................................................... 4-11
4.5.21 dss_fld_compound .................................................. 4-12
4.5.22 dss_fld_references_lst ............................................. 4-12
4.5.23 dss_flt_pd ................................................................ 4-12
4.5.24 dss_change_log ....................................................... 4-14
4.6 DSS API routines .....................................................4-14
4.6.1 Introduction ............................................................. 4-14
4.6.2 Text related to error mnemonics ............................. 4-15
4.6.3 Activate filter .......................................................... 4-16
4.6.4 Bind field ................................................................ 4-17
4.6.5 Cancel event request ............................................... 4-20
4.6.6 Close data set table ................................................. 4-22
4.6.7 Close an event channel ........................................... 4-23
4.6.8 Check if dataset is concealed .................................. 4-24
4.6.9 Check if field is concealed ...................................... 4-26
4.6.10 Connect to DSS ....................................................... 4-28
4.6.11 Check if record matches filter criteria .................... 4-30
4.6.12 Deactivate filter ....................................................... 4-32
4.6.13 Disconnect from DSS ............................................. 4-33
4.6.14 Define filter ............................................................. 4-34
4.6.15 Delete filter ............................................................. 4-39
4.6.16 Delete record ........................................................... 4-40
4.6.17 Dump DSS API data structures .............................. 4-41
4.6.18 Check if field is enabled ......................................... 4-42
4.6.19 Get flow control information .................................. 4-44
4.6.20 Enable/disable exclusive data set access ................ 4-45
4.6.21 Insert record ............................................................ 4-47
4.6.22 Lock a record .......................................................... 4-48
4.6.23 User routine called upon log off DSS ..................... 4-50
4.6.24 User routine called upon log on to DSS ................. 4-51
4.6.25 Log off DSS ............................................................ 4-52
4.6.26 Log on to DSS ......................................................... 4-53
4.6.27 Open data set table .................................................. 4-55
4.6.28 Open an event channel ............................................ 4-58
4.6.29 Open MEMO/UNKNOWN field ............................ 4-62
4.6.30 Request properties at data set level ......................... 4-64
4.6.31 Request properties at DSS level .............................. 4-67
4.6.32 Request properties at field level .............................. 4-69
4.6.33 Request properties at index level ............................ 4-73
4.6.34 Recover DSS client ................................................. 4-75
4.6.35 Read equal operation .............................................. 4-76
4.6.36 Read event information ........................................... 4-78
DATABASE/FAST DSS Programmer’s Guide v

Table of Contents
4.6.37 Read sequential operation ....................................... 4-80

4.6.38 Set event request ..................................................... 4-82
4.6.39 Set current index ..................................................... 4-85
4.6.40 Unbind field ............................................................ 4-86
4.6.41 Unlock a record ....................................................... 4-87
4.6.42 Update record .......................................................... 4-89
4.6.43 Get valid field values .............................................. 4-90
4.6.44 Check if field value is valid .................................... 4-92
4.6.45 Activate change log ................................................ 4-94
4.6.46 Access change log ................................................... 4-95
4.6.47 Get encrypted password of a user ........................... 4-97
4.6.48 Set encrypted password of a user ............................ 4-98
5 Reference data access server ...............................................5-1
5.1 Introduction ...............................................................5-1
5.2 DSS Macros ...............................................................5-1
5.2.1 Introduction ............................................................... 5-1
5.2.2 DSS_ADT_ACTION ................................................ 5-2
5.2.3 DSS_ADT_FLD_NM ............................................... 5-3
5.2.4 DSS_ADT_NEW_VAL ............................................ 5-4
5.2.5 DSS_ADT_OFF ........................................................ 5-5
5.2.6 DSS_ADT_OLD_VAL ............................................ 5-6
5.2.7 DSS_ADT_ON ......................................................... 5-7
5.2.8 DSS_CLT_PRC ........................................................ 5-8
5.2.9 DSS_CONT_CHK .................................................... 5-9
5.2.10 DSS_CURRENT_TIME ......................................... 5-10
5.2.11 DSS_DAS_C .......................................................... 5-11
5.2.12 DSS_DAS_C_DECLARATION ............................ 5-12
5.2.13 DSS_DATA_ACCESS_SERVER .......................... 5-13
5.2.14 DSS_DO_DEFAULT ............................................. 5-14
5.2.15 DSS_DS_FILE_CHN ............................................. 5-15
5.2.16 DSS_DS_FILE_FMT ............................................. 5-16
5.2.17 DSS_DS_FILE_NAME .......................................... 5-17
5.2.18 DSS_DS_NM .......................................................... 5-18
5.2.19 DSS_DS_NODE_NUMBER .................................. 5-19
5.2.20 DSS_DS_OPERATIONS ....................................... 5-20
5.2.21 DSS_DS_PATH_NUMBER .................................. 5-21
5.2.22 DSS_DS_TERM_NM ............................................ 5-22
5.2.23 DSS_DS_USER_NM ............................................. 5-23
5.2.24 DSS_DUR_C .......................................................... 5-24
5.2.25 DSS_END_DATA_ACCESS_SERVER ............... 5-25
5.2.26 DSS_END_EVENTS .............................................. 5-26
5.2.27 DSS_ERROR .......................................................... 5-27
5.2.28 DSS_ERROR_EVT ................................................ 5-28
5.2.29 DSS_ERROR_FLOW ............................................ 5-29
5.2.30 DSS_ERROR_LIC ................................................. 5-30
5.2.31 DSS_EVENT .......................................................... 5-31
5.2.32 DSS_EVENTS ........................................................ 5-32
5.2.33 DSS_EVT_CRIT .................................................... 5-33
DATABASE/FAST DSS Programmer’s Guide vi

Table of Contents
5.2.34 DSS_EVT_MSG_ID .............................................. 5-35

5.2.35 DSS_EVT_REC ...................................................... 5-36
5.2.36 DSS_EVT_REF ...................................................... 5-37
5.2.37 DSS_EVT_TIME .................................................... 5-38
5.2.38 DSS_FLD_CUR_GET ............................................ 5-39
5.2.39 DSS_FLD_CUR_NM ............................................. 5-40
5.2.40 DSS_FLD_CUR_SET ............................................ 5-41
5.2.41 DSS_FLD_FTC ...................................................... 5-42
5.2.42 DSS_FLD_FTR ...................................................... 5-43
5.2.43 DSS_FLD_FTS ....................................................... 5-44
5.2.44 DSS_FLD_GET_FILE ........................................... 5-45
5.2.45 DSS_FLD_MARK .................................................. 5-46
5.2.46 DSS_FLD_NR ........................................................ 5-47
5.2.47 DSS_FLD_PUT_FILE ............................................ 5-48
5.2.48 DSS_FLW_ENABLED .......................................... 5-50
5.2.49 DSS_FLW_MSG_ID .............................................. 5-51
5.2.50 DSS_FLW_TIMEOUT ........................................... 5-52
5.2.51 DSS_IDX_FLD ...................................................... 5-53
5.2.52 DSS_IDX_FLDS .................................................... 5-54
5.2.53 DSS_IDX_ISF ........................................................ 5-55
5.2.54 DSS_IDX_NAME .................................................. 5-56
5.2.55 DSS_INIT_SUPPORT ............................................ 5-57
5.2.56 DSS_ITM_C ........................................................... 5-58
5.2.57 DSS_NO_DEFAULT ............................................. 5-59
5.2.58 DSS_O_DS_CLS .................................................... 5-60
5.2.59 DSS_O_DS_DEL ................................................... 5-61
5.2.60 DSS_O_DS_INS ..................................................... 5-62
5.2.61 DSS_O_DS_OPN ................................................... 5-63
5.2.62 DSS_O_DS_RD ...................................................... 5-64
5.2.63 DSS_O_DS_UPD ................................................... 5-65
5.2.64 DSS_O_FLD_GET ................................................. 5-66
5.2.65 DSS_O_FLD_IDX .................................................. 5-67
5.2.66 DSS_O_FLD_NR ................................................... 5-68
5.2.67 DSS_O_FLD_REP ................................................. 5-69
5.2.68 DSS_O_FLD_SET .................................................. 5-70
5.2.69 DSS_O_IDX_SET .................................................. 5-71
5.2.70 DSS_O_REC_LEN ................................................. 5-72
5.2.71 DSS_O_REC_NM .................................................. 5-73
5.2.72 DSS_O_REC_RD ................................................... 5-74
5.2.73 DSS_O_REC_WR .................................................. 5-75
5.2.74 DSS_O_REC_WR .................................................. 5-76
5.2.75 DSS_ON_EES ........................................................ 5-77
5.2.76 DSS_ON_ENS ........................................................ 5-78
5.2.77 DSS_ON_ES ........................................................... 5-79
5.2.78 DSS_RD_MODE .................................................... 5-80
5.2.79 DSS_RD_TYPE ...................................................... 5-81
5.2.80 DSS_REC_DIFF ..................................................... 5-82
5.2.81 DSS_REC_LEN ...................................................... 5-83
5.2.82 DSS_REC_MSG_ID .............................................. 5-84
DATABASE/FAST DSS Programmer’s Guide vii

Table of Contents
5.2.83 DSS_REC_NM ....................................................... 5-85

5.2.84 DSS_REC_RD ........................................................ 5-86
5.2.85 DSS_REC_WR ....................................................... 5-87
5.2.86 DSS_RES_UMH_C ................................................ 5-88
5.2.87 DSS_SAV_UMH_C ............................................... 5-89
5.2.88 DSS_SEL_NODE ................................................... 5-90
5.2.89 DSS_SET_PAG ...................................................... 5-91
5.2.90 DSS_SET_TYPE .................................................... 5-92
5.2.91 DSS_SYSTEM_FROM .......................................... 5-93
5.2.92 DSS_SYSTEM_TO ................................................ 5-94
5.2.93 DSS_TIME_AS_GMT ........................................... 5-95
5.2.94 DSS_UMH_C ......................................................... 5-96
6 Very Simple Dataset Interface ............................................6-1
6.1 Introduction ...............................................................6-1
6.2 Available functionality ..............................................6-1
6.3 Using the VSD interface ............................................6-1
6.4 Return value/Error indication ....................................6-3
6.5 Arguments .................................................................6-3
6.6 dssv.h header file .......................................................6-4
6.7 Structures ...................................................................6-4
6.7.1 dssv_string_buff ........................................................ 6-4
6.7.2 dssv_field_prop ......................................................... 6-4
6.8 VSD-API routines ......................................................6-5
6.8.1 Introduction ............................................................... 6-5
6.8.2 Close connection to DSS .......................................... 6-7
6.8.3 Close Dataset ............................................................ 6-8
6.8.4 Connect to DSS ......................................................... 6-9
6.8.5 Delete Dataset record .............................................. 6-10
6.8.6 Get dataset names ................................................... 6-11
6.8.7 Get field buffer ........................................................ 6-12
6.8.8 Get field value as double ........................................ 6-13
6.8.9 Get field names ....................................................... 6-14
6.8.10 Get field properties ................................................. 6-16
6.8.11 Get field value as string .......................................... 6-18
6.8.12 Get index fields ....................................................... 6-19
6.8.13 Insert record ............................................................ 6-20
6.8.14 Logoff from DSS .................................................... 6-21
6.8.15 Logon to DSS .......................................................... 6-22
6.8.16 Open dataset ............................................................ 6-23
6.8.17 Open dataset with all fields ..................................... 6-25
6.8.18 Read equal ............................................................... 6-27
6.8.19 Read next ................................................................ 6-28
6.8.20 Remove filter .......................................................... 6-30
6.8.21 Rewind dataset ........................................................ 6-31
6.8.22 Set field value with Double .................................... 6-32
6.8.23 Set field value with string ....................................... 6-33
6.8.24 Set filter expression ................................................ 6-34
DATABASE/FAST DSS Programmer’s Guide viii

Table of Contents
6.8.25 Set active index ....................................................... 6-36

6.8.26 Update record .......................................................... 6-37
DATABASE/FAST DSS Programmer’s Guide ix

Objectives Preface
0 Preface
0.1 Objectives
functionality of the Data Set Services (DSS).
• Provide experienced users with a reference for the use of the DSS
Application Programming Interface (API).

language C.
The reader is assumed to have knowledge of BUS/FAST, especially the
Message passing principle (DUR) and the Unsolicited Message Handler
(see 0.4 Associated documents).

• Chapter 1 contains an introduction to DSS.
It describes where DSS is meant for and it introduces some
concepts related to the DSS functionality.
• Chapter 2 introduces the DSS API. It gives an overview of all
available DSS API functions and shortly introduces them.
• Chapter 3 introduces the concepts of data access servers.
• Chapter 4 contains a detailed description of each individual DSS
API function. This is the type of information that a programmer
needs when the DSS API functions are actually used.
• Chapter 5 contains detailed information about the way a data access
server need to be implemented. This is the type of information a
programmer needs when an existing data access server is changed
or a new one is implemented.
DATABASE/FAST DSS Programmer’s Guide 0-1


1 DATABASE/FAST DSS System Integrator’s manual

CONVENTION MEANING
() Parentheses when used in routine syntax
indicates a list of arguments that need to be
passed.
DUR_NOWAIT.
input.
returns.
output.
literally.
0-2 DATABASE/FAST DSS Programmer’s Guide


n.u. not used.
a terminal.
from the user.
The following abbreviations are used throughout this document:
• API: Application Programming Interface
• DAS: Data Access Servers
• DSS: Data Set Services
• PML: Physical Mapping Layer


Global description of functionality Introduction to DSS
1 Introduction to DSS
1.1 Global description of functionality

DSS is a brick of the tool DATABASE/FAST. Its main function can be
described as “offering a general and uniform interface to FAST/TOOLS
data”. No matter how the FAST/TOOLS data is stored, the interface
offered by DSS to the data, is always the same.
Via the DSS external interface, the DSS API, FAST/TOOLS data can be
read and manipulated (insertion of new data, modification and deletion
of existing data). Via the interface, the data can be obtained both in a
synchronous way (request for data and wait for the reply) and
asynchronous way (request for a notification when data changes).
Programs that interact with DSS via the DSS API, are referred to as
“DSS clients”.
1.2 The data set model

DSS is based on the so called “data set model”. In this model, a data set
consists of a “data container” and a collection of properties related to this
data container. The container embodies the data being stored in the data
set. The properties describe specific characteristics of the data set.
No matter how the FAST/TOOLS data is actually stored, the data

contained by a data set is always modeled as a 2 dimensional table with
fixed length rows. The rows in the table correspond with records, the
columns of a table correspond with fields in a record.
In this data set model, the columns in a row have “simple” data types like
“TLS_SHORT ”, “TLS_LONG”, “TLS_UBYTE” etc. Constructed data
types (like structures in the C-programming language) and arrays, are
not allowed. There is one exception to this rule: arrays for the storage of
strings.
Each data set table has at least one unique index associated with it. In
addition to this (primary) unique index, the table may have other
(unique) indices associated with it. At least the primary index of a data
set table, uniquely identifies the records in the table. In addition to this,
all indices are meant to have a way to quickly retrieve a subset of records

Introduction to DSS The data set model
from the data set table.
Among others, data set properties describe the structure of the data
contained by the data set and the way DSS will treat the data contained
by the data set. It also describes at which node(s) a data set is physically
stored and the type of checks or operations that must be performed on
data to be inserted in a data set table. DSS internally uses the data set
properties to perform its task. In addition to this, the DSS API also offers
various routines to let a DSS client request for the properties of a data
set. This “property data” of DSS will also be referred to as (data set)
meta data.
The properties of a data set are stored in a data dictionary. The contents
of this dictionary, controls for a large part the way DSS responds to
requests issued via the DSS API. For example when a read request is
issued via the DSS API, the information in the dictionary is used to
determine at which node the data must be fetched.
Without additional programming effort, the behavior that DSS exhibits
towards a certain data set, can be influenced via the data set properties.
The properties of a data set can be specified with an ordinary text editor
in an ASCII file. The contents of this ASCII file is checked and compiled
by the DSS compiler. The result of the compilation is (optionally)
written in the DSS data dictionary, ready for use by DSS.
These data set services concepts, have been depicted in the following
figure.

The data set model Introduction to DSS
Data set model
DSS client
DSS compiler
DSS API
DSS
DSS
source file dictionary
FAST/TOOLS
data
Figure 1-1 DSS global function
DSS clients do not necessarily have to be limited to FAST/TOOLS

programs. Since DSS can be regarded as the gateway to FAST/TOOLS
data, DSS is a strategic point to plug in additional third party software
needing access to FAST/TOOLS data.
Among others, it is the task of DSS to service all of these DSS clients by:
• Determining where to retrieve and/or store certain type of data. If
data can not be obtained via the “primary” path, DSS will try to
obtain data via an alternative path.
• Retrieving and/or manipulating FAST/TOOLS data in the most
optimum way.
• Notify interested parties when data in a data set table changes.
• Perform a number of checks before performing operations on data.
These operations are meant to verify that:
- The requested operation is supported for the data set in
question.
- The user is authorised to perform the requested operation.
- The data is valid and complete.
• Perform standard operations on the data provided by the DSS
client. Examples of these standard operations are: case conversion
and removal of spaces.

Introduction to DSS DSS and authorisation
1.3 DSS and authorisation

DSS provides facilities to prevent data from being read and/or
manipulated by non-authorised DSS clients. Within DSS the following
authorisation philosophy is maintained:
• By default a DSS client is authorised to perform all possible
operations on data set tables via the DSS API.
This “mode” can be used when the DSS client is a “utility like”
program without or with less interaction with a human. When a user
is authorised to run the DSS client, virtually all data can be read and
manipulated via this DSS client. In this situation, DSS assumes that
the operating system has verified the identity of the user and has
granted the user permission to start this type of DSS client.
The default behavior is also necessary in situations where a kind of
“bootstrap” problem exists (e.g. the creation of user profiles is
necessary before a logon attempt can be handled successfully).
• Via the DSS API, the DSS client is enabled to let DSS check a user
name/password combination. When the supplied user name/
password combination is correct, DSS has knowledge about the
authorisation group related to the user. With this knowledge DSS is
able to reject certain kind of requests from the user.
When a user has logged in to DSS, DSS also knows which process
areas are related to the user. When the user is accessing a data set
table having a relation with a process area, DSS will also take the
process area information into account when deciding about
authorisation issues.
1.4 DSS and data replication

DSS provides facilities to replicate data. In general reasons for
replicating data are:
• Improved performance:
When data is kept at 1 single node, this node may become a
bottleneck when operations on this data are required. When (a copy
of) data can be maintained “close” to the place where it is used
(preferably at the same node), total throughput of the entire system
will improve.
• Improved data availability:
Having copies of data at more than 1 system makes the DSS
mechanism less sensitive to failures of certain system components.

DSS and data replication Introduction to DSS
A DSS client may have an alternative access path should the

primary access path not be available for any reason.
An important parameter when making decisions about replication of
data is the read/write ratio for the data. The higher this ratio (many read
operations in relation to the amount of write/update/delete operations on
the data), the more attractive and effective replication of data becomes.
DSS offers mechanisms to replicate both data in data set tables as well
as data set meta data (the data in the dictionary). The nodes at which data
set tables must be replicated, can be defined as a property of the data set
(thus is available as knowledge in the DSS data dictionary). The data set
meta data is vital to the functioning of almost all DSS components. It
will therefore be present at all nodes in a FAST/TOOLS system. This is
something that will be taken care of by DSS itself.
The DSS replication mechanism is transparent to DSS clients. The DSS

clients are not aware of the presence of more than one physical copy of
data.
With respect to the replication mechanism, the concept of “primary
node” is introduced. The primary node is the node where DSS will start
a data manipulation action. When for one or other reason a data
manipulation action can not correctly be rolled-back, it is assumed that
the primary node has the “current” version of the data. This information
is used to repair possible inconsistencies that might be introduced
The primary node is also the node where the so called locking token is
stored. This locking token is related to the functionality of the DSS
locking mechanism and is described in more detail in ref [1].
With different physical copies of the “same” data, there is a risk of
inconsistency between these physical copies. For this reason the
replication philosophy applied is:
• When reading the contents of a data set table, DSS has the
possibility to select an alternative node should the “primary”
attempt fail.
Basically DSS will select the node that is “closest” to the DSS
client, i.e. if a replica of the desired data is available on the DSS
client’s node, this copy is used. Otherwise the node with the
“highest priority” is selected to obtain the desired data. Priority is
an attribute that can be assigned to a node as part of data set
properties. This node priority expresses the importance/”quality” of
a node relative to other nodes in the system.
• For data manipulation actions, all nodes on which the data set table
is replicated, should be available. If this is not the case, the data

Introduction to DSS Bulk operations
manipulation action will not be executed.

DSS has implemented the data manipulation action as a
synchronous operation, i.e. the DSS client has to wait until all
replica’s involved, have completed the data manipulation action.
• When DSS is in the middle of a data manipulation action in which
more than 1 node is involved and the data manipulation action fails,
there is a risk of not being able to roll back parts of the action. Such
situation may occur in case the network connection between nodes
become broken in the middle of a transaction. In such a situation the
data in the system becomes inconsistent. This is because physical
copies of the “same” data set table, are not in sync anymore.
To recover from these type of situations DSS provides a
consistency check and repair utility.
1.5 Bulk operations

Basically DSS offers via its API, functions to read and/or manipulate
single records in a data set table. However for some of the DSS
functions, DSS clients will be given the possibility to issue requests for
a collection of records instead of one single record. This type of
operations will be referred to as “bulk operations”. This possibility
exists for “read” as well as “locking” operations.
This option might be useful in situations where a DSS client needs a lot
of data or wants to issue a lock for a large number of records in the same
data set. By using bulk operations, overhead can be limited to a
minimum and will have a positive impact on the total performance of the
system.
1.6 Field binding mechanism

Another way to limit overhead and improve throughput is the
appropriate use of the DSS field binding mechanism.
For read operations, the field binding mechanism offers the DSS client
the possibility to select only the fields in a data set table record that the
DSS client is interested in. For data manipulation operations, the
mechanism offers the DSS client the possibility to only supply the
minimum required number of fields for a record.

Data access servers Introduction to DSS
What the field binding mechanism basically does is that it offers the DSS
client the possibility to bind a memory location (a program variable) to
a field in a data set table. When reading records from the data set table
or manipulating records in a data set table, DSS “knows” in which
program variables respectively data must be stored or data can be read.
So the DSS client does not need structure definitions (representing a data
set record) to be able to read and/or manipulate data in a data set table.
This make the DSS client (programmatically) insensitive to changes in
the data set table structure.
In addition to this, since only the required data is transferred back and
forth between a DSS client and other DSS components, the field binding
mechanism reduces data traffic.
The field binding mechanism requires the DSS client to create so called
field sets. A field set is a collection of fields related to a certain data set.
Only the system resources limit the amount of fields in a field set. It is
possible for a DSS client to include the same field more than once
(although this will be less efficient in communication between DSS
components). When a DSS client wants to access a certain data set table,
it must specify which field set(s) it wants to use.
1.7 Data access servers

DSS clients communicate with DSS via the DSS-API. DSS itself
accesses FAST/TOOLS data via so called “data access servers”. These
are isolated parts of code that solve data set specific interface issues. One
of the properties of a data set describe which Data Access Server applies.
The data access servers are provided in source form. This enables a
system integrator to change an existing data access server. Furthermore
a system integrator is enabled to write own data access servers.
More information about data access servers will be given in Chapter 3
of this document.

Introduction to DSS Data access servers

Introduction The DSS API
2 The DSS API
2.1 Introduction
This chapter will introduce the use of the DSS API. After having read
this chapter the reader should have global insight in the possibilities of
the entire DSS API. For details regarding the use of the API, the reader
is directed to Chapter 4 of this document.
As indicated in the previous chapter, the DSS API basically offers

services to a DSS client to retrieve and manipulate data.
The DSS API is a routine interface that hides all of the details not
relevant for the DSS client’s task at hand. The DSS API is set up in such
a way, that the DSS client needs as less program code as possible to
accomplish a certain data set related task.
All DSS API routines have been defined as routines with a variable
number of arguments. This has been done to anticipate to possible future
extensions of the DSS API.
The entire DSS API can be split up in the following category of
functions:
• General functions
These are the functions to perform the general DSS related tasks.
Among others functions to log-on/log-off and functions to retrieve
data set properties, belong to this category.
• Synchronous data access functions
These are the functions to actually read and manipulate the data
contained by a data set table. This category also contain functions
to lock/unlock data set table records.
• Functions related to the DSS event mechanism.
These are functions that enable a DSS client to detect changes in the
contents of data set tables at various levels.
The table below gives an alphabetical overview of the DSS API
functions in each of the mentioned categories:

The DSS API Introduction
Function
Category Description
name
General dss_bnd_fld Bind field

dss_con_dcl Connect to DSS
dss_conc_ds Check if dataset is concealed
dss_conc_fld Check if dataset field is concealed
dss_cri_mtch Check if record matches filter criteria.
dss_dcon_dcl Disconnect from DSS
dss_def_flt Define filter
dss_del_flt Delete filter
dss_dmp Dump DSS API data structures
dss_enabled Check if a field is enabled
dss_lgof_usr User routine called upon log off DSS
dss_lgon_usr User routine called upon log on to DSS
dss_logoff Log off DSS
dss_logon Log on to DSS
dss_prop_ds Request properties at data set level
dss_prop_dss Request properties at DSS level
dss_prop_fld Request properties at field level
dss_prop_idx Request properties at index level
dss_rcvr_dcl Recover DSS client
dss_ubnd_fld Unbind field
dss_val_list Get a list of valid field values
dss_valid Check if a field has a valid value
Table 1: DSS API function overview

Introduction The DSS API
Function
Category Description
name
Synchronous dss_act_flt Activate filter

dss_cls_ds Close data set table
dss_dac_flt Deactivate filter
dss_del_rec Delete record
dss_ins_rec Insert record
dss_lck_rc Lock a record
dss_opn_ds Open data set table
dss_opn_fld Open MEMO/UNKNOWN field
dss_rd_eql Read equal operation
dss_rd_seq Read sequential operation
dss_set_idx Set current index
dss_unlck_rc Unlock a record
dss_upd_rec Update record
Event dss_canc_evt Cancel event request
dss_cls_evc Close an event channel
dss_get_flwc Get flow control information
dss_opn_evc Open an event channel
dss_rd_evt Read event information
dss_set_evt Set event request
Table 1: DSS API function overview
The following paragraphs describe more in detail where each of the

functions is meant for. Some of the functions will be described group
wise, since they are functionally related. The functions will not be
discussed in alphabetical order. Instead they will be described in
“functional” order.

The DSS API General DSS API functions
2.2 General DSS API functions
2.2.1 Connect to/Disconnect from DSS
Before a DSS client is able to interact with DSS and to use any of the
other DSS API functions, the DSS client has to connect to DSS. After
the DSS client has successfully connected to DSS, the DSS client has
obtained a so called “connection handle”. This connection handle
uniquely identifies the connection between the DSS client and the DSS
and is needed in many of the other DSS routines.
To connect to DSS use: dss_con_dcl().
As soon as the DSS client terminates or no longer need services from
DSS, the DSS client has to disconnect from DSS. By calling this routine
system resources in use by DSS, will be freed.
To disconnect from DSS use: dss_dcon_dcl().
2.2.2 Request data set properties
As soon as a DSS client has connected to DSS, the DSS client is able to
request for data set properties. Data set properties exists at various
levels:
• At data set services level (e.g. to request for a list of data set names).
To request properties at this level use: dss_prop_dss().
• At data set level (e.g. to request for the structure of a specific data
set table or the length of a record in this table).
To request properties at this level use: dss_prop_ds().
• At data set table field level (e.g. to request for a descriptive text of
a specific field in a specific data set table or to request for a list of
characters that are not allowed in the contents of a specific field).
To request properties at this level use: dss_prop_fld().
• At data set table index level (e.g. to determine which fields in the
data set table together comprise a certain index for the data set
table).
To request properties at this level use: dss_prop_idx().
2.2.3 Bind/Unbind fields
Before a DSS client is able to access or manipulate information in data

set tables or to use the DSS event mechanism, it must have created one

General DSS API functions The DSS API
or more field sets. A field set is a collection of fields related to one and
the same data set table. The field set contains the “binding” knowledge,
i.e. the field set contains the relation between a field in a data set table
and an address in the DSS client’s memory space.
Associated with each field set is a field set ID, which is needed when
using some of the other DSS API functions.
To bind a data set table field to a DSS client variable use: dss_bnd_fld().
To throw away an entire field set, i.e. to unbind all fields in a certain field
set, use: dss_ubnd_fld().
2.2.4 Log-on to/Log-off from DSS
As described before, DSS implements an authorisation mechanism.

As long as the DSS client has not logged on to DSS, the DSS client is
authorised to perform all defined operations on data set tables.
When the DSS client wants to use the DSS authorisation mechanism it
has to call: dss_logon().
When the DSS client logs on a second time (without logging off), the
current log on data is discarded. This means that logging off after having
logged on twice (without logging off) does not bring the DSS client back
to the state after the first successful log on action. Logging off always
means that the DSS client is brought back in the (authorisation) state
prior to the very first log on.
When the DSS client wants to log off from DSS it should call:
dss_logoff().
With the DSS mechanism 2 routines are provided in source form. These
are dss_lgon_usr() and dss_lgof_usr(). The first one is always called
after a successful log on action. The second one is called after a log off
action. Both routines do not contain any functionality. The routines are
meant to provide system integrators a hook to code “proprietary” actions
related to DSS log on and DSS log off actions.
2.2.5 Define/Delete filter
For both read operations on data sets as well as the DSS event
mechanism, it is possible to specify a filter. Via this filter, the DSS client
is enabled to impose certain filter criteria upon DSS. Before the filter can
be used/activated it must be defined. As part of the filter definition
action the filter expression as stated by the DSS client is checked for

The DSS API General DSS API functions
errors and compiled to an internal representation of the filter.

To define a filter expression the DSS client should use: dss_def_flt().
Calling this routine does not activate the filter. The routine returns a
“filter id” that can be used at a later stage to activate the filter.
When a filter is no longer in use, the DSS client can remove the filter by
calling: dss_del_flt(). The latter routine will free system resources
occupied by the filter definition.
NB: All fields referred to in an extended query, must be present in the

field set defined for the read operation.
2.2.6 Check if record matches filter criteria
After having obtained (parts of) a record from a data set table, the data
can be checked to see if it matches predefined filter criteria. To perform
this type of operation, use: dss_cri_mtch().
2.2.7 Recover DSS client from dictionary update
Data set meta data, as contained by the data dictionary, is replicated on

all nodes at which DSS components have been installed. When the data
set meta data is updated, this change has to be propagated to all nodes on
which DSS components are running. The propagation of these type of
changes is a responsibility of DSS and is an automatic mechanism.
However when such an event occurs, the internal administration of the
DSS API becomes outdated (e.g. offset of a field in a data set table
record is not correct anymore).
DSS contains a mechanism that instantly detects that the contents of the
DSS data dictionary has been changed. From that moment on, calls to
DSS API routines will block, i.e. they return a specific error indicating
that the data dictionary has been updated and that a recovery must be
performed. To facilitate recovery of the DSS client in this type of
situations, call: dss_rcvr_dcl(). When called the routine clears a large
part of the internal DSS API administration and closes open data sets and
event channels. Effectively the DSS client is brought back to the state
just after the DSS connect. Calling the routine also flags the DSS client
for DSS as being recovered. As long as the DSS client has not called the
routine after a dictionary update, the DSS client is not able to use the
DSS API anymore.

Synchronous DSS API functions The DSS API
2.2.8 Dump DSS API data structures
For debug purposes, a specific API call is provided. By calling this

function various parts of the internal DSS API administration can be
dumped either to a file or to the standard output.
To dump this information, the routine dss_dmp() should be called.
2.3 Synchronous DSS API functions
2.3.1 Open/Close data set table
Before data in a data set table can be read and/or manipulated, the data
set table must be opened. This provides the caller of the routine with a
so called data set handle. This data set handle is needed in most of the
other synchronous DSS API functions.
To open a data set table for synchronous operations, use dss_opn_ds().
When the data set handle is no longer needed, the data set table can be
closed with dss_cls_ds().
2.3.2 Read data from a data set table
After a data set table has been opened, the records in the data set table
can be read. To be able to read information from a data set table, the DSS
client should have sufficient privileges for the data set table.
Two forms of reading the information in the data set table are available:
1 Reading a record with an exact match of the value of one of its
indices. This type of reading will be referred to as “read equal”.
2 Reading a record relative to a previous read record. This type of
reading will be referred to as “read sequential”.
To perform a “read equal” operation, use the routine: dss_rd_eql().
To perform a “read sequential” operation, use the routine: dss_rd_seq().
2.3.3 Set current index
A data set table should have at least 1 (primary) index. However it is

possible to have more than 1 index on a data set table. These indices
become important during read operations on a data set table.

The DSS API Synchronous DSS API functions
When performing a read equal operation, the value specified with the
operation, should exactly match the value of the “current index” for the
data set table. When performing a read sequential operation, the next
record read, has a value that is “greater than” the contents of the “current
index” of the previous record read.
By default the “current index” on a data set table, is the primary one.
Thus after having opened the data set table, the current index is set to the
primary index. By calling the routine dss_set_idx(), the current index
can be set to one of the other defined indices for the data set table.
2.3.4 Activate/Deactivate filter
When opening a data set table, a reference to a previously defined filter

can be specified. During read operations on the data set table, this filter
may limit the amount of information that is returned on read operations.
When no filter was specified at the moment the data set table was
opened, it is still possible to activate a filter for the data set table. From
that moment on, read operations on the data set table, will only return
information that satisfy the filter criteria.
To activate a filter for a data set table, use dss_act_flt().
To deactivate a filter for an open data set table, use dss_dac_flt().
2.3.5 Insert record
After a data set table has been opened, records can be inserted in the
table. To be able to insert information in a specific data set table, the
DSS client should have insert privileges for the data set table.
To perform the insert operation on a data set table, use dss_ins_rec().
2.3.6 Update record
After a data set table has been opened, records can be updated in the
table. To be able to update information in a specific data set table, the
DSS client should have update privileges for the data set table.
The record to be updated, is uniquely identified by the primary key value
of the record. The primary key value can not be changed.
To perform the update operation on a data set table, use dss_upd_rec().

Synchronous DSS API functions The DSS API
2.3.7 Delete record
After a data set table has been opened, records can be deleted from the
table. To be able to delete information from a specific data set table, the
DSS client should have delete privileges for the data set table.
The record to be deleted, is uniquely identified by the primary key value
of the record.
To perform the delete operation on a data set table, use dss_del_rec().
2.3.8 Open MEMO/UNKNOWN field
Some data set tables may contain one or more fields in which a huge
amount of information could be present (e.g. the source of a PROCESS/
FAST class definition). This data is not directly presented in such a field.
Instead the field contains the name of an ASCII file in which the data is
stored. This file may reside on a remote system and as long as the DSS
client does not need the contents of the file, it remains at the remote
system. The DSS API recognises the special function of such a field
because the field must be of type “MEMO” or “UNKNOWN”.
When the DSS client wants to inspect the contents of the field (or
actually the contents of the file), it calls the function dss_opn_fld().
This function takes care that:
• The contents of the field (the file possibly residing at a remote
system), is fetched in a (temporary) file at the local system.
When the contents of the field is contained by a file on the local
node, no additional copy actions are performed.
• The file is opened (with the standard-C fopen() function call)
• A file pointer is returned to the caller of the function.
2.3.9 Lock/Unlock record
After a DSS client has opened a data set table, it is enabled to lock one
or more records in this table. This might be useful if the DSS client
wants exclusive access to these records e.g. in a situation where a certain
update must be collectively applied to a set of records.
To lock a record in a data set table, use: dss_lck_rc().
To unlock a record in a data set table, use: dss_unlck_rc().
Remark: Both functions enable the caller to lock or unlock a set of

records in one function call.

The DSS API Functions related to the event mechanism
2.4 Functions related to the event mechanism
2.4.1 Open/Close an event channel
Before a DSS client is able to express its interest in certain type of

events, it has to open a so called event channel on a data set table.
This provides the caller of the routine with a so called event channel
handle. This handle is needed in most of the other functions related to
the DSS event mechanism. Beyond some other information, the DSS
client must supply one or more field set ID’s to indicate to the DSS API
in which variables event information should be written.
To open an event channel on a data set table, use dss_opn_evc().
To close an event channel when it is no longer needed, use
dss_cls_evc().
2.4.2 Set/Cancel event request
After an event channel has been opened, the DSS client has to express
its interest in the type of events it is interested in. The DSS client may be
interested in all type of actions happening in a data set table. As soon as
a record is inserted, deleted or modified, the DSS client may wish to
receive a notification of this type of event. In other situations, the DSS
client may only be interested when a specific record in a data set table is
modified or deleted.
Via the dss_set_evt() routine, the DSS client is able to express these
type of interests. The routine may be called multiple times to add
additional criteria to the set of existing criteria.
To remove one or more criteria, use dss_canc_evt().
2.4.3 Read event information
As soon as the DSS client has subscribed to certain type of events, DSS
takes care that the appropriate event messages will be put in the BUS/
FAST message queue of the DSS client. For the DSS client to obtain
event information (if available), it must call at regular intervals the
dss_rd_evt() routine.
From a global point of view, this routine performs the following actions:

Sessions The DSS API
• It checks if event information is internally cached in an DSS API

buffer. If not, it will copy event information possibly present in the
message queue of the DSS client, to the internal DSS API cache.
• It copies (for one event) the event information internally cached in
an DSS API buffer, to the appropriate field set variables. These
field set variables have been specified by the DSS client at the
moment the event channel for a data set table was opened.
If no event information is present or in case the routine detects a problem
with the event channel (flow control), it returns (for each situation) a
specific error code, to be tested upon by the DSS client.
2.4.4 Get flow control information
As indicated before, it is possible that the routine to read events,

indicates that there is a flow problem with the event channel. Since there
may be several causes of the flow control problem, a routine is available
to find out what causes the flow control problem. When the routine to
read events has signalled that a flow problem exists, the routine
dss_get_flwc() can be called to detect the cause of the problem.
The caller is not obliged to call the routine. However when used, it
should be called immediately after the routine to read events, has
signalled a flow control problem.
2.5 Sessions
To enable a DSS client to have concurrent access for different users to
data sets via the DSS API, sessions are introduced. A session is
identified by a unique number. The default session used by the DSS API
is the session with number zero. Using the default session is sufficient
for all the DSS clients that use the DSS API to serve only one user at the
time.
When a DSS client has to server more that one user concurrent it can
supply a, for each user, a unique session number (the optional argument
DSS_ARG_SESSION_ID) to the routines dss_logon(), dss_logoff(),
dss_opn_ds(), dss_opn_evc() and dss_prop_ds(). These functions use
then the authorisation of the user that is logged on for the specific
session. When a session number is supplied which has no user logged
on, then this session is granted all permissions.

The DSS API Sessions

Introduction Data access servers
3 Data access servers
3.1 Introduction
This chapter will introduce the use of the data access servers (DAS).
After having read this chapter the reader should have global insight in
the possibilities of the DAS. For details regarding the use of the
functions within a DAS, the reader is directed to Chapter 5 in this
document.
The following figure shows the layers of the DSS.
DSS
clients
Data
API dictionary
Core
Mapping
F/T
data
Figure 3-1 Decomposition of DSS
The mapping layer can be further decomposed into the following parts:
• The Physical Mapping Layer (PML)
• The Data Access Servers (DAS)

Data access servers Introduction
3.1.1 The physical mapping layer
Via the PML, the DSSSDA and DSSEVT processes get access to the
FAST/TOOLS data. PML contains generic facilities to offer this access
(e.g. certain type of checks, calling the appropriate DAS) and it uses
functionality of DAS for functionality that is unique to a certain (type of)
data set.
When the PML is used by a PML client (DSSSDA/DSSEVT process) to
get access to a data set, PML knows which DAS it has to use. This is
because this knowledge is present in the FAST/TOOLS data dictionary.
The PML is implemented as a routine set that is linked with the
DSSSDA/DSSEVT processes.
The PML dynamically links the DAS that it needs, to performs its task.
This prevents from rebuilding the DSSSDA/DSSEVT processes at the
moment the functionality of a DAS changes or when a new DAS is
added.
3.1.2 The Data Access Servers
The DAS is used by PML to delegate certain data set specific tasks. For
this purpose the PML generates events for the DAS related to the data
set involved. Such a PML event represents a specific state of the PML
during the processing of a request. The DAS must decide to handle the
event processing itself, to handle it partly or to let it be handled by the
PML.
3.1.3 Interaction between PML and DAS
The PML contains logic to process FAST/TOOLS data in a default way

by assistance of special type specific DAS. It uses the DSS data
dictionary to obtain information about the relation between the data set
and the FAST/TOOLS data. Exceptions to the default behavior are
programmed in the data set specific DAS.

Data access server types Data access servers
3.2 Data access server types

A DAS must be classified as being of a certain type. This DAS type,
signals to the PML what kind of default services it can perform for the
DAS. The following type of DAS are distinguished:
• ISF type (DSS_ISF_TYPE):
The PML assumes that a DAS of this type facilitates access to
ISAM files. Data sets handled by a DAS of this type can be
replicated.
• HIS type (DSS_HIS_TYPE):
The PML assumes that a DAS of this type facilitates access to
ISAM files logically grouped in a FAST/TOOLS storage group
(historical organised ISAM files). Data sets handled by a DAS of
this type can not be replicated.
• Unknown type (DSS_UNK_TYPE):
The PML makes no assumptions whatsoever about the type of
access that can be performed. Support for access to these types of
data sets, must be completely coded in the DAS.
The DAS itself, also has a layered architecture. When PML needs
support from the DAS, it raises a specific event. Such an event
represents the elementary service that PML is requesting for. This event
traverses a number of DAS.
• The data set specific DAS.
First the event arrives at the data set specific DAS (if any has been
defined). These DAS contain the actions that are so specific for the
data set in question, that they must be coded separately in the data
set specific DAS (e.g. the insertion of an item in the item table).
If the data set specific DAS is not available, ignores the event or
indicates that the event must be handled in a default way, the event
is sent to the “type specific” DAS.
• The type specific DAS (dsid_das_his, dsid_das_isf and
dsid_das_unk).
These DAS contain the default actions, for a specific type of event,
that are common to the DAS of a specific type. An example of such
a type specific action could be the open or close action on an ISAM
file.
The type specific DAS, comes into action when:
- No data set specific DAS is available.
- When the event is ignored by the data set specific DAS.
- When the data set specific DAS has indicated that the event
must be handled in a default way.

Data access servers General processing
When the type specific DAS ignores the event or indicates that the
event must be handled in a default way, the event is sent to the
default DAS. The type specific DAS to use are specified in the DSS
setup file (dss.sup).
• The default DAS (dsid_das_def).
This DAS contains the default actions, for a specific type of event,
that are common to all DAS types. An example of such a type of
action is the audit trailing of changes in data set records. The default
DAS to use is specified in the DSS setup file (dss.sup).
The DAS are provided in source form, so they can be changed or
extended by system integrator’s. A system integrator is also enabled to
write a dedicated DAS.
3.3 General processing

The PML receives request from the DSS core layer to perform some
operation (for example to open a data set for synchronous access).
On receipt of a request from the DSS core layer by the PML, the PML
performs some preprocessing and may need some help from the DAS to
complete the request. When it needs help it issues events to the DAS that
signal the DAS to perform a specific operation. The first time it needs to
access the DAS, the PML performs the following actions:
• The data dictionary is accessed to obtain information about the data
set being accessed.
• The data set specific DAS mentioned in the data dictionary is
loaded from the library that is also mentioned in the data dictionary.
It is only loaded when not loaded before.
• When loaded, the PML queries the DAS for its type and the events
it handles. The DAS type is used for accessing the appropriate type
specific DAS. The PML will only call the data set specific DAS for
the events it is capable to handle.
The data dictionary may mention one of the type specific DAS directly.
In this case there is no access to the data set specific DAS and all events
are handled by the type specific DAS directly. Note that once loaded a
DAS is never unloaded by the PML.
When the PML issues an event to the DAS it is processed in the
following way:

Physical units Data access servers
• When a data set specific DAS is available it is feed the event when
this DAS is capable of handling the event.
• When no data set specific DAS did handle the event then the event
is sent to the type specific DAS.
• When the type specific DAS did not handle the event then the event
is sent to the default DAS.
• When the event is processed by any DAS, the PML performs some
post processing and returns the result to the DSS core layer.
On receipt of an event by a DAS, the DAS does some processing to
fulfill the event. An example is the DAS for PROCESS/FAST classes.
On receipt of the delete event (DSS_DEL_REC) it calls the appropriate
PROCESS/FAST routine to delete the class. This DAS is of type
DSS_UNK_TYPE (unknown) because accessing PROCESS/FAST to
maintain classes is a very specific method not generally usable for an
other DAS.
A DAS accesses the PML via support macro’s to obtain information, to
set information and to signal situations. An example of a DAS accessing
the PML is to obtain the record to determine the PROCESS/FAST class
to be deleted on receipt of the delete event.
Summarising, a DAS receives an event from the PML which tells the
DAS to perform a specific action. The DAS accesses the PML to obtain
additional information, to set information or to signal situations. After
processing of the event, the control is returned to the PML.
3.4 Physical units

The DAS operates on so called physical units (for example, an ISAM
file). The physical records are stored in physical units. These terms are
introduced to distinct between data sets and logical records on the API
side of the DSS and the way the data is physically stored on the PML
side of DSS.
3.5 Data replication

The PML handles data replication to gain redundant and high available
FAST/TOOLS systems. Whether data replication has to be performed

Data access servers Events
for a specific data set is specified in the data dictionary. There is always
a primary node involved and one ore more replica nodes.
3.6 Events
The following table summarises the events that can be generated by the
PML for the DAS:
Event name Description
DSS_ADT_FLD Log action at audit trail. It is generated by the PML

after a successful update (modification) of a field.
DSS_ADT_REC Log action at audit trail. It is generated by the PML
after a successful insert, update or delete of a record.
DSS_CHK_DEL Check the user is authorised to delete the record. It is
generated by the PML prior deletion of the record.
DSS_CHK_INS Check the user is authorised to insert the record. It is
generated by the PML prior insertion of the record and
prior the DSS_CHK_REC event.
DSS_CHK_NODE Check if the primary record is replicated on another
node. Used during consistency check.
DSS_CHK_REC Check if a record to be inserted or updated contains cor-
rect data.
DSS_CHK_UPD Check the user is authorised to update the record. It is
generated by the PML prior update of the record and
prior the DSS_CHK_REC event.
DSS_CLS_DS Close the primary physical unit of a data set.
DSS_CLS_EVT Close event channel.
DSS_CLS_REP Close a data set replica physical unit of a data set. Rep-
licas may be kept open independent from the main data
set open and close to improve overall performance.
DSS_CMP_REC Compare the primary and replication record to see if the
contents are different. Used during consistency check.
DSS_CNV_LOG Convert logical field to physical field. It is only gener-
ated for fields which are not mapped to a physical field
in the data dictionary.
DSS_CNV_PHY Convert physical field to logical field. It is only gener-
ated for fields which are not mapped to a physical field
in the data dictionary.

Events Data access servers
DSS_CNV_TO_REP Convert the contents of the physical record to the

record needed on the replication node. Used during
consistency repair.
DSS_DEL_EVT This event occurs when an event from a physical unit
has been received with an unknown reference id in it.
DSS_DEL_NOT Record is deleted. This event is generated when the
record has been successfully deleted.
DSS_DEL_REC Delete a record from the primary physical unit.
DSS_DEL_REP Delete a record from a replica physical unit.
DSS_GET_PAG This event occurs when the PML requires the Process
Area list of a physical record to determine whether or
not the record can be modified. It is generated after a
DSS_RD_REC. On the event, by calling the macro
DSS_SET_PAG, the Process Area list is set.
DSS_INS_NOT Record is inserted. This event is generated when the
record has been successfully inserted.
DSS_INS_REC Insert a record into the primary physical unit of a data
set.
DSS_INS_REP Insert a record in a replica physical unit of a data set.
DSS_OPN_DS Open the primary physical unit of a data set.
DSS_OPN_EVT Open a data set event channel.
DSS_OPN_REP Open a data set replica physical unit of a data set. Rep-
licas may be kept open independent from the main data
set open/close to improve overall performance.
DSS_PRO_EVT Process event. This event occurs when an event has
been received. The processing includes system conver-
sion and creation of a physical record when required.
DSS_PRO_FLW Process flow control message.
DSS_RD_REC Read record from the primary physical unit. The index
has been set and the physical record contains the correct
value for the index. The DSS_RD_MODE macro
returns the read mode like read the first or next record.
DSS_SET_EVT Subscribe for events. The physical record contains the
index value to be used for requesting the event.
DSS_SET_IDX Set certain index. Set the index to be used for the next
read or subscribe for events.
DSS_TIMER Time signal. Occurs each second.

DSS_UDEL_REC Undo record deletion from the primary physical unit.

Used to recover from an unsuccessfull delete of a
record.
DSS_UDEL_REP Undo record deletion from a replica physical unit. Used
to recover from an unsuccessfull delete of a record.
DSS_UINS_REC Undo record insertion from the primary physical unit.
Used to recover from an unsuccessfull insert of a
record.
DSS_UINS_REP Undo record insertion in a replica physical unit. Used to
recover from an unsuccessfull insert of a record.
DSS_UPD_NOT Record is updated. This event is generated when the
record has been successfully updated.
DSS_UPD_REC Update a record in the primary physical unit of a data
set.
DSS_UPD_REP Update a record in a replica physical unit.
DSS_UUPD_REC Undo record update from the primary physical unit.
Used to recover from an unsuccessfull update of a
record.
DSS_UUPD_REP Undo record update in a replica physical unit. Used to
recover from an unsuccessfull update of a record.
The next table supplies an overview of the events and the DAS that
handles, may handle or must handle it for the different types of DAS. In
the table numbers are used which are explained as follows:
0 This event is handled by the type specific or default DAS. The data
set specific may handle the event and optional disable the type
specific or default DAS to handle the event
1 This event is not handled by the type specific DAS nor by the
default DAS. When required the event can be handled by the data
set specific DAS.
2 This event is handled by the type specific DAS. When required, the
data set specific DAS may handle the event and optional disable the
type specific DAS to handle the event.
3 This event is handled by the default DAS. When required, the data
set specific DAS may handle the event and optional disable the
default DAS to handle the event.
4 When not all logical fields are mapped to physical fields in the data
dictionary, on these events the data set specific DAS has to handle
the conversion.

Events Data access servers
5 This event must be handled by the data set specific DAS.

6 This event must be handled by the data set specific DAS when it
supports asynchronous data access. Otherwise it may be ignored.
7 This event must be handled by the data set specific DAS when the
data set is distributed. Otherwise it may be ignored.
data set supports deletions of records.
data set supports insertion of records.
data set has more than one index.
data set supports updates of records.
When the no number is specified, the event is not handled or can not be
handled (for the data set specific DAS).
Unknown
ISF type HIS type
type
Data set specific DAS
Default DAS
Type specific DAS
Type specific DAS
Type specific DAS

Event name
DSS_ADT_FLD 3 3 3 0
DSS_ADT_REC 3 3 3 0
DSS_CHK_DEL 1 1 1
DSS_CHK_INS 1 1 1
DSS_CHK_NODE 3 3 3 0
DSS_CHK_REC 1 1 1
DSS_CHK_UPD 1 1 1
DSS_CLS_DS 2 0 2 0 5
DSS_CLS_EVT 2 0 2 0 6
DSS_CLS_REP 2 0 7 7
DSS_CMP_REC 3 3 3 0
DSS_CNV_LOG 4 4 4

Unknown
ISF type HIS type
type
Default DAS
Type specific DAS
Type specific DAS
Type specific DAS

Event name
DSS_CNV_PHY 4 4 4
DSS_CNV_TO_REP 3 3 3 0
DSS_DEL_EVT 2 0 2 0 6
DSS_DEL_NOT 1 1 1
DSS_DEL_REC 2 0 2 0 8
DSS_DEL_REP 2 0 7,8 7, 8
DSS_GET_PAG 3 3 3 0
DSS_INS_NOT 1 1 1
DSS_INS_REC 2 0 2 0 9
DSS_INS_REP 2 0 7,9 7, 9
DSS_OPN_DS 2 0 2 0 5
DSS_OPN_EVT 2 0 2 0 6
DSS_OPN_REP 2 0 7 7
DSS_PRO_EVT 2 0 2 0 6
DSS_PRO_FLW 2 0 2 0 6
DSS_RD_REC 2 0 2 0 5
DSS_SET_EVT 2 0 2 0 6
DSS_SET_IDX 2 0 2 0 10
DSS_TIMER 2 0 2 0 1
DSS_UDEL_REC 2 0 8 8
DSS_UDEL_REP 2 0 7,8 7, 8
DSS_UINS_REC 2 0 9 9
DSS_UINS_REP 2 0 7,9 7, 9
DSS_UPD_NOT 1 1 1

Data access server layout Data access servers
Unknown
ISF type HIS type
type
Default DAS
Type specific DAS
Type specific DAS
Type specific DAS

Event name
DSS_UPD_REC 2 0 11
DSS_UPD_REP 2 0 7, 11
DSS_UUPD_REC 2 0 11
DSS_UUPD_REP 2 * 7, 11
3.7 Data access server layout

Each DAS is written in a separate C-language file with the name of the
DAS. The file has the following layout:
#include <dss.h> 1
static TLS_BOOLEAN my_function_1(); 2
DSS_DATA_ACCESS_SERVER(<name of the DAS>) 3
<local declarations> 4
DSS_SET_TYPE(DSS_ISF_TYPE); 5
DSS_EVENTS 6
DSS_EVENT(DSS_CNV_REC) 7
DSS_NO_DEFAULT; 8
<event processing>
if <some_error> 9
{
umh_set_code(DSS_UMH_C, <my error code>);
DSS_ERROR;
}

Data access servers Data access server layout
DSS_EVENT(DSS_RD_REC) 10
<event pre processing>
DSS_DO_DEFAULT; 11
<event post processing>
if (!my_function_1(DSS_DAS_C ,...)) DSS_ERROR; 12
DSS_END_EVENTS 13
DSS_END_DATA_ACCESS_SERVER 14
static TLS_BOOLEAN my_function_1(DSS_DAS_C, ...) 15

DSS_DAS_C_DECLARATION; 16
...
{
DSS_INIT_SUPPORT; 17
...
return TRUE; 18
error_exit: 19
return FALSE;
}
The explanation:
1 The header file dss.h contains all declaration and definition
required by the DAS. All PML support macros are declared in
dss.h.
2 It is possible to call functions within a DAS. When PML support
macros should be used within such a function, the function is called
a DAS support function and a DAS support function must be
declared as shown here.
3 This statement declares the DAS. Its name must be the same as the
C-language file containing the DAS.
4 As required, private declarations can be put here.
5 The type of the DAS is specified. Other possibilities are
DSS_HIS_TYPE and DSS_UNK_TYPE.
6 The statement starts the event processing section.

Processing Data access servers
7 This statement starts the DSS_CNV_REC event processing

section.
8 This statement suppresses the default processing for this event.
9 Example of error handling.
10 This statement starts the DSS_RD_REC event processing.
11 This statement executes the default processing for this event.
12 An own DAS support function is called. Note that DSS_DAS_C
(DAS context) is passed as the first argument.
13 The end of the event processing section.
14 The end of the DAS.
15 An own DAS support function.
16 The DAS context is declared.
17 The support routine is initialised. After this initialisation all the
PML support macros (as described in Section 3.8) are accessible.
18 Successful exit of the DAS support function.
19 Error exit for the DAS support function.
For each event not listed in the event processing section, the PML passes
the event to the type specific DAS. Thus only exceptions to the default
event processing are to be coded in the DAS.
3.8 Processing
In this section the processing to be performed and the methods to do so
are described. Relations between PML events and PML macros are
supplied.
3.8.1 Global processing
A DAS is declared using the following construction:

DSS_DATA_ACCESS_SERVER(<name of the DAS>)
<DAS code>
DSS_END_DATA_ACCESS_SERVER
3.8.2 Setting the DAS type
To initialize the PML for correct default processing the type of the DAS
must be declared as follows:

Data access servers Processing
DSS_SET_TYPE(<DAS type>);
3.8.3 PML event processing
PML events are handled as follows:

DSS_EVENTS
DSS_EVENT(<PML event 1>)
<event processing>
DSS_EVENT(<PML event n>)
<event processing>
DSS_END_EVENTS
All events not handled by the DAS are always handled by the type
specific and default DAS. Normally events that are handled by a DAS
are not handled anymore by the type specific and default DAS.
However, the PML must be explicitly told to behave this way otherwise
the PML will issue the event also to the type specific DAS after
processing by the data set specific DAS. The macro
DSS_NO_DEFAULT and DSS_DO_DEFAULT are used for this
purpose. Using this mechanism, the <event processing> section has one
out of three occurrences:
<do some processing>
DSS_DO_DEFAULT
or
DSS_NO_DEFAULT
or
The first occurrence does some processing, then instructs the PML to
call the type specific DAS for the event, and when the type specific DAS
processed the event, control is returned back to the data set specific DAS
for doing some additional processing. An example of this occurrence is
a DAS that lets the type specific DAS read the record and does some
additional processing on the record read by itself.
The second occurrence, the DAS does the processing totally by itself and
instructs the PML not to pass the event to the type specific DAS.

In the last occurrence, the data set specific DAS does some processing.
When done the PML passes the event to the type specific DAS.
Note: The data set specific DAS can not influence
how the default DAS paticipates in
processing the event.
3.8.4 Error handling
When the DAS encounters an error condition, this condition has to be

signalled to the PLM. On signalling, control is directly taken over by the
PML. The PML may try to recover from the error condition by rolling-
back processing done so far. For example, when an error is encountered
during insertion of a record in a replica database, PML tries to recover
by deleting the record it was trying to insert, from the primary and
replica physical units inserted so far. The following macros are used for
error signaling:
Macro Description
DSS_ERROR Signals an error and exits the DAS.

DSS_ERROR_EVT Signals an event sequence error and
exits the DAS. Used for asynchro-
nous processing.
DSS_ERROR_FLOW Signals an event flow time out error
and exits the DAS. Used for asyn-
chronous processing.
DSS_ERROR_LIC A licence error is encountered. The
FAST/TOOLS tool or brick is not
installed or licensed.
Prior calling one of these macro, the error context must be set with a
valid UMH error code:
umh_set_code(DSS_UMH_C, <error_code>);
In addition to these macros there are some DSS error codes which have
some special meaning for the PML:
Error code Description
DSS_E_NOREC This error must be set when a record can not be found.
DSS_E_RECTHERE This error must be set when the record already exists.

3.8.5 Synchronous access
Synchronous access is initiated by an open event for the DAS.

Depending on data replication, an open event (DSS_OPN_DS) is issued
for the primary node and one ore more replica nodes (DSS_OPN_REP).
The open event request the DAS to open a physical unit. Note that the
same physical unit may be opened more than once by the PML.
When no more access to the physical unit is required the close event is
issued by the PML (DSS_CLS_DS for the primary node and
DSS_CLS_REP for the replica nodes).
While the physical units are open, the PML may issue events, for
example, to read, insert, update and delete records.
The following PML macros are useful to be used for processing the open
events:
Macro Description
DSS_DS_FILE_CHN Used to store the channel to an open physical

unit and returns the channel to an open physical
unit. It is the context that is interpreted by the
DAS only and used to distinct between the open
physical units. An example is the ISF context.
DSS_DS_FILE_FMT Returns the file record format string.
DSS_DS_FILE_NAME Returns the file name of the physical unit of a
data set to be opened.
DSS_DS_NODE_NUMBER Returns the node number where the physical
unit of a data set has to be opened.
DSS_DS_OPERATIONS Returns the way a physical unit has to be
opened.
DSS_DS_PATH_NUMBER Returns the FAST/TOOLS directory path
number where the physical unit of a data set has
to be opened.
DSS_REC_LEN Returns the length of a physical record.
The next code shows an example of the processing of an open event:

DSS_EVENT(DSS_OPN_DS)
int opn_mode;
DSS_NO_DEFAULT;

if (DSS_DS_OPERATIONS & DSS_OPER_READ)

{
if (DSS_DS_OPERATIONS &
(DSS_OPER_INSERT | DSS_OPER_UPDATE|
DSS_OPER_DELETE))
opn_mode = ISINOUT;
else
opn_mode = ISINPUT;
}
else
opn_mode = ISOUTPUT;
if ((DSS_DS_FILE_CHN = (void*)
isf_uopen(DSS_DUR_C, DSS_UMH_C,
DSS_DS_NODE_NUMBER,
DSS_DS_PATH_NUMBER,
DSS_DS_FILE_NM, opn_mode, 0,
(struct keydesc *)NULL, DSS_REC_LEN,
DSS_DS_FILE_FMT, 0)) == NULL)
DSS_ERROR;
3.8.6 Reading a record
When the PML wants to obtain a record from a data set it issues the
DSS_RD_REC event. On this event the DAS reads the requested record
from the physical unit. The DSS_RD_REC event operates in different
modes. The DAS has to obtain the mode by using the DSS_RD_MODE
macro. This macro returns one of:
Read mode Description
DSS_RD_EQUAL read a specific record

DSS_RD_NEXT read the next record
DSS_RD_FIRST read first record
DSS_RD_GTEQ read a record greater or equal to
DSS_RD_GREAT read a record greater than

In case of the DSS_RD_EQUAL, DSS_RD_GTEQ and

DSS_RD_GREAT the macro DSS_REC_RD returns a pointer to the
record which contains the value of the index to be used for the read.
Prior the read event, the PML may issue the DSS_SET_IDX event to tell
the DAS the index to use for the read action. The DAS should always
return the records in order of the index for the DSS_RD_NEXT,
DSS_RD_GTEQ and DSS_RD_GREAT modes. When no
DSS_SET_IDX event is received prior the read event, the DAS is
assumed to use the primary index.
The record read has to be stored in the buffer that is returned by the
DSS_REC_RD macro.
When a record could not be found or when there are no more records,
the DAS has to set the DSS_E_NOREC error.
When read, the PML may issue events for dedicated conversions from
physical to logical layout (see SubSection 3.8.10) followed by an event
to obtain the process area of the record (see SubSection 3.8.16).
The following table lists the macros that are useful handling the events
described in this section:
Macro Description
DSS_DS_FILE_CHN Returns the channel to an open physical unit to read

the record from.
DSS_RD_MODE Returns the mode for the DSS_RD_REC event.
DSS_RD_TYPE Returns the context of the DSS_RD_REC event. This
supplies the DAS the reason why the read event was
issued.
DSS_REC_RD Returns a pointer to the physical record containing
the index values or upon the read, to store the record
read.
The following example shows the processing of the DSS_RD_REC

event:
DSS_EVENT(DSS_RD_REC)
int mode;
DSS_NO_DEFAULT;
switch (DSS_RD_MODE)
{
case DSS_RD_EQUAL: mode = ISEQUAL; break;

case DSS_RD_NEXT: mode = ISNEXT; break;

case DSS_RD_FIRST: mode = ISFIRST; break;
case DSS_RD_GTEQ: mode = ISGTEQ; break;
case DSS_RD_GREAT: mode = ISGREAT; break;
}
if (!isf_read(DSS_UMH_C,
(struct isf_file_info*)DSS_DS_FILE_CHN,
(char*)DSS_REC_RD, mode))
{
if (umh_error(DSS_UMH_C) == ISF_E_NOREC)
umh_add_code(DSS_UMH_C, DSS_E_NOREC);
DSS_ERROR;
}
3.8.7 Inserting a record
When the PML is requested to insert a record into a data set, a number
of events are fired to the DAS. These events enable the DAS to perform:
• dedicated conversions from logical to physical layout (see
SubSection 3.8.10),
• to check the record prior insertion (DSS_CHK_REC),
• to check whether the record may be inserted (DSS_CHK_INS),
• to insert the record into the physical unit on the primary node
(DSS_INS_REC) and any replica node (DSS_INS_REP) ,
• to perform post processing when the record is inserted
(DSS_INS_NOT),
• to rollback any insertion when insertion or post processing failed
somewhere (DSS_UINS_REC for the primary and
DSS_UINS_REP for any replicas),
• perform audit trailing (see SubSection 3.8.15).
The DSS_CHK_REC event enables the DAS to check the record prior
insertion. When an error is signalled during this check by the DAS then
the insertion of the record is cancelled. It is also possible to make
changes to the physical record on this event. Note that many checks can
be specified in the data dictionary for the data set. They will be
performed by the DSS API and PML without intervention of the DAS.
The DSS_CHK_INS event enables the DAS to check whether the record
may be inserted.
When the checks returns successful, the PML fires the DSS_INS_REC
telling the DAS to insert the record in the physical unit on the primary

node. The primary node is always the node where the DAS is physically
running. The DSS core layer takes care of addressing the PML and DAS
on the primary node. On this event the error DSS_E_RECTHERE may
be returned when the record is already defined in the physical unit.
When replication is defined for the data set then for each replication
node the DSS_INS_REP event is addressed to the DAS.
When all DSS_INS_REC and DSS_INS_REP events where handled
successfully then the DSS_INS_NOT event signals the DAS to perform
some post processing. An example of post processing is to signal an
application that a record is inserted into the data set.
When the DAS responded with an error to one of the DSS_INS_REC,
DSS_INS_REP or DSS_INS_NOT events, the PML tries to undo the
insertion. First DSS_UINS_REP events are issued to the DAS to delete
the record from any replica where the record was already successfully
inserted. Then the DAS uses the DSS_UINS_REC to remove the record
from the primary physical unit.
Macro Description
DSS_DS_FILE_CHN Returns the channel to an open physical unit to insert

or remove the record from.
DSS_REC_WR Returns a pointer to the physical record to check,
insert, to notify or to remove.
The following example shows the processing of the DSS_INS_REC

event:
DSS_EVENT(DSS_INS_REC)
DSS_NO_DEFAULT;
if (!isf_write(DSS_UMH_C,
(char*)DSS_REC_WR))
{
if (umh_error(DSS_UMH_C) == ISF_E_DUPKEY)
umh_add_code(DSS_UMH_C, DSS_E_RECTHERE);
DSS_ERROR;
}

3.8.8 Updating a record
When the PML is requested to update a record into a data set a number
of events are fired to the DAS. These events enable the DAS to perform:
• reading the current record to restore it when the update fails (see
SubSection 3.8.6),
SubSection 3.8.10),
• to obtain the process area of the record (see SubSection 3.8.16),
• to check the record prior updating (DSS_CHK_REC),
• to check whether the record may by updated (DSS_CHK_UPD),
• to update the record in the physical unit on the primary
(DSS_UPD_REC) and any replica node (DSS_UPD_REP) ,
• to perform post processing when the record is updated
(DSS_UPD_NOT),
• to rollback any update when updating or post processing failed
somewhere (DSS_UUPD_REC for the primary and
DSS_UUPD_REP for any replicas),
The DSS_CHK_REC event enables the DAS to check the record prior
updating. It is the same event as issued while inserting a record.
The DSS_CHK_UPD event enables the DAS to check whether the
record may be updated.
When the checks returns successful, the PML fires the DSS_UPD_REC
telling the DAS to update the record in the physical unit on the primary
node. When replication is defined for the data set then for each
replication node the DSS_UPD_REP event is addressed to the DAS.
When all DSS_UPD_REC and DSS_UPD_REP events where handled
successfully then the DSS_UPD_NOT event signals the DAS to perform
application that a record is updated in the data set.
When the DAS responded with an error to one of the DSS_UPD_REC,
DSS_UPD_REP or DSS_UPD_NOT events, the PML tries to undo the
update by rewriting the original record.
First DSS_UUPD_REP events are issued to the DAS to rewrite the
original record in any replica where the record was already successfully
updated. Then the DAS uses the DSS_UUPD_REC to rewrite the record
in the primary physical unit.

Macro Description
DSS_DS_FILE_CHN Returns the channel to an open physical unit to update

the record in.
update or to notify.
DSS_REC_RD Returns a pointer to the physical record to rewrite in
case of the DSS_UUPD_REC and DSS_UUPD_REP
events.
The following example shows the processing of the DSS_UUPD_REP

event:
DSS_EVENT(DSS_UUPD_REP)
DSS_NO_DEFAULT;
if (!isf_rewrite(DSS_UMH_C,
(char*)DSS_REC_RD))
{
if (umh_error(DSS_UMH_C) == ISF_F_NOT_OPEN)
{
if (!re_open(DSS_DAS_C) ||
!isf_rewrite(DSS_UMH_C,
(char*)DSS_REC_RD))
{
if (umh_error(DSS_UMH_C) != ISF_E_NOREC ||
!isf_write(DSS_UMH_C,
(char*)DSS_REC_RD))
DSS_ERROR;
}
}
else if (umh_error(DSS_UMH_C) != ISF_E_NOREC ||
!isf_write(DSS_UMH_C,
(char*)DSS_REC_RD))
DSS_ERROR;

else
DSS_ERROR;
}
Because the replica is located on another node then were the DAS is
physically running, the open physical unit may be closed because the
connection has been down some while.Therefore the ISF error
ISF_F_NOT_OPEN is used to recover from this situation. An example
of defensive programming is to use isf_write to insert the record when
the rewrite returned the error that the record is not there.
3.8.9 Deleting a record
If the PML is requested to delete a record from a data set a number of

events are fired to the DAS. These events enable the DAS to perform:
• reading the current record to restore it when the delete fails (see
SubSection 3.8.6),
SubSection 3.8.10),
• to check the record prior deletion (DSS_CHK_DEL),
• to delete the record from the physical unit on the primary
(DSS_DEL_REC) and any replica node (DSS_DEL_REP) ,
• to perform post processing when the record is deleted
(DSS_DEL_NOT),
• to rollback any update when deletion or post processing failed
somewhere (DSS_UDEL_REC for the primary and
DSS_UDEL_REP for any replicas),
The DSS_CHK_DEL event enables the DAS to check the record prior
deletion or to perform some post processing, for example to check
whether the record can be deleted. Note however, that DSS itself checks
whether a record can be deleted using the relations as specified in the
data dictionary.
When the check returns successful, the PML fires the DSS_DEL_REC
telling the DAS to delete the record in the physical unit on the primary
node. When replication is defined for the data set then for each
replication node the DSS_DEL_REP event is addressed to the DAS.
When all DSS_DEL_REC and DSS_DEL_REP events where handled
successfully then the DSS_DEL_NOT event signals the DAS to perform


application that a record is deleted from the data set.
When the DAS responded with an error to one of the DSS_DEL_REC,
DSS_DEL_REP or DSS_DEL_NOT events, the PML tries to undo the
deletion by inserting the original record. First DSS_UDEL_REP events
are issued to the DAS to insert the original record in any replica where
the record was already successfully deleted. Then the DAS uses the
DSS_UDEL_REC to insert the record in the primary physical unit.
Macro Description
DSS_DS_FILE_CHN Returns the channel to an open physical unit to delete

the record from or to insert the record into.
delete or to notify.
DSS_REC_RD Returns a pointer to the physical record to re-insert in
case of the DSS_UDEL_REC and DSS_UDEL_REP
events.
3.8.10 Conversion
The PML is capable of many types of conversion between the logical

record and the physical record. These conversions are specified in the
data dictionary for the data set. However, when a conversion is required
that can not be handled by the PML (and thus can not be specified in the
data dictionary) is can be handled by the DAS.
The DAS receives events for each logical field in the data set for which
no conversion (mapping) is specified in the data dictionary of the data
set. The DSS_CNV_LOG event is issued to the DAS to convert a field
from its logical value to its physical value. The DSS_CNV_PHY event
is issued to the DAS to convert a physical field to its logical value.
Note that the PML has no knowledge about the related physical field. It
is the responsibility of the DAS to perform the correct conversion and to
address the correct field in the physical record.
Macro Description

DSS_FLD_CUR_GET Obtains the logical value of the logical field to be

converted. To be used with the DSS_CNV_LOG
event.
DSS_FLD_CUR_NM Returns the name of the logical field which value
must be converted.
DSS_FLD_CUR_SET Sets the logical value of the logical field just con-
verted. To be used with the DSS_CNV_PHY event.
DSS_REC_RD Returns the pointer to the physical record in case of
the DSS_CNV_PHY event.
DSS_REC_WR Returns the pointer to the physical record in case of
the DSS_CNV_LOG event.
The example below shows the usage of the DSS_CNV_PHY event:

DSS_EVENT(DSS_CNV_PHY)
if (stricmp(DSS_FLD_CUR_NM, "PROCESS_AREAS") == 0)
{
struct user_df_p *user_df_p =
(struct user_df_p*)DSS_REC_RD;
char pa_list[80];
if (!fmf_bmap_str(DSS_UMH_C,
(TLS_LONG*)&user_df_p->pa_list1,
DSS_PA_MAX,
pa_list, sizeof(pa_list)))
DSS_ERROR;
if (!DSS_FLD_CUR_SET(DSS_DTYPE_CHAR, pa_list))
DSS_ERROR;
}
3.8.11 Asynchronous data access
A DSS client can subscribe to changes of a certain data set. It receives

events when a record is inserted, updated or deleted from the data set.
The PML translate subscriptions into a number of PML events issued to
the DAS. The DAS may then subscribe itself for events on a physical
unit. When the PML receives an event from the physical unit, it searches
the DAS that owns the subscription and issues a PML event to the DAS
to translate the physical unit event to a physical record. Then the PML
and DSS core take care of passing the record to the DSS client.

Asynchronous access is initiated by an open event channel event

(DSS_OPN_EVT) for the DAS.
When no more asynchronous access to the physical unit is required then
a close event channel event is issued by the PML (DSS_CLS_EVT).
While the physical units are open, the PML may issue events, for
example, to subscribe, to process events from physical units and to
process flow control.
The following PML macros are useful to be used for processing the open
events:
Macro Description
DSS_DS_FILE_CHN Used to store the channel to an open physical

unit subscription and returns the channel to an
open physical unit subscription. It is the context
which is interpreted by the DAS only and used
to distinct between the open physical units. An
example is the ISF context.
DSS_DS_FILE_FMT Returns the file record format string.
DSS_DS_FILE_NAME Returns the file name of the physical unit of a
data set to be subscribed.
DSS_DS_NODE_NUMBER Returns the node number where the physical
unit of a data set has to be subscribed.
DSS_DS_PATH_NUMBER Returns the FAST/TOOLS directory path
number where the physical unit of a data set to
be subscribed.
DSS_EVT_MSG_ID Returns a BUS/FAST message id to be used by
the physical unit to send events to the PML.
DSS_FLW_MSG_ID Returns a BUS/FAST message id to be used by
the physical unit to send flow control messages
to the PML.
DSS_REC_LEN Returns the length of a physical record.
The following example show how the DSS_OPN_EVT event is handled

to open an event channel to an ISAM file:
DSS_EVENT(DSS_OPN_EVT)
int opn_mode = ISINPUT;
DSS_NO_DEFAULT;

if ((DSS_DS_FILE_CHN =
(void*)isf_opn_evt(DSS_DUR_C, DSS_UMH_C,
DSS_DS_NODE_NUMBER,
DSS_DS_PATH_NUMBER,
DSS_DS_FILE_NM, opn_mode,
DSS_EVT_MSG_ID(0),
DSS_REC_LEN, DSS_DS_FILE_FMT))
== NULL)
DSS_ERROR;
3.8.12 Subscribe for events
Once an event channel is opened, the PML may issue DSS_SET_EVT

events to subscribe itself to (event criteria):
• any record inserted in the data set,
• any record updated in the data set,
• any record deleted from the data set,
• a specific record updated in the data set,
• a specific record deleted in the data set.
The macros DSS_EVT_CRIT and DSS_REC_RD are used to determine
the mode. DSS_EVT_CRIT returns the event criteria for any record
when the macro DSS_REC_RD returns a NULL pointer. It returns the
event criteria for a specific record when the macro DSS_REC_RD
returns the pointer to the physical record to subscribe on. More than one
DSS_SET_EVT event can be issued by the PML overwriting the
subscription of a previous one, for any record or a specific record. The
following example code shows the usage of these two macro’s:
record = DSS_REC_RD;
if (record == NULL) /* Subscription on data set level */
{
if (DSS_EVT_CRIT = 0)
{
/* Cancel subscription for all records */
}
else
{
if (DSS_EVT_CRIT & DSS_EVT_CRIT_DS_INS)
{
/* Subscribing on any record inserted in the data set */
}

if (DSS_EVT_CRIT & DSS_EVT_CRIT_DS_UPD)

{
/* Subscribing on any record updated in the data set */
}
if (DSS_EVT_CRIT & DSS_EVT_CRIT_DS_DEL)
{
/* Subscribing on any record delete in the data set */
}
}
}
else /* Subscription on a specific record */
{
if (DSS_EVT_CRIT = 0)
{
/* Cancel subscription for the specific record */
}
else
{
if (DSS_EVT_CRIT & DSS_EVT_CRIT_DS_REC_UPD)
{
/* Subscribing on specifc record updated in the data set */
}
if (DSS_EVT_CRIT & DSS_EVT_CRIT_DS_REC_DEL)
{
/* Subscribing on specific record delete in the data set */
}
}
}
The following PML macros are useful to be used for processing the
DSS_SET_EVT event:
Macro Description
DSS_EVT_CRIT Returns the event criteria.

DSS_EVT_REF Returns an PML reference to the subscription. When a
DAS processes a physical unit event via the PML
DSS_PRO_EVT event then this macro is used to return the
reference to the subscription so that PML can quickly find
the related information.

DSS_REC_RD Returns the pointer to the record to subscribe on.
The following code shows an example how to use the DSS_SET_EVT

event using ISF:
DSS_EVENT(DSS_SET_EVT)
char *record = (char*)DSS_REC_RD;
TLS_ULONG crit = DSS_EVT_CRIT;
int mode = 0;
DSS_NO_DEFAULT;
if (crit & DSS_EVT_CRIT_DS_INS)
mode |= ISF_CRI_WRITE;
if (crit & DSS_EVT_CRIT_DS_UPD)
mode |= ISF_CRI_REWRITE;
if (crit & DSS_EVT_CRIT_DS_DEL)
mode |= ISF_CRI_DELETE;
if (crit & DSS_EVT_CRIT_DS_REC_UPD)
mode |= ISF_CRI_REWRITE;
if (crit & DSS_EVT_CRIT_DS_REC_DEL)
mode |= ISF_CRI_DELETE;
mode |= ISF_INF_OLD_RECORD | ISF_INF_NEW_RECORD;
if (!isf_set_evt(DSS_UMH_C,
(struct isf_file_info *)DSS_DS_FILE_CHN,
record, mode, DSS_EVT_REF))
DSS_ERROR;
3.8.13 Handle events from the physical unit
When any subscription is active then the PML receives events from the
physical units. PML uses the message code of such event to determine
the data set that owns the subscription. The related DAS is issued the
DSS_PRO_EVT event to decode the event from the physical unit.
The macro DSS_EVT_REC returns the pointer to the event as received
by the PML. The DAS is responsible for unpacking the event and fill the
physical record buffer with the correct data (the record inserted, updated
or deleted). In addition, the DAS may check whether flow control is still
good and when not good issue a DSS_ERROR_EVT error.
When an record is updated, the DAS has to signal the PML the fields that
got a new value.

When the PML detects that, although an event is received from a

physical unit, that no DSS client is interested anymore, the
DSS_DEL_EVT is issued to the DAS.
The following macros are used with the DSS_PRO_EVT event:
Macro Description
DSS_EVT_CRIT Sets the criteria of the event, insertion, update or deletion

of a record.
DSS_EVT_REC Returns a pointer to a buffer that contains the physical
unit event as received by the PML.
DSS_EVT_REF Sets the PML subscription reference as obtained during
the DSS_SET_EVT. When set to zero, PML ignores this
physical unit event.
DSS_EVT_TIME Sets the time of the event. The time the record was
inserted, updated or deleted.
DSS_REC_RD Returns the pointer to the buffer to store the physical
record inserted, updated or deleted.
DSS_FLD_MARK Used to set the fields that have been changed in case of a
record update.
3.8.14 Handle flow control from the physical unit
When any subscription is active then the PML may receive flow control
messages from the physical units when such flow control has been
enabled by the DAS. PML uses the message code of such message to
determine the data set that owns the subscription. The related DAS is
issued the DSS_PRO_FLW event to decode the message from the
physical unit and to determine whether the flow is still good. When not,
the DAS has to issue a DSS_ERROR_EVT error.
The following macros are used with the DSS_PRO_FLW event:
Macro Description
DSS_EVT_REC Returns a pointer to a buffer that contains the physical

unit flow message as received by the PML.

3.8.15 Audit trailing
After insertion, updating or deletion of a record, PML issues events to

the DAS to perform audit trailing. Normally, the data set specific DAS
does not need to handle these events because they are handled in a
generic way by the default DAS.
First the event DSS_ADT_REC is issued followed by, in case of an
update of the record, an DSS_ADT_FLD event for each logical field
which value has been changed.
Macro Description
DSS_ADT_ACTION Returns the action for the DSS_ADT_REC event.

DSS_ADT_FLD_NM Returns the name of the field which value has been
changed for the DSS_ADT_FLD event.
DSS_ADT_NEW_VAL Returns the value of the field after the change for
the DSS_ADT_FLD event.
DSS_ADT_OFF This macro switches audit trail for the data set off.
Is used to switch audit trailing off for the data set
when no audit trailing is required and eliminates
overhead within the PML. Must be used on the first
DSS_ADT_REC event.
DSS_ADT_OLD_VAL Returns the value of the field prior the change for
the DSS_ADT_FLD event.
DSS_ADT_ON This macro switches audit trail for the data set on.
3.8.16 Process area authorisation
Some fields within some data sets may use process area authorisation.
This means that the field may only be changed when the current user has
a process area defined that corresponds with the process area of the
record in which the field is intended to be modified.
The PML knows the process areas of the current user (which has logged
in to the DSS). It needs the process area of the record. Therefore it issues
the DSS_GET_PAG event. It is normally issued after a read of the
record and process area authorisation is defined for the field in the data
set.

Macro Description
DSS_REC_RD Pointer to the physical record to obtain the process

area of.
DSS_SET_PAG Sets the process area of a record just read.
3.8.17 Accessing other data sets
A set of macros is supplied to access the physical records of another data

set within a DAS. An example is blocking and unblocking an
installation. In this case all items located in the installation must be
blocked or unblocked to.
A set of, so called O routines, is supplied for this purpose:
Macro Description
DSS_O_DS_CLS Closes a data set

DSS_O_DS_DEL Deletes a record from the data set
DSS_O_DS_INS Inserts a record in the data set
DSS_O_DS_OPN Opens a data set.
DSS_O_DS_RD Reads a record from the data set
DSS_O_DS_UPD Updates a record in the data set
DSS_O_FLD_GET Gets the logical or physical value of a field in the
data set
DSS_O_FLD_IDX Sets the field to be used as an index for the follow-
ing read actions
DSS_O_FLD_REP Returns the data type of the logical field
DSS_O_FLD_SET Sets the logical or physical value of a field in the
data set
DSS_O_IDX_SET Sets the index to be used for the following read
actions
DSS_O_REC_LEN Returns the length of the physical read and write
buffers
DSS_O_REC_RD Returns the pointer to the physical read buffer
DSS_O_REC_WR Returns the pointer to the physical write buffer

The following code shows an example of the usage of the O routines:

static TLS_BOOLEAN upd_blocked(DSS_DAS_C, nam1, on_off)
DSS_DAS_C_DECLARATION;
char *nam1;
TLS_LONG on_off;
{
DSS_INIT_SUPPORT;
DSS_DS_CHN ds_chn = NULL;
struct item_def *item_def;
if ((ds_chn =
DSS_O_DS_OPN("ITEM_DF", DSS_OPER_READ |
DSS_OPER_UPDATE)) == NULL)
return FALSE;
if (!DSS_O_FLD_IDX(ds_chn,
DSS_O_FLD_NR(ds_chn, "NAME")))
goto error_exit;
item_def = (struct item_def *)DSS_O_REC_RD(ds_chn);
strcpy(item_def->item_gen.item_name.name1, nam1);
while (DSS_O_DS_RD(ds_chn, DSS_RD_GREAT))
{
TLS_LONG on_off_old;
if (strcmp(item_def->item_gen.item_name.name1, nam1) != 0)
{
umh_set_code(DSS_UMH_C, DSS_E_NOREC);
break;
}
on_off_old = item_def->item_oth.on_off;
item_def->item_oth.on_off =
(on_off_old & ~ITEM_NAM1_OFF) | on_off;
memcpy(DSS_O_REC_WR(ds_chn),
DSS_O_REC_RD(ds_chn),
DSS_O_REC_LEN(ds_chn));
if (!DSS_O_DS_UPD(ds_chn)) goto error_exit;
}
if (umh_error(DSS_UMH_C) == DSS_E_NOREC)
{
DSS_O_DS_CLS(ds_chn);

return TRUE;
}
error_exit:
if (ds_chn != 0) DSS_O_DS_CLS(ds_chn);
return FALSE;
}
3.8.18 Regular actions
Each second the DSS_TIMER event is issued to the DAS. On receipt of

the event the DAS may, for example, check whether there is still a flow
going on with a subscribed physical unit.
3.8.19 Consistency check
DSSCHK is used to perform a consistency check on replicated data sets.

The goal is to check whether the data set is consistent between the
primary node and the replicated nodes. In addition it is able to repair any
inconsistencies. DSSCHK accesses the data set on the primary node of
the data set for checking and repairing. It issues events to the DAS to
help for checking and repairing. Events fired are, for example,
DSS_REC_RD, DSS_INS_REP, DSS_UPD_REP and
DSS_DEL_REP. These events are described in other subsections of this
section.
In addition to these events a number the following events are fired:
Event Description
DSS_CHK_NODE Check whether the primary record is replicated over

another node. The DSS_REC_RD points to the primary
record and DSS_SEL_NODE is the node to check (-1
when all replication nodes should be checked). The
return value should be put in DSS_CONT_CHK. When
this event is not handled all nodes will be checked.
DSS_CMP_REC Compare the primary and replication record to see if the
contents are different. The primary record is placed in
DSS_REC_RD and the replication record in
DSS_REC_WR. The result should be placed in
DSS_REC_DIFF. When this event is not handled then
the default DAS will compare the records.

Making a DAS Data access servers
Event Description
DSS_CNV_TO_REP Convert the contents of the primary record to the record

needed on the replication node. For example in case of
ITEM_DF the member fe_node should be 0 on the rep-
lication node. This conversion is done when an insert or
update is done on the replication node. When this event
is ignored then conversion is not performed.
3.9 Making a DAS

When a new data set is added to the data dictionary and the data from the
data set must be available for the DSS api then a number of rules must
be followed:
• There must always be a field with the name “NAME” that is also
the unique primairy index. This field may be a compound field
composed out of a number of other fields.
• Use as many features of the dictionary to avoid programming in a
DAS.

Data access servers Making a DAS

Introduction Reference DSS API
4 Reference DSS API
4.1 Introduction
This chapter contains a detailed description of the DSS API functions.
The chapter is subdivided as follows:
• First a description is given of some general notes that apply
throughout this chapter. These are issues like return value and
arguments of DSS API functions.
• The header file used by the DSS API.
• A description of data structures used by the DSS API.
• A detailed description of each of the DSS API functions.
4.2 Return value/Error indication

Most functions return either TRUE or FALSE as return value. In the
case of FALSE additional information is passed in the UMH context.
In the case of dss_opn_fld, the return value will be a file pointer or a
NULL. A NULL indicates that an error has occurred, and that additional
information is found in the UMH context.
4.3 Arguments
All arguments which are passed by reference may be assumed to be
To anticipate to possible future extensions of the DSS API, each of the
routines of the DSS API has been prototyped as a routine with a variable
argument list. Most of the routines at least have some fixed number of
arguments. These fixed arguments appear first in the argument list. The
optional arguments come next and are indicated in the list through “...”.
The argument list is always terminated with the constant
‘DSS_ARG_EOL’ (End Of List). This constant is passed as an argument
of type TLS_ULONG. It is very important that is constant is passed to
signal the end of the argument list, otherwise behavior of the function
call will be undefined.

Reference DSS API dss.h header file
If the routine has one or more optional arguments, they can be used in
the argument list (at the place of the three dots) in the following way:
For each of the optional arguments an ‘argument id’ has been defined.
Such an argument id is passed to the routine as an argument of type
TLS_ULONG. The argument that follows a certain argument id, is the
actual optional argument. Both the argument id and the (data type of the)
optional argument, have been described for each individual DSS API
routine.
For example:
[stat=] = dss_con_dcl(
struct umh_context *umh_c,
TLS_ULONG *conn_hnd,
...
DSS_ARG_EOL);
One of the optional arguments for this routine are:
• DSS_ARG_LANG, ULONG
Code for the selected language
This means that for this routine an optional argument with id
DSS_ARG_LANG exists and the argument is of type TLS_ULONG.
The call of the routine would in this case look like:
...
if (!dss_con_dcl(umh_c, conn_hnd, DSS_ARG_LANG,
language, DSS_ARG_EOL))
...
4.4 dss.h header file

are defined in the dss.h. This file contains definitions of structures that
are used in the calls.
In order that the DSS API routines can be used for clients, it is necessary
to ensure that the following requirements are met:
• BUS/FAST and DATABASE/FAST are installed
• dss.h has been included in the source
• The DSS client has been linked with the BUS and DATABASE/
FAST libraries.

Structures Reference DSS API
4.5 Structures
Most of the structures used in the argument list are defined in the file
dss.h. This paragraph gives an overview of the DSS structures used by
the DSS API.
4.5.1 dss_conn_sta
This structure is used to return, for a specific data set, information about
possible flow control problems.
struct dss_conn_sta
{
char ds_nm[DSS_DS_NM_SZ]; /* Dataset having
problems */
TLS_ULONG status; /* Type of problems (see
comment below) */
}
The field “status” in the structure above contains one or more of:
• DSS_EVC_CONN_MIS_EVT_DSS
Probably missed 1 or more events between DSS components.
• DSS_EVC_CONN_BROKEN_DSS
Connection broken between DSS components.
• DSS_EVC_CONN_MIS_EVT_FT
Probably missed 1 or more events between DSS components and
remaining part of FAST/TOOLS.
• DSS_EVT_CONN_BROKEN_FT
Connection broken between DSS components and remaining part
of FAST/TOOLS.
4.5.2 dss_flw_sta
This structure is used to return status info for all data sets for which flow
control problems exist.

Reference DSS API Structures
struct dss_flw_sta
{
TLS_ULONG nr_conn_sta; /* Nr. of status blocks
to follow */
struct dss_conn_sta conn_sta[1]; /* Status blocks
*/
}
4.5.3 dss_gen_arr
This structure is used as general array definition and is used in various

contexts
struct dss_gen_arr
{
TLS_ULONG size; /* Total size of the data
structure including
size and entries field
*/
TLS_ULONG entries; /* Number of array
entries */
TLS_ULONG arr[1]; /* First array element */
}
4.5.4 dss_user
This structure represents the user profile record as present in the (new)
user profile file. This struct is not defined in dss.h but in the file
dss_user.h
struct dss_user
{
char user_name[DSS_USER_NM_SZ];/* User name */
char description[DSS_USER_DESC_SZ];/* Descriptive
text */
char password[DSS_PASSWD_SZ];/* Password */
char initial_display[DSS_INI_DISPLAY_SZ];
/* Initial display */
char asa[DSS_ASA_NM_SZ]; /* Alarm selection area */
TLS_ULONG ath_grp_nr; /* Ref. to auth. grp. */
TLS_ULONG pag_nr[DSS_NR_PA_GRPS];/* Ref. to process

area
groups */
... /* Reserved for future
use YIS */
... /* Reserved for future
use customer */
}
4.5.5 dss_fld_basics
This structure is used to return information about field properties.

struct dss_fld_basics
{
TLS_ULONG fld_id; /* Field id */
char fld_nm[DSS_FLD_NM_SZ];/* Field name */
TLS_ULONG fld_offset; /* Field offset */
TLS_SHORT fld_type; /* Field type */
TLS_SHORT fld_len; /* Field length in bytes*/
TLS_ULONG fld_operations;/* Possible operations on
field */
TLS_ULONG maps_upon_id; /* Id of physical field
upon which the logical
field is mapped */
}
The field “fld_typ” in the structure above is one of:
• DSS_DTYPE_CHAR
Field is of type “character”.
• DSS_DTYPE_SHORT
Field is of type “short”.
• DSS_DTYPE_USHORT
Field is of type “unsigned short”.
• DSS_DTYPE_LONG
Field is of type “long”.
• DSS_DTYPE_ULONG
Field is of type “unsigned long”.
• DSS_DTYPE_FLOAT
Field is of type “float”.
• DSS_DTYPE_DOUBLE
Field is of type “double”.
• DSS_DTYPE_BOOLEAN
Field is of type “boolean”.
• DSS_DTYPE_BYTE
Field is of type “byte”.

• DSS_DTYPE_UBYTE
Field is of type “unsigned byte”.
The field “fld_operations” in the structure above contains one or more
of:
• DSS_OPER_READ
“Read” operation.
• DSS_OPER_UPDATE
“Update” operation.
4.5.6 dss_rec_struct
This structure is used as container for the ‘dss_fld_basics’ structure and

is used to describe the structure of a record.
struct dss_rec_struct
{
TLS_ULONG fld_entries; /* Nr. of entries to
follow */
struct dss_fld_basics fld_basics[1];/* Basic field
info */
}
4.5.7 dss_str_lst
This structure is used to hold a list of pointers to strings.

struct dss_str_lst
{
TLS_ULONG entries; /* The number of string
pointers to follow */
char *str_p[1]; /* Pointers to the strings
*/
}
4.5.8 dss_str_nr_lst
This structure is used to hold a list of number, string pointer

combinations. Is is e.g. used by the property routines to return a list of
data set names and related data set ID’s.

struct dss_str_nr_lst
{
TLS_ULONG entries; /* The number of
dss_str_nr-structs to
follow */
struct dss_str_nr
{
TLS_ULONG number; /* The numeric value */
char *str_p; /* Pointer to the string*/
} str_nr_lst[1]; /* First element in the
str_nr_lst */
}
4.5.9 dss_idx_basics
This structure is used to return information about index properties.

struct dss_idx_basics
{
char idx_nm[DSS_IDX_NM_SZ];/* Name of the index */
TLS_ULONG idx_len; /* Index length */
TLS_ULONG general_prop; /* Index properties (see
below) */
struct dss_str_nr_lst *fld_lst; /* Field
identification */
char *idx_fmt; /* Format string of the
index */
}
The field “general_prop” in the structure above contains one or more of:
• DSS_IDX_PRIM
The index is a “primary” index.
• DSS_IDX_UNIQUE
The index contains a unique value.
4.5.10 dss_idcs
This structure is used as container for the ‘dss_idx_basics’ structure and

is used to describe all indices of a data set table.

struct dss_idcs
{
TLS_ULONG idx_entries; /* Number of entries */
struct dss_idx_basics idx_basics[1];/* Detailed data
*/
}
4.5.11 dss_node_info
This structure is used to describe some characteristics of one single

node.
struct dss_node_info
{
char node_nm[DUR_NOD_NAM_SIZ];/* Node name */
TLS_ULONG flags; /* See below */
TLS_SHORT node_nr; /* Node number */
TLS_USHORT node_prio; /* Node priority */
}
The field “flags” in the structure above contains one or more of:
• DSS_NODE_FLG_PRIMARY
The node is the primary node.
4.5.12 dss_node_lst
This structure is used as container for the ‘dss_node_info’ structure and

is used to describe all nodes of a data set table.
struct dss_node_lst
{
TLS_USHORT entries; /* Number of entries */
TLS_USHORT dummy;
struct dss_node_info node_info[1];/* List of nodes */
}
4.5.13 dss_das
This structure is used to describe the Data Access Server specification

for a data set.

struct dss_das
{
char name[DSS_DAS_NM_SZ];/* Function name */
char path[DSS_DAS_PATH_SZ];/* Shared library path
and name */
}
4.5.14 dss_filespec
This structure is used to describe a file name and path.

struct dss_filespec
{
TLS_LONG log_path; /* TLS directory number */
char name[TLS_FSPEC_SZ]; /* File name (may include
path) */
}
The field “log_path” in the structure above contains one of:
• TLS_NODIR_T
• TLS_INIT_T
• TLS_SAVE_T
• etc. (see tools.h)
4.5.15 dss_mbstr_lst
This structure is used to hold a list of pointers to multi byte strings.

struct dss_mbstr_lst
{
TLS_ULONG entries; /* Number of entries to
follow */
TLS_MBCHAR* mbstr_p[1]; /* Array of pointers to
strings */
}
4.5.16 dss_dbl_rng
This structure is used to hold “range” information for a field.

struct dss_dbl_rng
{
TLS_DOUBLE low_val; /* Minimum value */
TLS_DOUBLE high_val; /* Maximum value */
TLS_DOUBLE step; /* Step value */
TLS_DOUBLE visual_change; /* Visual change */
}
The fields ‘low_val’ and ‘high_val’ contain the lower and upper limit of
the range. If not all values in the specified range are allowed, the field
‘step’ contains a value unequal 0. The field ‘visual_change’ contains the
value that can be used in HMI like applications to define a “visual step”
in the HMI.
4.5.17 dss_def_val
This structure is used to hold a (default) value.

struct dss_def_val
{
TLS_ULONG val_selector; /* Indicates which field
to use (see below) */
union
{
char *str_val; /* String value */
TLS_MBCHAR *mbstr_val; /* Multibyte string */
TLS_DOUBLE dbl_val; /* Double value */
} def_val;
}
The field ‘val_selector’ in the structure above contains one of:
• DSS_VAL_SEL_STR
The “str_val” field in the union is selected.
• DSS_VAL_SEL_MBSTR
The “mbstr_val” field in the union is selected.
• DSS_VAL_SEL_DBL
The “dbl_val” field in the union is selected.
4.5.18 dss_fld_operation
This structure is used to hold the operations that will be caried out by
DSS for a given field.

struct dss_fld_operation
{
TLS_ULONG fld_operation; /* See description of
flags below */
char blank_char; /* "Blank" character */
char dummy[3];
}
The field ‘fld_operation’ in the structure above contains one or more of:
• DSS_FLD_TO_UPPER
Convert field to upper case.
• DSS_FLD_TO_LOWER
Convert field to lower case.
• DSS_FLD_REM_LEAD_SPACE
Remove leading spaces.
• DSS_FLD_REM_TRAIL_SPACE
Remove trailing spaces.
• DSS_FLD_ADD_BLANKS
Add “blank” characters.
4.5.19 dss_fld_transform_lst
This structure is meant to hold field transformation info.

struct dss_fld_transform_lst
{
TLS_ULONG entries; /* Nr. of entries to
follow */
struct dss_fld_transform /* One transformation */
{
TLS_LONG int_val; /* Numeric value */
TLS_MBCHAR *str_p; /* String value */
TLS_MBCHAR *str_c; /* Valid condition
expression */
} fld_transform[1];
}
4.5.20 dss_fld_relation
This structure is meant to hold a relation description for a field in a data

set table.

struct dss_fld_relation
{
char ds_nm[DSS_DS_NM_SZ];/* Related data set */
char fld_nm[DSS_FLD_NM_SZ];/* Related field */
char via_fld_nm[DSS_FLD_NM_SZ];/* Relation goes via
(optional) */
}
4.5.21 dss_fld_compound
This structure is used to describe which data set table fields together
make up a compound field.
struct dss_fld_compound
{
struct dss_str_nr_lst *fld_lst;/* Fields in the
compound */
char *cmp_lay; /* Compound field layout (
format string) */
}
4.5.22 dss_fld_references_lst
This structure is meant to describe which other data sets are referring to
a specific field in a given data set table.
struct dss_fld_references_lst
{
TLS_ULONG entries; /* Number of entries */
struct dss_fld_reference
{
char ds_nm[DSS_DS_NM_SZ];/* Referencing data set */
char fld_nm[DSS_FLD_NM_SZ];/* Referencing field */
char via_fld_nm[DSS_FLD_NM_SZ];/* Relation goes via
(optional) */
} fld_reference[1];
}
4.5.23 dss_flt_pd
This structure is meant to describe which other data sets are referring to
a specific field in a given data set table.

struct dss_flt_pd
{
TLS_LONG mark; /* Must always be
DSS_FLT_PD_MARK */
TLS_LONG nodes; /* Number of nodes that
follow */
struct dss_flt_nd
{
TLS_USHORT operator; /* The operator, one of
DSS_PD.. */
TLS_UBYTE left_nd; /* The index of the left
node */
TLS_UBYTE right_nd; /* The index of the right
node */
TLS_ULONG fld_id; /* The field id */
struct dss_def_val val; /* The value */
} nd[1]; /* The nodes */
}
The field “operator” in the structure above contains one or more of:
• DSS_PD_AND
The members “left_nd” and “right_nd” are valid. The members
“fld_id” and “val” are not used.
• DSS_PD_OR
The members “left_nd” and “right_nd” are valid. The members
“fld_id” and “val” are not used.
• DSS_PD_EQUAL
The members “left_nd” and “right_nd” are not used. The members
“fld_id” and “val” are valid.
• DSS_PD_LESS
• DSS_PD_LTEQ
• DSS_PD_GREAT
• DSS_PD_GTEQ
The members “left_nd” and “right_nd” are not usd. The members
• DSS_PD_LIKE
“fld_id” and “val” are valid. “Val” contains a string that includes
wildcards characters like “*” and “?”.

Reference DSS API DSS API routines
4.5.24 dss_change_log
This structure is used as input and output of the dss_acc_clog() function.

struct dss_change_log
{
TLS_LONG id; /* Change log
identification*/
TLS_ULONG time; /* Time of the change
(GMT)*/
TLS_ULONGsequence; /* Change sequence within
the same time */
char ds_nm[SS_DS_NM_SZ]; /* The name of the dataset
*/
TLS_UBYTEtype; /* The type of change */
char key[DSS_CHANGE_LOG_KEY_LENGTH];
/* The key (name) of the
entity */
}
The field “type” in the structure above contains one or of:
• DSS_CHANGE_LOG_TYPE_INSERT
The entity with the name specified in the ‘key’ field is inserted in
the dataset.
• DSS_CHANGE_LOG_TYPE_UPDATE
The entity with the name specified in the ‘key’ field is updated in
the dataset.
• DSS_CHANGE_LOG_TYPE_DELETE
The entity with the name specified in the ‘key’ field is deleted from
the dataset.
4.6 DSS API routines
4.6.1 Introduction
This paragraph contains a detailed description of all DSS API routines.

The routines are described in alphabetical order. For each of the routines
the following items are described:
• The syntax of the routine.
• A description of fixed and optional arguments of the routine.
• The semantics of the routine.
• If necessary some comment on the use of the routine.

DSS API routines Reference DSS API
• The most important errors that the routine may return.

This information is given in the form of a list of UMH error
mnemonics. The text related to these mnemonics is included in the
next subsection of this paragraph.
• A list of possibly related routines.
A lot of routines need some form of “handle” e.g. a connection handle,
data set handle, filter_id etc. The table below gives an overview how the
caller of these routines can obtain such a handle:
Handle Description Obtained via call to:
conn_hnd Connection handle dss_con_dcl()

ds_hnd Data set handle dss_opn_ds()
evc_hnd Event channel handle dss_opn_evc()
fld_set_id Field set ID dss_bnd_fld()
flt_id Filter ID dss_def_flt()
4.6.2 Text related to error mnemonics
As indicated in the previous section, for each of the DSS API functions
a list of the most important error mnemonics that these function may
return, is given with the detailed description of the routine.
For a description of the error text related to an error mnemonic, please
consult the “dsserrs.umh” file.

4.6.3 Activate filter
Syntax [stat=] dss_act_flt(

TLS_ULONG ds_hnd,
TLS_ULONG flt_id,
...
DSS_ARG_EOL);
Fixed • umh_c
Arguments Pointer to UMH context.
• ds_hnd
Handle to data set.
• flt_id
Identification of the filter to be activated.
Optional • None
Arguments
Semantics Once a data set table has been opened, it is possible to activate a
previously defined filter for this table. This may limit the amount of
records returned during read operations on this table. Once an filter has
been activated for a table, it is possible to activate another filter for the
same table. However before doing so, the “old” filter must be
deactivated first.
Notes • When no filter has been activated for a data set table, it is yet
possible to check if a record read, does satisfy the filter criteria. Use
the routine dss_cri_mtch() for this purpose.
Errors • DSS_E_DCL_NOT_CON
• DSS_E_DD_UPD
• DSS_E_DEA_FLT_FST
• DSS_E_FLT_DS_MTCH
• DSS_E_NORD_NOAFLT
• DSS_E_UNK_DS_HND
• DSS_E_UNK_FLT_ID
Related Routines
Errors dss_cri_mtch, dss_dac_flt, dss_def_flt, dss_del_flt

4.6.4 Bind field
Syntax [stat=] dss_bnd_fld(

TLS_ULONG conn_hnd,
char *ds_nm,
char *fld_nm,
void *fld_var,
TLS_ULONG fld_var_sz,
TLS_ULONG *fld_set_id,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• ds_nm
Pointer to string containing the name of the data set for which field
binding must be performed.
• fld_nm
Name of the field to bind.
When a NULL pointer is specified for this argument, the routine
assumes the binding of the entire data set record is required.
• fld_var
Field variable. This is the address of the variable in which the
contents of the field will be stored (data retrieval actions) or
obtained (data manipulation actions). In case a NULL pointer is
passed for the 'fld_nm' argument, the 'fld_var' argument should
contain the start address of the buffer in which the entire data set
record must be stored.
In both situations, it is the responsibility of the caller to offer an
address that is suitably aligned for an object of any type.
• fld_var_sz
Size in bytes of the field variable to bind. If this size does not match
the size of the field as present in the dictionary, the routine will
return an error.
If the value zero is specified, the routine will not perform this
check.
• fld_set_id
Pointer to variable containing the identification of the field set. For
the first "bind field" call for a (new) field set, the caller should fill
the variable pointed to by ‘fld_set_id’, with the value
DSS_NO_FLD_SET_ID. This is to signal to the "bind field"

routine that this is the first field for the field set. After the first "bind
field" call for a field set, the "bind field" routine will fill this
variable with a new generated field set id. This field set id must be
used in subsequent "bind field" calls for the same field set.
Optional • None
Arguments
Semantics Field binding is an important means to reduce communication overhead
and makes DSS clients less sensitive to changes in the structure of the
data set.
The DSS client has the possibility to express its interest in only a subset
of the fields of a data set record. With the "bind fields" function the DSS
client has the possibility to indicate at which storage locations the data
set record fields must be stored (data retrieval) or at which storage
locations field values can be found (data manipulation).
The DSS client is not obliged to perform explicit field binding. If the
DSS client does not explicitly bind individual fields prior to a data
access operation, the data retrieval and manipulation actions assume the
involvement of all fields of a data set record. In this situation (no specific
field binding), the bind field routine is used to pass the start address of
the buffer in which the entire data set record need to be stored.
The possible usage of the field binding routine is listed in the table
below:
Field name Storage location

Result
specified specified
Yes Yes Explicit field binding.
One single field is bound to a specified data set
location.
Yes No Undefined (error situation).
No Yes Entire data set record binding. Storage location
is the (start) address of the buffer in which the
data set record must be stored (data retrieval) or
will be available (data manipulation).
No No Undefined (error situation).
By defining more than one field set for the same data set, different type
of operations on the same data set, can use different combinations of
fields.

It is allowed to bind a field more than once. It is not allowed to bind

fields from different data sets in the same field set.
If a certain field set is no longer used anymore, it is recommended to
unbind the fields in the field set (see Unbind fields). This will free
system resources.
Notes • It is not allowed to extend a field set which is already in use.
Errors • DSS_E_BND_VAR_SZ
• DSS_E_DCL_NOT_CON
• DSS_E_DD_UPD
• DSS_E_DIFF_DS_NM
• DSS_E_FST_IN_USE
• DSS_E_FST_STO_LOC
• DSS_E_ILLCNV
• DSS_E_INT_ADM
• DSS_E_NOT_BND_REC
• DSS_E_SO_FST
• DSS_E_UNK_FST_ID
Related Routines
Errors dss_opn_evc, dss_rd_eql, dss_rd_evt, dss_rd_seq, dss_ubnd_fld

4.6.5 Cancel event request
Syntax [stat=] dss_canc_evt(

TLS_ULONG evc_hnd,
TLS_ULONG crit,
...
DSS_ARG_EOL);
Fixed • umh_c
• evc_hnd
Event channel handle.
• crit
The possible values are:
- DSS_EVT_CRIT_DS_INS
Cancels the "inserted" notification at data set level.
- DSS_EVT_CRIT_DS_UPD
Cancels the "updated" notification at data set level.
- DSS_EVT_CRIT_DS_DEL
Cancels the "deleted" notification at data set level.
- DSS_EVT_CRIT_DS_REC_UPD
Cancels the "updated" notification at data set record level.
When this criterion is reset, the primary index of the data set
record involved must also be specified via the optional
argument DSS_ARG_FLD_SET_PIDX.
- DSS_EVT_CRIT_DS_REC_DEL
Cancels the "deleted" notification at data set record level.
When this criterion is reset, the primary index of the data set
record involved must also be specified via the optional
argument DSS_ARG_FLD_SET_PIDX.
- DSS_EVT_CRIT_DS_REC_FLD_UPD
Cancels the "updated" notification at data set record field
level. The primary index of the record concerned must be
specified via the optional argument
DSS_ARG_FLD_SET_FMON.
Optional • DSS_ARG_FLD_SET_ID_PIDX, ULONG

Arguments Field set of which the bound variables contain the complete primary
index value of the data record for which the event request must be
cancelled.
This argument is required when event notification must be

selectively cancelled at data set record level or at data set record

field level.
• DSS_ARG_FLD_SET_ID_FMON, ULONG
Field set containing the field(s) for which the event request must be
cancelled.
This argument is required when event nofication must be
selectively cancelled at data set record field level.
Semantics With this routine, the DSS client is enabled to cancel event notification
either for all criteria or for specific criteria.
Notes • None.
Errors • DSS_E_DD_UPD
• DSS_E_FLD_SET_FD
• DSS_E_FLD_SET_PID
• DSS_E_FST_FMON_DS
• DSS_E_FST_PIDX_DS
• DSS_E_MIS_FST
• DSS_E_UNK_EVC_HND
Related Routines
Errors dss_cls_evc, dss_opn_evc, dss_rd_evt, dss_set_evt

4.6.6 Close data set table
Syntax [stat=] dss_cls_ds(

TLS_ULONG ds_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
Optional • None.
Arguments
Semantics When an open data set table, is no longer needed by a DSS client, the
DSS client should close the data set. This enables DSS to free all
resources occupied by the open data set table.
Notes • None.
• DSS_E_DD_UPD
Related Routines
Errors dss_opn_ds

4.6.7 Close an event channel
Syntax [stat=] dss_cls_evc(

TLS_ULONG evc_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• evc_hnd
Handle to the data set event channel.
Optional • None.
Arguments
Semantics An event channel to a data set can be closed with this call. All
outstanding event requests will be cancelled as part of the execution of
this call.
Notes • None.
Errors • DSS_E_DD_UPD
Related Routines
Errors dss_canc_evt, dss_opn_evc, dss_rd_evt, dss_set_evt

4.6.8 Check if dataset is concealed
Syntax [stat=] dss_conc_ds(

TLS_ULONG conn_hnd,
char *ds_nm,
TLS_BOOLEAN *concealed,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• ds_nm
Pointer to string containing the dataset name.
• concealed
Pointer to TLS_BOOLEAN in which result will be returned.
Optional • None.
Arguments
Semantics With this routine a DSS client is able to check if a dataset is concealed.
The purpose of this routine is to make it possible for a DSS-client to
present only meaningful data to the user.
Whether a dataset is relevant can depend on the FAST/TOOLS
configuration. For example, some dataset may only be relevant in a host-
front_end configuration.
The logic that determines if a dataset is concealed can be specified in the
<concealed> property in the definition for the dataset. This is done in the
dataset definition file (*.dss file). For details on how to use the
<concealed> property please see the DSS Language Manual.
The concealed property is optional, datasets with no concealed
properties specified are never concealed.
Notes • The concealed expression that is evaluated for a specific dataset can
be retrieved using the dss_prop_ds() routine using the property
code DSS_SPROP_CONCEALED_COND.
• DSS_E_DS_NM_LEN

• DSS_E_FLT_SYN_ERR
Related Routines
Errors dss_conc_fld

4.6.9 Check if field is concealed
Syntax [stat=] dss_conc_fld(

TLS_ULONG conn_hnd,
char *ds_nm,
char *fld_nm,
TLS_BOOLEAN *concealed,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• ds_nm
Pointer to string containing the dataset name.
• fld_nm
Pointer to string containing the field name.
• concealed
Optional • None.
Arguments
Semantics With this routine a DSS client is able to check if a field in a dataset is
concealed. The purpose of this routine is to make it possible for a DSS-
client to present only meaningful data to the user.
Whether a field is relevant can depend on the FAST/TOOLS
configuration.
The logic that determines if a field is concealed can be specified in the
<concealed> property in the field definition for the dataset. This is done
in the dataset definition file (*.dss file). For details on how to use the
<concealed> property please see the DSS Language Manual.
The concealed property is optional, fields with no concealed properties
specified are never concealed.
Notes • The concealed expression that is evaluated for a specific dataset can
be retrieved using the dss_prop_fld() routine using the property
code DSS_FPROP_CONCEALED_COND.
Errors

• DSS_E_DS_NM_LEN
• DSS_E_FLD_NM_LEN
Related Routines
Errors dss_conc_ds

4.6.10 Connect to DSS
Syntax [stat=] dss_con_dcl(

...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Pointer to variable in which the connection handle will be stored.
Optional • DSS_ARG_ADT_SAS, TLS_ULONG

Arguments The AUDIT/FAST action source code.
DSS will send a notification message for some of the actions
performed via the DSS API. To be able to do this, the DSS API
needs knowledge about the so called AUDIT/FAST action source
code related to the DSS client. This action source code is part of the
AUDIT/FAST event classifier. When not specified the default
action source code ADT_SAS_GDSS is used. For other action
codes, please consult the “adt_ece.h” header file.
• DSS_ARG_BMSG_ID, TLS_ULONG
Base message id to be used by the DSS event mechanism. DSS will
claim an interval of DSS_MSGC_RANGE message codes for
"internal" BUS/FAST message processing purposes. To prevent
from interfering with BUS/FAST message codes used by the DSS
client itself, the DSS client has the possibility to specify where this
DSS message code interval should start. The caller of this routine
must take care that the message id range falls within the range 0 to
MAXSIGNEDSHORT
When this argument is not specified, DSS will itself select an
interval of message codes.
• DSS_ARG_LANG, TLS_ULONG
Code for selected language. Code is one of:
- TLS_LANG_DEFAULT
The default language used within the client.
This default language is the language specified during the
installation of the tool BUS/FAST.
- TLS_LANG_ENGLISH
- TLS_LANG_NEDERLANDS

- TLS_LANG_FRANCAIS
- TLS_LANG_DEUTSCH
When this argument is not specified, TLS_LANG_DEFAULT is
taken as default.
• DSS_ARG_FLAGS, TLS_ULONG
Connection options.
This is a bit wise OR of one or more of the following bits:
- DSS_CONN_FLG_NO_FLW_CTRL
When this flag is set, no flow control will be used over the DSS
event channel(s).
When this argument is not specified, flow control will be used over
the event channel.
Semantics Before a DSS client is able to use any of the other functions provided by
DSS, the DSS client should connect to DSS.
When the DSS client has successfully connected to DSS, the function
returns a so called "connection handle". This handle needs to be
preserved by the DSS client since it is needed by some of the other DSS
functions.
Notes • None.
Errors • DSS_E_DCL_CON_TWC
• DSS_E_DSS_SHM
• DSS_E_MSG_ID
• DSS_E_SHM_NOT_PRS
Related Routines
Errors dss_dcon_dcl

4.6.11 Check if record matches filter criteria
Syntax [stat=] dss_cri_mtch(

TLS_ULONG fld_set_id,
TLS_ULONG flt_id,
TLS_BOOLEAN *match,
...
DSS_ARG_EOL);
Fixed • umh_c
• fld_set_id
Field set to be used.
It is the responsibility of the caller of this routine to offer a field set
which contains all fields being present in the filter being referred to.
• flt_id
Identification of the filter to be used.
• match
Pointer to TLS_BOOLEAN variable in which the result of the
evaluation will be stored (TRUE or FALSE).
If for some reason an error occurs during the evaluation, the
TLS_BOOLEAN variable will contain the value FALSE.
Optional • None.
Arguments
Semantics Enables a DSS client to check whether a given data set record matches
certain filter criteria. The routine can be used just after a record has been
read.
The “value” of the data set record is contained by the variables of the
field set identified by argument ‘fld_set_id.
Notes • It is not relevant to the routine in which way the data set record to
be matched, is obtained. This can be either via the DSS API read
routines or via the DSS event mechanism.
• DSS_E_DD_UPD

Related Routines
Errors dss_act_flt, dss_dac_flt, dss_def_flt, dss_del_flt

4.6.12 Deactivate filter
Syntax [stat=] dss_dac_flt(

TLS_ULONG ds_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
Optional • None.
Arguments
Semantics Deactivates the “current” filter of an open data set table.
Notes • None.
• DSS_E_DD_UPD
• DSS_E_NORD_NODFLT
Related Routines
Errors dss_act_flt, dss_cri_mtch, dss_def_flt, dss_del_flt

4.6.13 Disconnect from DSS
Syntax [stat=] dss_dcon_dcl(

TLS_ULONG conn_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
Optional • None.
Arguments
Semantics As soon as the DSS client no longer needs services from DSS, the DSS
client has to disconnect from DSS. This enables DSS to free all
resources used so far for the DSS client.
Notes • None.
Related Routines
Errors dss_con_dcl

4.6.14 Define filter
Syntax [stat=] dss_def_flt(

TLS_ULONG conn_hnd,
char *ds_nm,
char *filter,
char *list_file,
TLS_ULONG *flt_id,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• ds_nm
Pointer to string containing the data set name.
• filter
Pointer to a buffer containing the textual filter expression (char*) or
a push down filter (struct dss_flt_pd *). For more detailed
information about the filter expression syntax to be used for the
filter expression, see the notes section of this paragraph.
• list_file
Name of the list file (including the file path).
- If list_file == NULL, then no listing is outputted.
- If list_file[0] != ‘\0’, then listing is outputted to a specified file.
- If list_file[0] == ‘\0’, then listing is outputted to standard
output (stdout).
• flt_id
Pointer to variable in which the filter id will be stored.
Optional • None.
Arguments
Semantics To define a filter, the DSS client has the possibility to pass a textual filter
expression or a binary push down filter to this routine. After the routine
has checked the expression, it transforms the expression to an internal
format and returns a “filter-id” to the caller of the routine.
The filter definition is global, i.e. within the same program the filter-id
can be used for different “instances” of the same data set. This might be
valuable in situations where a certain data set is opened more than once.
The routine does not check if the same filter (a filter with exactly the
same semantics) is defined more than once.

When the filter is not used anymore, the filter should be deleted, in order
to free system resources.
For textual filter expressions, a string buffer is passed that contains the
expression (for more detailed information about the filter expression
syntax to be used for the filter expression, see the notes section of this
paragraph).
For push down filters, the filter is passed via a pointer to a buffer of type
struct dss_flt_pd. Passing push down filters is used when a compiled
filter is already available within the application.
Consider the following textual filter:
(A = 1 and B = “z” ) or C >= 1
where A, B and C are field names. It is represented in a push down filter
organised as a tree:
or
and c >= 1
A=1 B = “z”
In this example the push down filter contains 5 nodes. This tree is
represented in struct dss_flt_pd as follows:
struct dss_flt_ps
{
TLS_LONG mark = DSS_FLT_PD_MARK;
TLS_LONG nodes = 5;
struct dss_flt_nd
{
TLS_USHORT operator = DSS_PD_OR;
TLS_UBYTE left_nd = 1;
TLS_UBYTE right_nd = 4;
TLS_ULONG fld_id = not used;
struct dss_def_val val = not used;
} nd[0];
struct dss_flt_nd
{
TLS_USHORT operator = DSS_PD_AND;
TLS_UBYTE left_nd = 2;
TLS_UBYTE right_nd = 3;
TLS_ULONG fld_id = not used;

struct dss_def_val val = not used;

} nd[1];
struct dss_flt_nd
{
TLS_USHORT operator = DSS_PD_EQUAL;
TLS_UBYTE left_nd = not used;
TLS_UBYTE right_nd = not used;
TLS_LONG fld_id = field id of field “A”;
struct dss_def_val val = 1;
} nd[2];
struct dss_flt_nd
{
TLS_USHORT operator = DSS_PD_EQUAL;
TLS_ULONG fld_id = field id of field “B”
struct dss_def_val val = “Z”;
} nd[3];
struct dss_flt_nd
{
TLS_USHORT operator = DSS_PD_GTEQ;
TLS_LONG fld_id = field id of field “C”;
struct dss_def_val val = 1;
} nd[4];
Notes This section gives a description of the syntax for the DSS filter
expressions. The following symbols and conventions are used for the
syntax description:
• Bold printed elements are part of the language itself.
• []
Means: enclosed item is optional.
• { }..
Means: enclosed item(s) may be repeated one or more times.
• < >:
Means: Enclosed item is defined as .........
• <>
Means: use definition of enclosed item.
An filter expression has one out of two possible layouts:
<wildcards string constant>

or
<logical expression>
where:
<wildcards string constant>:
"[{<wc char>}..]"
<wc char>:
All printable characters, including '*' and '?'.
The character '*' is meant to indicate: zero or more characters.
The character '?' is meant to indicate: exactly one character.
The <wildcards string constant> is a short notation for the <logical
expression>: NAME LIKE <wildcards string constant>
<logical expression>:
<comparison> [{<logical operant> <comparison>}..]
<comparison>:
<field name> <comparison operator> <constant value>
<field name>:
One of:
• Name of a field
• <process area>
<comparison operator>:
One of:
• =
• !=
• <
• <=
• >
• >=
• LIKE
<constant value>:
<numeric constant> | <string constant>
<numeric constant>:
For example: 12.4
<string constant>:

For example: "INS.UNI.VALVE2"

<logical operand>:
One of:
• OR
• AND
<process area>:
PROCESS_AREAS(<process areas string>)
<process area string>:
A process area expression as definable in the engineering module
surrounded by quotes (“”).
Examples of <process area string> are:
“” None
“1” Process area 1
“1-5, 10” Process areas 1 to 5 inclusive and 10
“1 4 7” Process areas 1, 4 and 7
Note: A process area comparison is a boolean expression and can only

be compared with “TRUE” or “FALSE” using the <comparison
operators> = and !=. Using any other <constant value> or <comparison
operator> will generate an error.
Examples of <logical expressions> are:

NAME LIKE "INS.*" (is same as: "INS.*")
(ITEM_TYPE = "Output" OR ITEM_TYPE = "Input") AND
HIGH_LIMIT > 100.2
Note that <string constants> are case sensitive and that <field names>
and the operators are case insensitive.
• DSS_E_DD_UPD
Related Routines
Errors dss_act_flt, dss_dact_flt, dss_cri_mtch, dss_del_flt

4.6.15 Delete filter
Syntax [stat=] dss_del_flt(

TLS_ULONG flt_id,
...
DSS_ARG_EOL);
Fixed • umh_c
• flt_id
Identification of the filter to be deleted.
Optional • None.
Arguments
Semantics When the DSS client does not use a certain filter anymore, it is
recommended to delete the filter. By deleting the filter, system resources
fill be freed which will have a positive effect on the overall performance
of the system.
Notes • The filter can not be deleted as long as it is in use.
• DSS_E_DD_UPD
• DSS_E_FLT_IN_USE
Related Routines
Errors dss_act_flt, dss_dact_flt, dss_cri_mtch, dss_def_flt

4.6.16 Delete record
Syntax [stat=] dss_del_rec(

TLS_ULONG ds_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
Optional • None.
Arguments
Semantics Enables a DSS client to delete a record from a data set table.
If the DSS client itself has put a lock on the record to be deleted, it is not
necessary for the DSS client to remove the lock prior to the delete action.
As part of the delete action, DSS will check if no referential integrity
rules become violated when the record is deleted. If referential integrity
rules would become violated, the record won't be deleted and the routine
returns an error code.
The DSS client is obliged to specify the value of the primary index of
the record that must be deleted. During the "Open data set" operation,
the DSS client has specified which field set is applicable during the
record delete operation. Because of this, the delete record routine
"knows" where to obtain the value(s) for the unique index.
Notes • None
• DSS_E_DD_UPD
• DSS_E_NO_AUTH
• DSS_E_OP_NOT_INT
Related Routines
Errors dss_ins_rec, dss_lck_rc, dss_rd_eql, dss_rd_seq, dss_unlck_rc,
dss_upd_rec

4.6.17 Dump DSS API data structures
Syntax [stat=] dss_dmp(

TLS_ULONG dmp_flags,
FILE *fp,
...
DSS_ARG_EOL);
Fixed • umh_c
• dmp_flags
Dump flags, indicating what the caller of this function wants to be
dumped. The contents of this argument is one or more of the
following flags:
- DSS_DMP_MIB
Dump main information block.
- DSS_DMP_ODS
Dump open data set tables information.
- DSS_DMP_FST
Dump field set information.
- DSS_DMP_EVC
Dump event channel information.
- DSS_DMP_FLT
Dump filter information.
- DSS_DMP_EQ
Dump event queue information.
- DSS_DMP_EVP
Dump event processor information.
Optional • None.
Arguments
Semantics Via this routine (parts of) the internal DSS API administration can be
dumped. This routine is solely meant for debug purposes. The
information dumped is not self explanatory and is meant as information
for the provider of the DSS brick.
Notes • None
Errors • DSS_E_DCL_NOT_CON.
• DSS_E_DMP_FILE
Related Routines
Errors All other DSS routines.

4.6.18 Check if field is enabled
Syntax [stat=] dss_enabled(

TLS_ULONG ds_hnd,
char *fld_nm,
TLS_BOOLEAN *enabled,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to dataset.
• fld_nm
• enabled
Optional • None.
Arguments
Semantics With this routine a DSS client is able to check if a dataset field is
enabled. The enabled condition is used to check if the field is relevant
for a specific dataset record. The result is return in the enabled
parameter.
The purpose of this routine is to make it possible for a DSS-client to
present only meaningful data to the user.
For example, the dataset ITEM_DF has a field called HIGH_LIMIT to
store the high limit for an item. This field is only relevant for an item of
type INTEGER or REAL. For items of type STRING this field is not
meaningful.
This shows that weather a dataset field is relevant can depend on the
value of other fields in the dataset. The logic that determines if a field is
enabled can be specified in the <enabled> property in the field definition
for the dataset. This is done in the dataset definition file (*.dss file). For
details on how to use the <enabled> property please see the DSS
Language Manual.
The enabled property is optional, fields with no enabled properties
specified are always enabled.
The record data must be stored in the buffers specified by the field set
prior calling this function (as in dss_ins_rec()).

Notes • The enabled expression that is evaluated for a specific field can be
retrieved using the dss_prop_fld() routine using the property code
DSS_FPROP_ENABLE_COND.
• DSS_E_NO_INS_FLD
• DSS_E_FLD_NM_NFD
Related Routines
Errors dss_valid

4.6.19 Get flow control information
Syntax [stat=] dss_get_flwc(

struct dss_flw_sta **flw_sta,
...
DSS_ARG_EOL);
Fixed • umh_c
• flw_sta
Address of pointer to flow control information.
When a NULL pointer is returned by this routine, no flow control
information is present yet.
Optional • None.
Arguments
Semantics With this routine a DSS client is able to obtain flow control information.
After being called, the flow control information is reset, i.e. it can not be
obtained a second time.
Notes • None.
Related Routines
Errors dss_rd_evt

4.6.20 Enable/disable exclusive data set access
Syntax [stat=] dss_excl_acc(

TLS_ULONG conn_hnd,
TLS_ULONG excl_acc_id,
TLS_ULONG umh_msg_code,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• excl_acc_id
Exclusive access id.
• umh_msg_code
UMH message code.
Optional • None.
Arguments
Semantics With this routine a DSS client is able enable exclusive access to all the
data sets. In addition the DSS client an disable this exclusive access.
When a DSS client has enabled then no other local or remote DSS client
is able to insert or delete records in any data set. The DSS client that
enabled exclusive access can insert and delete records. Only one DSS
client can have enabled exclusive access at a time.
The excl_acc_id argument identifies the DSS client. Normally the brick
number of the DSS client is used. If a zero is supplied then the exclusive
access is disabled. The exclusive access is also disabled when the client
calls dss_dcon_dcl() or exists.
The umh_msg_code argument supplies the code of an umh message that
is returned to an DSS client that fails to insert or delete a record because
the exclusive access is enabled.
Insertion an deletion is disabled for all data sets except those mentioned
in dss.sup.
Notes • None.

DSS_E_OTHEREACC
Related Routines
Errors

4.6.21 Insert record
Syntax [stat=] dss_ins_rec(

TLS_ULONG ds_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
Optional • None.
Arguments
Semantics Via this routine, a DSS client is enabled to insert a record in a data set
table.
Some of the fields of the data set might be optional when inserting a new
record in the data set. The meta information of the data set, describes to
which fields this applies. When the DSS client does not explicitly
specify values for these fields, these fields will be filled with the default
values specified in the data dictionary.
During the "Open data set" operation, the DSS client has specified which
field set is applicable during the record insert operation. Because of this,
the insert routine "knows" where to obtain the values for the fields of the
record to be inserted.
Notes • None.
• DSS_E_DD_UPD
• DSS_E_NO_AUTH
Related Routines
Errors dss_del_rec, dss_opn_ds, dss_rd_eql, dss_rd_seq, dss_set_idx,
dss_unlck_rc, dss_upd_rec

4.6.22 Lock a record
Syntax [stat=] dss_lck_rc(

TLS_ULONG ds_hnd,
struct dss_gen_arr *index,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
• index
Pointer to buffer containing the primary index value(s) of the
record(s) to be locked.
In case no "bulk locking" is required, one single primary index
value is passed via this argument.
In case the DSS client wants to perform "bulk locking" of data set
records, a number of primary index values are passed via this
argument.
Optional • None.
Arguments
Semantics This routine enables a DSS client to lock (a) record(s) in a data set. The
record(s) to be locked is/are identified by its/their primary index
value(s).
If a DSS client "unexpectedly" exits without removing its locks, the
locks will be removed automatically.
If for any reason the connection between the DSS client and the node at
which the locking information is kept, disappears (even for a short time),
the lock is released immediately. An error will be generated when the
DSS client tries to perform an operation on a data set, which it presumes
it has currently locked but in reality is no longer locked anymore by the
same DSS client.
Notes • In case of bulk locking, it's an "all or nothing" attempt, either all
records become locked or none of them become locked.
• DSS_E_DD_UPD
• DSS_E_LCK_DS

• DSS_E_LCK_DS_REC
• DSS_E_LOCK_LOST
• DSS_E_PIDX_DATA
Related Routines
Errors dss_unlck_rc

4.6.23 User routine called upon log off DSS
Syntax void dss_lgof_usr(

struct umh_context *umh_c);
Fixed • umh_c
Optional • None.
Arguments
Semantics Routine that is called upon successfull DSS log off action. Since the
source of this routine is provided to System Integrators, customer
specific actions can be programmed in this routine.
Notes • None.
Errors • None.
Related Routines
Errors dss_lgon_usr, dss_logoff, dss_logon

4.6.24 User routine called upon log on to DSS
Syntax void dss_lgon_usr(

struct dss_user *user);
Fixed • umh_c
• user
pointer to struct containing data of the user that logged on.
Optional • None.
Arguments
Semantics Routine that is called upon successfull DSS log on action. Since the
source of this routine is provided to System Integrators, customer
specific actions can be programmed in this routine.
Notes • None.
Errors • None.
Related Routines
Errors dss_lgof_usr, dss_logoff, dss_logon

4.6.25 Log off DSS
Syntax [stat=] dss_logoff(

TLS_ULONG conn_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
Optional • DSS_ARG_SESSION_ID, TLS_ULONG

Arguments The identification of the session to logoff from. This effectively
means that the client using this session has gained the most
extensive permission for operations on data sets. When omitted the
default session (session zero) is used.
Semantics Once a DSS client has logged-on to DSS, the DSS client can log-off
from DSS. This action causes the DSS client to return to the state prior
to the very first log-on action. Effectively this means that the DSS client
has gained the most extensive permission for operations on data sets.
Notes • None.
• DSS_E_DD_UPD
Related Routines
Errors dss_lgof_usr, dss_lgon_usr, dss_logon

4.6.26 Log on to DSS
Syntax [stat=] dss_logon(

TLS_ULONG conn_hnd,
char *user_nm,
char *password,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• user_nm
User name.
• password
Password. May be a NULL pointer.

Arguments The identification of the session to logon. When omitted the default
session (session zero) is used to logon.
• DSS_ARG_TERM_NM, char *
The name of the terminal where the user is located. When omitted
a blank terminal name is used.
• DSS_ARG_NODE_NM, char *
The name of the BUS/FAST node where to logon and start a remote
session. This is used to start a DSS session on a remote BUS/FAST
node. If omitted then DSS_ARG_NODE_NR will be used.
• DSS_ARG_NODE_NR, TLS_ULONG *
The BUS/FAST node number where to logon and start a remote
session. If omitted then the session is started on the own node.
• DSS_ARG_ADT_SAS, TLS_ULONG *
The AUDIT/FAST action source code to be used for this session.
When omitted then the action source code as specified with the
dss_con_dcl() function will be used.
• DSS_ARG_ENT_USR, TLS_BOOLEAN *
If TRUE is specified then the user must be an Enterprise user. If not
then the login fails.
Semantics DSS implements an authorization scheme. This authorization scheme is

used by DSS to determine what kind of data a DSS client is able to
retrieve and what kind of operations a DSS client is able to perform.

When the DSS client does not perform a separate log-on action, DSS
will grant the most extensive permissions to the DSS client. In such a
situation the DSS client is enabled to perform all valid operations on data
sets.
When the DSS client performs a separate log-on, the DSS client has to
pass a user name and (optionally) a password. DSS will use this
information to determine what kind of permissions can be granted to the
DSS client. Furthermore the user-name information will be used by DSS
when reporting events to AUDIT/FAST.
When a NULL pointer for the password is supplied then no checking for
the correct password is performed.
The DSS client can log-on as many times as needed. This might be
useful to (temporary) grant the DSS client a more or less extensive
permission level. DSS will not preserve context information in such a
situation, i.e. successive log-on actions will overwrite previously
specified information.
When a log-on attempt fails, the DSS client will keep its current
authorization level.
Using the DSS_ARG_SESSION_ID and DSS_ARG_NODE_NM or
DSS_ARG_NODE_NR optional arguments, a session can be started on
a remote BUS/FAST node. Dictionary access and data set access using
the session id for which the remote session is initiated will be executed
on the remote node and data will be transported to and from the remote
node. This remote access is transparent to the user of the DSS functions.
The remote node may contain a different dictionary.
Notes • None.
Errors • DSS_E_ATHGRP_DATA
• DSS_E_DD_UPD
• DSS_E_UNK_USER
• DSS_E_USER_DATA
• DSS_E_PAG_DATA
Related Routines
Errors dss_lgof_usr, dss_lgon_usr, dss_logoff

4.6.27 Open data set table
Syntax [stat=] dss_opn_ds(

TLS_ULONG conn_hnd,
char *ds_nm,
TLS_ULONG *ds_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• ds_nm
Pointer to string containing the name of the data set to be opened.
• ds_hnd
Pointer to variable in which the data set handle will be stored.

Arguments The identification of the session for which the data set table must
be opened. When omitted the default session (session zero) is used.
• DSS_ARG_OPERATIONS, TLS_ULONG
Types of operations that the DSS client intends to perform. The
contents of the 'operations' argument is a bitwise OR of one or more
- DSS_OPER_READ
- DSS_OPER_INSERT
- DSS_OPER_UPDATE
- DSS_OPER_UPDATE_IGN
Has the same function as DSS_OPER_UPDATE except that
an update of a record doesn’t result in an error if a read-only
field is tried to be updated. Instead, the new value for the read-
only field is ignored.
- DSS_OPER_DELETE
- DSS_OPER_ALL
By default the DSS API assumes that the DSS client intends to
perform all types of operations.
• DSS_ARG_FILTER_ID, TLS_ULONG
Id of a possibly defined filter.

• DSS_ARG_FLD_SET_ID_RD, TLS_ULONG
Field set to be used when reading records from the data set.
The caller is obliged to specify this field set, when the caller intends
to perform a read operation.
• DSS_ARG_FLD_SET_ID_INS, TLS_ULONG
Field set to be used when inserting records in the data set.
to perform an insert operation.
• DSS_ARG_FLD_SET_ID_UPD, TLS_ULONG
Field set to be used when updating records in the data set.
to perform an update operation.
• DSS_ARG_FLD_SET_ID_DEL, TLS_ULONG
Field set to be used when deleting records from the data set.
to perform a delete operation.
• DSS_ARG_NODE_NM, char *
• DSS_ARG_NODE_NR, TLS_SHORT
Specifies a name of a FAST/TOOLS node name or node number
where the data set must be opened. When both are specified then
the node name is used. These optional arguments overrule the
default node selection mechanism of DSS. When specified the data
set can be opened for read access only. Even a node that is not part
of the distributed FAST/TOOLS environment can be specified. In
this case it is the System Integrator’s responsibility to make sure
that the data dictionaries on the systems are the same.
• DSS_ARG_TIME_AS_GMT, TLS_BOOLEAN
Default the value of a field of type DSS_DTYPE_DATE contains
the date/time in LCT. This behavior can be modified using the
DSS_ARG_TIME_AS_GMT argument. If set to TRUE then the
fields of type DSS_DTYPE_DATE will contain GMT date/time.
Semantics Prior to an operation on a data set table, the data set table need to be
opened.
Opening a data set table, enables DSS to prepare for things to come.
Opening a certain data set table, can be done by the DSS client as many
times as needed. After a data set table has been successfully opened, the
routine returns a handle that is needed for subsequent operations on the
data set table.

When using the "Open data set" routine, a number of options can be
specified. These options are meant to:
• Enable the DSS to optimize the services it is going to provide.
• Give the DSS client the possibility to indicate what kind of
additional services it requests from DSS.
Notes • During the "data set open" action it is possible to specify different
field sets for the read, insert, update and delete operations on the
data set. It is however also possible to use exactly the same field set
for these type of operations.
• The primary index should always be part of field sets used for read,
insert, update and/or delete operations.
• DSS_E_DD_UPD
• DSS_E_INT_OP
• DSS_E_FST_DS_REL
• DSS_E_FSTD_NEX
• DSS_E_FSTI_NEX
• DSS_E_FSTR_NEX
• DSS_E_FSTU_NEX
• DSS_E_MIS_FST
• DSS_E_NO_PRIM_ND
• DSS_E_RQ_FLD_FSTI
• DSS_E_RQ_FLD_FSTU
Related Routines
Errors dss_cls_ds

4.6.28 Open an event channel
Syntax [stat=] dss_opn_evc(

TLS_ULONG conn_hnd,
char *ds_nm,
TLS_ULONG *evc_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• ds_nm
Pointer to string containing data set name.
• evc_hnd
Pointer to variable in which the event channel handle will be stored.
This handle is required for subsequest calls to the DSS API routines
related to the DSS event mechanism.

Arguments The identification of the session for which the event channel must
be opened. When omitted the default session (session zero) is used.
• DSS_ARG_OPERATIONS, TLS_ULONG
Types of “operations” that the DSS client intends to perform. The
contents of the 'operations' argument is a bitwise OR of one or more
- DSS_OPER_EVT_DS
For event requests at data set level.
- DSS_OPER_EVT_DSR
For event requests at data set record level.
- DSS_OPER_EVT_DSRF
For event requests at data set record field level.
By default the DSS API assumes that the DSS client intends to
perform all types of operations.
• DSS_ARG_FLD_SET_ID_DS, TLS_ULONG
Field set to be used when event is generated at data set level.
• DSS_ARG_FLD_SET_ID_DSR, TLS_ULONG
Field set to be used when event is generated at data set record level.

• DSS_ARG_FLD_SET_ID_DSRF,TLS_ULONG
Field set to be used when an event is generated at data set record
field level.
• DSS_ARG_FILTER_ID, TLS_ULONG
Id of filter. This filter is applied when an event occurs. When the
event does not pass the filter, the event is not sent to the DSS client.
When this argument is not specified, no filtering applies.
• DSS_ARG_TIME_AS_GMT, TLS_BOOLEAN
Default the value of a field of type DSS_DTYPE_DATE contains
the date/time in LCT. This behavior can be modified using the
DSS_ARG_TIME_AS_GMT argument. If set to TRUE then the
fields of type DSS_DTYPE_DATE will contain GMT date/time.
Semantics In order for the DSS client to be notified about events related to a data
set, the DSS client has to subscribe to the DSS event mechanism. Once
the DSS client has subscribed, the event request remains active until it is
deleted or until the DSS client terminates.
The DSS client will be enabled to express its interest in certain type of
events by specifying so called event criteria. These event criteria will be
related to so called "event" levels. The following event levels will be
distinguished:
• data set level
Operations on the data set are globally monitored by DSS. As soon
as DSS detects a change in the contents of the data set, the DSS
client is notified.
• data set record level
The DSS client can request for monitoring of changes on specific
data set records. As soon as DSS detects a change of such a specific
data set record, the DSS client is notified.
• data set record field level
If the DSS client is only interested in changes of (a) specific field(s)
in a specific data set record.
The table below gives an overview of possible event criteria for each of
the levels mentioned above.
Level Event criterion
data set Record inserted

Record deleted

Level Event criterion
Record updated
data set record Record deleted
Record updated
data set record field Field updated
Different event criteria can be specified in parallel. For similar situations

however, an event will only be sent once. Example: Suppose a DSS
client has expressed its interest in changes on a data set by specifying the
criteria "Record updated" at data set record level and "Field updated" at
data set record field level. Now suppose the contents of the field in
question changes. In that situation only 1 event will be sent with in it
information that indicates that both the “Record updated" and "Field
updated" criteria are fulfilled.
For all three "event" levels (data set, data set record and data set record
field level), it is possible to specify separate field sets (as obtained with
the "Bind fields" routine). This possibility might be useful in situations
where the DSS client is interested in e.g. the "record inserted" criterion
(data set level) and the "field updated" criterion (data set record field
level) on the same data set. When the "record inserted" criterion
becomes true, the DSS client is probably interested in the entire data set
record. However if the "field updated" criterion becomes true, the DSS
client is possibly only interested in the contents of the field(s) being
updated. By offering the possibility to specify different field sets during
the event request, the DSS client is enabled to express its wishes for
different situations, thereby reducing communication and processing
overhead as much as possible. It is however not necessary to specify
different field sets for each event level. Field sets can be shared across
event levels.
With the "Open event channel" routine, the possibility exists to specify
the id of a filter that has been previously defined with the "Define filter"
routine.
Notes • A DSS client can open only 1 event channel for a given data set
table.
• When the DSS client uses flow control and the DSS client has
opened an event channel it should start polling on the event
channel. This is because DSS will send flow control messages to
the DSS client as soon as the event channel has been opened.
• When for an event, more than one criterion is fulfilled at the same
time (e.g. "data set record field updated and data set record updated

and data set updated"), the "in hierarchy, lowest level" field set
specified is used.
Example:
When an event is generated for which the following criteria are
fulfilled: "data set record field updated, data set record updated and
data set updated" the field set specified for the data set record field
level will be used.
• DSS_E_DD_UPD
• DSS_E_EVC_ALROPEN
• DSS_E_FSTDS_NEX
• DSS_E_FSTDSR_NEX
• DSS_E_FSTDSRF_NEX
• DSS_E_FST_DS_REL
• DSS_E_INT_OP
• DSS_E_MIS_FST
• DSS_E_NO_AUTH
Related Routines
Errors dss_canc_evt, dss_cls_evc, dss_rd_evt, dss_set_evt

4.6.29 Open MEMO/UNKNOWN field
Syntax FILE *fp=dss_opn_fld(

TLS_ULONG ds_hnd,
char *fld_nm,
char *mode,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to the data set.
• fld_nm
Name of the field containing the name of the data container . If the
field set used for read operations, only contains one field of the
MEMO or UNKNOWN type, it is allowed to pass a NULL pointer
for this argument. In that case the routine itself determines which
field must be meant.
• mode
As specified for standard C routine fopen().
Optional • DSS_ARG_PATH_FILE_NM, char *

Arguments Variable holds system dependent file name and path that can be
used to directly access the file. The file holds the actual data for the
MEMO or UNKNOWN datatype.
When a file name is specified then the data will be placed in this
file. When an empty file name is specified then DSS itself will
gererate a file name to put the data into. The name of the generated
file name is returned. Therefor make sure that the empty file name
buffer is large enough to contain the generated file name
(TLS_FSPEC_SZ).
Semantics With this routine, the DSS client is able to fetch the data represented by
a field of datatype MEMO or datatype UNKNOWN. During a read
action, fields of data type MEMO and UNKNOWN, contain the name
of the data container in which additional data is stored. The data
container itself is not fetched during the read. By calling this routine, the
data container itself is fetched and opened.
Notes • It is the responsibility of the caller of this routine, to close the data
container with a call to the standard-C function fclose().

• DSS_E_DD_UPD
• DSS_E_IMPRP_TYP
• DSS_E_NO_AUTH
• DSS_E_NO_CUR_REC
• DSS_E_NO_PRP_TYP
• DSS_E_UNK_FLD_NM
Related Routines
Errors None

4.6.30 Request properties at data set level
Syntax [stat=] dss_prop_ds(

TLS_ULONG conn_hnd,
char *ds_nm,
TLS_ULONG prop_req,
void **prop_data,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• ds_nm
• prop_req
Code for requested property. For a detailed description of all
possible data set level properties, see table in notes section.
• prop_data
Address of pointer to data set property information.
The routine itself allocates space to return property data. It is the
responsibility of the caller to preserve property data (if required)
after a call to this routine has been made. This is because the routine
will re-use the internally allocated buffer in which property data is
returned, in a subsequent call to this routine.
Be carefull when the property structures contain pointer variables.
It is the responsibility of the caller to separately copy the data, that
is pointed to by pointer variables.
For a description of applicable data structures, see notes section.

Arguments The identification of the session for which the properties must be
requested. When omitted the default session (session zero) is used.
• DSS_ARG_DATA_SZ, TLS_ULONG *
Pointer to variable in which the "property data" size is stored (i.e.
the number of bytes written in the property data buffer). This
information might be useful if the caller of this routine wants to
make a local copy of the returned property data.

Semantics With this interface all kind of meta information at the data set level can
be obtained.
The routine performs in the most optimum way when properties of the
same data set are requested before properties of other data sets are
requested.
If the caller of this routine wants to preserve the data returned by this
routine, the caller should do this before any of the other DSS API
routines are called or before this routine is called again.
Notes • The table below gives a description of possible properties that can
be requested at data set level. The table also provides information
about the related data types and data structures used by the routine
to return property data.
Property code Description Data structure

DSS_SPROP_SET_STRUCT Data set record structure dss_rec_struct
DSS_SPROP_PREC_STRUCT Physical record structure dss_rec_struct
DSS_SPROP_PREC_FMT Physical record format char

Zero terminated string.
DSS_SPROP_DESCRIPTION data set description TLS_MBCHAR

Multi-byte character array .
DSS_SPROP_LREC_LEN Total length of logical data set TLS_ULONG

record (in bytes)
DSS_SPROP_PREC_LEN Total length of physical record TLS_ULONG

(in bytes)
DSS_SPROP_NR_OF_LFLDS Number of fields in logical TLS_ULONG

record
DSS_SPROP_NR_OF_PFLDS Number of fields in physical TLS_ULONG

record
DSS_SPROP_LFLD_NAMES List of field names in logical dss_str_lst

record.
DSS_SPROP_LFLD_IDS List of field ids in logical record. dss_gen_arr

Field id's will be returned as
TLS_ULONG.
DSS_SPROP_IDCS Index data for data set. dss_idcs
Remark: The first index in the
dss_idcs data structure is the pri-
mary index.


DSS_SPROP_OPERATIONS Defined operations on data set. TLS_ULONG
Value DSS_NO_OPERATIONS Contains zero or more of
means no operations on data set (bitwise OR):
at all. DSS_OPER_READ
DSS_OPER_INSERT
DSS_OPER_UPDATE
DSS_OPER_DELETE
DSS_OPER_EVT_DS
DSS_OPER_EVT_DSR
DSS_OPER_EVT_DSRF
DSS_SPROP_PERMISSIONS Permissions granted on data set, TLS_ULONG

given current authorisation level.
Value Contains zero or more of
DSS_NO_PERMISSIONS (bitwise OR):
means no permissions granted at DSS_PERM_READ
all. DSS_PERM_INSERT
DSS_PERM_UPDATE
DSS_PERM_DELETE
DSS_SPROP_STO_NODE Storage node(s). dss_node_lst

Remark: The nodes returned are
sorted on decreasing priority
level.
DSS_SPROP_DAS Data Access Server. dss_das
DSS_SPROP_FILESPEC Physical data file used to obtain dss_filespec

the data set data.
DSS_SPROP_HIDDEN Hidden property for a data set. TLS_BOOLEAN
DSS_SPROP_DS_ID ID of the dataset TLS_ULONG

DSS_SPROP_LOC_STAMP Returns the timestamp of data TLS_ULONG
set in the local data dictionary
DSS_SPROP_HOST_STAMP Returns the timestamp of data TLS_ULONG

set in the host data dictionary
DSS_SPROP_CONCEALED_COND Concealed condition for the char

dataset. Null terminated string.
• DSS_E_DD_UPD
• DSS_E_DD_LOCK
• DSS_E_UNK_DS_NM
• DSS_E_UNK_DS_PRP
Related Routines
Errors dss_prop_dss, dss_prop_fld, dss_prop_idx

4.6.31 Request properties at DSS level
Syntax [stat=] dss_prop_dss(

TLS_ULONG conn_hnd,
TLS_ULONG prop_req,
void **prop_data,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• prop_req
• prop_data
Optional • DSS_ARG_DATA_SZ, TLS_ULONG *

Arguments Pointer to variable in which the "property data" size is stored (i.e.
Semantics With this interface all kind of meta information at the DSS level can be
obtained.

be requested at DSS level. The table also provides information

DSS_DPROP_DATA_SETS Returns all defined data sets, by name dss_str_nr_lst
and id
DSS_DPROP_LOC_STAMP Returns the timestamp of the local data TLS_ULONG

dictionary
DSS_DPROP_HOST_STAMP Returns the timestamp of the host data TLS_ULONG

dictionary
• DSS_E_DD_UPD
• DSS_E_DD_LOCK
• DSS_E_UNK_DS_PRP
Related Routines
Errors dss_prop_ds, dss_prop_fld, dss_prop_idx

4.6.32 Request properties at field level
Syntax [stat=] dss_prop_fld(

TLS_ULONG conn_hnd,
char *ds_nm,
char *fld_nm,
TLS_ULONG prop_req,
void **prop_data,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• ds_nm
• fld_nm
• prop_req
• prop_data


Semantics With this interface all kind of meta information at the data set field level
can be obtained.
same data set are requested before properties of other data sets are
requested.
be requested at field level. The table also provides information

DSS_FPROP_DESCRIPTION Field description TLS_MBCHAR
Multi-byte character array.
DSS_FPROP_FLD_BASICS Basic properties of a dss_fld_basics

field
DSS_FPROP_HEAD Field heading TLS_MBCHAR

DSS_FPROP_FMT Format string char

Nuu terminated string.
Describes the "output" format for
the field.
DSS_FPROP_VAL_LIST List of possible values dss_mbstr_lst

for this field. This field
property is only valid
for string type fields.
DSS_FPROP_VAL_RANGE Value range for field. dss_dbl_rng

Also returns the "step"
value within the range.
This field property is
only valid for numeric
type fields.
DSS_FPROP_REQUIRED Describes whether the TLS_ULONG

field contents must be Contains one or more of (bitwise
specified during an OR):
insert or update opera- DSS_FLD_REQ_INSERT
tion, i.e. whether or not DSS_FLD_REQ_UPDATE
field is required.
DSS_FPROP_DEF_VAL_INS Default value stored in dss_def_val

the field in case of
insert operation
DSS_FPROP_DEF_VAL_UPD Default value stored in dss_def_val

the field in case of
update operation


DSS_FPROP_CHAR_RESTRICT Describes possible TLS_ULONG
character restrictions Contains zero or more of (bitwise
for a field. OR):
DSS_FLD_NO_SPACES
DSS_FLD_NO_DOTS
DSS_FLD_ONLY_PRINTABLE
DSS_FLD_ONLY_ALPHA_NUM
DSS_FLD_ONLY_NUMERIC
DSS_FLD_ONLY_IDENTIFIER
DSS_FPROP_CHAR_OPERATION Describes the character dss_fld_operation

operations for a field.
The property only
applies if the field is of
data type string.
DSS_FPROP_TRANSFORMATION List of transformation dss_fld_transform_lst

values.
DSS_FPROP_HIDDEN Hidden property TLS_BOOLEAN
DSS_FPROP_PW_ENCRYPTED Describes whether the TLS_BOOLEAN

field in question will be Returns TRUE when the field will
password encrypted. be handled as encrypted field, other-
wise it returns FALSE.
DSS_FPROP_RELATION Describes the relation to dss_fld_relation

another data set.
DSS_FPROP_COMPOUND Describes the compo- dss_fld_compound

nents of a compound
field. This property can-
not be requested of a
field that has a relation
to a compound field.
DSS_FPROP_REFERENCES Describes data sets that dss_fld_references_lst

have a relation to the
field.
DSS_FPROP_OPERATIONS Defined operations on TLS_ULONG

field of the data set. (Contains zero or more of (bitwise
Value OR):
DSS_NO_OPERATIO DSS_OPER_READ
NS means no operations DSS_OPER_INSERT
on field at all. DSS_OPER_UPDATE
DSS_OPER_DELETE
DSS_OPER_EVT_DS
DSS_OPER_EVT_DSR
DSS_OPER_EVT_DSRF
DSS_FPROP_ENABLE_COND Enable expression for char

the field. Null terminated string.
DSS_FPROP_VALID_CONDITIONS Valid conditions for the dss_mbstr_lst

field. Each condition is Conditions are returned in an array
associated with a mes- of dss_mbstr_lst. The conditions are
sage explaining the con- grouped as sets where the first entry
dition. contains the condition expression
and the second one the associated
message.


DSS_FPROP_CONCEALED_COND Concealed condition for char
the field. Null terminated string.
DSS_FPROP_VAL_LIST_COND List of valid values to dss_mbstr_lst

enter into a field. Values are returned in an array of
Each value in the list is dss_mbstr_lst. The values are
associated with a condi- grouped as sets where the first entry
tional expression. If the contains the condition expression
expression is TRUE the and the second one the associated
associated value is valid value.
to enter into the field.
DSS_FPROP_GROUP The group property for TLS_MBCHAR

the field. Multi-byte character array.
• DSS_E_DD_UPD
• DSS_E_DD_LOCK
• DSS_E_UNK_DS_NM
• DSS_E_UNK_FLD_NM
• DSS_E_UNK_FLD_PRP
Related Routines
Errors dss_prop_ds, dss_prop_dss, dss_prop_idx

4.6.33 Request properties at index level
Syntax [stat=] dss_prop_idx(

TLS_ULONG conn_hnd,
char *ds_nm,
TLS_ULONG prop_req,
void **prop_data,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• ds_nm
• prop_req
• prop_data

• DSS_ARG_IDX_NM, char *
Index name.
When this argument is not specified, the primary index is taken as
default.

Semantics With this interface all kind of meta information about the indices of a
data set can be obtained.
index of the same data set are requested before index properties in other
data sets are requested.
It is not necessary to open the data set prior to requesting meta
information.
be requested for an index. The table also provides information

DSS_IPROP_STRUCT Index structure dss_idx_basics
DSS_IPROP_DESCRIPTION Index description TLS_MBCHAR

DSS_IPROP_LENGTH Total index length in bytes. TLS_ULONG

DSS_IPROP_GENERAL Describes general properties for TLS_ULONG
the index. Contains one or more of (bitwise
OR):
DSS_IDX_UNIQUE
DSS_IPROP_LFLD_NAMES List of field names that together dss_str_lst

comprises the index. Order in
which the fields are returned, also
determine the order of the fields
in the index.‘
DSS_IPROP_LFLD_IDS List of ids of the field that dss_gen_arr

together comprise the index.
Order in which the fields are
returned, also determine the order
of the fields in the index.
• DSS_E_DD_UPD
• DSS_E_DD_LOCK
• DSS_E_UNK_DS_NM
• DSS_E_UNK_IDX_NM
• DSS_E_UNK_IDX_PRP
Related Routines
Errors dss_prop_ds, dss_prop_dss, dss_prop_fld

4.6.34 Recover DSS client
Syntax [stat=] dss_rcvr_dcl(

TLS_ULONG conn_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
Optional • None.
Arguments
Semantics A specific DSS routine is available to let a DSS client recover from a
situation where the data dictionary has been updated at the local node.
The DSS client is able to detect a situation where it is expected to call
the recovery routine because most DSS routines return a specific error
code (DSS_E_DD_UPD) when a data dictionary update occurs.
When the DSS recover routine is called, the DSS client remains
connected to DSS and remains its current "log-on status". However all
other context is removed and must be set up again.
Notes • None.
Related Routines
Errors dss_con_dcl, dss_dcon_dcl

4.6.35 Read equal operation
Syntax [stat=] dss_rd_eql(

TLS_ULONG ds_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
Optional • DSS_ARG_PERMISSIONS, TLS_ULONG *

Arguments Via this argument the routine returns the possible operations on the
data set record.
The variable contains zero or more of the following flags:
- DSS_PERM_READ
- DSS_PERM_UPDATE
- DSS_PERM_DELETE
Semantics When the DSS client possesses the value of a data set index, the DSS
client is able to perform a "read equal" operation. This operation is
performed using the index currently set. If the read operation is
performed on an index that is not unique, the operation will return the
first occurrence of the record satisfying the index value.
The index value must be put in the appropriate variables of the field set
specified with the "Open data set" routine.
With the "read equal" operation either the entire record is returned or one
or more individual fields. This depends on the field binding operation
performed by the caller of this routine. The information read, will be
available in the variables bound to the fields of the data set record.
No filter criteria apply with this type of data retrieval operation.
Notes • None.
Errors • DSS_E_CUR_IDX_FST
• DSS_E_DD_UPD
• DSS_E_NO_AUTH

• DSS_E_EOS
Related Routines
Errors dss_rd_seq, dss_set_idx

4.6.36 Read event information
Syntax [stat=] dss_rd_evt(

char *ds_nm,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle to which the event applies.
• ds_nm
Pointer to variable in which the name of the data set for which the
event was raised, will be stored.
Optional • DSS_ARG_EVT_CRIT, TLS_ULONG *

Arguments Criteria that have been fulfilled with this event.
• DSS_ARG_REF_INFO, TLS_ULONG *
Data set reference info as specified with the event request.
• DSS_ARG_EVENT_MSG, struct dur_par_rcv *

Pass a received BUS/FAST message to read the event from.
Semantics When this routine is called by the DSS client, the DSS API checks for
the presence of DSS events in the BUS/FAST message queue or, if
DSS_ARG_EVENT_MSG is supplied, then the DSS API checks for the
presence of DSS events in the buffer specified by dur_par_rcv. If
available, this information is copied to an DSS API internal event buffer.
This internal event buffer is capable of holding a certain amount of
events (to be influenced by a setup file parameter, see the System
Integrator’s manual for more information).
After the "Read event" routine has been successfully called, the routine
has performed the following actions:
1 The required data set record information (the fields bound) have
been copied to the variables bound to the data set record fields.
2 The name of the data set to which the event applies has been
determined. This data set name can be obtained via the “ds_nm”
argument of the routine.

The read event routine is capable of detecting if the universal stop

message has been sent to the application. When this message is received,
the routine returns the error code DSS_E_DOEXIT. In case, the
application should tidy up and terminate as if it had received a
TLS_UNI_STOP message.
Notes • If DSS_ARG_EVENT_MSG is specified then the receiver buffer

specified by dur_par_rcv may not yet be converted from the system
type of the original sender. The DSS API takes care of this.
• DSS_E_DD_UPD
• DSS_E_FLOW
• DSS_E_NO_EVTS
• DSS_E_DOEXIT
Related Routines
Errors dss_canc_evt, dss_cls_evc, dss_opn_evc, dss_set_evt

4.6.37 Read sequential operation
Syntax [stat=] dss_rd_seq(

TLS_ULONG ds_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
Optional • DSS_ARG_FLAGS, TLS_ULONG

Arguments Flags that have been defined are:
- DSS_RD_FLG_RD_FIRST
Read the first record from the data set table (given the index
currently set). If this flag is not set, the routine assumes that the
record relative to the previous record read, must be returned.
DSS_RD_FLG_RD_FIRST is the default behaviour at the
first call to dss_rd_seq() after an open (dss_opn_ds()) of the
data set.
- DSS_RD_FLG_RD_BULK
“Bulk read" operation.
This flag is meant to optimise the internal processing in case
of data retrieval operations. By setting this flag, the DSS client
indicates that it intends to retrieve a bulk of records. So the
read routine "knows" beforehand that a lot of additional
information will be required. Instead of fetching just one
single record, the read routine is given the opportunity to
anticipate to this situation.
This type of optimisation is specifically meant for DSS clients
that need a small amount of fields from a bulk of records, e.g.
to fill up a list box with (a subset of) items.
When this argument is not specified, it is assumed that none of the
flags has been raised.
• DSS_ARG_PERMISSIONS, TLS_ULONG *
Via this argument the routine returns the possible operations on the
data set record.
The variable contains zero or more of the following flags:
- DSS_PERM_READ
- DSS_PERM_UPDATE

- DSS_PERM_DELETE
Semantics Via this routine either the "first" or the "next" record in the data set can
be read.
The index currently set, together with possibly specified filter criteria,
determines which record is considered as the "first" record in a data set.
The result from the last successful read operation, the index currently set
and possibly specified filter criteria, determine which record is
considered as the "next" record in a data set
Either the entire record is returned or one or more individual fields are
returned. This depends on the field binding operation performed by the
caller of this routine. The information read, will be available in the
variables bound to the fields of the data set record.
Notes • Do not change the contents of a bound variable between two
successive read requests. This is because the contents of bound
variables is used when recovery is necessary (e.g. to reposition in a
file on another system)
• DSS_E_DD_UPD
• DSS_E_EOS
• DSS_E_NO_AUTH
Related Routines
Errors dss_rd_eql, dss_set_idx

4.6.38 Set event request
Syntax [stat=] dss_set_evt(

TLS_ULONG evc_hnd,
TLS_ULONG crit,
...
DSS_ARG_EOL);
Fixed • umh_c
• evc_hnd
Handle to the data set event channel.
• crit
Event criteria, i.e. under which condition(s) must the DSS client be
notified. The following event criteria have been defined:
Perform a notification when it has been detected that a record
has been inserted in the data set table.
has been updated in the data set table.
has been deleted from the data set table.
Perform a notification when it has been detected that a specific
record has been updated in the data set table.
The primary index of the record to be monitored must be
passed via the optional argument
DSS_ARG_FLD_SET_PIDX (See description of Optional
arguments).
record has been deleted from the data set table.
The primary index of the record to be monitored, must be
arguments).
- DSS_EVT_CRIT_DS_REC_FLD_UPD
field in a specific record has been updated in the data set table.
The primary index of the record to be monitored, must be


arguments).
The field(s) within the record to be monitored, must be passed
via the optional argument DSS_ARG_FLD_SET_FMON.
These criteria can be bitwise OR'ed.
Optional • DSS_ARG_REF_INFO, TLS_ULONG

Arguments This information will appear again at the moment the DSS client
read an event for the data set.
When this argument is not specified, the value
DSS_NO_REF_INFO (MAXUNSIGNEDLONG) will appear at
the moment the DSS client receives the event.
• DSS_ARG_FLD_SET_ID_PIDX,TLS_ULONG
Field set to be used to pass the primary index value of the data
record to which the event request applies. This argument is required
when the event criteria, contains a criterion at data set record level
or at data set record field level.
• DSS_ARG_FLD_SET_ID_FMON,TLS_ULONG
Field set describing the fields to which the event request at data set
record field level applies.
This argument is required when the event criteria, contains a
criterion at data set record field level.
Semantics Once an event channel has been opened for a data set, requests for events
can be issued via this routine. Subsequent event requests for the same
data set will be interpreted as extensions to the existing event criteria.
When specifying an event criterion at data set record level, the data set
record being referred to is identified by its primary index. When
specifying an event criterion at data set record field level, the field(s)
being referred to is identified by both the primary index of the record and
a (list of) field name(s).
Notes • None.
• DSS_E_DD_UPD
• DSS_E_FLD_SET_FD
• DSS_E_FLD_SET_PID

• DSS_E_FST_FMON_DS
• DSS_E_FST_PIDX_DS
• DSS_E_MIS_FST
• DSS_E_PIDX_FST
Related Routines
Errors dss_canc_evt, dss_cls_evc, dss_opn_evc, dss_rd_evt

4.6.39 Set current index
Syntax [stat=] dss_set_idx(

TLS_ULONG ds_hnd,
char *idx_nm,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
• idx_nm
Name of the index to be set.
When a NULL pointer is passed for this argument, the primary
index is assumed.
Optional • None.
Arguments
Semantics Before issuing a data retrieval operation, the DSS client has the
possibility to set the index to use during the data retrieval operation.
From a functional point of view, the index determines in which order
records in a data set will be returned. Each data set table has at least one
unique index associated with it (the primary index).
The DSS client refers to an index by the index name. When the DSS
client has not explicitly set the index prior to a data retrieval operation,
DSS assumes the primary index needs to be used.
Notes • None.
• DSS_E_DD_UPD
• DSS_E_UNK_IDX_NM
Related Routines
Errors dss_rd_eql, dss_rd_seq

4.6.40 Unbind field
Syntax [stat=] dss_ubnd_fld(

TLS_ULONG fld_set_id,
...
DSS_ARG_EOL);
Fixed • umh_c
• fld_set_id
Identification of the field set for which the fields must be unbound.
Optional • None.
Arguments
Semantics The DSS client has the possibility to unbind all fields for a field set. This
will free system resources and will have a positive impact on the overall
performance of DSS.
Notes • Fields can not be unbound when the field set is in use.
• DSS_E_DD_UPD
• DSS_E_FLD_SET_UBD
Related Routines
Errors dss_bnd_fld

4.6.41 Unlock a record
Syntax [stat=] dss_unlck_rc(

TLS_ULONG ds_hnd,
struct dss_gen_arr *index,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
• index
Pointer to buffer containing the primary index value(s) of the
record(s) to be unlocked.
In case no "bulk locking" is required, one single primary index
value is passed via this argument.
In case the DSS client wants to perform "bulk unlocking" of data
set records, via this argument a number of primary index values are
passed.
By passing a NULL pointer for this argument, all outstanding locks
on this instance of the data set table, will be removed.
Optional • None.
Arguments
Semantics Enables a DSS client to unlock (a) record(s) in a data set. The record(s)
to be unlocked is/are identified by its/their primary key value. If the
primary key value is not specified explicitly (a NULL pointer is passed),
all records previously locked by the DSS client for the data set, will be
unlocked.
Notes • No error will be returned in case the DSS client performs an attempt
to release a type of lock that it has not activated.
• A data set unlock attempt on a record that is not/no longer locked
by the DSS client will do no harm and will not result in an error
being returned.
• DSS_E_DD_UPD
• DSS_E_LOCK_LOST

Related Routines
Errors dss_lck_rc

4.6.42 Update record
Syntax [stat=] dss_upd_rec(

TLS_ULONG ds_hnd,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to data set.
Optional • None.
Arguments
Semantics Via this routine, a DSS client is enabled to update a record in a data set.
As with the insert operation, some of the fields might be optional. When
the DSS client does not explicitly specify values for these fields, these
fields will be filled with either the default values specified in the data
dictionary or will retain their original value.
During the "Open data set" operation, the DSS client has specified which
field set is applicable during the record update operation. Because of
this, the update routine "knows" where to obtain the values for the fields
of the record to be updated.
Notes • Offering a certain field to the "Update record" routine (via the field
set id) is interpreted as an attempt to update the contents of the field.
This is important with regard to the authorisation mechanism.
• DSS_E_DD_UPD
• DSS_E_NO_AUTH
Related Routines
Errors dss_del_rec, dss_ins_rec, dss_lck_rc, dss_unlck_rc

4.6.43 Get valid field values
Syntax [stat=] dss_val_list(

TLS_ULONG ds_hnd,
char *fld_nm,
struct dss_mbstr_lst **values,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to dataset.
• fld_nm
• values
Address of a pointer to valid field values.
The routine itself allocates space to return valid values. It is the
responsibility of the caller to preserve this value data (if required)
will re-use the internally allocated buffer in which data is returned,
in a subsequent call to this routine.

Arguments Pointer to variable in which the "values" size is stored (i.e. the
number of bytes written in the values data buffer). This information
might be useful if the caller of this routine wants to make a local
copy of the returned values data.
Semantics With this routine a DSS-client can retrieve a list of valid values for a
field. The purpose of this routine is to make it possible for a DSS-client
to present a list of meaningful field values for a user to insert in a field.
The list of meaningful values for a field may be different for different
records in the same dataset. For example, an item of type STRING and
an item of type INTEGER are both stored in the dataset item_df, but can
have different lists of meaning full values for the same field.
The logic that determines this list is defined in the <LIST> property in
the field definition for the dataset. This is done in the dataset definition
file (*.dss file). For details on how to use the <LIST> property please see
the DSS Language Manual.

The LIST property is optional. If no LIST of values was defined for a

field the value of values will be NULL.
Notes • The list of valid values and the logic that is evaluated for a specific
field can be retrieved using the dss_prop_fld() routine using the
property code DSS_FPROP _VAL_LIST_COND.
• DSS_E_VALID_COND
Related Routines
Errors dss_valid
dss_prop_fld

4.6.44 Check if field value is valid
Syntax [stat=] dss_valid(

TLS_ULONG ds_hnd,
char *fld_nm,
struct dss_mbstr_lst **messages,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to dataset.
• fld_nm
• messages
Address of a pointer to messages.
The routine itself allocates space to messages. It is the
responsibility of the caller to preserve this value data (if required)
will re-use the internally allocated buffer in which data is returned,
in a subsequent call to this routine.

Arguments Pointer to variable in which the "messages" size is stored (i.e. the
number of bytes written in the values data buffer). This information
might be useful if the caller of this routine wants to make a local
copy of the returned values data.
Semantics With this routine a DSS-client can check if a field contains a valid value
before inserting it to the dataset.
If a value for a field is not valid the messages parameter will contain a
list of one or more messages explaining why the value is not valid. If the
value is valid the messages will contain a NULL pointer.
The logic that determines if a field value is valid is defined in the
<VALIDATE> property in the field definition for the dataset. This is
done in the dataset definition file (*.dss file). For details on how to use
the <VALIDATE> property please see the DSS Language Manual.
The VALIDATE property is optional. If no VALIDATE property was
defined for a field all values are valid.

Notes • The logic that is evaluated for a specific field and the messages can
be retrieved using the dss_prop_fld() routine using the property
code DSS_FPROP _VALID_CONDITIONS.
• DSS_E_VALID_COND
Related Routines
Errors dss_val_list
dss_prop_fld

4.6.45 Activate change log
Syntax [stat=] dss_act_clog(

TLS_ULONG ds_hnd,
TLS_ULONG clog_id,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to dataset.
• clog_id
The identification for the change log.
Optional • None.
Arguments
Semantics With this routine a DSS-client can activate a change log. When a change
log is activated then all modifications to all datasets are logged in the
change log. The DSS-client can use the change log to detect which
datasets and which records were modified since the activation of the
change log. The DSS-client uses the routine dss_acc_clog() to read the
information from the change log.
Once a change log is activated it cannot be deactivated. When FAST/
TOOLS is started then change log previously activated must be
activated again be the client. DSS can maintain different change logs
which are distinguish by the change log identification. Normally the
brick number of the DSS-client is used for the change log activated by
this DSS-client.
In dss.sup exception can be defined. These exceptions are not logged in
the change log.
Notes • None.
Related Routines
Errors dss_acc_clog

4.6.46 Access change log
Syntax [stat=] dss_acc_clog(

TLS_ULONG ds_hnd,
struct dss_change_log *change_log,
TLS_ULONG flags,
...
DSS_ARG_EOL);
Fixed • umh_c
• ds_hnd
Handle to dataset.
• change_log
The change log record.
• flags
Controls the functionality of the function.
Optional • None.
Arguments
Semantics With this routine a DSS-client can obtain the content of the change log.
purge the change log or close access to the change log. The functionality
is dependent on the content of flags:
• DSS_CHANGE_LOG_ACC_EQUAL
Obtains the record that matches the specified id, time and sequence.
This record is returned in change_log.
• DSS_CHANGE_LOG_ACC_GREAT
Obtains the record which time is greater than the time and sequence
specified. If 0 is specified for the id field then all records of all
change log identifications are taken in account else only records of
the specified change log identification are returned.
• DSS_CHANGE_LOG_ACC_GTEQ
Obtains the record that which time is greater or equal then the time
and sequence specified. If 0 is specified for the id field then all
records of all change log identifications are taken in account else
only records of the specified change log identification are returned.
• DSS_CHANGE_LOG_ACC_NEXT
Returns the next record. If 0 is specified for the id field then all
records of all change log identifications are taken in account else
only records of the specified change log identification are returned.
• DSS_CHANGE_LOG_ACC_PURGE
Purges (deletes) all records from the change log up to and inclusive

the time specified in the change_log argument. If the id in

change_log is specified then only the records matching this change
log identification are purged. If 0 is specified then the records of all
change log identifications are purged. If 0 is specified for the time
then all records of the specified change log identification are
purged. Specifying 0 for id and time purges all records from the
change log.
The DSS_CHANGE_LOG_ACC_PURGE can be bitwise or-ed
with DSS_CHANGE_LOG_ACC_EQUAL,
DSS_CHANGE_LOG_ACC_GREAT,
DSS_CHANGE_LOG_ACC_GTEQ or
DSS_CHANGE_LOG_ACC_NEXT. This means that each record
that is read from the change log is purged automatically.
• DSS_CNANGE_LOG_ACC_CLOSE
Closes access to the change log. Resources maintained by the
dss_acc_clog() function are freed.
Notes • None.
• ISF_E_NOREC
No change log record found.
Related Routines
Errors dss_act_clog

4.6.47 Get encrypted password of a user
Syntax [stat=] dss_get_passw(

TLS_ULONG conn_hnd,
char *user_nm,
char *password,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• user_nm
User name to get password of.
• password
Buffer to receive password.
Optional • None
Arguments
Semantics This function returns the password of a user. The password is returned
in the buffer supplied by the password argument. The called must be
sure that this buffer is large enough to receive the password
(DSS_PASSWD_SZ in dss_user.h). Not the readable password is
returned but the encrypted version.
Notes • None.
• DSS_E_DD_UPD
• DSS_E_UNK_USER
Related Routines
Errors dss_set_passw

4.6.48 Set encrypted password of a user
Syntax [stat=] dss_set_passw(

TLS_ULONG conn_hnd,
char *user_nm,
char *password,
...
DSS_ARG_EOL);
Fixed • umh_c
• conn_hnd
Connection handle.
• user_nm
User name to set password of.
• password
The password.
Optional • None
Arguments
Semantics This function sets the password of a user. The supplied password must
be the encrypted password.
Notes • None.
• DSS_E_DD_UPD
• DSS_E_UNK_USER
Related Routines
Errors dss_get_passw

Introduction Reference data access server
5 Reference data access server
5.1 Introduction
This chapter contains a detailed description of the PML macros that are
used in Data Access Servers (DAS). The macros are defined in the
global header file dss.h of DSS. The macros often reference to struct
members which are also defined in dss.h. It is strongly advised not to use
these structs and their members directly to prevent (upwards)
compatibility problems.
5.2 DSS Macros
5.2.1 Introduction
This paragraph contains a detailed description of all DSS macro. The

macro are described in alphabetical order. For each of the routines the
following items are described:
• The syntax of the macro.
• A description arguments of the macro.
• The semantics of the macro.
• When necessary an example of usage of the macro.

Reference data access server DSS Macros
5.2.2 DSS_ADT_ACTION
Syntax int action = DSS_ADT_ACTION
Arguments • action
Operation performed on the data set:
- DSS_OPER_INSERT Record inserted
- DSS_OPER_UPDATE Record updated
- DSS_OPER_DELETE Record deleted
Semantics Returns the action for the DSS_ADT_REC events.
This macro is used within the DSS_ADT_REC event to determine the
action to be audited. The action for the DSS_ADT_FLD event is always
update.
Example

DSS Macros Reference data access server
5.2.3 DSS_ADT_FLD_NM
Syntax char *field_name = DSS_ADT_FLD_NM
Arguments • field_name
Points to the name of the field.
Semantics Returns the name of the field which value has been changed for the
DSS_ADT_FLD event.
See also DSS_ADT_OLD_VAL and DSS_ADT_NEW_VAL.
Example

5.2.4 DSS_ADT_NEW_VAL
Syntax char *new_value = DSS_ADT_NEW_VAL
Arguments • new_value
The pointer to a string containing the new value
Semantics Returns the value of the field for the DSS_ADT_FLD event after it has
been changed.
See also DSS_ADT_OLD_VAL.
Example

5.2.5 DSS_ADT_OFF
Syntax DSS_ADT_OFF
Arguments None.
Semantics This macro switches audit trail for the data set off. On forehand, PML
does not know whether the DAS supports audit trail for the data set. On
the first insert, update or delete of a record the DSS issues the
DSS_ADT_REC event. Then the DAS can use the DSS_ADT_OFF
macro to let DSS know that it does not support audit trailing. From this
point the PML does not issue DSS_ADT_REC and DSS_ADT_FLD
events to the DAS anymore.
Note that audit trailing is handled default by the default DAS.
See also DSS_ADT_ON.
Example

5.2.6 DSS_ADT_OLD_VAL
Syntax char *old_value = DSS_ADT_OLD_VAL
Arguments • old_value
The pointer to a string containing the old value.
Semantics Returns the value of the field prior the change for the DSS_ADT_FLD
event.
See also DSS_ADT_NEW_VAL.
Example

5.2.7 DSS_ADT_ON
Syntax DSS_ADT_ON
Arguments None.
Semantics This macro switches audit trail for the data set on. The DAS can use this
macro to switch audit trail for the data set on again.
It has to issue this macro before an event other than DSS_ADT_REC or
DSS_ADT_FLD. This because these events are not issued anymore
when audit trail has been switched off using the DSS_ADT_OFF macro.
See also DSS_ADT_OFF.
Example

5.2.8 DSS_CLT_PRC
Syntax struct dur_adr *clt_adr = DSS_CLT_PRC
Arguments clt_adr
The BUS/FAST address of the client.
Semantics This macro returns a pointer to a struct dur_adr that contains the BUS/
FAST address of the client that accesses the data set.
Example

5.2.9 DSS_CONT_CHK
Syntax DSS_CONT_CHK = (TLS_BOOLEAN)continue
Arguments • continue
TRUE to check the node, FALSE to skip the node.
Semantics Signals the PML to check the replica on this node.
This event is used for the PML event DSS_CHK_NODE only. While the
consistency check is running (requested via the DSSCHK utility), the
PML issues the DSS_CHK_NODE event for each record and node
where the data set is replicated. The DAS has to set DSS_CONT_CHK
with TRUE or FALSE to tell the PML to check or ignore the record on
this replica node. It is normally used for data sets whose replication is
depending on the contents of a record.
For proper testing, DSS_DS_NODE_NUMBER returns the replica node
to be checked while DSS_SEL_NODE returns the nodes specified on
the command line of DSSCHK, all (-1) or a specific one.
Example DSS_EVENT(DSS_CHK_NODE)
DSS_NO_DEFAULT;
item_def = (struct item_def *) DSS_REC_RD;
if (item_def->item_ith.distr_type != GIN_ITM_DTYPE_LH &&

item_def->item_ith.fe_node != 0 &&
item_def->item_ith.fe_node !=
DSS_DS_NODE_NUMBER &&
(DSS_DS_NODE_NUMBER != 0 ||
DSS_OWN_NODE_NUMBER) &&
(DSS_SEL_NODE == -1 ||
DSS_SEL_NODE == item_def->item_ith.fe_node))
DSS_CONT_CHK = TRUE;
else
DSS_CONT_CHK = FALSE;

5.2.10 DSS_CURRENT_TIME
Syntax TLS_ULONG time = DSS_CURRENT_TIME
Arguments • time
The GMT time.
Semantics Returns the current time in seconds since 1970 GMT.
The time is established just prior generation of the PML event.
Example DSS_EVENT(DSS_TIMER)
if (time_off_last_event+flow_time_out < DSS_CURRENT_TIME)
{
umh_set_code(DSS_UMH_C, <my_error_code>);
DSS_ERROR_FLOW;
}

5.2.11 DSS_DAS_C
Syntax DSS_DAS_C
Arguments None.
Semantics Specifies the DAS context. Is passed within the DAS to a support routine
as the the first argument.
Example DSS_EVENT(DSS_UPD_REC)
TLS_LONG on_off_old, on_off_new;
DSS_DO_DEFAULT;
on_off_old =
((struct item_nam1_def *)DSS_REC_RD)->on_off;
on_off_new =
((struct item_nam1_def *)DSS_REC_WR)->on_off;
if (on_off_old != on_off_new)
{
if (!upd_blocked(DSS_DAS_C,
((struct item_nam1_def *)DSS_REC_WR)->item_nam1,
on_off_new))
DSS_ERROR;
}

5.2.12 DSS_DAS_C_DECLARATION
Syntax DSS_DAS_C_DECLARATION
Arguments None.
Semantics Declares the support routine context. The support routine context must
always be the first argument of the routine.
Example static TLS_BOOLEAN upd_blocked(DSS_DAS_C, nam1, on_off)
char *nam1;
TLS_LONG on_off;
{
DSS_INIT_SUPPORT;
…
return TRUE;
error_exit:
return FALSE;
}

5.2.13 DSS_DATA_ACCESS_SERVER
Syntax DSS_DATA_ACCESS_SERVER(server_name)
Arguments • server_name
The name of the server as specified in the data dictionary.
Semantics Declares a DAS.
This macro expands to a function declaration which includes the
declaration of data accessible within the DAS. The end of a DAS is
indicated by DSS_END_DATA_ACCESS_SERVER. The file dss.h
must be included prior this macro.
More than one DAS may be coded in one source file.
Example #include <dss.h>
DSS_DATA_ACCESS_SERVER(my_data_set_server)
…

5.2.14 DSS_DO_DEFAULT
Syntax DSS_DO_DEFAULT
Arguments None.
Semantics Executed the default processing for an event immediately.
Handling an event specifically in a DAS does not prevent the PML to
execute the default behavior for the event. This default behavior is
executed after the processing of the event within the DAS. However,
with the macros DSS_DO_DEFAULT this processing is done
immediately. The DSS_DO_DEFAULT macro should always occur
within the handling of a certain event.
Example DSS_EVENT(DSS_OPN_DS)
DSS_DO_DEFAULT; /* Open the data set */
if (!signal_my_process(…))
DSS_ERROR; /* Signal my process
that the data set is open */
DSS_EVENT(DSS_CLS_DS)

5.2.15 DSS_DS_FILE_CHN
Syntax void *channel = DSS_DS_FILE_CHN
or
DSS_DS_FILE_CHN = (void*)channel;
Arguments • channel
A channel to the physical unit.
Semantics Used to store the channel to an open physical unit and returns the
channel to an open physical unit.
This macro is used to store the channel associated with an opened
physical unit during the DSS_OPN_DS and DSS_OPN_REP events.
Later on, with events like DSS_INS_REC, DSS_RD_REC,
DSS_DEL_REP etc. it returns the channel associated with the open
physical unit.
DSS_DS_NODE_NUMBER,
DSS_DS_PATH_NUMBER, DSS_DS_FILE_NM,
ISINPUT
DSS_ERROR;
DSS_EVENT(DSS_INS_REC)
DSS_NO_DEFAULT;
if (!isf_write(DSS_UMH_C, (struct
isf_file_info*)DSS_DS_FILE_CHN,
(char*)DSS_REC_WR))
DSS_ERROR;

5.2.16 DSS_DS_FILE_FMT
Syntax char *file_format = DSS_DS_FILE_FMT
Arguments • file_format
Pointer to the file format of the physical records.
Semantics Returns the file record format string.
The file format string can be used for system conversion when physical
records are transported between systems of different architectures or to
open files using DATABASE/FAST. See also
DSS_DS_NODE_NUMBER.
Example See DSS_DS_NODE_NUMBER.

5.2.17 DSS_DS_FILE_NAME
Syntax char *file_name = DSS_DS_FILE_NAME
Arguments • file_name
Pointer to the name of the physical unit.
Semantics Returns the file name of the physical unit of a data set to be opened.
See DSS_DS_PATH_NUMBER.

5.2.18 DSS_DS_NM
Syntax char *dataset_name = DSS_DS_NM
Arguments • dataset_name
Pointer to the name of the data set.
Semantics Returns the name of the data set.
Example

5.2.19 DSS_DS_NODE_NUMBER
Syntax int node = DSS_DS_NODE_NUMBER
Arguments • node
The node number.
Semantics Returns the node number where the physical unit of a data set has to be
opened.
The node number has to be used during the DSS_OPN_DS,
DSS_OPN_REP, DSS_CLS_DS and DSS_CLS_REP events. The
macro returns the node number where the physical unit of the data set
has to be opened. See also DSS_DS_PATH_NUMBER,
DSS_DS_FILE_NM, DSS_DS_FILE_CHN, DSS_DS_OPERATIONS
and DSS_DS_FILE_FMT. They all are used to open and close physical
units of data sets. The node number is also available for DSS_(U)UPD..,
DSS_(U)INS.., DSS_(U)DEL.. and DSS_RD_REC events.
The node number returns 0 (zero) for physical units located on the own
node. For data sets opened for insertion, update or delete, this zero
means the primary node.
DSS_NO_DEFAULT;
DSS_DS_NODE_NUMBER,
ISINPUT, 0,
(struct keydesc *)NULL, DSS_EVT_REC_PLEN,
DSS_ERROR;

5.2.20 DSS_DS_OPERATIONS
Syntax int operations = DSS_DS_OPERATIONS
Arguments • operations
The open mode. The following bit or bits can be set:
- DSS_OPER_READ Open for read.
- DSS_OPER_INSERT Open for insert.
- DSS_OPER_UPDATE Open for update.
- DSS_OPER_DELETE Open for delete.
Semantics Returns the way a physical unit has to be opened.
int opn_mode;
DSS_NO_DEFAULT;
if (DSS_DS_OPERATIONS & DSS_OPER_READ)
{
if (DSS_DS_OPERATIONS &
(DSS_OPER_INSERT | DSS_OPER_UPDATE |
DSS_OPER_DELETE))
opn_mode = ISINOUT;
else
opn_mode = ISINPUT;
}
else
opn_mode = ISOUTPUT;
DSS_DS_NODE_NUMBER,
opn_mode, 0,
DSS_ERROR;

5.2.21 DSS_DS_PATH_NUMBER
Syntax int path_number = DSS_DS_PATH_NUMBER
Arguments • path_number
The FAST/TOOLS path (directory) number.
Semantics Returns the FAST/TOOLS directory path number where the physical
unit of a data set must be opened.
The path number can be converted to a directory string using the FAST/
TOOLS routine fmf_cnv_dir(). By appending the DSS_DS_FILE_NM
to the directory string the complete path of the physical unit is obtained.
See also DSS_DS_NODE_NUMBER.

5.2.22 DSS_DS_TERM_NM
Syntax char *terminal_name = DSS_DS_TERM_NM
Arguments • terminal_name
The name of the terminal where the user is working.
Semantics Returns the name of the terminal the user is working on.
The maximal length of the terminal name is defined by
DSS_TERM_NM_SZ.
Example

5.2.23 DSS_DS_USER_NM
Syntax char *user_name = DSS_DS_USER_NM
Arguments • user_name
The name of the user that is accessing the data set.
Semantics Returns the name of the user working on the data set.
The maximum length of the user name is defined by
DSS_USER_NM_SZ.
Example

5.2.24 DSS_DUR_C
Syntax struct dur_context *dur_c = DSS_DUR_C
Arguments • dur_c
The BUS/FAST DUR context.
Semantics Returns the DUR context to be used for calling FAST/TOOLS
functions. The DUR context is always initialised and ready to use.
Example DSS_EVENT(DSS_INS_REC)
dur_snd(DSS_DUR_C, …);

5.2.25 DSS_END_DATA_ACCESS_SERVER
Syntax DSS_END_DATA_ACCESS_SERVER
Arguments None.
Semantics Ends a DAS.
This macro expands to the exit and error handling part of the DAS.
DSS_DATA_ACCESS_SERVER(my_data_set)
…

5.2.26 DSS_END_EVENTS
Syntax DSS_END_EVENTS
Arguments None.
Semantics Ends the event handling section of the DAS.
This macro ends the event handling section within the DAS. The event
section is started with the DSS_EVENTS macro.
int field_nr; /* Private declaration */
DSS_SET_TYPE(DSS_ISF_TYPE);
DSS_EVENTS
…
DSS_END_EVENTS

5.2.27 DSS_ERROR
Syntax DSS_ERROR
Arguments None.
Semantics Signals an error and exits the DAS.
If during processing of an event an error is detected, the error can be
signalled by the DSS_ERROR macro. The event handing is then
aborted. The error code must be set by a call to umh_set_code().
if (!do_something(DSS_UMH_C, …))
{
umh_add_code(DSS_UMH_C, <my_error_numer>);
DSS_ERROR;
}

5.2.28 DSS_ERROR_EVT
Syntax DSS_ERROR_EVT
Arguments None.
Semantics Signals an event sequence error and exits the DAS.
When subscriptions on a physical unit are active and the data set specific
DAS has event flow control enabled with the physical unit, an event
count error must be signalled by the DSS_ERROR_EVT macro. The
event handing is then aborted. An error code must be set by a call to
umh_set_code().
Example DSS_EVENT(DSS_PRO_EVT)
if (event_seq != expected_event_seq)
{
DSS_ERROR_EVT;
}

5.2.29 DSS_ERROR_FLOW
Syntax DSS_ERROR_FLOW
Arguments None.
Semantics Signals an event flow time-out error and exits the DAS.
When subscriptions on a physical unit are active and the data set specific
DAS has flow control enabled with the physical unit, an event flow time-
out error must be signalled by the DSS_ERROR_FLOW macro. The
event handing is then aborted. An error code must be set by a call to
umh_set_code().
Example DSS_EVENT(DSS_TIMER)
if (time_off_last_event+flow_time_out < DSS_CURRENT_TIME)
{
DSS_ERROR_FLOW;
}

5.2.30 DSS_ERROR_LIC
Syntax DSS_ERROR_LIC
Arguments None.
Semantics Signals a licence error and exits the DAS.
This macro is used by the DAS to signal that the data set is not available
because it is not installed or licensed. Testing for a licence must be done
on the DSS_OPN_DS and DSS_OPN_EVT events. An error code must
be set by a call to umh_set_code().
if (!fmf_brick(DSS_UMH_C, TLS_BRK_ALM) ||
!alm_lic_chk(DSS_UMH_C))
DSS_ERROR_LIC;

5.2.31 DSS_EVENT
Syntax DSS_EVENT(int event)
Arguments • event
One of the DAS events.
Semantics Starts the handling of a certain event within the event handling section
of a DAS.
This macro starts the section handling of a particular event. The section
is ended with a next DSS_EVENT macro or the DSS_END_EVENTS
macro. Handling an event specifically in a DAS does not prevent the
PML to execute the default behavior for the event. This default behavior
is executed after the processing of the event within the DAS. However,
with the macros DSS_DO_DEFAULT and DSS_NO_DEFAULT this
behavior can be influenced. Directly after the DSS_EVENT macro,
private declarations can be put.
Example DSS_EVENTS
DSS_EVENT(DSS_OPN_DS)
int blocked;
…
…
DSS_END_EVENTS

5.2.32 DSS_EVENTS
Syntax DSS_EVENTS
Arguments None.
Semantics Starts the event handling section of the DAS.
This macro starts the event handling section within the DAS. The event
section is ended by the DSS_END_EVENTS macro. More than one
DSS_EVENTS/DSS_END_EVENTS pare in sequence may occur in the
same DAS. Effectively it is handled as one event section.
DSS_EVENTS
…
DSS_END_EVENTS

5.2.33 DSS_EVT_CRIT
Syntax int event_crit = DSS_EVT_CRIT
or
DSS_EVT_CRIT = (int)event_crit
Arguments • event_crit
Event criteria, one or more bits of:
A record inserted.
A record updated.
A record deleted.
A specific record updated.
A specific record deleted.
Semantics The macro returns the event criteria in case of the DSS_SET_EVT event
or sets the criteria in case of the DSS_PRO_EVT event.
On the DSS_SET_EVT event the macro DSS_EVT_CRIT returns the
event criteria for the events requested. It is used in combination with the
DSS_REC_RD macro to determine whether event for a specific record
or global events are requested. When DSS_REC_RD does not return a
NULL pointer then it points to the physical record for which events are
requested. If, in this case, neither DSS_EVT_CRIT_DS_REC_UPD nor
DSS_EVT_CRIT_DS_REC_DEL are set, then events for the specific
record should be cancelled. When one of these bits is set then the DAS
should request event for one of them or both.
On the DSS_PRO_EVT, the DAS decides after examination of the
event, what criteria were met. On result of that the DAS sets one or more
of the DSS_EVT_CRIT_... bits in DSS_EVT_CRIT. In addition the
DAS fills the DSS_REC_RD buffer with the physical record inserted,
updated or deleted. When the DAS wants to tell the PML to ignore the
event, it sets DSS_EVT_CRIT to zero.
Example if (evt->evt_cri & ISF_CRI_WRITE)
DSS_EVT_CRIT |= DSS_EVT_CRIT_DS_INS;
if (evt->evt_cri & ISF_CRI_REWRITE)
DSS_EVT_CRIT |= DSS_EVT_CRIT_DS_UPD |
DSS_EVT_CRIT_DS_REC_UPD |

DSS_EVT_CRIT_DS_REC_FLD_UPD;
if (evt->evt_cri & ISF_CRI_DELETE)
DSS_EVT_CRIT |= DSS_EVT_CRIT_DS_DEL |
DSS_EVT_CRIT_DS_REC_DEL;

5.2.34 DSS_EVT_MSG_ID
Syntax int event_message_id = DSS_EVT_MSG_ID(

int index)
Arguments • event_message_id
The message id for events send by the physical unit.
• index
Index of one of the available message ids (0-19).
Semantics This routine returns a message id that can be used for events from
physical units.
To determine the data set for which an event was sent by the physical
unit, PML needs knowledge about the ids used to sent the events. For
each data set opened for events (DSS_EVT_OPN event) up to 20
message ids are available (index 0 to 19).
Example DSS_EVENT(DSS_OPN_EVT)
int opn_mode = ISINPUT;
DSS_NO_DEFAULT;
isf_opn_evt(DSS_DUR_C, DSS_UMH_C,
DSS_DS_NODE_NUMBER,
DSS_DS_PATH_NUMBER,
DSS_DS_FILE_NM, opn_mode,
DSS_EVT_MSG_ID(0),
DSS_REC_LEN, DSS_DS_FILE_FMT)) ==
NULL)
DSS_ERROR;

5.2.35 DSS_EVT_REC
Syntax char *record_event_buffer = DSS_EVT_REC
Arguments • record_event_buffer
Pointer to the physical event buffer.
Semantics Returns the pointer to the physical event buffer.
The physical event buffer contains the contents of the event received
from the physical unit. The PML does not interpret the event because it
has no knowledge about its content. It is the responsibility of the DAS
to convert the contents of DSS_EVT_REC to a physical record to be put
into DSS_REC_RD on the DSS_PRO_EVT event from the PML. When
the event was coming from a physical unit located on an other system, it
is also the responsibility of the DAS to perform system conversion on
the DSS_EVT_REC buffer before using its contents.
struct itm_event_gen *event_gen;
struct item_val_p *df_p;
event_gen = (struct itm_event_gen*)DSS_EVT_REC;
df_p = (struct item_val_p *)DSS_REC_RD;
if (!rd_rec(DSS_DAS_C, df_p, DSS_RD_EQUAL,

&event_gen->itm_id))
DSS_ERROR;

5.2.36 DSS_EVT_REF
Syntax TLS_ULONG event_ref = DSS_EVT_REF
or
DSS_EVT_REF = (TLS_ULONG)event_ref
Arguments • event_ref
Event reference.
Semantics This macro gets the subscription reference or sets the subscription
reference.
On the DSS_SET_EVT event the macro DSS_EVT_REF returns the
event reference for the events requested. As soon as the DAS processes
an event from the physical unit that is a result of requesting this event
then the DAS has to store the event reference into DSS_EVT_REF.
struct rpt_evt *evt;
struct report_df_p *df_p;
df_p = (struct report_df_p *)DSS_REC_RD;

evt = (struct rpt_evt *)DSS_EVT_REC;
strcpy(df_p->name, evt->name);
DSS_EVT_REF = evt->ref_id;
DSS_FLD_MARK(0, DSS_REC_LEN - 1);

5.2.37 DSS_EVT_TIME
Syntax DSS_EVT_TIME = (TLS_ULONG)event_time
Arguments • event_time
Event time.
Semantics This macro is used to set the time of an event.
On the DSS_PRO_EVT event this macro is used to set the time the event
from the physical unit occurred.
Example

5.2.38 DSS_FLD_CUR_GET
Syntax DSS_FLD_CUR_GET(int rep,

char *val)
Arguments • rep
The representation of val.
• val
A buffer to receive the value of the field.
Semantics This macro returns the value of the logical field for which the
DSS_CNV_LOG events is generated.
The correct buffer should be applied and the representation is one of the
DSS_DTYPE_... values.
Example DSS_EVENT(DSS_CNV_LOG)
struct opc_trg_def *trg_def;
trg_def = (struct opc_trg_def *)DSS_REC_WR;
if (stricmp(DSS_FLD_CUR_NM, "TRIGGER_INTERVAL") ==
0)
{
TLS_DOUBLE trg_int;
TLS_BOOLEAN trg_once = FALSE;
if (!DSS_FLD_CUR_GET(DSS_DTYPE_DOUBLE,
(char*)&trg_int))
DSS_ERROR;
if (!dsig_opc_ct(DSS_UMH_C, &trg_int, &trg_def->interval,
&trg_once, TRUE))
DSS_ERROR;
}

5.2.39 DSS_FLD_CUR_NM
Syntax char *field_name = DSS_FLD_CUR_NM
Arguments • field_name
The name of the field as specified in the data dictionary.
Semantics This macro returns the name of the field for which the DSS_CNV_PHY
and DSS_CNV_LOG events are generated.
Example DSS_EVENT(DSS_CNV_LOG)
trg_def = (struct opc_trg_def *)DSS_REC_WR;
0)
{
TLS_DOUBLE trg_int;
TLS_BOOLEAN trg_once = FALSE;
if (!DSS_FLD_CUR_GET(DSS_DTYPE_DOUBLE,
(char*)&trg_int))
DSS_ERROR;
&trg_once, TRUE))
DSS_ERROR;
}

5.2.40 DSS_FLD_CUR_SET
Syntax DSS_FLD_CUR_SET(int rep,

char *val)
Arguments • rep
The representation of val.
• val
A buffer containing the value for the field.
Semantics This macro sets the value of the logical field for which the
DSS_CNV_PHY events is generated.
The correct buffer should be applied and the representation is one of the
DSS_DTYPE_... values.
Example DSS_EVENT(DSS_CNV_PHY)
trg_def = (struct opc_trg_def *)DSS_REC_RD;
0 &&
trg_def->interval.ftm_sec != OPC_TRG_01)
{
TLS_DOUBLE trg_int;
TLS_BOOLEAN trg_once;

&trg_once, FALSE))
DSS_ERROR;
if (!DSS_FLD_CUR_SET(DSS_DTYPE_DOUBLE,
(char*)&trg_int))
DSS_ERROR;
}

5.2.41 DSS_FLD_FTC
Syntax TLS_BOOLEAN changed = DSS_FLD_FTC(int start_range,

int end_range)
Arguments • changed
TRUE when something is changed.
• start_range
The start of the range (starting from 0) in the physical record buffer.
• end_range
The end of the range.
Semantics This macro is used to test whether something is changed in the physical
record during the DSS_UPD_REC event. A range in the physical record
has to be specified. The result can be used to optimize update of the
record because it detects the fields that have been changed.
At least one byte of a field in the physical record must be referred to, to
include the field in the check.
Example struct item_val_p *df_p = (struct item_val_p*)DSS_REC_WR;
if (DSS_FLD_FTC((char*)&df_p->quality - (char*)df_p,
(char*)&df_p->quality - (char*)df_p))
{
... /* Quality code changed, update it at ITM */
}
In the example above, at least on byte of the field is referred to. So the
entire field is included in the check.

5.2.42 DSS_FLD_FTR
Syntax TLS_BOOLEAN required = DSS_FLD_FTR(int start_range,

int end_range)
Arguments • required
TRUE when something is required.
• start_range
• end_range
Semantics This macro is used to test whether something has to be supplied in the
physical record during the DSS_RD_REC event. A range in the physical
record has to be specified.The result can be used to optimize read of the
record because it can be detected what fields have to be filled.
This macro only returns whether a DSS client is interested in the field.
However, PML also performs internal reads (for recovery purposes) and
in this case PML may require all fields. Therefor always check the
DSS_RD_TYPE in combination with the DSS_FLD_FTR macro. The
DSS_FLD_FTR should be only used when DSS_RD_TYPE returns
DSS_RD_RD.
At least one byte of a field in the physical record must be specified in the
range to include the field in the check.
Example struct object_df_p *df_p = (struct object_df_p *)DSS_REC_RD;
if (DSS_RD_TYPE != DSS_RD_RD ||
DSS_FLD_FTR((int)((char*)&df_p->class - (char*)df_p),
(int)((char*)&df_p->class - (char*)df_p)))
{
opc_cls_get(dsi_opc_c, &cls_def);
strcpy(df_p->class, cls_def.name);
}

5.2.43 DSS_FLD_FTS
Syntax TLS_BOOLEAN supplied = DSS_FLD_FTS(int start_range,

int end_range)
Arguments • supplied
TRUE when something is supplied.
• start_range
• end_range
Semantics This macro is used to test whether something is supplied in the physical
record during the DSS_UPD_REC event. A range in the physical record
has to be specified. The result can be used to optimize update of the
record because it detects the fields that have been supplied.
Example

5.2.44 DSS_FLD_GET_FILE
Syntax TLS_BOOLEAN status = DSS_FLD_GET_FILE(char *dst,

char *src,
int seq)
Arguments • status
TRUE when successful. Any error is returned in DSS_UMH_C.
• dst
The pointer to the buffer to receive the file name of the transferred
file on the own node.
• src
The pointer to the memo or unknown field in the physical record
that contains the file name.
Semantics This macro retrieves the name and contents of a file stored in the
physical record which corresponds with a memo or unknown field in the
logical record. When the physical file resides on an other node it is
transferred to the own node. This macro is used with the DSS_INS_REC
and DSS_UPD_REC to obtain the contents of the memo or unknown
fields.
Its function can been seen as a strcpy(), however the contents of the file
is transferred to the own node when the file (DSS client) resides on an
other node.
Example struct class_df_p *df_p;
struct opc_cls_def cls_def;
df_p = (struct class_df_p *)DSS_REC_WR;
memset((char *)&cls_def, 0, sizeof(struct opc_cls_def));

strcpy(cls_def.name, df_p->name);
cls_def.file[0] = '\0';
if (!DSS_FLD_GET_FILE(cls_def.file, df_p->method, __LINE__))
DSS_ERROR;
if (!opc_cls_ins(dsi_opc_c, &cls_def))
{
if (umh_error(DSS_UMH_C) == OPC_E_CLS_EXIST)
umh_add_code(DSS_UMH_C, DSS_E_RECTHERE);
DSS_ERROR;
}

5.2.45 DSS_FLD_MARK
Syntax DSS_FLD_MARK(int start_range,

int end_range)
Arguments • start_range
• end_range
Semantics This macro is used to set the fields that have been changed in the
physical record for the DSS_PRO_EVT event. A range in the physical
record has to be specified.
Example old_rec = (char*)&old_df_p;
new_rec = (char*)&old_df_p;
for (end = 0, start = -1; end < DSS_REC_LEN;
end++, old_rec++,new_rec++)
{
if (*old_rec == *new_rec)
{
if (start > 0)
{
DSS_FLD_MARK(start, end-1);
start = -1;
}
}
else
if (start < 0) start = end;
}
if (start >= 0) DSS_FLD_MARK(start, end-1);

5.2.46 DSS_FLD_NR
Syntax int field_id = DSS_FLD_NR(char *field_name)
Arguments • field_id
The numerical id associated with the field. When a number less
than zero is returned, the field name is unknown and the error is
returned in DSS_UMH_C.
• field_name
The name of the field as specified within the data dictionary.
Semantics This macro returns the numerical id of a field name.
Some other macro’s require a field id. This macro is used to obtain the
id.
Example

5.2.47 DSS_FLD_PUT_FILE
Syntax TLS_BOOLEAN status = DSS_FLD_PUT_FILE(char *dst,

char *src,
int id,
int seq)
• dst
The pointer to the field in the physical record, that is related to the
memo or unknown field in the logical record, to receive the file
name.
• src
The pointer to the buffer which holds the file name.
• id
The id for the file.
• seq
The sequence for the file.
Semantics This macro puts the name of a file in a field of a physical record that
corresponds with a memo or unknown field on a DSS_RD_REC event.
For memo and unknown fields, both the logical and physical field
contains the name of the file where the real contents for the field can be
found. On a read (DSS_RD_REC event) the DAS has to store the name
of the file containing the contents in the memo or unknown field of the
physical record. This macro operates in one of two ways:
If the name of the file is already known then the macro is used as
follows:
struct my_rec *rec = (struct my_rec*)DSS_REC_RD;
char *the_file;
...
the_file = his_fname(..., the_file);
if (!DSS_FLD_PUT_FILE(my_rec->memo, the_file, 0, 0))
DSS_ERROR;
An example of this situation is REPORT/FAST where the generated
report is already stored in a file that we can use.
In the second way, the data to put in the memo or unknown field is not
yet available as a file. In this case the DSS_FLD_PUT_FILE is used to
create a temporary file in which the contents can be put:

struct my_rec *rec = (struct my_rec*)DSS_REC_RD;
FILE *fp;
char *the_file;
...
the_file[0] = ’\0’;
if (!DSS_FLD_PUT_FILE(my_rec->memo, the_file, id,
__LINE__))
DSS_ERROR;
fp = fopen(the_file, "w");
fprintf(fp, "The contents");
fclose(fp);
In this case the id and seq arguments are used to create an unique file
name. Id must be filled for each record with an unique number. Mostly
such a number is available in the physical record. When the data set
contains more than one memo or unknown field, then the seq argument
must be set to an unique value for the each memo or unknown field. This
can be simple released by the __LINE__ directive.
Example

5.2.48 DSS_FLW_ENABLED
Syntax TLS_BOOLEAN flow_enabled = DSS_FLW_ENABLED
or
DSS_FLW_ENABLED = (TLS_BOOLEAN)flow_enabled;
Arguments • flow_enabled
Whether the flow is enabled.
Semantics Used to store whether or not flow control between a DAS and a physical
unit has been enabled.
This macro is used to let the PML know that flow control between the
DAS and the physical unit has been enabled or to check whether the flow
is enabled.
Example

5.2.49 DSS_FLW_MSG_ID
Syntax int flow_message_id = DSS_FLW_MSG_ID(int index)
Arguments • flow_message_id
The message id for flow messages send by the physical unit.
• index
Index of one of the available message ids (0-19).
Semantics This routine returns a message id that can be used for flow messages
from physical units.
To determine the data set for which a flow message was sent by the
physical unit, PML needs knowledge about the ids used to sent the flow
messages. For each DAS having flow control with a physical unit up to
20 message ids are available (index 0 to 19).
Example if (!opc_flw_evt(dsi_opc_c, OPC_FLOW_CONTROL,
DSS_FLW_MSG_ID(0), 60))
DSS_ERROR;

5.2.50 DSS_FLW_TIMEOUT
Syntax TLS_ULONG flow_timeout = DSS_FLW_TIMEOUT
or
DSS_FLW_TIMEOUT = (TLS_ULONG)flow_timeout;
Arguments • flow_timeout
The time (GMT) that the next event or flow message from the
physical unit must have been received.
Semantics Used to store and retrieve the time of the next flow time-out.
This macro is used for flow control timing. It is set with the time that the
next event or flow message from the physical unit must have been
received. When not received in time, the DAS must signal a
DSS_ERROR_FLW error.
Example

5.2.51 DSS_IDX_FLD
Syntax int field_id = DSS_IDX_FLD(int index)
The numerical id of one of the fields composing the index.
• index
The index of the field, ranging from 0 to DSS_IDX_FLDS.
Semantics Returns a member of the index to be used with the DSS_SET_IDX
event.
Example

5.2.52 DSS_IDX_FLDS
Syntax int index_fields = DSS_IDX_FLDS
Arguments • index_fields
Number of logical fields making up the index.
Semantics Returns the number of fields composing the index in case of the
DSS_SET_IDX event.
Example

5.2.53 DSS_IDX_ISF
Syntax struct keydesc *keydesc = DSS_IDX_ISF
Arguments • keydesc
The index by its description.
Semantics Returns the index to be set during the DSS_SET_IDX event. The index
is returned in a format as defined by ISF.
Example DSS_EVENT(DSS_SET_IDX)
DSS_NO_DEFAULT;
if (!isf_start(DSS_UMH_C,
DSS_IDX_ISF, 0, (char*)DSS_REC_RD,
ISFIRST) &&
umh_error(DSS_UMH_C) != ISF_E_NOREC)
DSS_ERROR;

5.2.54 DSS_IDX_NAME
Syntax char *index_name = DSS_IDX_NAME
Arguments • index_name
Name of the index to be set.
Semantics Returns the name of the index to be set in case of the DSS_SET_IDX
event.
The name returned is one of the indexes defined in the data dictionary of
the data set.
Example

5.2.55 DSS_INIT_SUPPORT
Syntax DSS_INIT_SUPPORT
Arguments None.
Semantics Initializes a DAS support routine. A DAS support routine, is a routine
called within the DAS and where all DAS macros remain available.
Example static TLS_BOOLEAN upd_blocked(DSS_DAS_C, nam1, on_off)
char *nam1;
TLS_LONG on_off;
{
DSS_INIT_SUPPORT;
…
return TRUE;
error_exit:
return FALSE;
}

5.2.56 DSS_ITM_C
Syntax struct itm_context *itm_c = DSS_ITM_C
Arguments • itm_c
The ITEM/FAST ITM context.
Semantics Returns the ITM context to be used for calling ITEM/FAST functions.
The first DAS that accesses DSS_ITM_C performs the actual attach to
ITEM/FAST.
Example DSS_EVENT(DSS_SET_EVT)
itm_req_evt(DSS_ITM_C, …);

5.2.57 DSS_NO_DEFAULT
Syntax DSS_NO_DEFAULT
Arguments None.
Semantics Prohibits the default processing for an event.
Handling an event specifically in a DAS does not prevent the PML to
execute the default behavior for the event. This default behavior is
executed after the processing of the event within the DAS. However,
with the macros DSS_NO_DEFAULT this processing is inhibited. The
DSS_NO_DEFAULT macro should always occur within the handling
of a certain event.
DSS_NO_DEFAULT; /* No default */
if (!open_unit(…))
DSS_ERROR; /* Let my routine do the work */

5.2.58 DSS_O_DS_CLS
Syntax TLS_BOOLEAN status = DSS_O_DS_CLS(DSS_DS_CHN ds_chn)
• ds_chn
The channel that identifies the data set to close.
Semantics This is a routine of the O collection. It closes a data set.
Example DSS_O_DS_CLS(ds_chn);

5.2.59 DSS_O_DS_DEL
Syntax TLS_BOOLEAN status = DSS_O_DS_DEL(DSS_DS_CHN ds_chn)
• ds_chn
The channel that identifies the opened data set.
Semantics This is a routine of the O collection. It deletes a record from the data set.
The record to be deleted can be set-up directly in the data set's write
buffer (DSS_O_REC_WR) or the macro DSS_O_FLD_SET can be
used.
Example

5.2.60 DSS_O_DS_INS
Syntax TLS_BOOLEAN status = DSS_O_DS_INS(DSS_DS_CHN ds_chn)
• ds_chn
Semantics This is a routine of the O collection. It inserts a record in the data set.
The record to be written can be set-up directly in the data set's write
buffer (DSS_O_REC_WR). Or the macro DSS_O_FLD_SET can be
used.
Example

5.2.61 DSS_O_DS_OPN
Syntax DSS_DS_CHN ds_chn = DSS_O_DS_OPN(char *ds_nm, int mode)
Arguments • ds_chn
The channel that identifies the opened data set. When NULL is
returned, the open has failed. The error is stored in DSS_UMH_C.
• ds_name
The name of the data set to open.
• mode
The open mode. One or more of:
- DSS_OPER_READ Open for read.
- DSS_OPER_INSERT Open for insert.
- DSS_OPER_UPDATE Open for update.
- DSS_OPER_DELETE Open for delete.
Semantics This is a routine of the O collection. It opens a data set.
Example DSS_DS_CHN ds_chn;
if ((ds_chn =
DSS_O_DS_OPN("ITEM_DF",
DSS_OPER_READ | DSS_OPER_UPDATE))
== NULL)
DSS_ERROR;

5.2.62 DSS_O_DS_RD
Syntax TLS_BOOLEAN status = DSS_O_DS_RD(DSS_DS_CHN ds_chn, int

mode)
• ds_chn
• mode
The read mode. One of:
- DSS_RD_EQUAL Read a record equal to.
- DSS_RD_NEXT Read next record.
- DSS_RD_FIRST Read the first record.
- DSS_RD_GTEQ Read greater or equal to.
- DSS_RD_GREAT Read record greater than.
Semantics This is a routine of the O collection. It reads a record from the data set.
The index to read on, can be set by DSS_O_FLD_IDX or
DSS_O_IDX_SET. The information is read into the data set's read
buffer (DSS_O_REC_RD). For the read modes DSS_RD_EQUAL,
DSS_RD_GTEQ and the value for the index must be set in the data set's
read buffer. This can be done by directly accessing the read buffer or by
the macro DSS_O_FLD_SET. Alter the read, the data can be directly
accessed in the read buffer or via the DSS_O_FLD_GET macro.
Example item_def = (struct item_def *)DSS_O_REC_RD(ds_chn);
strcpy(item_def->item_gen.item_name.name1, "my_install");
while (DSS_O_DS_RD(ds_chn, DSS_RD_GREAT))

{
…

5.2.63 DSS_O_DS_UPD
Syntax TLS_BOOLEAN status = DSS_O_DS_UPD(DSS_DS_CHN ds_chn)
• ds_chn
Semantics This is a routine of the O collection. It updates a record in the data set.
The record to be updated can be set-up directly in the data set's write
buffer (DSS_O_REC_WR) or the macro DSS_O_FLD_SET can be
used.
Example int mode = DSS_RD_FIRST;
while (DSS_O_DS_RD(ds_chn, mode))
{
memcpy(DSS_O_REC_WR(ds_chn), DSS_O_REC_RD(ds_chn),
DSS_O_REC_LEN(ds_chn));
((struct my_struct*)DSS_O_REC_WR(ds_chn))->count++;
if (!DSS_O_DS_UPD(ds_chn))
DSS_ERROR;
mode = DSS_RD_NEXT;
}

5.2.64 DSS_O_FLD_GET
Syntax TLS_BOOLEAN status = DSS_O_FLD_GET(DSS_DS_CHN ds_chn,

int field_id,
int dtype,
char *val)
• ds_chn
• field_id
The number of the field (can be obtained with DSS_O_FLD_NR).
• dtype
The data type (representation) wanted. One of DSS_DTYPE_*.
• val
A pointer to the buffer where the value will be stored. The buffer
must be large enough to store the value.
Semantics This is a routine of the O collection. It gets the logical or physical value
of a field in the data set.
Depending on data type wanted and the data type of the field, the field's
logical value or physical value is returned. The physical value is returned
when there is a translation or relation defined for the field and the
wanted data type is a numeric data type. In all other cases the logical
value is returned. The data is fetched from the read buffer.
Example TLS_BOOLEAN blocked;
if (!DSS_O_DS_RD(ds_chn, DSS_RD_FIRST) ||
!DSS_O_FLD_GET(ds_chn, 3, DSS_DTYPE_BOOLEAN,
&blocked))
DSS_ERROR;

5.2.65 DSS_O_FLD_IDX
Syntax TLS_BOOLEAN status = DSS_O_FLD_IDX(DSS_DS_CHN ds_chn,

int field_id)
• ds_chn
• field_id
An error is returned when the field can not be used as an index.
Semantics This is a routine of the O collection. It sets the field to be used as an
index for the following read actions.
Example if (!DSS_O_FLD_IDX(ds_chn, 3) ||
!DSS_O_DS_RD(ds_chn, DSS_RD_FIRST))
DSS_ERROR;

5.2.66 DSS_O_FLD_NR
Syntax int field_id = DSS_O_FLD_NR(DSS_DS_CHN ds_chn,

char *field_name)
The number associated within the field. When a number less than
zero is returned the field name is unknown and the error is returned
in DSS_UMH_C.
• ds_chn
• field_name
The name of the field as specified within the data dictionary.
Semantics This is a routine of the O collection. It reads the field number of a field.
Example if (!DSS_O_FLD_IDX(ds_chn,
DSS_O_FLD_NR(ds_chn, "INSTALL") ||
DSS_ERROR;

5.2.67 DSS_O_FLD_REP
Syntax int dtype = DSS_O_FLD_REP(DSS_DS_CHN ds_chn,

int field_id)
Arguments • dtype
The logical data type of the field
• ds_chn
• field_id
Semantics This is a routine of the O collection. It returns the data type of the logical
field.
Example

5.2.68 DSS_O_FLD_SET
Syntax TLS_BOOLEAN status = DSS_O_FLD_SET(DSS_DS_CHN ds_chn,

int field_id,
int dtype,
char *val)
• ds_chn
• field_id
• dtype
The data type (representation) wanted. One of DSS_DTYPE_*.
• val
A pointer to the buffer with the value.
Semantics This is a routine of the O collection. It set the logical or physical value
of a field in the data set.
Depending on the data type wanted and the data type of the field, the
field's logical value or physical value is set. The physical value is set if
there is a translation or relation defined for the field and the specified
data type is a numeric data type. In all other cases the logical value is set.
Logical values are automatically translated to physically values and
stored in the write buffer.
Example

5.2.69 DSS_O_IDX_SET
Syntax TLS_BOOLEAN status = DSS_O_IDX_SET(DSS_DS_CHN ds_chn,

char *index_name)
• ds_chn
• index_name
The name of the index to set (as specified in the data dictionary).
Semantics This is a routine of the O collection. It sets the index to be used for the
following read actions.
Example if (!DSS_O_IDX_SET(ds_chn, "INSTALL") ||
DSS_ERROR;

5.2.70 DSS_O_REC_LEN
Syntax int record_length = DSS_0_REC_LEN(DSS_DS_CHN ds_chn)
Arguments • record_length
The length of the physical record.
• ds_chn
Semantics This is a routine of the O collection. It returns the length of the physical
record and the physical read and write buffers.
See DSS_REC_LEN.
Example

5.2.71 DSS_O_REC_NM
Syntax char *record_name = DSS_O_REC_NM(DSS_DS_CHN ds_chn)
Arguments • record_name
The pointer to the name of the current record.
• ds_chn
Semantics Returns the name of the last record read, inserted, updated or deleted.
The name of the record is the contents of the logical NAME field in the
data set.
Example

5.2.72 DSS_O_REC_RD
Syntax char *record_read_buffer = DSS_O_REC_RD(

DSS_DS_CHN ds_chn)
Arguments • record_read_buffer
Pointer the read buffer.
• ds_chn
Semantics This is a routine of the O collection. It returns the pointer to the physical
read buffer.
See DSS_REC_RD.
Example

5.2.73 DSS_O_REC_WR
Syntax char *record_write_buffer = DSS_O_REC_WR(

DSS_DS_CHN ds_chn)
Arguments • record_write_buffer
Pointer the write buffer.
• ds_chn
write buffer.
See DSS_REC_WR.
Example

5.2.74 DSS_O_REC_WR
Syntax char *record_write_buffer = DSS_O_REC_WR(

DSS_DS_CHN ds_chn)
Pointer the write buffer.
• ds_chn
write buffer.
See DSS_REC_WR.
Example

5.2.75 DSS_ON_EES
Syntax int on_ees = DSS_ON_EES
Arguments • on_ees
A non-zero value when running on the Enterprise Engineering
Server.
Semantics Supplies whether the DAS is running on the Enterprise Engineering
Server.
See DSS_ON_ENS and DSS_ON_ES.
Example

5.2.76 DSS_ON_ENS
Syntax int on_ens = DSS_ON_ENS
Arguments • on_ens
A non-zero value when running on an Enterprise Namespace
Server.
Semantics Supplies whether the DAS is running on an Enterprise Namspace
Server.
See DSS_ON_EES and DSS_ON_ES.
Example

5.2.77 DSS_ON_ES
Syntax int on_ees = DSS_ON_ES
Arguments • on_es
A non-zero value when running on an Enterprise Server.
Semantics Supplies whether the DAS is running on an Enterprise Server.
See DSS_ON_EES and DSS_ON_ENS.
Example

5.2.78 DSS_RD_MODE
Syntax int read_mode = DSS_RD_MODE
Arguments • read_mode
The read mode for the record, one of:
- DSS_RD_EQUAL Read a record equal to.
- DSS_RD_NEXT Read next record.
- DSS_RD_FIRST Read the first record.
- DSS_RD_GTEQ Read greater or equal to.
- DSS_RD_GREAT Read record greater than.
Semantics Returns the mode for the DSS_RD_REC event.
This macro is used within the DSS_RD_REC event to determine how
the record is to be read. In case of DSS_RD_EQUAL, DSS_RD_GTEQ
or DSS_RD_GREAT, the DSS_REC_RD buffer contains the value of
the index to be used with the read operation.
Example

5.2.79 DSS_RD_TYPE
Syntax int read_type = DSS_RD_TYPE
Arguments • read_mode
The read mode for the record, one of:
- DSS_RD_DAS
The record was read by the DSS_O_DS_RD function.
- DSS_RD_DEL
The record was read prior to the delete to recover from the
delete.
- DSS_RD_REF
The record was read by the delete function to verify that the
record to delete is used by a referencing data set.
- DSS_RD_REL
The record was read to obtain a relation between data sets.
- DSS_RD_RD
The record was read for the DSS client.
- DSS_RD_UPD
The record was read prior to an update to be able to recover
from an update failure.
Semantics Returns the type for the DSS_RD_REC event.
This macro is used within the DSS_RD_REC event to determine why
the record is to be read.
Example if (DSS_RD_TYPE != DSS_RD_RD ||
DSS_FLD_FTR((int)((char*)&df_p->class - (char*)df_p),
(int)((char*)&df_p->class - (char*)df_p)))
{
opc_cls_get(dsi_opc_c, &cls_def);
strcpy(df_p->class, cls_def.name);
}

5.2.80 DSS_REC_DIFF
Syntax DSS_REC_DIFF = (TLS_BOOLEAN)different
Arguments • different
TRUE or FALSE to indicate whether the records are different.
Semantics Sets whether a record is different between the master node and a replica
node.
This macro is used for the DSS_CMP_REC event that is issued during
a consistency check of the data set. Returning TRUE signals the PML
that the records are different and that, in case of a repair, the records
should be made consistent again. The physical records to compare are
found in DSS_REC_RD and DSS_REC_WR.
Example DSS_EVENT(DSS_CMP_REC)
DSS_NO_DEFAULT;
DSS_REC_DIFF =
(TLS_BOOLEAN)(memcmp(DSS_REC_RD, DSS_REC_WR,
DSS_REC_LEN) != 0);

5.2.81 DSS_REC_LEN
Syntax int record_length = DSS_REC_LEN
Arguments • record_length
The length of the physical record.
Semantics Returns the length of the physical record and the physical read and write
buffers.
DSS_NO_DEFAULT;
DSS_DS_NODE_NUMBER,
DSS_DS_OPERATIONS, 0,
DSS_ERROR;

5.2.82 DSS_REC_MSG_ID
Syntax int message_id = DSS_REC_MSG_ID
Arguments • message_id
The message id of an event or flow message sent by the physical
unit.
Semantics This routine returns the message id of an event or flow message sent by
the physical unit.
This macro is used with the PML DSS_PRO_EVT and DSS_PRO_FLW
events to determine the id of the message.
if (DSS_REC_MSG_ID == DSS_EVT_MSG_ID(0))
{
...
}
else if (DSS_REC_MSG_ID == DSS_EVT_MSG_ID(1))
{
...
}

5.2.83 DSS_REC_NM
Syntax char *record_name = DSS_REC_NM
Arguments • record_name
The pointer to the name of the current record.
Semantics Returns the name of the last record read, inserted, updated or deleted.
The name of the record is the logical value of the logical NAME field in
the data set.
This macro is mainly used for the DSS_ADT_REC event to obtain the
name of the record involved.
Example

5.2.84 DSS_REC_RD
Syntax char *record_read_buffer = DSS_REC_RD
Arguments • record_read_buffer
Pointer to the physical read buffer.
Semantics Returns the pointer to the physical read buffer.
The physical read buffer contains the physical record in case of one of
the following events:
• DSS_RD_REC
Record contains the essential index values. The record read is
stored or has to be stored in this buffer.
• DSS_UPD_REC
Complete record prior the update.
• DSS_UPD_REP
• DSS_UPD_NOT
• DSS_UUPD_REC
Complete record to rewrite.
• DSS_UUPD_REP
Complete record to rewrite.
• DSS_UDEL_REC
Complete record to undelete.
• DSS_UDEL_REP
Complete record to undelete.
Example DSS_EVENT(DSS_UPD_REC)
struct my_record *new_record =
(struct my_record *)DSS_REC_WR;
struct my_record *old_record =
(struct my_record *)DSS_REC_RD;
if (record_new->low >= record_old->low)

{
…
}

5.2.85 DSS_REC_WR
Syntax char *record_write_buffer = DSS_REC_WR
The buffer that contains the physical record to write.
Semantics Returns the pointer to the physical write buffer.
The DSS_REC_WR macro returns a NULL pointer (no buffer) when the
data set has been opened for read access only. The physical write buffer
contains the physical record in case of one of the following events:
• DSS_CHK_REC Complete record to check.
• DSS_CHK_INS Complete record to check
• DSS_INS_REC Complete record to insert.
• DSS_INS_REP Complete record to insert.
• DSS_INS_NOT Complete record inserted.
• DSS_UINS_REC Complete record to uninsert.
• DSS_UINS_REP Complete record to uninsert.
• DSS_CHK_UPD Complete record to check.
• DSS_UPD_REC Complete record to update with.
• DSS_UPD_REP Complete record to update with.
• DSS_UPD_NOT Complete record updated.
• DSS_CHK_DEL Complete record to check.
• DSS_DEL_REC Complete record to delete.
• DSS_DEL_REP Complete record to delete.
• DSS_DEL_NOT Complete record deleted.
Example DSS_EVENT(DSS_CHK_REC)
struct my_record *record =
(struct my_record *)DSS_REC_WR;
if (record->low >= record->high)

{
…
}

5.2.86 DSS_RES_UMH_C
Syntax DSS_RES_UMH_C
Arguments None.
Semantics Restores the previous saved UMH context.
A DAS needs sometimes a temporary UMH context to be able to call
functions while the original error should be saved. Up to 9 UMH context
buffers can be saved. The macro DSS_SAV_UMH_C saves the correct
UMH context and initiates a new one.
Example if (!dsig_itmi_eq(DSS_DAS_C, item_def))
{
DSS_SAV_UMH_C;
del_cop(DSS_DAS_C, item_def, distr_flag);
DSS_RES_UMH_C;
DSS_ERROR;
}

5.2.87 DSS_SAV_UMH_C
Syntax DSS_SAV_UMH_C
Arguments None.
Semantics Saves the current UMH context and setups a new one.
A DAS needs sometimes a temporary UMH context to be able to call
functions while the original error should be saved. Up to 9 UMH context
buffers can be saved. The macro DSS_RES_UMH_C restores the
previous saved UMH context.
Example if (!dsig_itmi_eq(DSS_DAS_C, item_def))
{
DSS_SAV_UMH_C;
del_cop(DSS_DAS_C, item_def, distr_flag);
DSS_RES_UMH_C;
DSS_ERROR;
}

5.2.88 DSS_SEL_NODE
Syntax int selected_node = DSS_SEL_NODE
Arguments • selected_node
The node to be checked during consistency check or the node where
the physical unit event was generated.
Semantics This macro is used for two purposes:
• Supplies the node to be checked during consistency check.
While the consistency check is running (requested via the
DSSCHK utility), the PML issues the DSS_CHK_NODE event for
each record and node where the data set is replicated. The DAS can
use the result of the DSS_SEL_NODE macro to determine whether
all replica nodes (-1) are checked or only a specific one. The macro
is often used in combination with the DSS_CONT_CHECK macro.
• Supplies the node where the physical unit event is coming from.
In case of the DSS_PRO_EVT event, the macro DSS_SEL_NODE
returns the node where the physical unit event came from. When it
was generated on the same node as where the DAS is running, then
zero is returned.
Example DSS_EVENT(DSS_CHK_NODE)
DSS_NO_DEFAULT;
item_def = (struct item_def *) DSS_REC_RD;
if (item_def->item_ith.distr_type != GIN_ITM_DTYPE_LH &&

item_def->item_ith.fe_node != 0 &&
DSS_DS_NODE_NUMBER &&
(DSS_DS_NODE_NUMBER != 0 ||
DSS_OWN_NODE_NUMBER) &&
(DSS_SEL_NODE == -1 ||
DSS_SEL_NODE == item_def->item_ith.fe_node))
DSS_CONT_CHK = TRUE;
else
DSS_CONT_CHK = FALSE;

5.2.89 DSS_SET_PAG
Syntax TLS_BOOLEAN status = DSS_SET_PAG(int pag_nr)
• pag_nr
The process area bit number (0 - 999) to set.
Semantics Sets the process area of a record just read. This routine may only be
called when the process area is requested by the DSS_GET_PAG event.
The macro may be used more than once to set more than one process
area bit.
Example DSS_EVENT(DSS_GET_PAG)
struct item_df *item_df;
DSS_NO_DEFAULT;
item_df = (struct item_df *)DSS_REC_RD;
DSS_SET_PAG(item_df->process_area[0]);
DSS_SET_PAG(item_df->process_area[1]);

5.2.90 DSS_SET_TYPE
Syntax DSS_SET_TYPE(int server_type)
Arguments • server_type
The type of the server. Can be one of:
- DSS_ISF_TYPE
The DAS handles standard ISAM (DATABASE/FAST) files.
- DSS_HIS_TYPE
The DAS handles historical organised DATABASE/FAST
files.
- DSS_UNK_TYPE
The DAS handles any other data.
Semantics Specifies the type of the DAS. It defines the functionality to perform for
certain events when the event is not handled by the data set specific DAS
itself.
This macro must be positioned directly after any private declarations
within the DAS. Multiple DSS_SET_TYPE definition within the same
DAS have no effect.

5.2.91 DSS_SYSTEM_FROM
Syntax int system_type = DSS_SYSTEM_FROM
Arguments • system type

The BUS/FAST system type.
Semantics This macro is used to obtain the system type of the node that send the
event from the physical unit.
On the DSS_PRO_EVT event this macro is used to determine the
system type of the node where the physical unit is running that did sent
an event. In combination with the DSS_SYSTEM_TO, the DAS is able
to perform system conversion of the event located in DSS_EVT_REC
before interpretation of its content.
Example

5.2.92 DSS_SYSTEM_TO
Syntax int system_type = DSS_SYSTEM_TO
Arguments • system type

The BUS/FAST system type.
Semantics This macro is used to obtain the system type of the node where the DAS
is running.
On the DSS_PRO_EVT event this macro is used to determine the
system type of the node where the DAS is running. In combination with
the DSS_SYSTEM_FROM, the DAS is able to perform system
conversion of the event located in DSS_EVT_REC before interpretation
of its content.
Example

5.2.93 DSS_TIME_AS_GMT
Syntax TLS_BOOLEAN time_as_gmt = DSS_TIME_AS_GMT
Arguments • time_as_gmt
True is all times should be returned in GMT.
Semantics This macro is used to determine whether times should be passed in
GMT. If true all times must be in GMT format else the times must be in
LCT format.
Example

5.2.94 DSS_UMH_C
Syntax struct umh_context *umh_c = DSS_UMH_C
Arguments • umh_c
The BUS/FAST UMH context.
Semantics Returns the UMH context to be used for calling FAST/TOOLS
functions.
if (event_seq != expected_event_seq)
{
DSS_ERROR_EVT;
}

Introduction Very Simple Dataset Interface
6 Very Simple Dataset Interface
6.1 Introduction
The VSD-API is an easy to use C-interface that provides just enough
functionality to implement the most common uses of the DSS interface.
DSS datasets are intended to evolve over time, fields are added or
extended in size. This means that a DSS-Client that use the DSS-API has
to implement a lot of "boilerplate code" to anticipate changes to
datasets. The VSD-API is intended to solve this problem. It will take
care of allocation of fieldset memory when a dataset is opened and will
free the memory as soon as the dataset is closed.
The VSD-API is intentionally kept simple, sacrificing completeness for
simplicity. I you find the VSDVSD-API does not serve your
requirements you have to use the DSS-API.
6.2 Available functionality

The VSD-API provides the following functionality:
• Login/logoff
• Open/Close datasets
• Get basic field properties
• Read sequential
• Read equal
• Provide dataset filters
• Update dataset records
• Insert datasets records
• Delete dataset records
6.3 Using the VSD interface

The following picture gives an overview of how the VSD-API works.

Very Simple Dataset Interface Using the VSD interface
readNext() Fieldset
DSS readEqual()
getField()
setField()
dssv_dss_hnd
updateRecord()
For each DSS dataset that is opened the VSD-API creates a fieldset
buffer. With the dssv_readNext() or dssv_readEqual() routines
this buffer is filled with data from DSS. The Client can then use getField
routines to read the value for one specific field or use setField to modify
the field value.
The dssv_updateRecord()routine is then used to write the
contents of the fieldset buffer back to DSS. Changes to the fieldset by
the setField routines are only written to DSS after a call to
dssv_updateRecord().
The VSD-API provides two methods of reading and writing data to the
fieldset buffer. The first method is by getting a pointer to the address of
the field in the buffer. The second method is to read the field as a text
string.
If you want to access the field buffer directly through a pointer you need
to use use the dssv_getFieldBuffer()routine . This will return
the address of the field in a pointer of type void. You will have to cast
this pointer to the actual data type of your field.
The he right datatype to cast the pointer to can be either be found in the
dataset definition file or programmatically by using the
dssv_getFieldProperties() routine.

Return value/Error indication Very Simple Dataset Interface
Example:
char *name;
name = (char *) dssv_getFieldBuffer(umh_c,
dss_conn,ds_handle,
"NAME");
printf(“record name = %s\n", name);
Alternatively you can use the routines dssv_getFieldStr() and

dssv_setFieldStr(). These routine let you manipulate the
fieldset buffer as string values.
Example:
/*-----------------------------------------------
| Get item value as string
+-----------------------------------------------*/
char value[10];
dssv_getFieldStr(umh_c, ds_hnd, “VALUE”, value);
printf(“Item value = %s\n”, value);
/*------------------------------------------------
| Set item value to 200
+-----------------------------------------------*/
dssv_setFieldStr(umh_c, ds_hnd, “VALUE”, “200”);
dssv_updateRecord(umh_c, &dss_conn, ds_hnd);
6.4 Return value/Error indication

Most functions return either TRUE or FALSE as return value. In the
case of FALSE additional information is passed in the UMH context.
There are a few routines that return a pointer. In case of an error these
routines return a NULL and additional information is found in the UMH
context.
6.5 Arguments
All arguments which are passed by reference may be assumed to be

Very Simple Dataset Interface dssv.h header file
6.6 dssv.h header file

are defined in the dssv.h. This file contains definitions of structures that
are used in the calls.
6.7 Structures
Most of the structures used in the argument list are defined in the file
dssv.h. This paragraph gives an overview of the structures used by the
VSD-API.
Some of the structs used by the VSD-API are only intended for internal
use by the API and should never be changed by the API client. The
following struct are for API internal use only:
• struct dssv_dss_hnd DSS context struct.

• struct dssv_ds_hnd Dataset context struct.
6.7.1 dssv_string_buff
This structure is used to receive a list of strings. It is for example used to

transfer a list of available dataset names or the field names in a dataset.
#define VSD_MAX_STR_BUFF 300
struct dssv_string_buff
{
int entries; /* Number of entries */
char name[VSD_MAX_STR_BUFF][DSS_FLD_NM_SZ];
}
6.7.2 dssv_field_prop
This structure is used by the routine dssv_getFieldProperties to return

the basic properties of a dataset field.
struct dssv_field_prop
{
TLS_SHORT fld_type; /* Field type */
TLS_SHORT fld_len; /* Field length in bytes */

VSD-API routines Very Simple Dataset Interface
TLS_ULONG fld_operations;/* Allowed operations */

}
The field fld_type in the structure above is one of the following:
DSS constant Field type

DSS_DTYPE_CHAR Character
DSS_DTYPE_SHORT Short
DSS_DTYPE_USHORT Unsigned short
DSS_DTYPE_LONG Long
DSS_DTYPE_ULONG Unsigned long
DSS_DTYPE_FLOAT Float
DSS_DTYPE_BOOLEAN Boolean
DSS_DTYPE_BYTE Byte
DSS_DTYPE_BYTE Unsigned byte
The field fld_len in the structure holds the field length in bytes.
The field fld_operations contains a bit-mask indicating the
allowed operations on the field. Possible values are:
• DSS_OPER_READ - Read operation is allowed.

• DSS_OPER_UPDATE - Update operation is allowed.
• DSS_OPER_INSERT - Insert operation is allowed.
• DSS_OPER_DELETE - Delete operation is allowed.
6.8 VSD-API routines
6.8.1 Introduction
This paragraph contains a detailed description of all DSS-API routines.

The routines are described in alphabetical order. For each of the routines
the following items are described:

Very Simple Dataset Interface VSD-API routines
• The syntax of the routine.

• A description of fixed and optional arguments of the routine.
• The semantics of the routine.
• If necessary some comment on the use of the routine.
• The most important errors that the routine may return.
This information is given in the form of a list of UMH error
mnemonics.

6.8.2 Close connection to DSS
Syntax TLS_BOOLEAN dssv_close(

struct dssv_dss_conn *dss_hnd)
Arguments • umh_c
Pointer to UMH context.
• dss_hnd
Connection handle to DSS.
Semantics Closes the connection to DSS. When the connection to DSS is no longer
needed by a DSS client, it should close the connection. This enables
VSD-API to free all resources. Any datasets that are still open will be
closed when the connection to DSS is closed.
Notes • None
Errors • DSSV_E_CLOSE
Error while closing connection to DSS.

6.8.3 Close Dataset
Syntax TLS_BOOLEAN dssv_closeDataset(

struct umh_context*umh_c,
struct dssv_ds_hnd *ds_hnd)
Arguments • umh_c
• ds_hnd
Dataset connection handle.
Semantics When an open data set table, is no longer needed by a DSS client, the
DSS client should close the data set. This enables DSS to free all
resources occupied by the open data set table.
Notes • None.
Errors • DSSV_E_NOT_CONN
Not connected to DSS.
• DSSV_E_DS_CLOSED
Attempted operation on closed dataset.
• DSSV_E_CLOSE
Error while closing connection to DSS.

6.8.4 Connect to DSS
Syntax TLS_BOOLEAN dssv_connect(

struct dssv_dss_hnd *dss_hnd)
Arguments • umh_c
• dss_hnd
Address of a DSS connection handle
Semantics This routine initializes the connection between the client and DSS. The
client needs to pass the address of a dssv_dss_hnd struct that will be
initialized by the routine.
The initialized struct will serve a connection handle between DSS and
the client. Most of the DSI routines will need this handle. This handle
should be treated as opaque to the client and never be changed by the
client.
Notes None.
Errors • DSSV_E_CONNECT
Error while connecting to DSS.

6.8.5 Delete Dataset record
Syntax TLS_BOOLEAN dssv_deleteRecord(

struct dssv_ds_hnd *ds_hnd,
char *index);
Arguments • umh_c
• ds_hnd
Handle to data set.
• index
Index value of the record.
Semantics This routine is used to delete a record from a dataset. Index points to a
string that contains the index value of the record to delete. This field is
ussually called “NAME”. The index value is passed as a string.
Notes • None.
Errors • DSSV_E_DS_CLOSED
Attemped operation on closed dataset.
• DSSV_E_IDX_CNT
To many Index fields.
• DSSV_E_IDX_SZ
Index field size to long.
• DSSV_E_DEL_REC
Error while deleting dataset record.

6.8.6 Get dataset names
Syntax TLS_BOOLEAN dssv_getDatasetNames(

struct dssv_dss_hnd *dss_hnd,
struct dssv_string_buff *str_buff);
Arguments • umh_c
• dss_hnd
Handle to data set.
• str_buff
String buffer containing all available datasets
•
This routine can be used to retrieve the names of available datasets in
Semantics DSS. It will fill the struct dssv_string_buff with datasets names.
Notes • None.
• DSSV_E_GET_DS_NM
Error while getting dataset names.
• DSSV_E_GET_FLDS
Error while getting field names.
• DSSV_E_BUFF_SIZE

6.8.7 Get field buffer
Syntax void *dssv_getFieldBuffer(

struct dssv_ds_hnd *dss_hnd,
char *field_name);
Arguments • umh_c
• dss_hnd
Handle to data set.
• field_name
Name of the field
This routine returns a pointer to the position of the data buffer for the
DSS field indicated by ‘field_name’. The user must cast the returned
pointer to the correct datatype. The datatype of the fields can be found
Semantics in the datatset definition file or by using the
dssv_getFieldProperties() routine.
Notes • None.
Errors • DSSV_E_STR_SZ
Invalid string size.
• DSSV_E_GET_STR
Error while retrieving string value.
• DSSV_E_FLD_NM
Unknown field name.

6.8.8 Get field value as double
Syntax TLS_BOOLEAN dssv_getFieldDouble(

char *field_name,
TLS_DOUBLE *value);
Arguments • umh_c
• ds_hnd
Handle to data set.
• field_name
Name of the field to retrieve.
• value
TLS_DOUBLE variable for receiving the value.
Semantics This routine places the value of the given dataset field in the
TLS_DOUBLE variable ‘value’.
Notes • None.
• DSSV_E_STR_SZ
• DSSV_E_GET_STR
• DSSV_E_FLD_NM
Unknown field name.

6.8.9 Get field names
Syntax TLS_BOOLEAN dssv_getFieldNames(

char *ds_name,
struct dssv_string_buff *str_buff)
Arguments • umh_c
• dss_hnd
Handle to data set.
• ds_name
Dataset name
• str_buff
String buffer containing all fieldnames in the dataset.
Semantics Returns a struct dssv_string_buff containing all field names in a

dataset.
This small example prints the names in all the fields in the dataset
ITEM_DF.
/*---------------------------------------------
| Get field names
+---------------------------------------------*/
struct dssv_string_buff field_name_buff;
if(!dssv_getFieldNames(umh_c, &dss_conn,
”ITEM_DF”, &field_name_buff))
{
return FALSE;
}
for(i=0; i < field_name_buff.entries; i++)
{
printf(" Field -> %s\n", field_name_buff.name[i]);
}
Notes • None.
• DSSV_E_GET_DS_NM
Error while getting dataset names.

• DSSV_E_GET_FLDS
Error while getting field names.
• DSSV_E_BUFF_SIZE

6.8.10 Get field properties
Syntax TLS_BOOLEAN dssv_getFieldProperties(

char *ds_name,
char *field_name,
struct dssv_field_prop *prop);
Arguments • umh_c
• dss_hnd
Handle to data set.
• ds_name
Dataset name.
• field_name
Dataset field name for which to get the properties.
• prop
Field properties struct.
Semantics This routine fills the struct dssv_field_prop with the basic properties
for a given dataset and field. The layout and use of the
dssv_field_prop struct is described in SubSection 6.7.2
The following example prints the properties for the NAME field in the
ITEM_DF dataset.
/*----------------------------------------------------
| Get field properties
+----------------------------------------------------*/
struct dssv_field_prop fld_prop;
if(!dssv_getFieldProperties(umh_c, &dss_conn,
“ITEM_DF”, “NAME”, &fld_prop))
{
return FALSE;
}
else
{
printf("Length = %d\n", fld_prop.fld_len);
printf("DSS type = %d\n", fld_prop.fld_type);
printf("Operations = %d\n", fld_prop.fld_operations);
}
Notes • None.

• DSSV_E_GET_FPROP
Error while getting field properties.

6.8.11 Get field value as string
Syntax TLS_BOOLEAN dssv_getFieldString(

char *field_name,
char *value);
Arguments • umh_c
• ds_hnd
Handle to data set.
• field_name
Field to be received
• value
String for receiving value
•
Semantics This routine places the value of the given dataset field in the string
‘value’.
Notes • None.
• DSSV_E_STR_SZ
• DSSV_E_GET_STR
• DSSV_E_FLD_NM
Unknown field name.

6.8.12 Get index fields
Syntax TLS_BOOLEAN dssv_getIndexFields(

char *ds_name,
char *index_name,
struct dssv_string_buff *str_buff)
Arguments • umh_c
• dss_hnd
Handle to DSS.
• ds_name
Name of the Dataset.
• index_name
Name of the index.
• str_buff
String buffer to receive index.
This routine returns the dataset fields that compose an index for a given
dataset and index name. In most cases an index on a dataset consists of
just one dataset field, usually “NAME”.
DSS however supports ‘composed indexes’ whereby an index can
consist of more then one dataset fields. Therefore this routine needs to
Semantics use a struct of type dssv_string_buff.
Notes • None.
• DSSV_E_GET_IDX
Error while getting index fields.
• DSSV_E_IDX_CNT
Too many index fields.
• DSSV_E_NO_IDX_NM
Not an index name.

6.8.13 Insert record
Syntax TLS_BOOLEAN dssv_insertRecord(

struct dssv_ds_hnd *ds_hnd);
Arguments • umh_c
• ds_hnd
Handle to dataset.
•
Semantics This routine inserts the current data in the fieldset as a new record in
DSS.
Notes • None.
• DSSV_E_REC_INS
Error while inserting record.

6.8.14 Logoff from DSS
Syntax TLS_BOOLEAN dssv_logoff(

struct dssv_dss_hnd *dss_hnd);
Arguments • umh_c
• dss_hnd
Handle to DSS.
•
Semantics Logoff from DSS.
The dssv_logoff routine does not close the DSS connection.
Notes • None.
• DSSV_E_LOGOFF
Failed to logoff from DSS.

6.8.15 Logon to DSS
Syntax TLS_BOOLEAN dssv_logon(

char *user,
char *password);
Arguments • umh_c
• dss_hnd
Handle to DSS.
• user
User name
• password
User password
Semantics Logon to DSS. After logging on as a specific user the DSS client will be
restricted to the authorization as set for that specific user. An DSS client
that is not logged on has unrestricted access to DSS.
Before you can logon you need to be connected to DSS using the
dssv_connect() routine. The dssv_logon routine does not
automatically connect you to DSS.
Notes • None.
• DSSV_E_NOT_CONN
Errors Not connected to DSS.
• DSSV_E_NO_USER
No user name provided.
• DSSV_E_STR_SZ
• DSSV_E_LOGON
Failed to logon to DSS.

6.8.16 Open dataset
Syntax TLS_BOOLEAN dssv_openDataset(

char *ds_name,
char *dataset_fields,
char *mode)
Arguments • umh_c
• dss_hnd
Handle to DSS. This handle must already be initialized using the
dssv_connect routine.
• ds_hnd
Dataset handle, this struct will be initialized by this routine. It will
be used with every subsequent operation on the dataset.
• ds_name
Name of the dataset to open.
• dataset_fields
Dataset fields to include in the fieldset. The field names are passed
as a comma separated string. For example the string “NAME,
DESCRIPTION, VALUE” will open the dataset with a fieldset
containing only these three fields.
• mode
This string defines the settings for the dataset. It can contain any
combination of the following characters:
- ‘r’ Allow read operations.
- ‘u’ Allow update (write) operations.
- ‘d’ Allow delete operations.
- ‘i’ Allow insert operations.
- ‘t’ All time fields are in UTC (GMT), default is LCT
For example the mode string “ri” will allow reading and inserting of
dataset records. The string “rudi” will allow every operation on the
dataset records.
Semantics Opens a dataset with a limited fieldset.

Example:

/*----------------------------------------------------
| Open the item_df dataset with the fields NAME and
| DESCRIPTION in read only mode
+---------------------------------------------------*/
if(!dssv_openDataset(&dss_conn, &ds_handle,
“ITEM_DF”, "NAME, DESCRIPTION", "r"))
{
return FALSE;
}
Notes • None.
• DSSV_E_FLD_SZ
Field name string to long.
• DSSV_E_OPEN_DS
Error while opening dataset.

6.8.17 Open dataset with all fields
Syntax TLS_BOOLEAN dssv_openDatasetAllFields(

char *ds_name,
char *mode)
Arguments • umh_c
• dss_hnd
Handle to DSS. This handle must already be initialized using the
dssv_connect routine.
• ds_hnd
Dataset handle, this struct will be initialized by the routine and
needs to be used on every subsequent operation on the dataset.
• ds_name
The name of the dataset to open.
• mode
This string defines the settings for the dataset. It can contain any
combination of the following characters:
- ‘r’ Allow read operations.
- ‘u’ Allowd update (write) operations.
- ‘d’ Allow delete operations.
- ‘i’ Allow insert operations.
- ‘t’ All time fields are in UTC (GMT), default is LCT
For example the mode string “ri” will allow reading and inserting of
dataset records. The string “rudi” will allow every operation on the
dataset records.
Semantics Open dataset with all fields. For this variant of the openDataset routine
it is not necessary to specify a field set, since fields will be included in
the fieldset.
Notes • None.
• DSSV_E_FLD_SZ
Field name string too long.

• DSSV_E_OPEN_DS
Error while opening dataset

6.8.18 Read equal
Syntax TLS_BOOLEAN dssv_readEqual(

char *index)
Arguments • umh_c
• dss_hnd
Handle to DSS.
• index
Index value of the record to read.
This routine fills the fieldset buffer with the DSS dataset record of the
Semantics index value as given in the index parameter. In most cases an index on
a dataset consists of the dataset field “NAME”.
Semantics
Notes • None.
Not connected to DSS
• DSSV_E_IDX_SZ
Index field size to long.
• DSSV_E_IDX_COUNT
Invalid number of fields in index
• DSSV_E_READ_EQL
Error while reading record.

6.8.19 Read next
Syntax TLS_BOOLEAN dssv_readNext(

struct dssv_ds_hnd *ds_hnd);
Arguments • umh_c
• ds_hnd
Handle to dataset
Semantics Read next record from dataset. If successful this routine will read the
next dataset record into the fieldset buffer and return TRUE. If the
routine returns FALSE it might be either because on error occurred or
because we tried to read beyond the last record in the dataset.
If we reached the and of the dataset DSS will place the error code
“DSS_E_EOS” on the UMH-stack. This way can distinguish between
an error and the end of the dataset. The following example illustrates
this:
/*----------------------------------------------+
| Read record sequentially
+----------------------------------------------*/
while(dssv_readNext(umh_c, &ds_handle))
{
/*--------------------------------
| Do something interesting here
+-------------------------------*/
}
if(umh_error(umh_c)== DSS_E_EOS)
{
/*---------------------------------------------+
| No error, just reached end of dataset
+---------------------------------------------*/
dssv_close(umh_c, &dss_conn);
return TRUE;
}
else
{
/*--------------------------------------------+
| Error
+---------------------------------------------*/
dssv_close(umh_c, &dss_conn);
return FALSE;
}

Notes • None.
• DSSV_E_READ_NEXT
Error while reading next record.

6.8.20 Remove filter
Syntax TLS_BOOLEAN dssv_removeFilter(

Arguments • umh_c
• ds_hnd
Handle to dataset
Semantics Remove a DSS filter from a dataset.
Notes • None.
• DSSV_E_REM_FLTR
Error while removing filter.

6.8.21 Rewind dataset
Syntax TLS_BOOLEAN dssv_rewindDataset(

Arguments • umh_c
• ds_hnd
Handle to dataset
Semantics Rewind dataset. This routine places the ‘record pointer’ for the
dssv_readNext routine at the beginning of the dataset. After a ‘rewind’
the readNext routine will always read the first record fron the dataset.
Notes • None.
• DSSV_E_REW_REC
Error while rewinding dataset.

6.8.22 Set field value with Double
Syntax TLS_BOOLEAN dssv_setFieldDouble(

char *field_name,
TLS_DOUBLE value)
Arguments • umh_c
• ds_hnd
Handle to dataset
• field_name
Field to be changed
• value
New field value
Semantics Update the value of a dataset field with the TLS_DOUBLE value in the
value parameter. If the data type of the field is not a TLS_DOUBLE the
DSSV-API will try to convert the value to the appropriate data type
before inserting it into the dataset.
Notes • None.
• DSSV_E_FLD_NM
Unknown field name.

6.8.23 Set field value with string
Syntax TLS_BOOLEAN dssv_setFieldString(

char *field_name,
char *value)
Arguments • umh_c
• ds_hnd
Handle to dataset
• field_name|
Field to be changed
• value
New field value
Semantics Update the value of a dataset field with the string value in the value
parameter. If the datatype of the field is not a string the DSSV-API will
try to convert the value. You can for example update a field of type float
by passing a value string as “12.4”.
Notes • None.
• DSSV_E_FLD_NM
Unknown field name.

6.8.24 Set filter expression
Syntax TLS_BOOLEAN dssv_setFilter(

char *filter_expr)
Arguments • umh_c
• ds_hnd
Handle to dataset
• filter_expr
Filter expression
Semantics Create a filter on a dataset. This routine will set and activate a filter
expression on a dataset. The filter expression must be passed as a string
in the filter_expr parameter. For a detailed description on the filter
syntax please see the DSS programmer’s guide.
Example:
struct dssv_dss_hnd *dss_conn;
struct dssv_ds_hnd ds_handle;
char item_name[64];
/*----------------------------------------------------------------------
| This filter on items from installation "DSSV_TEST" and UNIT "UNIT_2"
| Quote characters inside the expression need to be proceeded by '\'
+---------------------------------------------------------------------*/
char filterExpression[] = "INSTALL = \"DSSV_TEST\" AND UNIT = \"UNIT_2\"";
/*----------------------------------------------------------------------
| Connect to dss and open ITEM_DF dataset
+---------------------------------------------------------------------*/
vsd_test_connect_dss();
dssv_openDatasetAllFields(umh_c, dss_conn, &ds_handle, "ITEM_DF","r");
/*---------------------------------------------------------------------
| Set filter expression.
+---------------------------------------------------------------------*/
dssv_setFilter(umh_c, &ds_handle, filterExpression);
/*------------------------------------------------------------------
| Only read records that pass the filter criteria.
+----------------------------------------------------------------------*/
while(dssv_readNext(umh_c, &ds_handle))
{
dssv_getFieldString(umh_c, &ds_handle,"NAME",item_name);
printf("Item name = %s\n", item_name);
}

Notes • None
• DSSV_E_SET_FLTR
Error while setting a filter.

6.8.25 Set active index
TLS_BOOLEAN dssv_setIndex(
char *index_name)
Arguments • umh_c
• ds_hnd
Handle to dataset
• index_name
Name of the index to set active.
Semantics Set the index on a dataset. When a dataset is opened the primary index
is active by default. For datasets that have more than one indexes this
routine can be use to change the active index.
Notes • None.
• DSSV_E_SET_IDX
Error while setting index.

6.8.26 Update record
Syntax TLS_BOOLEAN dssv_updateRecord(

Arguments • umh_c
• ds_hnd
Handle to dataset
Semantics This routine updates the contents of the fieldset record in DSS.
Notes • None.
• DSSV_E_UPD_REC
Error while updating a record.


Index
A default data access server 3-4

Define filter 4-34
Access change log 4-95 Define/Delete filter 2-5
Activate change log 4-94
Delete filter 4-39
Activate filter 4-16, 6-7
Delete record 2-9, 4-40
Activate/Deactivate filter 2-8 Disconnect from DSS 4-33
ASCII file 2-9
disconnect from DSS 2-4
Asynchronous data access 3-25
dsid_das_def 3-4
Audit trailing 3-31 dsid_das_his 3-3
authorisation 1-4, 2-5, 3-31
dsid_das_isf 3-3
dsid_das_unk 3-3
B dss 2-5
Bind field 4-17 DSS API 1-2, 1-7, 2-1
Bind/Unbind fields 2-4 DSS API routines 4-14, 6-5
bulk operations 1-6 DSS client 1-2
BUS/FAST message 2-10 DSS compiler 1-2
DSS structures 4-3, 6-4
C dss.h 3-11, 4-2, 6-4
Cancel event request 4-20, 6-9 dss_acc_clog 4-14
Check filter criteria 4-30 dss_acc_clog() 4-94, 4-95
C-language 3-11 dss_act_clog() 4-94, 4-96
Close data set 4-22, 6-10 dss_act_flt() 2-8, 4-16, 6-7
Close event channel 4-23, 6-11, 6-12, 6- DSS_ADT_ACTION 3-31, 5-2
13, 6-14, 6-16, 6-18, 6-19, 6-20, DSS_ADT_FLD 3-6, 3-9, 3-31, 5-2, 5-
6-21, 6-22, 6-23, 6-25, 6-27, 6- 3, 5-4, 5-5, 5-6, 5-7
28, 6-30, 6-31, 6-32, 6-33, 6-34, DSS_ADT_FLD_NM 3-31, 5-3
6-36, 6-37 DSS_ADT_NEW_VAL 3-31, 5-3, 5-4,
columns 1-1 5-6
Connect to DSS 4-28 DSS_ADT_OFF 3-31, 5-5, 5-7
connect to DSS 2-4 DSS_ADT_OLD_VAL 5-3, 5-4, 5-6
connection handle 2-4 DSS_ADT_ON 5-5, 5-7
Consistency check 3-34 DSS_ADT_REC 3-6, 3-9, 3-31, 5-2, 5-
consistency check 1-6 5, 5-7, 5-85
DSS_ARG_ADT_SAS 4-53
D DSS_ARG_ENT_USR 4-53
DSS_ARG_EOL 4-1
DAS 3-1, 5-1
DSS_ARG_NODE_NM 4-53
Data Access Server 3-1
DSS_ARG_NODE_NR 4-53
data access servers 1-7, 3-1
DSS_ARG_SESSION_ID 2-11, 4-52,
data container 1-1
4-53, 4-55, 4-58, 4-64
data dictionary 1-2, 1-5
DSS_ARG_TERM_NM 4-53
data manipulation actions 1-5
dss_bnd_fld() 2-5, 4-17
Data replication 3-5
dss_canc_evt() 2-10, 4-20, 6-9
data replication 1-4
dss_change_log 4-14
data set 1-7
DSS_CHK_DEL 3-6, 3-9, 3-23, 5-87
data set model 1-1
DSS_CHK_INS 3-6, 3-9, 3-19, 5-87
data set properties 1-2, 2-4
DSS_CHK_NODE 3-6, 3-9, 3-34, 5-9,
data set services 1-2
5-90
DATABASE/FAST 5-16
DSS_CHK_REC 3-6, 3-9, 3-19, 3-21,
Deactivate filter 4-32
DATABASE/FAST DSS Programmer’s Guide 1

Index
5-87 DSS_DS_OPERATIONS 3-16, 5-20

DSS_CHK_UPD 3-6, 3-9, 3-21, 5-87 DSS_DS_PATH_NUMBER 3-16, 3-
DSS_CLS_DS 3-6, 3-9, 3-16, 5-19 26, 5-17, 5-21
dss_cls_ds() 2-7, 4-22, 6-10, 6-11 DSS_DS_TERM_NM 5-22
dss_cls_evc() 2-10, 4-23 DSS_DS_USER_NM 5-23
DSS_CLS_EVT 3-6, 3-9, 3-26 DSS_DUR_C 5-24
DSS_CLS_REP 3-6, 3-9, 3-16, 5-19 DSS_E_NOREC 3-15, 3-18
DSS_CLT_PRC 5-8 DSS_E_RECTHERE 3-15, 3-20
DSS_CMP_REC 3-6, 3-9, 3-34, 5-82 DSS_END_DATA_ACCESS_SERVE
DSS_CNV_LOG 3-6, 3-9, 3-24, 5-39, R 3-12, 3-13, 5-13, 5-25
5-40 DSS_END_EVENTS 3-12, 3-14, 5-26,
DSS_CNV_PHY 3-6, 3-10, 3-24, 5-40, 5-31, 5-32
5-41 DSS_ERROR 3-12, 3-15, 5-27
DSS_CNV_TO_REP 3-7, 3-10, 3-35 DSS_ERROR_EVT 3-15, 3-29, 3-30,
dss_con_dcl() 2-4, 4-28 5-28
dss_conn_sta 4-3, 6-4 DSS_ERROR_FLOW 3-15, 5-29
DSS_CONT_CHECK 5-90 DSS_ERROR_FLW 5-52
DSS_CONT_CHK 3-34, 5-9 DSS_ERROR_LIC 3-15, 5-30
dss_cri_mtch() 2-6, 4-30 DSS_EVENT 3-11, 3-14, 5-31
DSS_CURRENT_TIME 5-10 DSS_EVENTS 3-11, 3-14, 5-26, 5-32
dss_dac_flt() 2-8, 4-32 DSS_EVT_CRIT 3-27, 3-28, 3-30, 5-33
dss_das 4-8 DSS_EVT_CRIT_DS_DEL 5-33
DSS_DAS_C 3-12, 5-11 DSS_EVT_CRIT_DS_INS 5-33
DSS_DAS_C_DECLARATION 3-12, DSS_EVT_CRIT_DS_REC_DEL 5-33
5-12 DSS_EVT_CRIT_DS_REC_UPD 5-33
DSS_DATA_ACCESS_SERVER 3- DSS_EVT_CRIT_DS_UPD 5-33
11, 3-13, 5-13 DSS_EVT_MSG_ID 3-26, 5-35
dss_dbl_rng 4-9 DSS_EVT_OPN 5-35
dss_dcon_dcl() 2-4, 4-33 DSS_EVT_REC 3-30, 5-36, 5-93, 5-94
dss_def_flt() 2-6, 4-34 DSS_EVT_REF 3-28, 3-30, 5-37
dss_def_val 4-10 DSS_EVT_TIME 3-30, 5-38
DSS_DEL_EVT 3-7, 3-10, 3-30 dss_excl_acc() 4-45
dss_del_flt() 2-6, 4-39 dss_filespec 4-9
DSS_DEL_NOT 3-7, 3-10, 3-23, 5-87 dss_fld_basics 4-5
DSS_DEL_REC 3-5, 3-7, 3-10, 3-23, 5- dss_fld_compound 4-12
87 DSS_FLD_CUR_GET 3-25, 5-39
dss_del_rec() 2-9, 4-40 DSS_FLD_CUR_NM 3-25, 5-40
DSS_DEL_REP 3-7, 3-10, 3-23, 5-87 DSS_FLD_CUR_SET 3-25, 5-41
dss_dmp() 2-7, 4-41 DSS_FLD_FTC 5-42
DSS_DO_DEFAULT 3-12, 3-14, 5-14, DSS_FLD_FTR 5-43
5-31 DSS_FLD_FTS 5-44
DSS_DS_FILE_CHN 3-16, 3-18, 3-20, DSS_FLD_GET_FILE 5-45
3-22, 3-24, 3-26, 5-15 DSS_FLD_MARK 3-30, 5-46
DSS_DS_FILE_FMT 3-16, 3-26, 5-16 DSS_FLD_NR 5-47
DSS_DS_FILE_NAME 3-16, 3-26, 5- dss_fld_operation 4-10
17 DSS_FLD_PUT_FILE 5-48
DSS_DS_NM 5-18 dss_fld_references_lst 4-12
DSS_DS_NODE_NUMBER 3-16, 3- dss_fld_relation 4-11
26, 5-9, 5-16, 5-19, 5-21 dss_fld_transform_lst 4-11
2 DATABASE/FAST DSS Programmer’s Guide

Index
dss_flt_nd 4-13 65, 5-70

dss_flt_pd 4-12 DSS_O_IDX_SET 3-32, 5-71
DSS_FLW_ENABLED 5-50 DSS_O_REC_LEN 3-32, 5-72
DSS_FLW_MSG_ID 3-26, 5-51 DSS_O_REC_NM 5-73
dss_flw_sta 4-3 DSS_O_REC_RD 3-32, 5-74
DSS_FLW_TIMEOUT 5-52 DSS_O_REC_WR 3-32, 5-61, 5-62, 5-
dss_gen_arr 4-4 75, 5-76
dss_get_flwc() 2-11, 4-24, 4-26, 4-42, DSS_ON_EES 5-77, 5-78, 5-79
4-44 DSS_ON_ENS 5-77, 5-78, 5-79
DSS_GET_PAG 3-7, 3-10, 3-31, 5-91 DSS_ON_ES 5-77, 5-78
dss_get_passw 4-98 DSS_OPER_DELETE 5-2, 5-20, 5-63
dss_get_passwd() 4-97 DSS_OPER_INSERT 5-2, 5-20, 5-63
DSS_HIS_TYPE 3-3, 5-92 DSS_OPER_READ 5-20, 5-63
dss_idcs 4-7 DSS_OPER_UPDATE 5-2, 5-20, 5-63
dss_idx_basics 4-7 DSS_OPER_UPDATE_IGN 4-55
DSS_IDX_FLD 5-53 DSS_OPN_DS 3-7, 3-10, 3-16, 5-15, 5-
DSS_IDX_FLDS 5-54 19
DSS_IDX_ISF 5-55 dss_opn_ds() 2-7, 2-11, 4-55
DSS_IDX_NAME 5-56 dss_opn_evc() 2-10, 2-11, 4-58
DSS_INIT_SUPPORT 3-12, 5-57 DSS_OPN_EVT 3-7, 3-10, 3-26
DSS_INS_NOT 3-7, 3-10, 3-19, 5-87 dss_opn_fld() 2-9, 4-62
DSS_INS_REC 3-7, 3-10, 3-19, 5-45, DSS_OPN_REP 3-7, 3-10, 3-16, 5-15,
5-87 5-19
dss_ins_rec() 2-8, 4-47 DSS_PRO_EVT 3-7, 3-10, 3-29, 5-33,
DSS_INS_REP 3-7, 3-10, 3-19, 5-87 5-36, 5-38, 5-46, 5-84, 5-94
DSS_ISF_TYPE 3-3, 3-11, 5-92 DSS_PRO_FLW 3-7, 3-10, 3-30, 5-84
DSS_ITM_C 5-58 dss_prop_ds() 2-4, 2-11, 4-64
dss_lck_rc() 2-9, 4-48 dss_prop_dss() 2-4, 4-67
dss_lgof_usr() 2-5, 4-50 dss_prop_fld() 2-4, 4-69
dss_lgon_usr() 2-5, 4-51 dss_prop_idx() 2-4, 4-73
dss_logoff() 2-5, 2-11, 4-52 dss_rcvr_dcl() 2-6, 4-75
dss_logon() 2-5, 2-11, 4-53 DSS_RD_DAS 5-81
dss_mbstr_lst 4-9 DSS_RD_DEL 5-81
DSS_NO_DEFAULT 3-11, 3-14, 5-31, dss_rd_eql() 2-7, 4-76
5-59 DSS_RD_EQUAL 3-17, 5-64, 5-80
dss_node_info 4-8 dss_rd_evt() 2-10, 4-78
dss_node_lst 4-8 DSS_RD_FIRST 3-17, 5-64, 5-80
DSS_O_DS_CLS 3-32, 5-60 DSS_RD_GREAT 3-17, 5-64, 5-80
DSS_O_DS_DEL 3-32, 5-61 DSS_RD_GTEQ 3-17, 5-64, 5-80
DSS_O_DS_INS 3-32, 5-62 DSS_RD_MODE 3-17, 3-18, 5-80
DSS_O_DS_OPN 3-32, 5-63 DSS_RD_NEXT 3-17, 5-64, 5-80
DSS_O_DS_RD 3-32, 5-64 DSS_RD_RD 5-81
DSS_O_DS_UPD 3-32, 5-65 DSS_RD_REC 3-7, 3-10, 3-17, 5-43, 5-
DSS_O_FLD_GET 3-32, 5-66 48, 5-80, 5-81, 5-86
DSS_O_FLD_IDX 3-32, 5-67 DSS_RD_REF 5-81
DSS_O_FLD_NR 5-67, 5-68, 5-69, 5- DSS_RD_REL 5-81
70 dss_rd_seq() 2-7, 4-80
DSS_O_FLD_REP 3-32, 5-69 DSS_RD_TYPE 3-18, 5-43, 5-81
DSS_O_FLD_SET 3-32, 5-61, 5-62, 5- DSS_RD_UPD 5-81

Index
DSS_REC_DIFF 3-34, 5-82 dss_val_list() 4-90

DSS_REC_LEN 3-16, 3-26, 5-83 dss_valid() 4-92
DSS_REC_MSG_ID 5-84 DSSCHK 3-34, 5-9, 5-90
DSS_REC_NM 5-85 DSSEVT 3-2
DSS_REC_RD 3-18, 3-22, 3-24, 3-25, DSSSDA 3-2
3-27, 3-29, 3-30, 3-32, 3-34, 5- Dump DSS API data structures 2-7, 4-
33, 5-74, 5-86 41
dss_rec_struct 4-6 DUR context 5-24
DSS_REC_WR 3-20, 3-22, 3-24, 3-25,
3-34, 5-75, 5-76, 5-87 E
DSS_RES_UMH_C 5-88, 5-89 Enable/disable exclusive data set access
DSS_SAV_UMH_C 5-88, 5-89 4-45
DSS_SEL_NODE 3-34, 5-9, 5-90 error 4-1, 6-3
DSS_SET_EVT 3-7, 3-10, 3-27, 5-33, Error handling 3-15
5-37 error mnemonic 4-15
dss_set_evt() 2-10, 4-82 error_exit 3-12
DSS_SET_IDX 3-7, 3-10, 3-18, 5-53, event channel 2-10
5-54, 5-55, 5-56 event flow timeout 3-15
dss_set_idx() 2-8, 4-85 event information 2-10
DSS_SET_PAG 3-32, 5-91 event mechanism 2-1, 2-10
dss_set_passw 4-97 event message 2-10
dss_set_passwd() 4-98 event processing 3-14
DSS_SET_TYPE 3-11, 3-14, 5-92 event request 2-10
dss_str_lst 4-6 event sequence error 3-15
dss_str_nr_lst 4-6 exclusive access 2-9
DSS_SYSTEM_FROM 5-93, 5-94
DSS_SYSTEM_TO 5-93, 5-94 F
DSS_TERM_NM_SZ 5-22
DSS_TIME_AS_GMT 5-95 field binding 1-6
DSS_TIMER 3-7, 3-10, 3-34 field set 1-7, 2-5
dss_ubnd_fld() 2-5, 4-86 fields 1-1
DSS_UDEL_REC 3-8, 3-10, 3-23, 5-86 filter 2-5, 2-8, 4-16, 4-34
DSS_UDEL_REP 3-8, 3-10, 3-23, 5-86 filter criteria 2-5, 2-6
DSS_UINS_REC 3-8, 3-10, 3-19, 5-87 filter expression 2-5
DSS_UINS_REP 3-8, 3-10, 3-19, 5-87 fixed arguments 4-14, 6-6
DSS_UMH_C 3-15, 5-96 flow control 2-11
DSS_UNK_TYPE 3-3, 3-5, 5-92 flow control problem 2-11
dss_unlck_rc() 2-9, 4-87 fmf_cnv_dir() 5-21
DSS_UPD_NOT 3-8, 3-10, 3-21, 5-86,
5-87
G
DSS_UPD_REC 3-8, 3-11, 3-21, 5-42, Get flow control information 4-24, 4-
5-44, 5-45, 5-86, 5-87 26, 4-42, 4-44, 4-92
dss_upd_rec() 2-8, 4-89 Get valid field values 4-90
DSS_UPD_REP 3-8, 3-11, 3-21, 5-86,
5-87 H
dss_user 4-4 header file 4-2, 6-4
DSS_USER_NM_SZ 5-23 HIS type 3-3
DSS_UUPD_REC 3-8, 3-11, 3-21, 5-86
DSS_UUPD_REP 3-8, 3-11, 3-21, 5-86

Index
I read equal 2-7, 4-76

Read event 2-10
index 1-1, 2-7 Read event information 4-78
Insert record 2-8, 4-47
read operations 1-6
ISAM file 3-3
read sequential 2-7
ISF 5-55 Read sequential operation 4-80
ISF type 3-3
read/write 1-5
ISF_F_NOT_OPEN 3-23
records 1-1
ITM 5-58 Recover DSS client 4-75
recovery 2-6
L replica 3-15
licence error 3-15 replication 1-4
Lock record 4-48 replication mechanism 1-5
Lock/Unlock record 2-9 Request data set properties 4-64
Log off 4-50, 4-52 Request DSS properties 4-67
Log on 4-53, 4-97 Request field properties 4-69
log on 4-51 Request index properties 4-73
Log-on/Log-off 2-5 roll back 1-6
rows 1-1
M
memo field 5-45, 5-48 S
MEMO-field 2-9, 4-62 session 2-11, 4-52, 4-53, 4-55, 4-58, 4-
meta data 1-2 64
Set current index 4-85
N Set event request 4-82
notification 2-10 Set/Cancel event request 2-10
Subscribe for events 3-27
O Synchronous access 3-16
synchronous access 3-4
O routines 3-32
Synchronous data access 2-1
Open data set 4-55
Synchronous DSS API functions 2-7
Open event channel 4-58
synchronous operations 2-7
Open/Close data set 2-7
Open/Close event channel 2-10
optional arguments 4-14, 6-6 T
table 1-1
P transaction 1-6
Physical Mapping Layer 3-1
physical unit 3-29 U
Physical units 3-5 UMH 5-96
physical units 3-15 umh_set_code 3-15
PML 3-1, 3-2 umh_set_code() 5-27, 5-28, 5-29, 5-30
primary index 1-1, 2-8 Unbind field 4-86
primary node 1-5 unique index 1-1
Process area 3-31 unknown field 5-45, 5-48
process area 1-4 Unknown type 3-3
UNKNOWN-field 2-9, 4-62
R Unlock record 4-87
Update record 2-8, 4-89
Read data 2-7
user name 1-4

Index

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction ALARM/FAST FAST/TOOLS
IM50M02M00N-01EN/R10.03

IM50M02M00N-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Objectives ..................................................................0-1
0.3 Structure .....................................................................0-1
1 Introduction ..........................................................................1-1
1.1 Interfaces ...................................................................1-1
2 Input events interface ...........................................................2-1
2.1 Introduction ...............................................................2-1
2.2 The interface ..............................................................2-1
2.2.1 Item-based input events ............................................ 2-1
2.2.2 Non-item-based events ............................................. 2-2
3 Definitions interface .............................................................3-1
3.1 Introduction ...............................................................3-1
3.2 The interface ..............................................................3-1
3.2.1 First-out groups ......................................................... 3-1
3.2.2 Acknowledgment types ............................................. 3-2
3.2.3 Alarm attributes of items .......................................... 3-2
4 Acknowledge interface .........................................................4-1
4.1 Introduction ...............................................................4-1
4.2 The interface ..............................................................4-1
4.2.1 Process to communicate with ................................... 4-1
4.2.2 Number of items to acknowledge ............................. 4-1
4.2.3 Acknowledge information ........................................ 4-2
5 Distribution interface ...........................................................5-1
5.1 Introduction ...............................................................5-1
5.2 Connect ......................................................................5-1
5.2.1 Synchronization ........................................................ 5-1
5.2.2 Process to connect to ................................................. 5-2
5.2.3 Base message-id ........................................................ 5-3
5.2.4 Event types ................................................................ 5-3
5.2.5 Destination priority ................................................... 5-3
5.2.6 Alarm selection area ................................................. 5-4
5.2.7 Priority counting destination ..................................... 5-4
5.3 Disconnect .................................................................5-5
5.3.1 Process to disconnect from ....................................... 5-5
ALARM/FAST Programmer’s Guide iii

Table of Contents
5.3.2 Process to disconnect ................................................ 5-5

5.4 Receiving information from ALARM/FAST ........... 5-6
5.4.1 Alarm event message ................................................ 5-6
5.4.2 Overflow message ..................................................... 5-7
5.4.3 Synchronization message .......................................... 5-7
6 Retrieval interface ................................................................ 6-1
6.1 Introduction ............................................................... 6-1
6.2 The interface ............................................................. 6-1
6.2.1 Process to communicate with .................................... 6-1
6.2.2 Request/Reply parameters ......................................... 6-1
7 Recovery interface ............................................................... 7-1
7.1 Introduction ............................................................... 7-1
7.2 The interface ............................................................. 7-1
8 Alarm destinations ............................................................... 8-1
8.1 Introduction ............................................................... 8-1
8.2 VDU-based routine set .............................................. 8-1
8.2.1 Introduction ............................................................... 8-1
8.2.2 Internal window representation ................................. 8-3
8.3 Alarm destination manager ....................................... 8-5
8.3.1 Introduction ............................................................... 8-5
8.3.2 ALDMAN interface .................................................. 8-5
9 Reference Guide ................................................................... 9-1
9.1 Introduction ............................................................... 9-1
9.2 Conventions .............................................................. 9-1
9.3 Error handling ........................................................... 9-2
9.4 General data structures .............................................. 9-3
9.4.1 Alarm message format description (ald_line_fmt) ... 9-3
9.4.2 Screen context (ald_s_cont) ...................................... 9-5
9.4.3 Internal window representation (ald_s_l_elem) ........ 9-5
9.4.4 VDU initialization parameters (ald_vdu_gini) ......... 9-6
9.4.5 Retrieval parameters (alh_his_info) .......................... 9-7
9.4.6 Acknowledge information (alm_ack_inf2) ............... 9-7
9.4.7 Acknowledge time (alm_ack_time) .......................... 9-8
9.4.8 Alarm event (alm_gen_evt) ...................................... 9-8
9.4.9 General alarm event part (alm_alm_evnt) .............. 9-10
9.4.10 Alarm event identification (alm_evnt_id) ............... 9-10
9.4.11 General alarm event info (alm_evnt_inf) ................ 9-10
9.4.12 First-out group definition (alm_fo_def) .................. 9-13
9.4.13 Non-item based event (alm_nib_evnt) .................... 9-13
9.4.14 Overflow message (alm_q_ovflw) .......................... 9-14
9.4.15 Initiate item recovery message (alm_recover) ........ 9-14
9.4.16 Selection criterion structures ................................... 9-14
9.4.17 Alarm event selection bits ....................................... 9-15
9.4.18 Alarm source id (alm_src_id) ................................. 9-15
9.4.19 Alarm subject id (alm_subj_id) ............................... 9-15
iv ALARM/FAST Programmer’s Guide

Table of Contents
9.4.20 Synchronization message (alm_sync_upd) ............. 9-16

9.4.21 Get alm parameters info (alm_get_inf) ................... 9-16
9.5 Routines and BUS/FAST Messages ........................9-17
9.5.1 Compare selection criteria ...................................... 9-18
9.5.2 Decode event bits .................................................... 9-20
9.5.3 Format ASCII message for alarm event .................. 9-21
9.5.4 Get alarm message format from setup file .............. 9-23
9.5.5 User formatting routine ........................................... 9-24
9.5.6 Handle acknowledge action (1) .............................. 9-26
9.5.7 Handle acknowledge action (2) .............................. 9-27
9.5.8 Handle bottom browse command ........................... 9-28
9.5.9 Handle exit actions for destination ......................... 9-29
9.5.10 Fill window ............................................................. 9-30
9.5.11 Handle alarm event as generated by the
alarm kernel ............................................................ 9-31
9.5.12 Initialize VDU-based alarmdestination
(general) .................................................................. 9-32
9.5.13 Initialize VDU-based alarmdestination ................... 9-33
9.5.14 Handle next event browse command ...................... 9-35
9.5.15 Handle next page browse command ....................... 9-36
9.5.16 Handle overflow message generated by the
alarm kernel ............................................................ 9-37
9.5.17 Handle previous event browse command ............... 9-38
9.5.18 Process alarm event for a VDU type
destination ............................................................... 9-39
9.5.19 Handle previous page browse command ................ 9-40
9.5.20 Handle processing of synchronization
message ................................................................... 9-41
9.5.21 Handle top browse command .................................. 9-42
9.5.22 Retrieve historical information (general) ................ 9-43
9.5.23 Retrieve historical information ............................... 9-43
9.5.24 Retrieve conditional historical
information (general) .............................................. 9-46
information .............................................................. 9-47
9.5.26 Acknowledge of items (1) ....................................... 9-49
9.5.27 Acknowledge of items (2) ....................................... 9-50
9.5.28 Delete acknowledgment type in alarm kernel ......... 9-52
9.5.29 Insert acknowledgment type in alarm kernel .......... 9-53
9.5.30 Modify acknowledgment type alarm kernel ........... 9-54
9.5.31 Compare source identification ................................ 9-55
9.5.32 Compare selection criteria ...................................... 9-56
9.5.33 Disconnect destination from alarm kernel .............. 9-57
9.5.34 Connect destination to alarm kernel (general) ........ 9-58
9.5.35 Indicate deletion of first-out group ......................... 9-60
9.5.36 Indicate insertion of first-out group ........................ 9-61
9.5.37 Indicate modification of first-out group .................. 9-62
9.5.38 Notify alarm kernel of item activation .................... 9-63
9.5.39 Notify alarm kernel of item deactivation ................ 9-64
9.5.40 Notify alarm kernel of item modification ............... 9-65
ALARM/FAST Programmer’s Guide v

Table of Contents
9.5.41 Non item-based event interface ............................... 9-66

9.5.42 ALDMAN attach message ...................................... 9-67
9.5.43 ALDMAN detach message ..................................... 9-68
9.5.44 Change ASA message ............................................. 9-69
9.5.45 Recover message ..................................................... 9-70
9.5.46 Get ALM parameter info ......................................... 9-71
Appendix A:Examples ................................................................... A-1
A.1 Introduction .............................................................. A-1
A.2 Usage of V.D.U.-based routine set .......................... A-1
A.3 Usage of internal window representation ................ A-2
vi ALARM/FAST Programmer’s Guide

Objectives Preface
0 Preface
0.1 Objectives
functionality of ALARM/FAST from the programmers point of
view.
• Provide experienced users with a reference for the usage of the
several ALARM/FAST interfaces and auxiliary routines.

programming language.
The reader of this document is assumed to have a knowledge of the
contents of the following documents (to be read in the indicated order):
• USER/FAST, FAST/TOOLS User Manual (new HMI style),
specifically the part describing the basics of the alarming
mechanism from the system managers point of view.
• ALARM/FAST System Integrator’s Manual.
Furthermore, the reader is assumed to have a knowledge of the contents
of:
• The BUS/FAST message passing facilities.
• The BUS/FAST error logging facility.
• The FAST/CONVENTIONS reference guide volume 1.
0.3 Structure
This manual contains the following chapters.
• Chapter 1 introduces the reader to the external interfaces of
ALARM/FAST.
ALARM/FAST Programmer’s Guide 0-1

• Chapter 2 up to and including chapter 7 describe these external

interfaces more in detail.
• Chapter 8 describes a set of auxiliary ALARM/FAST routines that
can be used to implement (new) alarm destinations.
• Chapter 9 is the reference guide for the ALARM/FAST routine set.
It contains a description of all datastructures and routines that might
be of interest for the application programmer.
• Appendix A contains examples.

1 FAST/TOOLS User Manual, volume 1 and 2.
These manuals provides basic information about the functionality
of ALARM/FAST.
2 ALARM/FAST System Integrator’s Manual.
This manual provides system integrators with an overview of the
configuration possibilities of ALARM/FAST.
Furthermore this manual gives a description of the mechanisms that
a system integrator needs to have a knowledge of, to be able to
configure ALARM/FAST.
3 BUS/FAST Programmer’s Guide.
- Volume 1: DUR.
- Volume 2: UMH.
that are used.
- Volume 3: FAST/SUPPORT LIBRARY (FSL).
software.
4 FAST/CONVENTIONS Reference Guide volume 1.

CONVENTION MEANING
passed.
0-2 ALARM/FAST Programmer’s Guide


optional.
DUR_NOWAIT.
input.
returns.
output.
literally.
n.u. not used.
a terminal.
from the user.


Interfaces Introduction
1 Introduction
1.1 Interfaces
Figure 1-1, depicts from a global point of view, the external interfaces
of ALARM/FAST.
input events
recovery
retrieval ALARM/ definitions

FAST
acknowledge
distribution
Figure 1-1 The external interfaces of ALARM/FAST
• Input events:
Via this interface, ALARM/FAST is notified about:
- Events caused by status changes of items, the so called item-
based events.
- Events generated by application programs, the so called non-
item-based events.
• Definitions:
Via this interface, ALARM/FAST is notified about changes in the
definitions of first-out groups, acknowledgment types and alarm
attributes of items.
• Acknowledge:
Via this interface, application programs have the possibility to
acknowledge items.
• Distribution:
connect to ALARM/FAST in order to receive the events that
ALARM/FAST is able to generate.
• Retrieval:
retrieve alarm information that has been stored by ALARM/FAST.
• Recovery:

Introduction Interfaces
initiate a so called alarm recovery action for an item.

These interfaces are described in more detail, in the subsequent chapters
of this document in the same order as listed above.

Introduction Input events interface
2 Input events interface
2.1 Introduction
The input events interface consists of two separate parts:
• Item-based input events.
• Non-item based input events.
Both type of events are handled by the alarm kernel process of ALARM/
FAST. When such an event is received, the alarm kernel will transform
the information to an alarm event and distributes this event among its
destinations.
The item-based input events interface is used by ALARM/FAST to
detect status changes on items. ALARM/FAST uses the main event
mechanism of ITEM/FAST in order to obtain this information. The
item-based input events interface is not directly accessible by
application programs. However it has been described here because
application programs have the possibility to influence the contents of
item-based events.
The non-item-based input events interface is fully accessible by
application programs. This interface offers application programs the
possibility to notify ALARM/FAST about events that they have
detected.
2.2 The interface
2.2.1 Item-based input events
An item-based event is a DUR message sent by ITEM/FAST each time

the status of an item changes. This DUR message contains information
such as the identification of the item, the old and new status of the item
and the time the status change occurred.
Furthermore, the item-based event may contain so-called update
information. For more information about this update information
mechanism, please consult the ITEM/FAST product documentation.
If update information is present, the update information is used to

Input events interface The interface
overrule specific fields in the alarm event generated by the alarm kernel.
In this way, so-called diagnostic texts can be linked to an item that is
used for diagnostic purposes.
The following fields in the alarm event can be overruled by update
information:
• Item name (name1, name2, name3 and name4 field)
This can be done by using the update info codes:
- ITM_UPD_INF_NAM1
- ITM_UPD_INF_NAM2
- ITM_UPD_INF_NAM3
- ITM_UPD_INF_NAM4
• Status text
This can be done by using the update info code:
- ITM_UPD_INF_STA_TXT
• Item description
This can be done by using the update info code:
- ITM_UPD_INF_ITM_DSC
These update info codes are defined in the headerfile "itm_usr.h".
2.2.2 Non-item-based events
A non-item-based event is just like the item-based event a DUR

message. This event, however, can be generated by any process. The
event will always result directly (without intervening ALARM/FAST
mechanisms) in the generation of an alarm event of type informational.
Non-item-based input events could be used to log a non-item related
alarm situation or the recovery from such an alarm situation.
Example: A software module could use the non-item-based event to
have a message logged somewhere on an alarm device at the moment it
discovers that it is not able to communicate with another software
module. As soon as it discovers that it is able to communicate again, it
could use non-item-based event mechanism to log this.
All the information put in the non-item-based event will also appear in
the alarm event of type informational. By putting information in the non-
item-based event one should bear in mind that some of the information
is used by the alarm kernel to check whether or not a particular
destination should receive the informational event that is derived from
this event (the filter information).
The routine that represents the non-item-based event part of the input
events interface is: alm_nib()

Introduction Definitions interface
3 Definitions interface
3.1 Introduction
The definitions interface is used to notify the alarm kernel process of
ALARM/FAST, about changes that are made at run-time (e.g. via the
FAST/TOOLS user interface) in the definition of:
• First-out groups.
• Acknowledgment types.
• Alarm attributes of items.
The definition of first-out groups, acknowledgment types and alarm
attributes of items, are stored in databases. During start up of ALARM/
FAST most of this information is read and stored in the data area of the
alarm kernel process.
The definitions interface of ALARM/FAST must be used to notify the
alarm kernel about run-time changes (insert, delete and modify actions)
in these databases. By notifying the alarm kernel process about these
changes at run-time, the alarm kernel will adapt its internal
datastructures to reflect the new situation and will use the changed data
when performing its task.
3.2 The interface
3.2.1 First-out groups
The following routines are available to notify the alarm kernel when
changes are made in the first-out groups database:
• alm_foi_alm():
When a new first-out group is inserted in the first-out group
database.
• alm_fod_alm():
When a first-out group is removed from the first-out group
database.
• alm_fom_alm():
When the definition of a first-out group is changed in the first-out
group database.

Definitions interface The interface
3.2.2 Acknowledgment types
changes are made in the acknowledgment types database:
• alm_acki_alm():
When a new acknowledgment type is inserted in the
acknowledgment type database.
• alm_ackd_alm():
When an acknowledgment type is removed from the
• alm_ackm_alm():
When the definition of an acknowledgment type is changed in the
3.2.3 Alarm attributes of items
changes are made to the alarm attributes of items (stored in the item
definition database):
• alm_itm_act():
This routine must be called in the following situations:
- When the definition of an existing item is modified in the sense
that it should be monitored by ALARM/FAST.
- When a new item is inserted in the item definition database and
the item should be monitored by ALARM/FAST.
• alm_itm_dac():
This routine must be called in the following situations:
- When an item should no longer be monitored by ALARM/
FAST.
- When an entire item is deleted from the item definition
database.
• alm_itm_mod():
When the definition of the alarm attributes is changed in the item
definition database.

Introduction Acknowledge interface
4 Acknowledge interface
4.1 Introduction
ALARM/FAST offers a routine interface to acknowledge items. Via this
interface an application is able to acknowledge one specific item or a
number of items at once. For every item the application wants to
acknowledge, the alarm event as previously generated by ALARM/
FAST, should be offered to the routine interface.
For every item successfully acknowledged, ALARM/FAST distributes
an alarm event of type acknowledge.
The routines that make up the acknowledge interface are:
• alm_ack_itm():
Acknowledge without the possibility to specify acknowledge
information.
• alm_ack_itm2():
Acknowledge with possibility to specify acknowledge information.
4.2 The interface

of these routines, will be introduced in the following sections.
4.2.1 Process to communicate with
When the acknowledge routine is called, it is possible to specify the

DUR address of the alarm kernel process to communicate with. When
this information is not specified, the routine assumes the caller of the
routine wants to communicate with the process ALM on the local node.
4.2.2 Number of items to acknowledge
The amount of items to acknowledge at once, is limited (see reference

section of this document). If the number of events offered to the

Acknowledge interface The interface
acknowledge routine exceeds this maximum, the routine returns

FALSE.
4.2.3 Acknowledge information
In addition to the acknowledge event, ALARM/FAST is also able to

send an “acknowledge information event” (depending on the contents of
the alarm kernel setup file). This event contains information that is
supplied via the acknowledge information argument of the routine
interface.

Introduction Distribution interface
5 Distribution interface
5.1 Introduction
The distribution interface of ALARM/FAST can be split up into the
following parts:
• A part via which an application program connects to ALARM/
FAST.
• A part via which an application program disconnects from
ALARM/FAST.
• A part via which application programs being connected to
ALARM/FAST, receive information being generated by ALARM/
FAST.
These parts are described in more detail in the following sections.
5.2 Connect
When a destination wants to receive alarm events via the distribution
interface of ALARM/FAST, the destination has to connect to ALARM/
FAST. This is done via one of the routines:
• alm_dst_gcon()
• alm_dst_con()
of these routines, will be introduced in the following subsections.
5.2.1 Synchronization
In situations where a destination obtains information from both the

alarm kernel and the alarm storage process, a synchronization
mechanism is needed by the destination. This mechanism enables the
destination:
1 To determine if the information received from the alarm kernel is
more up to date compared to the information retrieved via the
storage process.

Distribution interface Connect
2 To determine if both the alarm destination and the alarm storage

process are in a consistent state in the sense that they both have
processed the same amount of events.
The following example illustrates the need for such a synchronization
mechanism:
Suppose a destination requests information from the alarm storage
process. After issuing the request, the destination blocks wait for the
reply from the alarm storage process. Suppose in the mean time, the
alarm kernel puts an alarm event in the queue for the destination. When
the reply from the alarm storage process has been processed, the
destination must decide whether or not to process the alarm event
queued by the alarm kernel. There is a possibility that this message has
already been received via the reply from the alarm storage process.
To cope with these types of problems, the following synchronization
mechanism is used:
• Alarm events sent by the alarm kernel to alarm destinations contain
a “stamp” field. Each time the alarm storage process receives an
alarm event, it saves the contents of this stamp field.
• When an alarm destination requests information from the alarm
storage process, the last stamp value received by the alarm storage
process is put in the reply to the destination.
• With this information, the destination is able to determine whether
or not it should ignore particular alarm events that reside in its
queue after it processed the reply from the alarm storage process.
This mechanism is based on the assumption that the alarm kernel sends
alarm events to the storage process before it sends alarm events to the
alarm destinations. How this can be arranged, is described in SubSection
5.2.5.
5.2.2 Process to connect to
When the connect routine is called, it is possible to specify the DUR

address of the process to which the caller of the routine wants to be
connected. When this information is not specified, the routine will
assume the caller of the routine wants to connect to the process ALM on
the local node.

Connect Distribution interface
5.2.3 Base message-id
When an application has successfully connected to ALARM/FAST, the

application should be prepared to receive one of the following types of
messages:
• alarm event messages
• overflow messages
• synchronization messages
An explanation for each message type can be found in the ALARM/
FAST System Integrator’s Manual.
Each of these message types has its own message identification
(message code). This message identification is calculated by adding a
fixed message type dependent offset to a so called base message-id.
The base message-id is application dependent and must be specified by
the application when it connects to ALARM/FAST.
For ALARM/FAST the 9 numbers following the base message-id, are
reserved for other alarm kernel messages. So, by specifying a base
message-id with value 3, the numbers 4 up to and including 12 can not
be used by the alarm destination for other purposes.
The reference section in this document describes the message type
dependent offsets that have been defined for ALARM/FAST.
5.2.4 Event types
The event type determines which type of alarm events (direct, alarm,
repeat, etc.) an alarm destination wants to receive. For each possible
alarm event type, an alarm event type bit has been defined.
An alarm destination specifies the type of alarm events it wants to
receive, by bitwise ORing the required alarm event type bits.
For a description of these alarm event type bits please refer to the
reference section in this document.
5.2.5 Destination priority
An application has to specify a destination priority when it connects to

the alarm kernel. This information enables the alarm kernel to determine
which of the connected destinations events should be sent to first. This
is important information in situations where an application is connected
to the alarm kernel and also retrieves information from the alarm storage

Distribution interface Connect
process (see SubSection 5.2.1). For this reason, a destination should use
a correct priority value when it connects to the alarm kernel.
Two destination priority groups apply:
• Destinations storing alarm information.
• Destinations displaying alarm information.
The alarm kernel sends events to all “storing” destinations first. After
this the “displaying” destinations are serviced.
5.2.6 Alarm selection area
The alarm selection area offers the possibility for an alarm destination to
specify a filter. Only alarm events satisfying this filter, are sent to the
alarm destination. The event types referred to in SubSection 5.2.4, are
logically ANDed with the contents of the alarm selection area.
Alarm selection areas are stored in a database and can be retrieved via
GIN routines.
5.2.7 Priority counting destination
For the ‘change priority mechanism’, it is necessary for the connecting

destination to indicate whether or not it must be regarded as ‘priority
counting destination’.
Whether or an alarm destination should be regarded as such, can be
specified during the connect action.
This paragraph describes the selection criteria. These “selection criteria”

were used as filter mechanism in previous versions of ALARM/FAST.
The functionality of the selection criteria is fully covered by the alarm
selection area mechanism. Selection criteria are still available for
upwards compatibility reasons, but the use of alarm selection areas, is
preferred.
The selection criteria the destination has to specify are subdivided into
two parts; a required part and an optional part.
• Required part:
The required part describes the type of alarm events a destination
wants to receive. By means of a bitmask a destination has the

Disconnect Distribution interface
possibility to specify these type of alarm events (see also

SubSection 5.2.4.)
• Optional part:
The optional part offers the possibility for a destination to state
which characteristic values the alarm event should contain, before
the alarm kernel sends it to the destination. Optional selection
criteria are mutually ORed. The required part of the selection
criteria is logically ANDed with the optional part. If no optional
part is specified, only the required part is checked.
It is possible for a destination to specify one or more of the
following optional selection criteria:
- Installation name
- Unit name
- Item name
- Subitem name
- Item id
- Array value
5.3 Disconnect
A destination that no longer wants to receive events, should disconnect
from ALARM/FAST. After the destination has disconnected, ALARM/
FAST has no knowledge about this destination anymore.
The routine that should be used to disconnect from ALARM/FAST is
alm_dst_dcon().
of this routine, are introduced in the following subsections.
5.3.1 Process to disconnect from
When the disconnect routine is called, it is possible to specify the DUR

address of the process to disconnect from. When this information is not
specified, the routine assumes, the caller of the routine wants to
disconnect from the process ALM on the local node.
5.3.2 Process to disconnect
With the disconnect action it is possible to specify the DUR address of

the process that should be disconnected from ALARM/FAST. This

Distribution interface Receiving information from ALARM/FAST
option enables applications, to disconnect other processes.

When no DUR address is specified, the disconnect routine assumes the
caller of the routine need to be disconnected.
5.4 Receiving information from ALARM/FAST

Once an application is connected to ALARM/FAST, it should be
prepared to receive the following type of messages:
• alarm event messages
• overflow messages
• synchronization messages
Each of these message types has its own message identification code.
This code is alarm destination specific and is determined by the base
message id specified by the destination at the time it connected to
ALARM/FAST.
A description of each of these message types is given in the following
subsections.
5.4.1 Alarm event message
Alarm events are DUR messages generated by the alarm kernel. An

alarm event contains information related to the item or object the event
is related to.
The layout of the event conforms to the structure alm_gen_evt if the
connect to the alarm kernel is done via the routine alm_dst_gcon(). If
the connect is done via the routine alm_dst_con(), the layout of the
event conforms to the structure alm_alm_evnt.
An alarm event can be generated as a result of:
• Non-item-based or item-based events.
• Internal alarm kernel events (e.g. delay timer times out).
• Inconsistency recovery actions.
• The update of internal alarm kernel definitions.
• The acknowledge action on an item.
Whether or not a particular destination receives all types of alarm events
depends on the selection filter the destination specified when it
connected to ALARM/FAST.

Receiving information from ALARM/FAST Distribution interface
The field in the alarm event enabling a destination to recognize the type
of alarm event, is filled with a particular bitmask. The bits that may be
set in this field, can be subdivided into two groups: selection bits and
informational bits. For more information about these selection and
informational bits, please consult the reference section of this document.
5.4.2 Overflow message
If a queue overflow occurs for an alarm destination ALARM/FAST

detects such an overflow and performs the following actions:
• It stops sending messages to the destination concerned.
• It starts counting the number of alarm events the destination is
missing.
• It checks at regular time intervals whether or not the number of
messages in the queue of the destination concerned, has dropped
below a certain value. If this is the case, ALARM/FAST sends an
overflow message to the destination concerned.
When the overflow message has been successfully sent to the
destination, the destination will receive events from ALARM/FAST as
before.
An overflow message contains the following information:
• The number of alarm events the destination missed since ALARM/
FAST stopped sending events to the destination.
• A timestamp indicating at which point in time the first event was
lost.
The layout of the overflow message conforms to the structure
alm_q_ovflw.
The overflow event cannot be filtered by a destination.
5.4.3 Synchronization message
As described in SubSection 5.2.1, a destination both connected to the

alarm kernel and requesting information from the alarm storage process,
needs a synchronization mechanism. The synchronization information
used by a destination, is obtained from a field in the alarm event
message.
If a destination specified a selection filter when it connected to the alarm
kernel, it is very likely that the destination will not receive all event
messages generated by the alarm kernel. Because of this, a destination

Distribution interface Receiving information from ALARM/FAST
could incorrectly assume that it is not synchronized. This causes the

destination to perform unnecessary actions.
To solve this problem, ALARM/FAST sends a so called
synchronization message in situations where the alarm event it normally
would have sent, is not passed to a destination (due to its selection filter).
This message contains the “synchronization stamp” value that the
destination normally would have received via the alarm event.
Only destinations that communicate both with the alarm kernel and the
alarm storage process, use the information in the message. Other
destinations should ignore the information.

Introduction Retrieval interface
6 Retrieval interface
6.1 Introduction
ALARM/FAST offers a routine interface to retrieve alarm events that
have been stored by the alarm storage process. With this retrieval action
it is possible to specify a selection filter. Depending on the contents of
this selection filter, only a subset of the alarm events stored, will be
retrieved.
The routines that make up the retrieval interface are:
• alh_get_ghis():
Retrieve alarm events with possibility to specify contents of alarm
selection area.
• alh_get_hist():
Retrieve alarm events with possibility to use “old” selection criteria
mechanism. This routine is still available because of upwards
compatibility reasons.
6.2 The interface

of these routines, will be introduced in the following subsections.
6.2.1 Process to communicate with
When the retrieval routine is called, it is possible to specify the DUR

address of the alarm storage process to communicate with. When this
information is not specified, the routine assumes the caller of the routine
wants to communicate with the process ALH on the local node.
6.2.2 Request/Reply parameters
The following parameters apply when performing the retrieve request:

• Storage type:
The storage type the alarm events must be retrieved from, must be

specified. The following storage types can be chosen from:

- Chronological storage type:
This storage type contains all alarm events generated by the
alarm kernel, sorted on time.
- Priority based current storage type:
This storage type contains the alarm events of all currently
outstanding alarms. These alarm events are sorted on priority.
Alarm events with equal priority are sorted on time.
- Time based current storage type:
This storage type contains the alarm events of all currently
outstanding alarms. These alarm events are sorted on time.
• Keyvalue of the event to start reading from.
• Include flag:
Via this flag applications can indicate whether the “event to start
reading from” should be included in the reply or not.
• Storage group:
This information must only be supplied in case the caller of the
routine wants to obtain information from the chronological storage
type.
• Read direction:
Via this parameter the caller of the routine has the possibility to
indicate whether it wants to read in the forward (ascending
keyvalue) or backward (descending keyvalue) direction (relative to
the keyvalue of the event from which reading started).
• Number of events to read.
• Required alarm event types.
• Alarm selection area.
If the caller of the routine wants to retrieve a subset of the
information stored, the caller has the possibility to use the alarm
selection area mechanism.
The following parameters are returned to the caller of the routine:
• Number of events actually read.
• The events read.
• The synchronization stamp of the alarm storage process (see also
5.2.1).

Introduction Recovery interface
7 Recovery interface
7.1 Introduction
In extreme situations, BUS/FAST queues might be flooded with
messages, resulting in data being lost. If such a situation occurs
inconsistency might be introduced between the information possessed
by:
• ITEM/FAST and the alarm kernel and/or
• The alarm kernel and its alarm destinations.
ALARM/FAST contains a recovery function to resolve the
inconsistency. By sending a ‘start recovery session’ request to ALM a
total recovery can be initiated. When the ALMUPD process is started it
will send one time this ‘start recovery session’ request. For more
information about this function, please consult the ALARM/FAST
System Integrator’ Manual.
Via the recovery interface, application programs have the possibility
themselves, to initiate an alarm recovery action for an item.
7.2 The interface

The recovery interface is a message interface. The body of the message
must contain the alarm parameters of the item to be recovered. These
alarm parameters can be retrieved via a GIN routine call.
When the alarm kernel receives the recovery message, it performs the
following actions:
• It checks and updates if necessary its internal administration.
• It constructs a ‘recovery’ type alarm event and distributes this
alarm event among alarm destinations being interested in this type
of event.

Recovery interface The interface

Introduction Alarm destinations
8 Alarm destinations
8.1 Introduction
To support the implementation of (new) alarm destinations, a set of
auxiliary ALARM/FAST routines are available. These routines are part
of the ALD brick of ALARM/FAST.
A detailed description of the usage of these routines is given in the
reference section in this document. With this information the usage of
most of these ‘ald_...()’ routines is obvious.
Because the usage of the so called VDU-based routine set is a little bit
more complex, the usage of these routines is explained in this chapter.
Furthermore this chapter describes how an alarm destination should
interface with a so called ‘alarm destination manager’ (ALDMAN).
Such an alarm destination manager is supposed to be an application
program that directs alarm destinations to dynamically change their
alarm selection filters.
8.2 VDU-based routine set
8.2.1 Introduction
A VDU-based alarm destination is regarded as a process that manages

an alarm overview. This alarm overview is assumed to be displayed in a
window on a Video Display Unit.
To support the development and implementation of VDU-based
destinations, the VDU-based routine can be used.
In the window managed by a VDU-based alarm destination, several
types of alarm overviews can be displayed. Possible overview types are:
• Chronological overview
• Priority based current overview
• Time based current overview
The window can have three so called global positions. These are:

Alarm destinations VDU-based routine set
• TOP:
Global position of the window is at the top of an overview. In a
window with this global position, an overview is built up starting at
the first line of the window. This means that if there is not enough
information to fill up the entire window, the last line or lines in the
window will be empty.
• BOTTOM:
Global position of the window is at the bottom of an overview. In a
window with this global position, an overview is built up starting at
the last line of the window. This means that if there is not enough
information to fill up the entire window, the first line or lines in the
window will be empty.
• BETWEEN:
Global position of the window is somewhere between top and
bottom of an overview. In a window being assigned this global
position an overview is build up, starting at the first line of the
window. This means that if there is not enough information to fill
up the complete window, the last line or lines in the window will be
empty.
The VDU-based routines store the contents of a window in a data
structure called “internal window representation”. This data structure is
described in more detail in the following section.
Another important data structure used by the VDU-based routine set, is
the “screen context”. A pointer to this data structure is passed to each
routine of the VDU-based routine set.
The VDU-based routine set contains routines to:
• Initialize and terminate VDU-based destinations:
ald_vdu_ini()
ald_vdu_gini()
ald_vdu_exit ()
• Handle the events sent by ALARM/FAST to its (VDU-based)
destinations:
ald_vdu_gevt ()
ald_vdu_ovf ()
ald_vdu_sync()
• Handle the events initiated by users (browse commands and
acknowledge actions):
ald_vdu_ack ():
ald_vdu_ack2():
ald_vdu_bot ()
ald_vdu_nev ()
ald_vdu_npg ()

VDU-based routine set Alarm destinations
ald_vdu_pev ()
ald_vdu_ppg ()
ald_vdu_top ()
8.2.2 Internal window representation
The contents of a window as maintained by the VDU-based routine set,

is represented as a double linked list. Each element in this list, represents
a message in the window.
Amongst some other information, a list element contains the following
information:
• A relative message number.
• The alarm event represented by the list element.
• The ASCII text displayed in the window and related to the alarm
event.
The relative message number of an element in the linked list, indicates
for which lines in the window a message is available in the linked list.
This will be illustrated by means of the following examples:
Consider a window in which 6 lines can be displayed. Suppose 2 lines
are needed to display a complete message in the window. This means 3
messages will fit in the window.
(1)
(2)
(3)
External representation of contents

of window
(1) (2) (3)
Internal representation of contents

of window
Figure 8-1 External and Internal window representation

Alarm destinations VDU-based routine set
In Figure 8-1 the relation between the external and internal

representation of a window has been depicted. Each message in the
window (the external representation), is given a so called message
position number. When the window is full, each message position
number is related to a relative message number in the linked list.
Now consider the next situation (see Figure 8-2). In this case, the
window is not completely full and the global position is either TOP or
BETWEEN. In this example not every message position number is
related to a relative message number in the linked list.’
(1)
(2) (1) (2)
(3)
External representation Internal representation

of contents of window of contents of window
Figure 8-2 TOP or BETWEEN position
Figure 8-3 describes another situation in which the window is not

completely filled. In this example, the global position of the window is
BOTTOM. The look of the overview differs from the previous example,
due to a different global position of the window. This applies to both the
external and internal representation of the window.
(1)
(2)
(2) (3)
(3)
External representation Internal representation

of contents of window of contents of window
Figure 8-3 BOTTOM position
An example of how this relative message number can be used to display

information in a window, is given in the appendix in this document.

Alarm destination manager Alarm destinations
8.3 Alarm destination manager
8.3.1 Introduction
Operators maybe interested in only a subset of the alarms that occur

within the system. For this reason each alarm destination may be
equipped with an alarm filter. This filter, the so called alarm selection
area, determines the type of alarm events being sent to the destination.
As the operators interest may change from time to time (e.g. difference
between night and day), the alarm filter being used must change as well.
To be able to make run-time modifications to the alarm filter, the
concept ‘alarm destination manager’ (ALDMAN) has been introduced.
8.3.2 ALDMAN interface
The ALDMAN process, is a system integrator written application which

is capable of dynamically changing the selection filters for alarm
destinations.
The interface between an alarm destination and the ALDMAN process
is depicted in Figure 8-4:
attach
detach
Destination
ALDMAN
change alarm selection
Figure 8-4 ALDMAN interface
The ALDMAN interface consists of the following parts:

• Attach to the ALDMAN
If an ALDMAN is specified in the alarm destination setup file, the
alarm destination will send an attach request to the ALDMAN
during initialization. The ALDMAN can use these requests to build
up an administration of all currently running destinations and the
alarm selection areas they use.

Alarm destinations Alarm destination manager
• Detach from the ALDMAN

If an alarm destination is stopped, then this destination will issue a
detach request, to let the ALDMAN clean up its administration.
• Change alarm selection area requests
The ALDMAN can send ‘change alarm selection area’ requests to
attached alarm destinations. In order to let the new alarm selection
area become effective the alarm destination has to dis- and
reconnect the alarm kernel.
The lay-out of these messages is discussed in the reference section of
this document please refer to sections 9.5.42, 9.5.43 and 9.5.44.

Introduction Reference Guide
9 Reference Guide
9.1 Introduction
This chapter serves as a reference for the ALARM/FAST interface
routines and related structure definitions. This chapter describes:
• Conventions
• Error handling
• Data structures
• Routines
9.2 Conventions
All ALARM/FAST routines have ‘C’-type interfaces. The syntax of all
routines as well as the examples comply with ‘C’ language conventions.
All parameters which are passed by reference must be assumed to be
Most of the routines return a TLS_BOOLEAN as the status indicator.
This is shown in the syntax descriptions as [status=].
Example:
[status=] alc_cri_matg(umh_c,....)

struct ....; /* .... */
....
Normally this return value will be tested directly rather than being
if (!alc_cri_matg(....))
{
/* error - use UMH context to log the error(s)*/
}

Reference Guide Error handling
The header files alm.h, alh.h, ald.h and alc.h contain all definitions that
might be necessary when calling ALARM/FAST routines.
The names of routines, data structures, and defined constants being part
of ALARM/FAST, all start with one of the following three letters ‘alc’,
‘ald’, ‘alh’ or ‘alm’.
letters.
9.3 Error handling

Most of the ALARM/FAST routines use the standard FAST/TOOLS
error handling facilities provided by UMH.
Details of the UMH error handling facilities can be found in the
BUS/FAST Programmer’s Guide, part UMH.

General data structures Reference Guide
9.4 General data structures

In order to have a reference to the structures mentioned in this chapter,
the definitions of these structures are given in the following sections.
All data structures are mentioned in alphabetical order.
9.4.1 Alarm message format description (ald_line_fmt)

An array of these data structures describes the layout of an alarm
message. The last element in such an array must contain the value ‘-1’
for all fields of the element. This is to signal the end of the array to
routines that use this data structure.
struct ald_line_fmt
{
TLS_SHORT msg_unit; /* Message unit */
TLS_SHORT size; /* Length of message unit
field */
};
An overview of message unit codes and their meaning are listed below:
Message unit codes and their meaning
Message unit code Meaning
ALD_ACKN_FMT Acknowledge indicator.

ALD_ENG_UNIT_FMT Engineering units
ALD_ITM_DESC_FMT Item description
ALD_NAM1_FMT Installation name of item
ALD_NAM2_FMT Unit name of item
ALD_NAM3_FMT Tag name of item
ALD_NAM4_FMT Tag name of subitem
ALD_NWLN_FMT Carriage return/line feed
ALD_PRIO_FMT Priority value
ALD_QC_DEC_FMT Quality value in decimal format
ALD_QC_HEX_FMT Quality value in hexadecimal format
ALD_SPAC_FMT Space
ALD_TDEF_FMT Time (default format)
ALD_TFMT_FMT Time (free format)
ALD_TANS_FMT Time (ANSI format)

Reference Guide General data structures
Message unit codes and their meaning
Message unit code Meaning

ALD_TEUR_FMT Time (european format)
ALD_TEXT_FMT Status text
ALD_TGEN_FMT Time (general format)
ALD_TJUL_FMT Time (julian format)
ALD_TYPE_FMT Event type
ALD_VAL_FMT Item value
ALD_STDEF_FMT Time original signal (default format)
ALD_STFMT_FMT Time original signal (free format)
ALD_STANS_FMT Time original signal (ANSI format)
ALD_STEUR_FMT Time original signal (european format)
ALD_TGEN_FMT Time original signal (general format)
ALD_TJUL_FMT Time original signal (julian format)
ALD_EVT_SOURCE_FMT Event source (OPC AE client)
ALD_EVT_CAT_FMT Event catagory (OPC AE client)
ALD_COND_NM_FMT Event condition(OPC AE client)
ALD_SUBC_NM_FMT Event sub-condition (OPC AE client)
ALD_ACTOR_ID_FMT Event actor id (OPC AE client)
ALD_C_EVT_SOURCE_FMT Event source ot item descr. (OPC AE client)
ALD_C_EVT_CAT_FMT Event catagory and event type (OPC AE client)
ALD_C_COND_NM_FMT Event condition and alarm text (OPC AE client)
ALD_C_SUBC_NM_FMT Sub-condition and alarm text (OPC AE client)
ALD_C_ACTOR_ID_FMT Actor id or “FAST/TOOLS” (OPC AE client)
The message units starting with ALD_C_' can be used as so-called

'combined keywords'. OPC AE event information is only available in
events coming from OPC AE clients. To avoid gaps in alarm messages
for events without OPC AE information the combined keywords can be
used. They display either the corresponding OPC AE information if
available or an other event property.

9.4.2 Screen context (ald_s_cont)

Via this data structure, access can be achieved to the internal
representation of an alarm overview.
The contents of the structure, as depicted below, is not complete. Only
the most important fields of this structure have been depicted.
struct ald_s_cont
{
.......
.......
TLS_SHORT overview_type;/* Kind of overview */
TLS_SHORT nr_char_lin; /* Maximum number of
characters per line */
TLS_SHORT lin_per_msg; /* Number of lines per
message */
TLS_SHORT max_msg; /* Maximum number of messages
per page */
TLS_SHORT msg_used; /* Number of messages
currently in use */
TLS_SHORT nr_wdw_chg; /* Current number of window
changes */
struct ald_s_l_elem *first_line;
/* First element of list
making up the contents
of the window */
struct ald_s_l_elem *last_line;
/* Last element of list
making up the contents
of the window */
....
....
};
The field overview_type is one of:

• ALD_CUR_T: for time-based current overview
• ALD_CUR_P: for priority-based current overview
• ALD_CHR: for chronological overview
The field nr_wdw_chg indicates the number of changes in the window,

after one of the VDU-based routines has been called. By inspecting this
field after a call to one of these routines, it is possible to prevent an alarm
destination from performing irrelevant write actions in the window.
9.4.3 Internal window representation (ald_s_l_elem)

This data structure represents one element of the internal window

representation of an alarm overview. The entire overview is represented

by a linked list of these datastructures.
struct ald_s_l_elem
{
TLS_SHORT rel_msg_nr; /* Relative message number
within window */
TLS_SHORT upd_nr; /* Used for effective
information update */
TLS_LONG gen_evt[(ALM_MAX_GEN_EVT+3)/sizeof(TLS_LONG)];
/* The alarm event */
char txt[ALD_MAX_CHAR_PER_MSG];
/* ASCII-equivalent of
alarm event */
struct ald_s_l_elem *nxt_line;
/* Next element */
struct ald_s_l_elem *prev_line;
/* Previous element */
};
9.4.4 VDU initialization parameters (ald_vdu_gini)

Via this datastructure most of the parameters required by the
‘ald_vdu_gini’ routine can be passed.
struct ald_vdu_gini
{
TLS_SHORT wdw_nr; /* Window number */
TLS_SHORT type; /* Overview type */
struct ald_wdw_coord *coord;
/* Window coordinates */
TLS_SHORT nr_char_lin; /* Chars per window line */
TLS_SHORT nr_lines; /* Max lines per window */
char grp_name[HIS_GRP_NAME_SZ];
/* Storage groupname */
char sup_file[TLS_FSPEC_SZ];
/* Setup file */
TLS_SHORT alm_msg_code; /* Base message id */
TLS_SHORT aldman_msg_code;/* message id for aldman */
struct gin_asa_def asa_def;
/* User ASA information */
/* User name */
char display_name[GIN_CWS_MAX_DIS_NAM];
/* Display name */
TLS_BOOLEAN con; /* Connect flag */
};

9.4.5 Retrieval parameters (alh_his_info)

Via this data structure most of the parameters required by the
‘alh_get_ghis’ routine can be passed.
struct alh_his_info
{
TLS_SHORT type; /* Overview type */
struct alm_gen_evt *cur_evt;
/* Event to start reading
from */
TLS_BOOLEAN incl; /* Include flag */
struct his_grp_nr grp; /* Storage group */
TLS_SHORT dir; /* Read direction */
TLS_SHORT num_to_read; /* Nr of events to read */
TLS_ULONG evnt_type; /* Event type */
TLS_ULONG evt_layout; /* Event layout */
TLS_ULONG ghis_layout; /* History selection
criteria mask */
char *ghis_desc; /* Selection criteria
descriptor */
TLS_SHORT num_read /* Number of events read */
char *buf; /* Buffer for events read */
TLS_ULONG sync; /* Synchronization info
from alarm storage
process */
};
The field evt_layout describes the required alarm info parts in the
returned alarm events. See section 9.4.8 for the description of the alarm
event.
The field evt_layout specifies the lay-out for the alarm events.
The field ghis_layout, specifies the lay -out of the history selection
filter.
The next table depicts the contents of the ghis_desc structure:
ghis_layout Request info description
ALM_ASA_PFX_DESC struct gin_asa_inf asa info
9.4.6 Acknowledge information (alm_ack_inf2)

This datastructure is used to pass the so called ‘acknowledge
information’ to the acknowledge interface. The information present in
this data structure is used by the alarm kernel when it generates the
‘acknowledge info’ event.

struct alm_ack_inf2
{
char node_name[ALM_NOD_NAM_SIZ];
char term_name[GIN_TERM_NAM_SIZ];
};
9.4.7 Acknowledge time (alm_ack_time)

This data structure, being part of the alarm event, contains in case of an
alarm event of type acknowledge, the time the item was acknowledged.
struct alm_ack_time
{
TLS_ULONG time /* Seconds since 1/01’70
00:00:00 (GMT) */
TLS_ULONG msec; /* Milli seconds */
TLS_ULONG stamp; /* Number to make time
unique */
};
9.4.8 Alarm event (alm_gen_evt)

This data structure represents the alarm event generated by the alarm
kernel, in case the routine ‘alm_dst_gcon()’ is used to connect to the
alarm kernel. In case applications use the ‘old’ connect routine
‘alm_dst_con()’, the alarm event generated by the alarm kernel is
represented by the data structure ‘alm_alm_evnt’ (see 9.4.9).
struct alm_gen_evt
{
TLS_ULONG evt_layout; /* Event layout */
struct alm_alm_evnt alm_evnt;
/* Main alarm event */
};
The alarm event represented by the data structure ‘alm_gen_evt’,

consists of several parts. The first part is general, which means that every
alarm event contains this part. The field evt_layout within this part,
describes by means of a bit pattern, what extra information is following
this general part. Each bit in this bit pattern is related to a certain
datastructure. A description of these bits and the data structures related

to these bits is given in the following table.
Event layout bits Data structure Description

- alm_alm_evnt
ALM_EVT_AOI_INF alm_aoi_inf Area of interest
ALM_EVT_QC_INF alm_qc_inf Quality code
ALM_EVT_STR_INF alm_str_inf String item value
ALM_EVT_OTS_INF alm_ots_inf Origianl timestamp
ALM_EXT_INF_FMT alm_ext_evt_inf External event info
struct alm_aoi_inf
{
TLS_SHORT itm_aoi[GIN_ITM_MAX_AOI];
};
struct alm_qc_inf
{
TLS_ULONG qc_old;
TLS_ULONG qc_new;
};
struct alm_str_inf
{
TLS_SHORT tot_size; /* Value + SHORTS */
TLS_SHORT info_size; /* Value size */
char value[ALM_MAX_STR_VAL_SZ];
};
struct alm_ots_inf
{
TLS_ULONG time; /* Origial time */
TLS_ULONG msec; /* Original time in ms */
TLS_ULONG stamp; /* unique number */
};
struct alm_ext_evt_inf
{
char source[ALM_EXT_EVT_SRC_SZ]; /* Event source */
char event_cat[ALM_EXT_EVT_CAT_SZ]; /* Event category */
char cond_name[ALM_EXT_EVT_CON_SZ]; /* Event condition */
char sub_cond_name[ALM_EXT_EVT_SUB_SZ]; /* Sub-condition */
char actor_id[ALM_EXT_EVT_ACTOR_SZ]; /*Source of acknow. request*/
TLS_LONG info_flags; /* Bit flag */
TLS_LONG cookie; /* OPC server cookie, opaque to FAST/TOOLS */
struct dur_adr clt_adr; /* DUR address of the event client */
struct alm_ots_inf activ_time; /* Event activation time */

};
9.4.9 General alarm event part (alm_alm_evnt)

This data structure represents the alarm event generated by the alarm
kernel, in case the routine ‘alm_dst_con()’ is used to connect to the
alarm kernel (old situation). In case applications use the ‘new’ connect
routine ‘alm_dst_gcon()’, the alarm event generated by the alarm kernel
is represented by the data structure ‘alm_gen_evt’ (see 9.4.8).
struct alm_alm_evnt
{
struct alm_evnt_inf alm_evnt_inf;
/* General event info */
struct alm_sel_inf alm_sel_inf;
/* Selection info */
struct alm_ack_time ack_time;
/* Time of acknowledgement
(only valid in case of
acknowledge event) */
};
9.4.10 Alarm event identification (alm_evnt_id)

struct alm_evnt_id
{
struct itm_id itm_id; /*Item-id */
struct alm_subj_id subj_id;/*Subject-id */
};
9.4.11 General alarm event info (alm_evnt_inf)

struct alm_evnt_inf
{
TLS_ULONG prio; /*
Priority of event */
TLS_ULONG time; /*
Sec.since 01/01/’70 */
00:00:00 (GMT) */
TLS_ULONG msec; /* Milliseconds */
TLS_ULONG stamp; /* Number to create unique
time stamp */
TLS_ULONG evnt_type; /* Type of event */
struct alm_src_id alm_src_id;
/* Source of event */
TLS_ULONG index; /* Repeat count (1=first
repeat) */

TLS_BOOLEAN ack; /*
Acknowledged=TRUE,
not acknowledged=FALSE */
char txt[GIN_ITEM_MAX_STA_TXT];
/* Status text */
char old_status; /* Old item status */
char old_opt_flag; /* Old option flags */
TLS_SHORT old_state; /* Old alarmstate */
char new_status; /* New item status */
char new_opt_flag; /* New option flags */
TLS_SHORT new_state; /* New alarmstate */
union itm_val_union old_val;
/* Old value */
union itm_val_union new_val;
/* New value */
TLS_SHORT old_repres; /* Old value repress */
TLS_SHORT new_repres; /* New value repress */
TLS_SHORT fo_grp; /* First-out group
number */
char item_desc[GIN_ITEM_MAX_ITM_DES];
/* Max length of item
description text */
/* Max length of eng.
unit text */
};
The field stamp contains a number to create a unique time stamp.
Furthermore this number is used in the synchronization mechanism of
ALARM/FAST. This synchronization mechanism is necessary in
situations where destinations obtain information from both the alarm
kernel and the alarm storage process (see 5.2).
The field evnt_type contains a combination of selection and
information bits. The selection bits are:
• ALM_SEL_DIR:
This bit is set on each item-based status change of the item
concerned.
• ALM_SEL_ALM:
This bit is set under the following conditions;
- On each item-based status change under the following two
conditions:
1 The item concerned is not a continuation item in an
active first-out group.
2 The item concerned does not trigger the delay
mechanism or is not yet active within the delay
mechanism.
- The delay timer for the item concerned times out and the item is

not a continuation item of an active first-out group.

- The first-out group in which the item was active as continuation
item timed out.
• ALM_SEL_REP:
This bit is set under the following conditions:
- Each time the repeat timer for the item concerned times out.
- The alarm state of the item concerned changed to (N)ormal and
at least one repeat event has been generated by the alarm kernel.
• ALM_SEL_ACK:
This bit is set in the case of an acknowledge event.
• ALM_SEL_INF:
This bit is set in the case of an informational event.
• ALM_SEL_DAC:
This bit is set in the case of a deactivation event.
• ALM_SEL_REC:
This bit is set in the case of a recovery event.
This bit can be set in the following combinations:
- Together with the ALM_SEL_DAC bit, to indicate that the item
concerned should no longer be monitored for alarm situations.
- Together with the bits ALM_SEL_DIR and ALM_SEL_ALM,
to indicate that the item concerned has a status which has been
marked as an alarm state for that item.
- Together with the bits ALM_INF_NML, ALM_SEL_ALM,
ALM_SEL_DIR and ALM_SEL_REP to indicate, that the item
concerned has a status which has not been marked as an alarm
state for that item.
• ALM_SEL_DIA:
This bit is set when the event is related to an item that is used for
diagnostic purposes. Furthermore the same conditions apply as
described for the bit ‘ALM_SEL_ALM’.
• ALM_SEL_QC
This bit is set in case of a quality code event.
• ALM_SEL_PRIO
This bit is set in case of a change priority event.
The information bits are:
• ALM_INF_NML:
This bit is set to indicate that the status of the item concerned has
changed to another non-alarm state.
• ALM_INF_REP:
This bit is set to indicate that the item concerned triggered the
repeat mechanism or that the repeat timer for the item concerned
timed out

• ALM_INF_TDL:
This bit is set to indicate that the item concerned triggered the delay
mechanism, or that the delay timer for the item concerned timed
out.
• ALM_INF_FDL:
This bit is set to indicate that the item concerned is active as
continuation item of a first-out group, or that the first-out group the
item was put in timed out.
• ALM_INF_ACK:
This bit is set (together with the ALM_SEL_ACK bit) to indicate
that the event is an acknowledge info event.
9.4.12 First-out group definition (alm_fo_def)

This data structure represents the layout of a record from the first-out
group definition file.
struct alm_fo_def
{
char fo_grp_name[ALM_MAX_FO_GRP_NAME];
/* Name of first-out
group */
TLS_SHORT fo_grp_nr; /* Number of first-out
group */
TLS_SHORT par_fog_nr[ALM_MAX_PAR_FO_GRP];
/* Numbers of parent
first-out groups */
TLS_ULONG int_delay; /* Spec. internal delay
time */
TLS_ULONG ext_delay; /* Spec. external delay
time */
TLS_ULONG times_used; /* Numbers of times
referred to */
};
9.4.13 Non-item based event (alm_nib_evnt)

This data structure represents the layout of non-item based events.
struct alm_nib_evnt
{
struct alm_src_id ext_evnt_id;
/* Sender + subject id */
TLS_ULONG time; /* Seconds since 1/01/’70 */
TLS_USHORT msec; /* Milli seconds */
TLS_USHORT prio; /* Priority of event */
char txt[GIN_ITEM_MAX_STA_TXT];

/* Status text */
/* Possible item name */
TLS_SHORT add_sel_inf [GIN_ITEM_MAX_SEL_ROW]
/* Possible additional
selection information */
char item_desc[GIN_ITEM_MAX_ITM_DES]
/* Description text */
struct alm_ext_evt_inf ext_evt_inf;
/* External event info */
};
9.4.14 Overflow message (alm_q_ovflw)

This data structure represents the layout of an “overflow message”.
struct alm_q_ovflw
{
TLS_ULONG nr_ovflw; /* Number of overflows since
next mentioned time */
TLS_ULONG time; /* Seconds since 01/01/’70
(GMT) */
TLS_ULONG msec; /* Milliseconds */
TLS_ULONG stamp; /* Stamp to make time
unique */
};
9.4.15 Initiate item recovery message (alm_recover)

This data structure represents the layout of an “initiate item recovery
message” for one item.
struct alm_recover
{
struct itm_val_sta vast;/* Not used (anymore) */
struct gin_item_alm2 item inf;
/* Alarmparameters */
};
9.4.16 Selection criterion structures

The structures mentioned in this paragraph cover the selection
criterions. The functionality of selection criteria is covered totally by the
alarm selection areas. The use of alarm selection areas is strongly
recommended.

struct alm_sel_inf
{
/* Item name */
TLS_SHORT add_sel_inf [GIN_ITEM_MAX_SEL_ROW]
};
9.4.17 Alarm event selection bits

The required selection criteria can be stated by bitwise ORing one or
more of the following #defines (header file alm.h);
• ALM_SEL_DIR for direct events
• ALM_SEL_ALM for alarm events
• ALM_SEL_REP for repeat events
• ALM_SEL_ACK for acknowledge events
• ALM_SEL_INF for informational events
• ALM_SEL_DAC for deactivate events
• ALM_SEL_REC for recovery events
• ALM_SEL_DIA for diagnostic events
• ALM_SEL_QC for quality code change events
• ALM_SEL_PRIO for priority change events
9.4.18 Alarm source id (alm_src_id)

struct alm_src_id
{
struct dur_adr src_id; /* DUR address of source */
TLS_SHORT id_used; /* Used id */
TLS_SHORT dummy 1;
union alm_evnt_id evnt_id;/*Event id */
};
The field id_used is one of:

• ALM_ITM_ID: indicating that the field itm_id in the union
alm_evnt_id is used.
• ALM_SUBJ_ID: indicating that the field subj_id in the union
alm_evnt_id is used.
9.4.19 Alarm subject id (alm_subj_id)

struct alm_subj_id
{

TLS_UBYTE node /* Node number */

TLS_UBYTE dummy;
TLS_SHORT id; /* Unique subject number */
};
9.4.20 Synchronization message (alm_sync_upd)

This data structure represents the layout of a “synchronization
message”.
struct alm_sync_upd
{
TLS_ULONG sync; /* Synchronization
information */
};
9.4.21 Get alm parameters info (alm_get_inf)

This data structure represents some parameters of alm which are also
usefull for destination processes.
struct alm_get_inf
{
char highest_prio; /* Highest priority number
(0 or 15) */
char spare[39]; /* Space for future
extentions */
};

Routines and BUS/FAST Messages Reference Guide
9.5 Routines and BUS/FAST Messages

Reference Guide Routines and BUS/FAST Messages
9.5.1 Compare selection criteria

Syntax [status=] alc_cri_matg (umh_c, sel_layout, sel_desc
evnt_type, gen_evt, match_stat)
Arguments TLS_BOOLEAN status; /* (R) TRUE (success) or

FALSE (error) */
struct umh_context umh_c; /* (M) Pointer to error
context */
TLS_ULONG sel_layout; /* (I) Layout of selection
criteria */
char *sel_desc; /* (I) Selection criteria
descriptor */
TLS_ULONG evnt_type /* (I) Alarm event type */
struct alm_gen_evt *gen_evt;
/* (I) Alarm event */
TLS_ULONG *match_stat /* (O) Match status */
Data Structs The field sel_layout describes the lay-out of the selection criteria
descriptor to which the alarm event must be checked. The information
contained in the sel_desc depends on the bit-mask in sel_layout,
next table depicts the dependency.
sel_layout Request info description

ALM_ASA_PFX_DESC struct gin_asa_inf ASA info
struct gin_asa_inf
{
TLS_USHORT size; /* Size of expression */
TLS_USHORT code; /* ASA info code */
TLS_LONG pfx_info[1]; /* Postfix expression */
};
The ASA information can be retrieved by a set of GIN routines, please
refer to the GIN programmers guide for more information.
Semantics This routine can be used to check if an alarmevent matches the event
types and possible alarm selection area offered to this routine. The flags
passed in sel_layout determine the selection criteria to which the
event is checked.
If this routine returns FALSE then an error is detected while evaluating
the postfix expression passed to the routine. A TRUE return code means
that a successful evaluation has been done. The results of criterion match
is returned in the field match_stat, next status values are defined:
• ALC_CRI_NOMATCH The event did not match the
selection criteria.

• ALC_CRI_MATCH The event matched the selection

criteria.
• ALC_CRI_DEACT The event did not match the
criteria at this moment. This
item could have matched to the
criteria before.
Error Codes • ALC_E_EVAL_ERR Error during evaluation of the

postfix ASA expression.

9.5.2 Decode event bits

Syntax [status=]ald_dec_ebit(evnt_bits,user_type)
TLS_BOOLEAN status /* Always TRUE */
Arguments TLS_ULONG event_bits; /* (I) Event bits to
decode */
TLS_SHORT *user_type; /* (O) User understandable
type */
Data Structs None.
This routine can be used to decode the field evnt_type as present in

Semantics the alarm event generated by the alarm kernel. The routine returns via
the user_type argument,one of the following types:
• ALD_TYPE_NORMAL for normal event
• ALD_TYPE_DIRECT for direct event
• ALD_TYPE_ALARM for alarm event
• ALD_TYPE_DELAY for delayed event
• ALD_TYPE_REPEAT for repeated event
• ALD_TYPE_INFO for informational event
• ALD_TYPE_ACKNOW for acknowledge event
• ALD_TYPE_RECOVER for recover event
• ALD_TYPE_DEACT for deactivate event
• ALD_TYPE_UNKNOWN when an event_bit (or
combination of event_bits) is
not recognized
• ALD_TYPE_DIAG for diagnostic event
• ALD_TYPE_QC for quality change event
Error Codes None.

9.5.3 Format ASCII message for alarm event

Syntax [status=]ald_fmt_msg(umh_c,alm_evnt,fmt,tfmt,val_prec,
dest_type,buf_length,buf)
Arguments TLS_BOOLEAN status; /*

(R) TRUE (success) or
FALSE (error) */
struct umh_context *umh_c;/* (M) Buffer for UMH
context */
struct alm_gen_evt *alm_evnt;
struct ald_line_fmt fmt[];/* (I) Format description */
char *tfmt; /* (I) Free time format */
TLS_SHORT val_prec; /* (I) Precision of value */
TLS_SHORT dest_type; /* (I) Destination type */
int buf_length; /* (I) Length of buffer to
put formatted
message in */
char *buf; /* (O) Buffer to put
formatted message
in */
Data Structs For general structures see section 9.4: General data structures.
Semantics This routine can be used to convert an alarm event, to an ASCII text.
Via the argument alm_evnt, the alarm event can be passed to this
routine. Both an alarm event of type ‘alm_alm_evnt’ and an alarm event
of type ‘alm_gen_evt’ can be passed to this routine.
The argument fmt specifies the format the alarm event must be
converted to. This argument is a pointer to an array containing ‘x’
elements of type ald_line_fmt. The last element in this array should
contain the value ‘-1’, to indicate the end of the array to this routine.
Each element of the array contains a message unit and a message unit
length. The message unit indicates which field in the alarm event is
meant. The message unit length indicates the maximum length that may
be used in the buffer to put the ASCII message in for that specific
message unit. The order in which the message units are situated in the
array that the argument fmt is pointing to, determines the order in which
the contents of the fields of the alarm event appear in the buffer the
argument buf is pointing to. Message units codes have been described
in 9.4.1.
The argument val_prec indicates the precision, i.e. the number of digits
after the ‘dot’, to use when printing the value of an item.
The argument dest_type is a number which is passed to the routine
ald_usr_fmt. This number is read from an alarm destination setup file

and can be used to distinguish between the several types of destinations

in the routine ald_usr_fmt.
Error Codes • ALD_E_INTERN_ERR Internal brick error.
• ALD_E_ILL_FLD_SIZ Illegal field size specified for message
unit.
• ALD_E_TXT_BUF_OVF Text buffer not large enough to hold
alarm message.
• ALD_E_ILL_MSGUNIT Unknown message unit specified.

9.5.4 Get alarm message format from setup file

Syntax [status=]ald_get_fmt (dur_c,umh_c,sup_fp,fmt,tfmt,
tfmt_siz)
(R) TRUE (success)
or FALSE (error) */
struct dur_context *dur_c;/* (I) Buffer for DUR
context */
context */
FILE *sup_fp; /* (I) Filepointer of
setup file */
struct ald_line_fmt **fmt;/* (O) Address of pointer
to format array */
char *tfmt; /* (I) Pointer to buffer
to put "free time
format" in */
int tfmt_siz; /* (I) Size of buffer to
put "free time
format" in */
Semantics This routine can be used to read the format description from a setup file
for a particular alarm destination.
The argument sup_fp specifies the filepointer of the setup file from
which the format description is read. The argument fmt should contain
the address of the pointer, in which the start address of the array of type
ald_line_fmt, is put by this routine. This routine allocates space for
each element needed in this array. It is the responsibility of the program
this routine is part of to free the memory occupied by this array. The last
element of this array can be recognized by monitoring the field
msg_unit in this array. In this field the last element in this array will
have the value ‘-1’.
It is possible to specify a so called ‘free time format’ in the setup file of
an alarm destination. If this is the case, the format string (picture string)
will be put into the character array the argument tfmt is pointing to. If
the size of this buffer (indicated by the argument tfmt_siz) is not big
enough to hold the total picture string, only the part that fits in the
character array will be considered as picture string.
• ALD_E_ILL_FMT_STX Illegal syntax for mainkeyword
‘FORMAT’ in setup file.
• ALD_E_MIS_KW_FMT Missing keyword for ‘format’ in setup
file.

9.5.5 User formatting routine

Syntax [status=]ald_usr_fmt (dur_c, umh_c, dest_type,
buf_length, text_buf, org_fmt)

(R) TRUE (success)
or FALSE (error) */
context */
context */
int dest_type; /* (I) User defined type of
destination (number
fetched from setup
file) */
int buf_length; /* (I) Total length of
character array */
char char *text_buf; /* (M) Character array
containing
‘original’
alarmtext */
struct ald_line_fmt *org_fmt;
/* (I) Original alarm
message format
description (conform
contents setup file)*/
Semantics This routine, which is delivered in source form, is meant to manipulate
the contents of a character array. This character array contains the alarm
text formatted according to the contents of a destination setup file. The
original alarm text in the character array is terminated with an ‘\0’
character.
The new formatted alarm text should also be terminated with a ‘\0’
character. Where the setup file states that the alarm text should be
written over more than one line, the original alarm text contains ‘\n’
characters to indicate this.
A description of the layout of the alarm message, is given by means of
the array of structs the argument org_fmt is pointing to. This array
describes the order in which the message units will appear and the size
a message unit will occupy. On no account should the contents of this
array be modified!!
It is the responsibility of the author of this routine to make this routine
as efficient as possible. This is because this routine is part of a chain of
routines which determines the overall performance of the alarm
destination that it is part of.

Error Codes User dependent.

9.5.6 Handle acknowledge action (1)

Syntax [status=]ald_vdu_ack (dur_c,umh_c,scn_c,index,ack_mode)

(R) TRUE (success)
or FALSE (error) */
context */
context */
struct ald_s_cont *scn_c;/* (M) Buffer for screen
context */
TLS_SHORT index; /* (I) Field index number */
TLS_SHORT ack_mode; /* (I) Acknowledge mode */
Semantics This routine can be used to handle the user acknowledge action for a
VDU-based destination.
The argument index must contain the index number of the field the
cursor is on at the moment the user wishes to acknowledge. The value of
this argument is only of importance if the user wants to acknowledge one
specific item.
The argument ack_mode is either ALD_ACK_ONE (if only one
specific item has to be acknowledged) or ALD_ACK_WDW (where all
items in the current window have to be acknowledged).
A newer version of this routine is available (ald_vdu_ack2). This routine
allows the caller of the routine to specify acknowledge information.
The routine ald_vdu_ack is only described here because of upwards
Error Codes • ALD_E_ACK_NO_SUCC Acknowledgment of items not
succeeded or partially succeeded.
• ALD_W_ALM_ALMRACK This item has already been
acknowledged.
• ALD_W_NOT_ACK Window empty. No items to
acknowledge at the moment.

9.5.7 Handle acknowledge action (2)

Syntax [status=]ald_vdu_ack2(dur_c,umh_c,scn_c,index,ack_mode
ack_inf)

FALSE (error) */
context */
context */
struct ald_s_cont *scn_c; /* (M) Buffer for screen
context */
int index; /* (I) Field index number */
int ack_mode; /* (I) Acknowledge mode */
struct alm_ack_inf2 *ack_inf;
/* (I) Acknowledge info */
Semantics This routine can be used to handle the user acknowledge action for a
The argument index must contain the index number of the field the
cursor is on at the moment the user wishes to acknowledge. The value of
this argument is only of importance if the user wants to acknowledge one
specific item.
The argument ack_mode is either ALD_ACK_ONE (if only one
specific item has to be acknowledged) or ALD_ACK_WDW (where all
items in the current window have to be acknowledged).
Via the argument ack_inf it is possible for the caller of this routine to
specify acknowledge info. This acknowledge info can be distributed by
the alarm kernel to alarm destinations.
Error Codes • ALD_E_ACK_NO_SUCC Acknowledgment of items partially or
not succeeded.
• ALD_W_ALM_ALMRACK This item is already acknowledged.
• ALD_W_NOT_ACK Window empty. No items to
acknowledge at the moment.

9.5.8 Handle bottom browse command

Syntax [status=]ald_vdu_bot (dur_c,umh_c,scn_c)

(R) TRUE (success)
or FALSE (error) */
struct dur_context *dur_c;/* (I) Buf. for DUR
context. */
context. */
context. */
Semantics This routine can be used to handle the ‘bottom’ browse command for a

9.5.9 Handle exit actions for destination

Syntax [status=]ald_vdu_exit(dur_c,umh_c,rcv_par,scn_c,
dcon,empty_que)
(R) Always TRUE
(success) */
struct dur_context *dur_c;/* (I) Buffer for
DUR context */
struct umh_context *umh_c;/* (M) Buffer for
UMH context */
struct dur_par_rcv *rcv_par;
/* (I) Receive parameters
of process */
struct ald_s_cont *scn_c;/* (M) Buffer for
screen context */
TLS_BOOLEAN dcon; /* (I) Disconnected flag */
TLS_BOOLEAN empty_que; /* (I) Empty queue flag */
Semantics This routine can be used to handle the exit actions for a VDU- based
alarm destination. The effect of a call to this routine is:
• Screen context is deleted.
• All internally allocated pieces of memory are freed.
• If the argument dcon contains the value TRUE, the destination is
disconnected from the alarm kernel.
• If the argument empty_que contains the value TRUE, DUR
messages still in the receive queue of the destination and sent by the
alarm kernel and/or alarm storage process are removed from the
receive queue of the alarm destination.
If the argument dcon contains the value TRUE, this routine disconnects
the destination from the alarm kernel. This argument may be useful if the
alarm destination manages a multi-window environment. If a particular
window in this environment should be terminated, it is possible to call
this routine without the alarm destination itself being disconnected from
the alarm kernel.
For the same reason the routine has the argument empty_que. If this
argument contains the value TRUE, DUR messages still in the queue of
the destination and sent by the alarm kernel and/or alarm storage
process, are removed from the queue.
Error Codes None.

9.5.10 Fill window

Syntax [status=]ald_vdu_fwdw(dur_c,umh_c,scn_c)
(R) Always TRUE
(success) */
DUR context */
UMH context */
screen context */
Semantics This routine can be used to fill the alarm window of a VDU-based
destination, with alarm messages. This can be useful after processing a
sequence of alarm events. As a result of processing these events, the
window may no longer be filled to capacity. In order to fill up the
window, this call will try to retrieve alarm information from the alarm
storage process and stores it in the window until it is 100% filled.
Error Codes None.

9.5.11 Handle alarm event as generated by the

alarm kernel
Syntax [status=]ald_vdu_gevt(dur_c,umh_c,scn_c,alm_evt)

FALSE (error) */
DUR context */
UMH context */
screen context */
struct alm_gen_evt *alm_evt;
Semantics This routine can be used to handle an alarm event received by a
VDU-based destination. This routine checks whether or not the alarm
event offered to this routine, has impact on the alarm overview. If it
does, the contents of the overview is updated. If necessary and possible,
the routine tries to fill up the overview after processing the alarm event
for the alarm overview. This is done by sending an information retrieval
request to the alarm storage process.
Via the argument alm_evt, the alarm event can be passed to this routine.
Both an alarm event of type ‘alm_alm_evnt’ and an alarm event of type
‘alm_gen_evt’ can be passed to the routine.

• ALD_E_COMM_ERR General communication error.


(general)
Syntax scn_c = ald_vdu_gini(umh_c, vdu_gini_par)
Arguments struct ald_s_cont *scn_c /*
(R) Pointer to screen
context */
context */
struct ald_vdu_gini *vdu_gini_par;
/* (M) Parameters */
Semantics This routine is used to initialize a VDU-based alarm destination. The
initialization actions are:
• Read setup file for this alarm destination to obtain:
- The selection criteria for this destination
- The layout of the alarm message to use for this destination.
- The key to built the alarm overview for this overview with
(incrementing/decrementing).
- The ASA information to be used by this alarm destination,
depending on whether or not the name in the structure asa_def
is specified. A NULL pointer means, the routine will search for
an ASA in the setup-file. If the asa_name is filled then this ASA
will be used.
• Perform initial request to retrieve information from the alarm
storage process. This is used to fill the alarm destination window
with “initial” information.
• If desired by the alarm destination, a connect action is performed to
the alarm kernel
In the ald_s_cont structure returned by this routine, the field
info_ptr is used as a pointer to the selection criteria data structure to
be used by this destination.
The structure ald_vdu_gini consists of the arguments used in
ald_vdu_ini(). For the meaning of these arguments, please refer to the
ald_vdu_ini() routine. The field aldman_msg_code contains the
message code to be used by an alarm destination manager.
Error Codes • ALM_E_ILL_ASA The alarm selection area specified
could not be used because it has
compilation errors
• ALM_E_NOASA The alarm selection area specified
doesn’t exist
• Other errors See function ald_vdu_ini()


Syntax [status=]ald_vdu_ini(dur_c,umh_c,scn_c,wdw_nr,coord,
nr_char_lin,nr_lines,msg_code,
grp_name,type,sup_file,con)
FALSE (error) */
/* (I) Buffer for DUR
context */
/* (M) Buffer for
UMH context */
struct ald_s_cont *scn_c;
/* (M) Buffer for
screen context */
TLS_SHORT wdw_nr; /* (I) Window number */
struct ald_wdw_coord *coord;
/* (I) Window coordinates */
TLS_SHORT nr_char_lin; /* (I) No.characters per
window line */
TLS_SHORT nr_lines; /* (I) No.of lines that
fits in the window */
TLS_SHORT msg_code; /* (I) Base message id */
char *grp_name; /* (I) Storage groupname */
TLS_SHORT type; /* (I) Overview type */
char *sup_file; /* (I) Setup file */
TLS_BOOLEAN con; /* (I) Connect flag */
Semantics This routine can be used to initialize a VDU-based alarm destination.
The initialization actions are:
• Read setup file, for this alarm destination, to obtain:
- The selection criteria for this destination
- The layout of the alarm message to use for this destination.
- The key to built the alarm overview for this overview with
(incrementing/decrementing).
• Performs an initial request to the alarm storage process to retrieve
“initial” information That is to be placed into the window of the
alarmdestination that this calling routine was initialized for.
• If desired by the alarm destination, a connect action is performed to
the alarm kernel
The arguments wdw_nr and coord are not used by the VDU-based
routines or other ALD_... routines. The values passed via these
arguments are just stored in the screen context and can be regarded as
application info.

The argument grp_name is important when the alarm destination

calling this routine is of type ALD_CHR (chronological type). For other
overview types, the contents of this argument is irrelevant (pass NULL
pointer). Currently the only storage group defined for ALARM/FAST is
named “ALH”.
Via the argument type, the kind of overview the VDU-based
alarmdestination is initializing for, can be passed to the routine.
The values allowed for type are:
• ALD_CHR: For chronological overview types.
• ALD_CUR_T: For time-based current overview types.
• ALD_CUR_P: For priority-based current overview types.
The argument sup_file should contain the name of the setup file (no
pahtname, no extension) of the alarm destination.
The argument con is a flag that indicates to the routine whether or not
a connect action to the alarm kernel should be performed. This flag may
be useful for VDU-based alarm destinations which have to manage a
multi-window environment. In such cases, a connect action to the alarm
kernel is only meaningful for the very first window becoming active. For
windows subsequently becoming active, the alarm destination will call
the initialization routine again. In this case however, no new connect
action should be performed.
Notes This routine is only described for upwards compatibility reasons. It is
recommended to use ald_vdu_gini()
Error Codes • ALD_E_ILL_EVT_STX Illegal syntax for main keyword
‘EVENTS’ in setup file.
• ALD_E_ILL_FMT_STX Illegal syntax for main keyword
‘FORMAT’ in setup file.
• ALD_E_ILL_OVRVTYP Unknown overview type specified.
• ALD_E_INI_ERR General destination initialization error.
• ALD_E_MIS_KW_FMT Missing keyword for format in setup
file.
• ALD_E_SUP_OPE_ERR Unable to find destination setup file.
• ALD_E_TO_MAN_NWLN More than one complete alarm message
will fit on the screen. Adjust alarmline
format in setup file.

9.5.14 Handle next event browse command

Syntax [status=]ald_vdu_nev(dur_c,umh_c,scn_c)

FALSE (error) */
struct dur_context *dur_c;/* (I) Buffur for DUR
context */
context */
context */
Data Structs
DA- For general structures see section 9.4: General data structures.
TASTRUCTS
Semantics This routine can be used to handle the Next Event browse command for
a VDU-based destination.
• ALD_W_NOMORALMHIS No more alarm history available at the
moment.
• ALD_W_NOT_SYNC Screen was not up-to-date during
request, try again.

9.5.15 Handle next page browse command

Syntax [status=]ald_vdu_npg(dur_c,umh_c,scn_c)

FALSE (error) */
context */
context */
context */
Semantics This routine can be used to handle the Next Page browse command for
a VDU-based destination.
moment.

9.5.16 Handle overflow message generated by the

alarm kernel
Syntax [status=]ald_vdu_ovf(dur_c,umh_c,scn_c,ovflw_inf)

FALSE (error */
DUR context */
UMH context */
screen context */
struct alm_q_ovflow *ovflw_inf;
/* (I) Overflow data */
Semantics This routine can be used to handle the overflow message for a
VDU-based destination. The routine performs the following actions:
• If overview is empty:
- Routine uses retrieval interface in attempt to fill up the overview
again. The retrieve request performed, is related to the global
position of the overview.
• If overview is not empty:
- Global position is TOP or BETWEEN:
Routine uses retrieval interface in attempt to fill up the overview
again. The first event currently displayed in the overview, is
used as ‘event to start reading from’ (read direction ‘forward’).
- Global position is BOTTOM:
Routine uses retrieval interface in attempt to fill up the overview
again. The last event currently displayed in the overview, is used
as ‘event to start reading from’ (read direction ‘backward’).

9.5.17 Handle previous event browse command

Syntax [status=]ald_vdu_pev(dur_c,umh_c,scn_c)

FALSE (error) */
context */
context */
context */
Semantics This routine can be used to handle the Previous Event browse command
for a VDU-based destination.
moment.
• ALD_W_NOT_SYNC Screen was not up-to-date during
request, try again.

9.5.18 Process alarm event for a VDU type

destination
Syntax [status=]ald_vdu_pevt(dur_c,umh_c,scn_c,alm_evt,
crit_check)

FALSE (error) */
DUR context */
UMH context */
screen context */
struct alm_gen_evt *alm_evt;
TLS_BOOLEAN crit_check; /* (I) Selection criteria
check flag */
Semantics This routine can be used to process an alarm event for a VDU-based
destination. The result of this processing determines whether or not the
alarm window must be updated (e.g. an alarm message may be removed
from a full alarm window because another alarm emerged from this
processing).
Each window has its own screen context. If the crit_check flag is
TRUE, the event will only be processed if the event matches the window
criteria (as stored in data structure appointed by scn_c). This is used in
applications where a single alarm destination manages more than one
window (each having its own criteria). The application attaches to alarm
kernel and demands all events.
Via the argument alm_evt, the alarm event can be passed to this routine.
Both an alarm event of type ‘alm_alm_evnt’ and an alarm event of type
‘alm_gen_evt’ can be passed to the routine.

• ALD_E_COMM_ERR General communication error.

9.5.19 Handle previous page browse command

Syntax [status=]ald_vdu_ppg(dur_c,umh_c,scn_c)

FALSE (error) */
context */
context */
struct ald_s_cont *scn_c;/* (M) Buffer for scn
context */
Semantics This routine can be used to handle the Previous Page browse command
for a VDU-based destination.
• ALD_W_NOMORALMHIS No more alarmhistory available at the
moment.

9.5.20 Handle processing of synchronization

message
Syntax [status=]ald_vdu_sync(umh_c,scn_c,sync)

FALSE (error) */
/* (M) Buffer for UMH
context */
/*
(M) Buffer for scn
context */
struct alm_sync_upd *sync;/* (I) Synchronize
message */
Semantics This routine can be used to handle the synchronization message for a
Error Codes None.

9.5.21 Handle top browse command

Syntax [status=]ald_vdu_top(dur_c,umh_c,scn_c)
Arguments TLS_BOOLEAN status; /* (R) TRUE(success) or

FALSE(error) */
context */
context */
struct ald_s_cont *scn_c;/* (M) Buffer for scn
context */
Semantics This routine can be used to handle the Top browse command for a

9.5.22 Retrieve historical information (general)

Syntax [status=] alh_get_ghis(umh_c, alh_proc, alh_ghis);
FALSE (error) */
context */
struct dur_adr *alh_proc; /* (I) Alarm kernel */
struct alh_his_info *alh_ghis;
/* (M) Get history info */
Semantics This routine is used to retrieve information from the alarm storage
process, with the possibility of specifying a selection filter. The default
storage process (local node, name = ALH) can be specified by stating a
NULL pointer for argument alh_proc.
For the explanation of the elements of the struct alh_his_info please
refer to the alh_get_hist() function description.
Notes Take into consideration that a complex ASA expression normally means
it will take a longer time to retrieve the alarm history information.
Error Codes See function alh_get_hist()
9.5.23 Retrieve historical information

Syntax [status=]alh_get_hist(dur_c,umh_c,alh_adr,type,cur_evt,
incl,grp,dir,num_to_read,
sel_crit,num_read,buf,sync)
FALSE error) */
context */
/* (M) Buffer for UMH
context */
struct dur_adr *alh_adr;
/* (I) Pointer to DUR
address of
alarmstorage
process */
TLS_SHORT type; /* (I) Overview type */
struct alm_alm_evnt *cur_evt;
/* (I) Event to start
reading from */
TLS_BOOLEAN incl; /* (I) Include flag */
struc his_grp_nr *grp; /* (I) Storage Group */

TLS_SHORT dir; /*
(I) Read direction */
TLS_SHORT num_to_read; /*
(I) Number of events to
read */
struct alm_sel_crit *sel_crit;
/* (I) Selection criteria */
TLS_SHORT *num_read; /* (O) Events read */
char *buf; /* (O) Buffer to put
events read in */
TLS_ULONG *sync; /* (O) Synchronization
information from
alarm storage
process */
Semantics This routine is used to retrieve information from the alarm storage
process. The maximum number of events to read at once is determined
by the #define ALH_MAX_EVNT_TO_REQ.
When a NULL pointer is passed for the argument alh_adr,the default
alarm storage process is assumed (local node, name = ALH).
For the argument type one of the following storage types can be used;
- ALD_CHR : For the chronological storage type.
- ALD_CUR_P : For the priority-based current storage type.
- ALD_CUR_T : For the time-based current storage type.
The key value of the event to start reading from (cur_evt) comprises
the fields prio, time, msec and stamp in this event. By specifying the
event to start reading from, only the values put into these fields are
relevant.
The argument incl indicates to the routine whether or not the event to
start reading from (argument cur_evt) should also be included in the
reply. By specifying TRUE for this argument, the event to start reading
from will also be returned.
The argument grp is only meaningful if the storage type is ALD_CHR.
Please consult the HISTORY/FAST Programmer’s Guide for
information concerning the conversion of group name to group number.
The argument dir should contain one of the following values:
• ALH_BEF_SPEC_EVNT:
For reading ‘backward’ (smaller keyvalue).
• ALH_AFT_SPEC_EVNT:
For reading ‘forward’ (larger keyvalue).
The argument buf is a pointer to a buffer where the events that are read
should be placed. The events that are read are of type struct

alm_alm_evnt and are concatenated into this buffer. It is the

responsibility of the caller of this routine, by declaring enough space for
this buffer, to hold all events read.
Notes This routine is described for upwards compatibility reasons only. It is
recommended to use the alh_get_ghis() routine. But take into
consideration the way your destination is being initialized, determines
the way historical information can be retrieved.
Error Codes • ALH_E_COMM_ERR General communication error.
• ALH_E_ILL_READDIR
Illegal read direction specified.
• ALH_E_ILL_STO_TYP
Illegal storage type specified.
• ALH_E_INTERN_ERRInternal alarm storage process error.
• ALH_E_NOTSUPSTO Alarm storage process was not set up to
support this kind of storage type.
• ALH_E_STG_NOTEXI Storage group does not exist.
• ALH_E_STG_NO_STU Storage group does not have storage
units specified.
• ALH_E_TO_MANY_EVT Too many historical events requested at
once.


information (general)
Syntax [status=]alh_get_gnac(umh_c, alh_proc, alh_ghis);
FALSE (error) */
context */
struct dur_adr *alh_proc; /* (I) Alarm kernel */
struct alh_his_info *alh_ghis;
/* (M) Get history info */
Semantics This routine is used to retrieve unacknowledged alarms from the alarm
storage process, with the possibility of specifying a selection filter.
When a NULL pointer is passed for the argument alh_proc,the default
For the explanation of the elements of the struct alh_his_info please
refer to the alh_get_hist() function description.
Notes Take into consideration that a complex ASA expression normally means
it will take a longer time to retrieve the alarm history information.
Error Codes See function alh_get_nack()


information
Syntax [status=]alh_get_nack(dur_c, umh_c, alh_adr,cur_evt,
incl,dir,um_to_read, sel_crit,
num_read, buf, sync)

FALSE (error) */
context */
struct umh_context *umh_c; /* (M) Buffer for UMH
context */
struct dur_adr *alh_adr; /* (I) Pointer to DUR
address of
alarmstorage
process */
struct alm_alm_evnt *cur_evt;
/* (I) Event to start
reading from */
TLS_BOOLEAN incl; /* (I) Include flag */
TLS_SHORT dir; /* (I) Read direction */
TLS_SHORT num_to_read; /* (I) Number of events to
read */
TLS_SHORT *num_read; /* (O) Events read */
char *buf; /* (O) Buffer to put events
read in */
TLS_ULONG *sync; /* (O) Synchronization
information
from alarmstorage
process */
Semantics This routine is used to retrieve unacknowledged alarms from the alarm
storage process. The maximum number of events to read at once is
determined by the #define ALH_MAX_EVNT_TO_REQ.
When a NULL pointer is passed for the argument alh_adr,the default
The key value of the event to start reading from (cur_evt) comprises
the fields prio, time, msec and stamp in this event. By specifying the
event to start reading from, only the values put into these fields are
relevant.
The argument incl indicates to the routine whether or not the event to

start reading from (argument cur_evt) should also be returned by the

routine. By specifying TRUE for this argument, the event to start
reading from will also be returned.
The argument dir should contain one of the following values:
• ALH_BEF_SPEC_EVNT:
For reading ‘backward’ (smaller keyvalue).
• ALH_AFT_SPEC_EVNT:
For reading ‘forward’ (larger keyvalue).
The argument buf is a pointer to a buffer in which the events read
should be put into. The events read are of type struct alm_alm_evnt
and are concatenated into this buffer. It is the responsibility of the caller
of this routine, by declaring enough space for this buffer, to hold all
events read.
Error Codes • ALH_E_COMM_ERR General communication error.
• ALH_E_ILL_READDIR
Illegal read direction specified.
• ALH_E_INTERN_ERRInternal alarm storage process error.
• ALH_E_NOTSUPSTO Alarm storage process was not set up to
support this kind of storage type.
• ALH_E_STG_NOTEXI Storage group does not exist.
• ALH_E_STG_NO_STU Storage group does not have storage
units specified.
• ALH_E_TO_MANY_EVT Too many historical events requested at
once.

9.5.26 Acknowledge of items (1)

Syntax [status=]alm_ack_itm(dur_c,umh_c,alm_adr,nr_evt,buf)

FALSE (error) */
context */
context */
struct dur_adr *alm_adr;
/* (I) Alarm kernel */
TLS_SHORT nr_evt; /* (I) Number of alarm-
events in buffer */
char *buf; /* (I) Buffer to put alarm
events in */
Semantics This routine is used to acknowledge items. A number of items can be
acknowledged simultaneously by clustering the alarm events in the
buffer pointed to by argument buf. Both alarm events of type
‘alm_alm_evnt’ and alarm events of type ‘alm_gen_evt’ can be put in
this buffer.
The number of events offered to this routine is not allowed to exceed the
value of the #define ALM_MAX_EVNT_ACK_AT_ONCE.
For every successful acknowledged item, the alarm kernel will generate
an acknowledge event.
When a NULL pointer is passed for the argument alm_adr, the default
alarm kernel process is assumed (local node, name = ALM).
A newer version of this routine is available (alm_itm_ack2). This
routine allows the caller of the routine to specify acknowledge
information.
The routine alm_itm_ack is only described here for upwards
Error Codes • ALM_E_ACK_NOT_ALL Not all items acknowledged due to
status inconsistency.
• ALM_E_COMM_ERR General communication error.
• ALM_E_ILL_NR_ACK Number of events to acknowledge has
an illegal value (0 <= nr.> max.
allowed).
• ALM_E_INTERN_ERR Internal alarm kernel error.
• ALM_E_UNKN_ITM_ID Unknown item-id specified.

9.5.27 Acknowledge of items (2)

Syntax [status=]alm_ack_itm2(dur_c,umh_c,alm_adr,ack_inf,
nr_evt,buf)

FALSE (error) */
context */
context */
struct dur_adr *alm_adr; /* (I) Alarm kernel */
struct alm_ack_inf2 *ack_inf2;
/* (I) Acknowledge info */
int nr_evt; /* (I) Number of alarm-
events in buffer */
char *buf; /* (I) Buffer to put
alarm events in */
Semantics This routine is used to acknowledge items. A group of items can be
acknowledged simultaneously by clustering the alarm events in the
buffer pointed to by the argument buf. Both alarm events of type
‘alm_alm_evnt’ and alarm events of type ‘alm_gen_evt’ can be put in
this buffer.
The number of events offered to this routine is not allowed to exceed the
value of the #define ALM_MAX_EVNT_ACK_AT_ONCE.
For every successful acknowledged item, the alarm kernel will generate
an acknowledge event.
When a NULL pointer is passed for the argument alm_adr, the default
It is possible for the caller of this routine to pass acknowledge info to the
routine via the argument ack_inf. The information present in this data
structure is used by the alarm kernel to generate the ‘acknowledge info’
event.
Error Codes • ALM_E_ACK_NOT_ALL Not all items acknowledged due to

status inconsistency.
• ALM_E_ILL_NR_ACK Number of events to acknowledge has
an illegal value (0 <= nr.> max.
allowed).

• ALM_E_UNKN_ITM_ID Unknown item-id specified.

9.5.28 Delete acknowledgment type in alarm kernel

Syntax [status=]alm_ackd_alm(dur_c,umh_c,ack_def,node,
error_mode)

FALSE (error) */
context */
context */
struct alm_ack_def *ack_def;
/* (I) Acknowledgement
type definition */
TLS_SHORT node; /* (I) Alarm kernel node */
TLS_BOOLEAN error_mode; /* (I) Error mode */
Semantics This routine is used to signal the deletion of an acknowledgment type to
the alarm kernel. The routine is part of the so-called definitions
interface.
The argument error_mode is used to indicate whether or not possible
error situations should be logged by the routine. By specifying the value
TRUE for this argument the routine itself will log possible error
situations.
Error Codes • ALM_E_ACK_NOTLIST Acknowledge type not known by alarm
kernel.

9.5.29 Insert acknowledgment type in alarm kernel

Syntax [status=]alm_acki_alm(dur_c,umh_c,ack_def,node,
error_mode)

FALSE (error) */
context */
context */
/* (I) Acknowledgement
type definition */
Semantics This routine is used to signal the insertion of an acknowledgment type
to the alarm kernel. The routine is part of the so-called definitions
interface.
The argument error_mode is used to indicate to the routine whether or
not possible error situations should be logged by this routine. By
specifying the value TRUE for this argument the routine itself will log
possible error situations.
Error Codes • ALM_E_ACK_ALRLIST Acknowledge type already known by
alarm kernel.

9.5.30 Modify acknowledgment type alarm kernel

Syntax [status=]alm_ackm_alm(dur_c,umh_c,ack_def,node,
error_mode)

FALSE (error) */
context */
context */
/* (I) Acknowledgement type
definition */
Semantics This routine is used to signal the modification of an acknowledgment
type to the alarm kernel. The routine is part of the so-called definitions
interface.
error situations should be logged by the routine. By specifying the value
situations.
Error Codes • ALM_E_ACK_NOTLIST Acknowledge type not known by alarm
kernel.

9.5.31 Compare source identification

Syntax [status=]alm_cmp_s_id(src_id1,src_id2)
Arguments TLS_BOOLEAN status; /* (R) TRUE (equal) or

FALSE (not equal) */
struct alm_src_id *src_id1;
/* (I) Source-id 1 */
struct alm_src_id *src_id2;
/* (I) Source-id 2 */
Semantics This routine can be used to compare two source identification fields.
This source identification field is used in the alarm event. If the
source-id’s match, the routine returns TRUE, otherwise it returns
FALSE.
Error Codes None.

9.5.32 Compare selection criteria

Syntax [status=]alm_cri_matc(sel_crit,alm_evnt)
(R) TRUE (match) or
FALSE (no match) */
struct alm_gen_evt *alm_evnt;
Semantics This routine can be used to check whether or not an alarm event matches
the selection criteria offered to this routine. The routine returns TRUE if
the alarm event matches the selection criteria, otherwise it returns
FALSE.
Via the argument alm_evnt, the alarm event to be checked, can be
passed to this routine. Both an alarm event of type ‘alm_alm_evnt’ and
an alarm event of type ‘alm_gen_evt’ can be passed to the routine.
Notes • The routine is available for upwards compatibility reasons only, the
use of alc_cri_matg() is recommended.
Error Codes None.

9.5.33 Disconnect destination from alarm kernel

Syntax [status=]alm_dst_dcon(dur_c,umh_c,alm_proc,dest)

FALSE (error) */
context */
contest */
struct dur_adr *alm_proc; /* (I) Kernel to
disconnect from */
struct dur_adr *dest; /* (I) Destination to
disconnect */
Semantics This routine is used to disconnect an alarmdestination from the alarm
kernel.
When a NULL pointer is passed for the alm_proc argument, the default
Via the dest argument, the DUR address of the process to disconnect
can be specified. When a NULL pointer is passed for the dest argument,
the process calling this routine is disconnected from the alarm kernel.
Error Codes • ALM_E_COMM_ERR General communication error.

• ALM_E_DEST_NOTEXI Destination is not known by alarm
kernel.

9.5.34 Connect destination to alarm kernel (general)

Syntax [[status=]alm_dst_gcon(umh_c,alm_proc,msg_id,dest_prio,
evnt_type,evt_layout,con_layout,
con_desc);
FALSE (error) */
struct umh_context *umh_c;/* (M) UMH context buffer */
struct dur_adr *alm_proc; /* (I) Alarm kernel */
TLS_SHORT msg_id; /* (I) Base message id */
TLS_SHORT dest_prio; /* (I) Destination
priority */
TLS_ULONG evnt_type /* (I) Alarm event type
selection */
TLS_ULONG evt_layout; /* (I) Alarm event layout */
TLS_ULONG con_layout /* (I) layout of connect
request */
char *con_desc; /* (I) Connection
descriptor */
Semantics This routine is used to connect an alarm destination to the alarm kernel
with the option to specify an ASA filter..
The field evt_layout specifies the layout of the alarm event required
by this alarm destination (please refer to section 9.4.8: Alarm event
(alm_gen_evt), for the exact meaning).
The con_layout field, specifies the layout of the connection
information passed to the alarm kernel. The next table depicts the
contents of the con_desc structure in relation to the flags specified in
con_layout:
con_layout Request info description
ALM_ASA_PFX_DESC struct gin_asa_def asa info

ALM_PRIO_DEST none
The argument alm_proc specifies the DUR address of the alarm kernel
with which to communicate. When a NULL pointer is specified for this
argument, the default alarm kernel process is assumed (local node, name
= ALM).
The value to be given for the argument dest_prio is, either
• ALM_DISP_DEST_PRIO; for display destinations
• ALM_STOR_DEST_PRIO; for storage destinations.

The field name in the con_desc specifies the ASA to be used for this
destination. Not specifying any flag for con_layout, means that no
connection information is passed to the kernel (no filtering for this
destination).
If the flag ALM_PRIO_DEST is set, then the destination should be counted
for the change priority mechanism.
The event_type parameter specifies which type of alarm events, the
connecting alarm destination wants to receive. Specification of these
type of alarm events is done, by bitwise ORing one or more of the
following event type bits:
ALM_SEL_DIR : for direct events.
ALM_SEL_ALM : for alarm events.
ALM_SEL_REP : for repeated events.
ALM_SEL_ACK : for acknowledge events.
ALM_SEL_INF : for informational events.
ALM_SEL_DAC : for deactivate events.
ALM_SEL_REC : for recovery events.
ALM_SEL_DIA : for diagnostic events.
ALM_SEL_QC : for quality code events
ALM_SEL_PRIO : for priority change events
Error Codes • ALM_E_ILL_DST_PRIO Illegal destination priority specified.

• ALM_E_COMM_ERR General communication error occurred.
• ALM_E_INTERN_ERR Internal alarm kernel error detected.
• ALM_E_ILL_ASA The alarm selection area specified.
could not be used because it has
compilation errors.
• ALM_E_NOASA The alarm selection area specified
does not exist.

9.5.35 Indicate deletion of first-out group

Syntax [status=]alm_fod_alm(dur_c,umh_c,fo_def,node,
error_mode)

FALSE (error) */
context */
context */
struct alm_fo_def *fo_def;/* (I) First-out group */
Data Structs For general structures seesection 9.4: General data structures.
Semantics This routine is used to signal the deletion of a first-out group to the alarm
kernel.The routine is part of the so-called definitions interface.
The argument error_mode is used to indicate to the routine whether or
not possible error situations should be logged by it. By specifying the
value TRUE for this argument the routine itself will log possible error
situations.
• ALM_E_FOG_NOT_TBL First-out group not known by alarm
kernel.

9.5.36 Indicate insertion of first-out group

Syntax [status=]alm_foi_alm (dur_c,umh_c,fo_def,node,
error_mode)
FALSE (error) */
context */
context */
struct alm_fo_def *fo_def;
/* (I) First-out group */
Semantics This routine is used to signal the insertion of a first-out group to the
alarm kernel. The routine is part of the so-called definitions interface.
error situations should be logged by this routine. By specifying the value
situations.
• ALM_E_FOG_ALR_TBL First-out group is already known by
alarm kernel.

9.5.37 Indicate modification of first-out group

Syntax [status=]alm_fom_alm(dur_c,umh_c,fo_def,node,
error_mode)
FALSE (error) */
context */
context */
struct alm_fo_def *fo_def;/* (I) First-out group */
Semantics This routine is used to signal the modification of a first-out group
definition to the alarm kernel. The new definition of the first-out group
should be offered to this routine. The routine is part of the so-called
definitions interface.
situations.
• ALM_E_FOG_NOT_TBL First-out group not known by alarm
kernel.

9.5.38 Notify alarm kernel of item activation

Syntax [status=]alm_itm_act(dur_c,umh_c,item_par,node,
error_mode)

FALSE (error) */
struct dur_contex *dur_c; /* (I) Buffer for
DUR context */
UMH context */
struct gin_item_alm2 *item_par;
/* (I) Item related
alarm parameters */
TLS_SHORT node; /* (I) Alarm kernel
node */
Semantics This routine is used to signal the ‘activation’ of an item, to the alarm
kernel. “Item activation” means, item must be monitored on alarm
situations. Hence, the routine should only be called for items that should
be monitored on alarm situations. The routine is part of the so-called
definitions interface.
The routine assumes the item to be activated, is already known by the
item handler and put in the item definition database.
A side effect of calling this routine is the generation of an alarm event
by the alarm kernel.
TRUE for this argument, the routine itself will log possible error
situations.
• ALM_E_UNKN_ITM_ID Unknown item id specified.

9.5.39 Notify alarm kernel of item deactivation

Syntax [status=]alm_itm_dac(dur_c, umh_c, item_par, node,
error_mode)
FALSE (error) */
context */
context */
struct gin_item_alm2 *item_par;
/* (I) Item related alarm
parameters */
Semantics This routine is used to signal the ‘deactivation’ of an item to the alarm
kernel. “Item deactivation” means, item need not be monitored on alarm
situations anymore. The routine is part of the so-called definitions
interface.
A side effect of calling this routine is the generation of a deactivate event
by the alarm kernel.
situations.
ALM_E_INTERN_ERRInternal alarm kernel error.

9.5.40 Notify alarm kernel of item modification

Syntax [status=]alm_itm_mod(dur_c,umh_c,old_item_par,
new_item_par,node,error_mode)

FALSE (error) */
context */
context */
struct gin_item_alm2 *old item_par;
/* (I) Old item related
alarm parameters */
struct gin_item_alm2 *new_item_par;
/* (I) New itemrelated
alarmparameters */
Semantics This routine is used to indicate to the alarm kernel the ‘modification’ of
item related alarm parameters. Item related alarm parameters are the
parameters as defined in the structure gin_item_alm. A side effect of
calling this routine, is the generation by the alarm kernel of:
• a deactivate event
• an alarm event in those cases that in the new situation alarm
monitoring is still required for the item concerned.
The routine is part of the so-called definitions interface. The argument
error_mode is used to indicate to the routine whether or not possible
situations.
• ALM_E_UNKN_ITM_ID Unknown item id specified.

9.5.41 Non item-based event interface

Syntax [status=]alm_nib(dur_c,umh_c,nib)

FALSE (error) */
context */
context */
struct alm_nib_evnt *nib; /* (I) Non item based
event */
Semantics This routine is used to send a non item based event to the alarm kernel.

• ALM_E_ILL_PRIO Illegal priority value specified.

9.5.42 ALDMAN attach message

BUS/FAST Message id: ALD_COD_MAN_ATT
Message Request data: struct ald_man_att
Reply data: struct ald_man_att
Data Structs struct ald_man_att
{
struct ald_id alarm_dest_id;
char asa_name[GIN_MAX_ASA_NAME];
TLS_SHORT chg_asa_msgid;
TLS_SHORT dummy;
TLS_LONG ref;
};
struct ald_id
{
struct dur_adr adr;
char display_name[GIN_CWS_MAX_DIS_NAM];
};
Semantics On start-up an alarm destination can attach to an alarm destination
manager, specifying the alarm selection area to be used. Alarm
destinations can be, for example, displays or alarm printers.
The destination manager will use the specified destination identification
ald_id, to communicate with the destinations.
The field chg_asa_msgid specifies the message id to be used in change
alarm selection area requests.
The field ref may contain application dependent information such as
the alarm window number. This field is always filled with the
information passed to the ALDMAN during the attach request.
The asa_name in the reply must contain the same asa_name as in the
request, when it must not be changed. The asa_name in the reply will be
used in the connection to the alarm kernel.
Error Codes None.

9.5.43 ALDMAN detach message
BUS/FAST Message id: ALD_COD_MAN_DET

Message Request data: struct ald_id
Reply data: struct ald_id
Semantics On exit an alarm destination should detach itself from the ALDMAN, by
sending a BUS/FAST detach message.
Notes No reply is required for this message.
Error Codes None.

9.5.44 Change ASA message

BUS/FAST Message id: as specified in the attach message
Message Request data: struct ald_chg_asa
Reply data: struct ald_id
Data Structs struct ald_chg_asa
{
struct ald_id alarm_dest_id;
char asa_name[GIN_MAX_ASA_NAME];
TLS_LONG ref;
};
Semantics This message is sent by the ALDMAN, if the alarm selection area for an
alarm destination has to be changed.

9.5.45 Recover message

BUS/FAST Message id: ALM_COD_REC
Message Request data: struct alm_recover
Data Structs struct alm_recover
{
struct itm_val_sta vast;/* Not used anymore */
struct gin_item_alm2 item_inf;
/* Alarmparameters */
};
Semantics This message can be sent to the alarm kernel to recover the specified
item. When this message is received, the alarm kernel fetches the current
item value/status and quality code. With this information, the alarm
kernel performs an internal self check and updates its internal
administration if any inconsistencies are found.
Independent of finding inconsistencies, the alarm kernel sends a
recovery event to the destinations interested in this type of event.
SEMANTICS
Error Codes None.

9.5.46 Get ALM parameter info

[status=]alm_get_inf(umh_c,alm_proc,inf)

FALSE (error) */
context */
struct dur_adr *alm_proc;
/* (I) Alarm kernel */
struct alm_get_inf *inf; /* (O) ALM parameter info */
Semantics This routine is used, to connect an alarm destination to the alarm kernel.
The argument alm_adr specifies the DUR address of the alarm kernel
to connect to. When a NULL pointer is passed for this argument, the
default alarm kernel process is assumed (local node, name = ALM).
The actual ALM parameters are returned in the alm_get_inf struct.


Introduction Examples
A.1 Introduction
In this appendix an example is given of what the framework of a VDU-
based alarm destination could look like. Furthermore an example is giv-
en of the usage of the internal window representation.
For detailed information about function arguments and other details,
please consult the reference section of this document.
A.2 Usage of V.D.U.-based routine set

This section illustrates the usage of the VDU-based routine set.
The code fragments presented in this section, could serve as an example
for a VDU-based alarmdestination.
...
#include <adt.h>
TLS_BOOLEAN vdu_dest(...)
{
TLS_SHORT event;
TLS_BOOLEAN exit = FALSE;
/* Initialize this alarm destination */

if ((scn_c = ald_vdu_gini(...)) == (struct ald_s_cont *)NULL)
{
}
/* Display initial screen */

...
while (!exit)
{
/* Wait for user event to happen (user browse action
or receipt of message from alarm kernel) */
accept (&event);
switch (event)
{
case BROWSE_ACT_TOP:
/* TOP browse action */
if (!ald_vdu_top(....,&scn_c))
{
}
break;
case BROWSE_ACT_*:
/* Other browse actions, causing related
ALARM/FAST Programmer’s Guide A-1

Examples Usage of internal window representation
’ald_vdu_* routines to be called */

break;
case ALARM_EVENT_MESSAGE:
if (!ald_vdu_gevt(...))
{
}
break;
case OVERFLOW_MESSAGE:
if (!ald_vdu_ovf(...))
{
}
break;
case SYNCHRONIZATION_MESSAGE:
if (!ald_vdu_sync(...))
{
}
break;
case EXIT:
ald_vdu_exit(...);
exit = TRUE;
break;
} /* End of ’switch()..’ */
/* Display contents of window */

...
} /* End of ’while()..’ */
return(TRUE);
}
A.3 Usage of internal window representation

This paragraph illustrates by means of a code fragment how the internal
window representation can be transformed to write actions to a display
device.
TLS_BOOLEAN write_window(scn_c,...)
{
char *back_n_p;
int nr;
int line;
int field_index;
int txt_idx;
struct ald_s_l_elem *cur_line;
/* If contents window did not change, no write actions necessary */

if (!scn_c->nr_wdw_chg)
return(TRUE);
for (cur_line = scn_c->first_line, nr = 1;

nr <= scn_c->max_msg;
nr++)
A-2 ALARM/FAST Programmer’s Guide

Usage of internal window representation Examples
{
/* Determine index number of field to start the write action
for this alarm line */
field_index = (nr - 1) * scn_c->lin_per_msg + 1;
/* Check if a linked list element is available for alarmline ‘nr’ */

if ((cur_line != (struct ald_s_l_elem *)NULL) &&
(cur_line->rel_msg_nr == nr))
{
/* Line element present, process it */
for (line = 1, txt_idx = 0;
line <= scn_c->lin_per_msg;
line++, field_index++)
{
/* The ‘\n‘ characters in the textbuffer must be converted
to write actions to the next index field */
if ((back_n_p = strchr(&cur_line->txt[txt_idx],‘\n‘))
!= (char *) NULL)
{
/* Replace ‘\n‘ character by (temporary) ‘0’ character, and
write the contents (up to ‘0‘ character) to current field index */
*back_n_p = ‘\0’;
...
/* Restore the original ‘\n‘ character */

*back_n_p = ‘\n’;
txt_idx = back_n_p - cur_line->txt + 1;
}
else
{
/* Appearently no ‘\n’ characters (anymore). Just write to the
current index field */
...
}
}
/* Point to next line in list */

cur_line = cur_line->nxt_line;
}
else
{
/* Appearantly no list element for this line, blank line */
for (line = 1;
line ‹ scn_c->lin_per_msg;
line++, field_index++)
{
...
}
}
} /* End of outermost ‘for (..)’ loop*/
} /* End of outermost ‘for()’ loop */
return (TRUE);
}
ALARM/FAST Programmer’s Guide A-3

Examples Usage of internal window representation
A-4 ALARM/FAST Programmer’s Guide

Index
Index
A connect
to ALARM/FAST 5-1, 5-6, 9-71
acknowledge 4-1, 9-26, 9-27 current storage type
info event 4-2 priority-based 9-44
interface 1-1, 4-1, 9-49, 9-50 time-based 9-44
acknowledgment type 3-1, 9-52, 9-53,
9-54 D
definition of 3-2
alarm datastructure
destination manager 8-5 ald_line_fmt 9-3
kernel 3-1 ald_s_cont 9-5
selection area 8-5, 9-18, 9-32 ald_s_l_elem 9-5
alarm attribute 3-1 ald_vdu_gini 9-6
definition of 3-2, 9-63, 9-64, 9-65 alh_his_info 9-7
alarm event 5-6, 9-8, 9-31 alm_ack_inf2 9-7
information bits 5-7 alm_ack_time 9-8
layout of 5-6 alm_alm_evnt 9-10
selection bits 5-7 alm_aoi_inf 9-9
alarm event message 9-31 alm_evnt_id 9-10
alarm event type 5-3, 9-18 alm_evnt_inf 9-10
acknowledge 4-1 alm_fo_def 9-13
deactivate 9-65 alm_gen_evt 9-8
informational 2-2 alm_nib_evnt 9-13
alarm selection area mechanism 5-4 alm_q_ovflw 9-14
ALD_COD_MAN_ATT 9-67 alm_qc_inf 9-9
ALD_COD_MAN_DET 9-68 alm_recover 9-14
ALDMAN 8-5 alm_sel_inf 9-15
attach 8-5, 9-67 alm_str_inf 9-9
change alarm selection area 8-6 alm_subj_id 9-15
detach 8-6, 9-68 alm_sync_upd 9-16
ALM_COD_REC 9-70 definition
attach of acknowledgment type 3-2
to ALDMAN 8-5 of alarm attribute 3-2
of first-out group 3-1
B definitions interface 1-1, 3-1, 9-52, 9-
53, 9-54, 9-60, 9-61, 9-62, 9-63,
base message id 5-6 9-64, 9-65
BETWEEN global position 8-2 destination priority 5-3
BOTTOM global position 8-2 detach
from ALDMAN 8-6
C diagnostic text 2-2
change priority mechanism 5-4 disconnect
chronological overview 8-1, 9-34 from ALARM/FAST 5-1, 5-5, 9-57
chronological storage type 9-44 distribution interface 1-1, 5-1
ALARM/FAST Programmer’s Guide 1

Index
E L
event layout
item-based 1-1, 2-1 of alarm event 5-6
non-item-based 1-1, 2-1, 2-2 of alarm message 9-21
event handling
for VDU-based destination 8-2 M
external window representation 8-4 mechanism
alarm selection area 5-4
F change priority 5-4
first-out group 3-1, 9-60, 9-61, 9-62 synchronization 5-7
definition of 3-1 message
format description alarm event 9-8, 9-31
of alarm line 9-23 overflow 5-7, 9-37
synchronization 9-16, 9-41
G message unit 9-21
global position length of 9-21
BETWEEN 8-2
BOTTOM 8-2 N
of window 8-1 non-item-based event 1-1, 2-1, 2-2
TOP 8-2
O
H optional selection criteria 5-4
historical information 9-47 overflow message 5-6, 5-7, 9-14, 9-37
overview
I chronological 8-1, 9-34
inconsistency priority-based current 8-1, 9-34
recovery from 7-1, 9-70 time-based current 8-1, 9-34
information
historical 9-47 P
information bits 9-12 priority counting destination 5-4
initialize VDU-based destination 8-2 priority of destination 5-3
input events interface 1-1 priority-based
interface current overview 8-1, 9-34
acknowledge 1-1, 4-1, 9-49, 9-50 current storage type 9-44
definitions 1-1, 9-52, 9-53, 9-54, 9- process
60, 9-61, 9-62, 9-63, 9-64, 9- ALDMAN 8-5
65
distribution 1-1, 5-1 Q
external 1-1 queue overflow 5-7, 9-14
input events 1-1
recovery 1-1 R
retrieval 1-1
recovery
interface definition 3-1
from inconsistent situations 9-70
internal window representation 8-3, 8-4
interface 1-1
item
required selection criteria 5-4
status change 2-1
retrieval interface 1-1
item-based event 1-1, 2-1
2 ALARM/FAST Programmer’s Guide

Index
S
screen context 8-2
selection bits
of alarm event 5-7
selection criteria 5-4, 9-56
optional 5-4, 5-5
required 5-4
selection filter 5-7
setup file 9-23, 9-24, 9-32, 9-33
status change
of item 2-1
storage type
chronological 9-44
priority-based current 9-44
time-based current 9-44
synchronization
mechanism 5-7
message 5-6, 5-7, 5-8, 9-16, 9-41
T
terminate VDU-based destination 8-2
time-based
current overview 8-1, 9-34
current storage type 9-44
TOP global position 8-2
U
update info code 2-2
ITM_UPD_INF_ITM_DSC 2-2
ITM_UPD_INF_NAM1 2-2
ITM_UPD_INF_STA_TXT 2-2
V
VDU-based destination
event handling for 8-2
initialization of 8-2
termination of 8-2
VDU-based routine set 8-3
W
window 8-1
window representation
external 8-4
internal 8-2, 8-4
ALARM/FAST Programmer’s Guide 3

Index
4 ALARM/FAST Programmer’s Guide

YOKOGAWA ELECTRIC
CORPORATION
Musashino-shi,
tel: +81-422-52-5616
email:
Reader’s Comment
improvement.
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
.....................................................................................................................................................
Name:....................................................................................................Date ..............................
Organization: ...............................................................................................................................
Address: .......................................................................................................................................
City and Zip code:........................................................................................................................
Country: .......................................................................................................................................
Instruction BUS/FAST FAST/TOOLS
Manual FSL Programmer’s Guide
IM50E02E02-01EN/R10.03

IM50E02E02-01EN/R10.03
Tel: +81-422-52-5616
YOKOGAWA
document.
ii
Table of Contents
Table of Contents
0 Preface ...................................................................................0-1
0.1 Manual objectives ......................................................0-1
1 Overall Reference .................................................................1-1
1.1 Conventions ...............................................................1-1
1.2 Compiling, linking and running programs ................1-2
1.3 Error handling ............................................................1-2
2 FCM .......................................................................................2-1
2.1 Communication routines ............................................2-1
2.1.1 FCM functions ..............................................2-1
2.1.2 Setup file .......................................................2-2
2.2 FCM routines .............................................................2-3
2.2.1 Attach communication port ..........................2-4
2.2.2 Detach communication port ..........................2-5
2.2.3 Initialize line parameters ...............................2-6
2.2.4 Read number of characters ...........................2-7
2.2.5 Read till terminating characters ....................2-8
2.2.6 Set break characters ......................................2-9
2.2.7 Set timeout ..................................................2-10
2.2.8 Read setup file ............................................2-11
2.2.9 Write number of characters ........................2-13
2.2.10 Read number of characters after prompt ....2-14
2.2.11 Read till terminating characters ..................2-15
3 FCR ........................................................................................3-1
3.1 Introduction ...............................................................3-1
3.2 FCR routines ..............................................................3-1
3.2.1 Case insensitive string compare ....................3-2
3.2.2 Case Insensitive string compare of
N characters ..................................................3-3
3.2.3 Memory compare ..........................................3-4
3.2.4 Memory copy ................................................3-5
3.2.5 Initialize struct or char-buffer .......................3-6
FSL Programmer’s Guide iii

Table of Contents
4 FDF ........................................................................................ 4-1

4.1 Introduction ............................................................... 4-1
4.2 Categories ................................................................. 4-1
4.3 Virtual display ........................................................... 4-2
4.4 Data structures .......................................................... 4-2
4.4.1 Virtual display representation ...................... 4-3
4.4.2 House keeping representation ...................... 4-3
4.4.3 Screen display representation ....................... 4-4
4.4.4 Terminal class characteristics ...................... 4-4
4.5 FDF routines ............................................................. 4-5
4.5.1 Set scroll area for displaying ........................ 4-6
4.5.2 Set reverse video attribute on/off for
displaying ..................................................... 4-7
4.5.3 Clear the physical display down to the bottom
line ................................................................ 4-8
4.5.4 Clear the physical display to the end of
line ................................................................ 4-9
4.5.5 Clear the entire physical display ................ 4-10
4.5.6 Move the physical text cursor .................... 4-11
4.5.7 Print text on physical display ..................... 4-12
4.5.8 Get terminal characteristics ........................ 4-13
4.5.9 Clear the virtual display down to the
bottom line ................................................. 4-14
4.5.10 Clear the virtual display to the end of line . 4-15
4.5.11 Clear the entire virtual display ................... 4-16
4.5.12 Terminate the usages of the virtual display 4-17
4.5.13 Update the physical display ....................... 4-18
4.5.14 Initialize the virtual display ........................ 4-19
4.5.15 Move the virtual text cursor ....................... 4-20
4.5.16 Print text on virtual display ........................ 4-21
4.5.17 Set the scroll mode ..................................... 4-22
5 FGR ....................................................................................... 5-1
5.1 Introduction ............................................................... 5-1
5.2 Description ................................................................ 5-1
5.3 Data structures .......................................................... 5-1
5.3.1 Graphic context ............................................ 5-1
5.3.2 Graphic line .................................................. 5-3
5.4 Routine flags ............................................................. 5-4
5.4.1 Graphic ......................................................... 5-4
5.4.2 Date and time ............................................... 5-6
5.4.3 Value ............................................................ 5-7
5.5 Display formats for line structure ............................. 5-8
5.5.1 G float .......................................................... 5-9
iv FSL Programmer’s Guide

Table of Contents
5.5.2 F float ............................................................5-9

5.5.3 E float ...........................................................5-9
5.5.4 Long representation ......................................5-9
5.6 FGR routines .............................................................5-9
5.6.1 Write date and/or time line .........................5-10
5.6.2 Convert a buffer with doubles ....................5-11
5.6.3 Terminate the graphic actions .....................5-13
5.6.4 Convert graphic point tables to graphic ......5-14
5.6.5 Initialize the graphic actions .......................5-15
5.6.6 Get the address of a line ..............................5-17
5.6.7 Convert a buffer with doubles ....................5-18
5.6.8 Make status texts known .............................5-20
5.6.9 Write the value table below the graphic .....5-21
6 FIM ........................................................................................6-1
6.1 Sequential indexed file in memory ............................6-1
6.1.1 FIM functions ...............................................6-1
6.1.2 Storage technique .........................................6-2
6.2 FIM routines ..............................................................6-3
6.2.1 Close and delete file .....................................6-4
6.2.2 Change key to a pre-defined key ..................6-5
6.2.3 Create indexed sequential file .......................6-6
6.2.4 Create alternate key for file ..........................6-7
6.2.5 Delete a record from the file .........................6-8
6.2.6 Insert a new record in the file .......................6-9
6.2.7 Modify a record ..........................................6-10
6.2.8 Read record from file ..................................6-11
7 FIO .........................................................................................7-1
7.1 Input functions ...........................................................7-1
7.2 FIO Routines .............................................................7-5
7.2.1 Get (non) confirmation character ..................7-6
7.2.2 Get input of type double ...............................7-8
7.2.3 Get input of type long .................................7-10
7.2.4 Get ASCIZ string ........................................7-12
7.2.5 Get input double within specified range .....7-14
7.2.6 Get long within specified range ..................7-16
7.2.7 Get limited ASCIZ string ...........................7-18
8 FMC .......................................................................................8-1
8.1 Introduction ...............................................................8-1
8.1.1 Clustered message layout .............................8-1
8.1.2 Clustering of messages .................................8-2
8.1.3 Message interpretation ..................................8-2
FSL Programmer’s Guide v

Table of Contents
8.2 FMC routines ............................................................ 8-4

8.2.1 Cluster message, add size and id .................. 8-5
8.2.2 Cluster message, return next address ........... 8-6
8.2.3 De-cluster message and handle error reply .. 8-7
8.2.4 De-cluster message and return address ........ 8-9
9 FMF ....................................................................................... 9-1
9.1 Introduction ............................................................... 9-1
9.2 Categories ................................................................. 9-1
9.2.1 Representation-type conversion routines ..... 9-1
9.2.2 System independent ‘system calls’ .............. 9-2
9.2.3 C look-alikes ................................................ 9-2
9.2.4 Other routines ............................................... 9-3
9.3 FMF Routines ........................................................... 9-3
9.3.1 General memory allocation routine .............. 9-3
9.3.2 Binary search routine to search in array ....... 9-4
9.3.3 Is brick installed ........................................... 9-5
9.3.4 Swap bits ...................................................... 9-6
9.3.5 Convert a bitmap .......................................... 9-6
9.3.6 Check a file string containing a directory
path ............................................................... 9-7
9.3.7 Convert directory number to
directory string ............................................. 9-7
9.3.8 Analyze command line ................................. 9-8
9.3.9 Convert representation to boolean ............. 9-10
9.3.10 Convert representation to double ............... 9-11
9.3.11 Convert representation types ...................... 9-12
9.3.12 System independent file delete .................. 9-15
9.3.13 Copy file ..................................................... 9-15
9.3.14 Format value using a format string ............ 9-16
9.3.15 Get the process name ................................. 9-17
9.3.16 Obtain function from a dynamic link library . 9-
18
9.3.17 Open a file using directory number ............ 9-19
9.3.18 Open a file using directory name ............... 9-19
9.3.19 System independent file print .................... 9-21
9.3.20 Print help information ................................ 9-23
9.3.21 Purge old versions of file ........................... 9-24
9.3.22 System independent file rename ................ 9-25
9.3.23 Spawn a process ......................................... 9-25
9.3.24 Convert a string to a bitmap ....................... 9-26
9.3.25 Find occurrence of one string in another ... 9-27
9.3.26 Convert ASCIZ string to lowercase ........... 9-27
9.3.27 Convert N characters to lowercase ............. 9-27
vi FSL Programmer’s Guide

Table of Contents
9.3.28 Convert N characters to uppercase .............9-27

9.3.29 Compare strings and returns different
position .......................................................9-28
9.3.30 Compare strings, allowing for wildcards ....9-28
9.3.31 Convert ASCIZ string to uppercase ............9-29
9.3.32 Wait some milliseconds ..............................9-29
10 FRF ......................................................................................10-1
11 FSC ......................................................................................11-1
11.1 Introduction to FSC .................................................11-1
11.1.1 External format ...........................................11-1
11.1.2 Internal format ............................................11-3
11.2 Converting a message ..............................................11-3
11.3 Routines ...................................................................11-5
11.3.1 Convert a struct to another system type ......11-6
11.3.2 Convert a data type to another system type 11-9
11.3.3 Convert external format to internal format 11-10
11.3.4 Collect formats .........................................11-12
12 FSU ......................................................................................12-1
12.1 The set up facility ....................................................12-1
12.1.1 Description ..................................................12-1
12.1.2 Set up file conventions ...............................12-3
12.1.3 Set up functions ..........................................12-4
12.1.4 Names of set up files ..................................12-4
12.2 FSU routines ............................................................12-5
12.2.1 Close set up file ..........................................12-6
12.2.2 Get current position in the file ....................12-7
12.2.3 Get next line from set up file ......................12-8
12.2.4 Open a set up file ......................................12-10
12.2.5 Position file for set up utility ....................12-11
12.2.6 Rewind file to beginning ..........................12-12
12.2.7 Search for line starting with keyword .......12-13
13 FTB ......................................................................................13-1
13.1 Introduction .............................................................13-1
13.2 Table context data structure .....................................13-1
13.3 Table flags ...............................................................13-2
13.3.1 Date and time ..............................................13-3
13.3.2 Doubles and statuses ...................................13-4
13.3.3 Example ......................................................13-4
13.4 Display formats .......................................................13-5
13.4.1 G float .........................................................13-6
13.4.2 F float ..........................................................13-6
FSL Programmer’s Guide vii

Table of Contents
13.4.3 E float ......................................................... 13-6

13.4.4 Long representations .................................. 13-7
13.5 FTB Routines .......................................................... 13-7
13.5.1 Write the date and/or time column with fixed
interval ....................................................... 13-8
13.5.2 Write the date and/or time column with
variable intervals ........................................ 13-9
13.5.3 Convert a buffer with doubles to table
values ....................................................... 13-10
13.5.4 Terminate table actions ............................ 13-11
13.5.5 Initialize the table actions ........................ 13-12
13.5.6 Get the table line address ......................... 13-13
13.5.7 Convert a buffer with longs to table values . 13-
14
13.5.8 Convert status numbers ............................ 13-15
14 FTM ..................................................................................... 14-1
14.1 Date and time functions .......................................... 14-1
14.2 Time representations ............................................... 14-1
14.2.1 Greenwich Mean Time (GMT) .................. 14-1
14.2.2 Local Standard Time (LST) ....................... 14-2
14.2.3 Local Civil Time (LCT) ............................. 14-2
14.3 Representations formats .......................................... 14-2
14.3.1 Packed format ............................................ 14-2
14.3.2 Unpacked format ........................................ 14-3
14.3.3 ASCII format .............................................. 14-4
14.4 The time zone .......................................................... 14-4
14.5 Date/time conventions ............................................ 14-5
14.6 Internal mechanism ................................................. 14-6
14.7 List of routines by format ....................................... 14-7
14.8 Date/time routines ................................................... 14-8
14.8.1 Convert GMT to formatted
LCT time string .......................................... 14-8
14.8.2 Calculate time + number of days ............. 14-10
14.8.3 Add two times .......................................... 14-11
14.8.4 Set system time to ASCII time ................. 14-12
14.8.5 Set system time to packed time ................ 14-14
14.8.6 Convert unpacked format to ASCII ......... 14-15
14.8.7 Complete struct tm ................................... 14-16
14.8.8 Convert packed format to ASCII ............. 14-17
14.8.9 Convert time to gmt/lst/lct (packed) ........ 14-18
14.8.10 Calculate number of days between 2 packed
times ......................................................... 14-19
14.8.11 Format date/time output with picture
viii FSL Programmer’s Guide

Table of Contents
string .........................................................14-20
14.8.12 Convert ASCII to unpacked format ..........14-23
14.8.13 Calculate (packed) time from number of
days ...........................................................14-24
14.8.14 Calculate daynumber since 1970.0 ...........14-25
14.8.15 Get system time in gmt and time-zone
info ............................................................14-26
14.8.16 Get time zone names .................................14-27
14.8.17 Get week-of-year number .........................14-28
14.8.18 Get time GMT, LST, LCT (packed) .........14-29
14.8.19 Convert ASCII to packed format ..............14-30
14.8.20 Update system-time(lct) using time-table .14-32
14.8.21 Get generation parameter values ..............14-33
14.8.22 Convert unpacked format to packed
format ........................................................14-34
14.8.23 Subtract two times ....................................14-35
14.8.24 Get system-time (ANSI) ...........................14-36
14.8.25 Fast routine to return time as hh:mm:ss ....14-37
14.8.26 Load time table in buscom ........................14-38
14.8.27 Convert packed to unpacked .....................14-40
FSL Programmer’s Guide ix

Table of Contents
x FSL Programmer’s Guide

Manual objectives Preface
0 Preface
0.1 Manual objectives
functionality of the FAST SUPPORT library.
• Provide experienced users with a reference to the usage of all
available routines.

C language.
The reader is assumed to have a knowledge of BUS/FAST, especially
the Message passing principle (DUR) and the Unsolicited Message
Handler (see section 0.4 Associated documents).

• Chapter 1 introduces the reader to the functionality of the FAST
SUPPORT library and gives reference information which applies to
all subsequent chapters.
• Chapter 2 to 13 describe all functions provided by FSL in detail.
Each chapter comprises a functional part of FSL, providing a
tutorial and reference information.

1 DUR PROGRAMMER’S GUIDE
2 UMH PROGRAMMER’S GUIDE
Provides a description of the standard error logging facilities which
are available.

FSL Programmer’s Guide 0-1

CONVENTION MEANING
() Parentheses used in routine syntax to indicate a listof
[,...] Indicates that the previous item may be repeated at

least once.
UPPERCASE Indicate reserved words and predefined letters

names, e.g. NULL, TRUE, DUR_NOWAIT.
(M) Indicates that the specified parameter may have been

modified when the routine returns.
(M)DUR Indicates that the description is valid.for both DUR

and MDUR usage.
"" Used in format descriptions. Double quotes indicate

that the character is to be taken literally.

variable.
<file_name>+ Used in syntax descriptions. One or more file names

may be entered.
n.u. Not used.
0-2 FSL Programmer’s Guide

Conventions Overall Reference
1 Overall Reference
1.1 Conventions
All FSL routines have C-type interfaces. The syntax of all routines as
well as the examples comply with C Language Bindings.
In the routine descriptions the pointer to each parameter, that is not a

scalar argument, is declared. Unless specified otherwise, you have to
declare the parameter itself also!
The direction of the argument is indicated with (R), (I), (O) or (M).
(R)eturn indicates the return value of the routine. For routines that are
of type void, the return value (R) is omitted.
(I)nput indicates that the buffer must contain information which is
used by the routine.
(O)utput indicates that information is returned in that argument.
(M)odify is a combination of both input and output; the contents of the
argument you pass as input might be modified when the
routine returns.
Example: the syntax of routine fsc_form() looks like this:
[status=]fsc_form(err_cont,int_form,size_left,ext_form)
TLS_BOOLEAN status; /* (R) TRUE if success, FALSE if

error */
/* (M) Error context */
char *int_form; /* (O) Internal format buffer */
int *size_left; /* (M) Size of internal format buffer
*/
char *text_form; /* (I) External format buffer */

syntax this is indicated with [status=]. The type TLS_BOOLEAN is
defined in header file global.h.
In some routines, you must enter symbol definitions. The symbol
definitions are written in CAPITALS, e.g. the fio_get_long() routine
requires a mode to be entered. The mode maybe a bitwise and of:
• FIO_RETRY
• FIO_FDL
• FIO_HEX

Overall Reference Compiling, linking and running programs
• FIO_SPACE
All routine names in FSL as well as the datastructs, have a name starting
with the letter F, followed by two other letters. Do not use a routine or
variable name that starts with these letters in your application.

The sources must include the proper .h files. By including the file fsl.h,
all header files of all subfunctions of FSL are included.
This might be overdone when only a few routines are used. It is also
possible to include only the header files that apply to specific routines.
These header files are:
• fsl_fcm.h
• fsl_fcr.h
• fsl_fdf.h
• fsl_fgr.h
• fsl_fim.h
• fsl_fio.h
• fsl_fmc.h
• fsl_fmf.h
• fsl_frf.h
• fsl_fsc.h
• fsl_fsu.h
• fsl_ftb.h
• fsl_ftm.h
Note that for some fsl routines it is necessary to be attached to (M)DUR

(see DUR Programmer’s Guide).
Most routines use the UMH facility for error information. These routines
require initialization of DUR and UMH context.
1.3 Error handling

A number of FSL routines use the standard error handling facilities of
UMH. Those routines require a buffer to be passed as argument in which
error context is returned. The error logging approach conforms to the
recommendation in the UMH Programmer’s Guide.

Communication routines FCM
2 FCM
2.1 Communication routines

The FCM routine set contains a number of routines to initiate and handle
communication for a serial port. By using this serial communication
routine set the communication can be programmed on a machine
independent way.
2.1.1 FCM functions
The FCM routine functions may be divided into the following

categories:
• Get communication line parameters and initialize access.
The function fcm_sersup() will read the communication line
parameters from a setup file and will create a line parameters block.
The function fcm_serini() can be used to create a line parameters
block specifying the parameters as arguments.
The function fcm_serstm() can be used to modify the timeout
parameter in the line parameters block.
The function fcm_sersbr() can be used to modify the brteak
characters parameter in the line parameters block.
• Initialize and terminate the communication.
The function fcm_seratt() attaches the communication port.
The function fcm_serdet() detaches the communication port.
• Read from communication line.
The function fcm_serrd1() reads a specified number of
characters from the communication port.
The function fcm_serrd2() reads characters from the
communication port until a special terminating character is read.
• Write to communication line.
The function fcm_serwr() writes a number of characters to the
communication port.
• Read after prompt functions.
These functions are a combination of the write action followed by
one of the read actions.
The function fcm_serwrd1() writes a number of characters to the
communication port and reads a specified number of characters
from the communication port

FCM Communication routines
The function fcm_serwrd2() writes a number of characters to the

communication port and reads characters from the communication
port until a special terminating character is read.
2.1.2 Setup file
The routine fcm_sersup() will read the communication port

parameters from a setup file. The routine will open the setup file and
search to a keyword LINE with the correct line number. Behind that
keyword and before the keyword END_LINE all communication port
parameters must be specified. The possible keywords are:
• baud = <baud rate>
<baud rate> is 300, 600, 1200, 2400, 4800 or 9600.
Default: 9600
• bits = <bits/char>
<bits/char> is 7 or 8.
Default: 8
• parity = <parity>
<parity> is NONE, ODD or EVEN.
Default: NONE
• stopbits = <stop bits>
<stop bits> is ONE or TWO.
Default: ONE
• xon_xof = <xon_xof>
<xon_xof> is YES or NO.
Default: NO
• time_out = <time>
<time> is timeout in milliseconds. Zero implies no timeout.
Default: 0
• write_wait = <time>
<time> is extra wait time before each write in milliseconds.
Default: 0
• type_ahead = <type_ahead>
<type_ahead> is YES or NO.
Default: NO (= Do not use type ahead buffer).
• break_chars = <break_char>[,<break_char>]...
Is comma separated list of so called break characters (in hex). These
characters are protocol dependent. If not specified then no break
characters are used.
Example:
LINE = 1

FCM routines FCM
BAUD = 9600
PARITY = EVEN
BREAK_CHARS = 03, 20, FF
END_LINE
2.2 FCM routines

This section describes the following FCM routines:
• fcm_seratt() Attach serial port.
• fcm_serdet() Detach port.
• fcm_serini() Initialise parameters.
• fcm_serrd1() Read number of characters.
• fcm_serrd2() Read till terminating characters.
• fcm_sersbr() Change break characters.
• fcm_serstm() Change time-out.
• fcm_sersup() Read setup file parameters.
• fcm_serwr() Write number of characters.
• fcm_serwrd1() Read number of characters after prompt.
• fcm_serwrd2() Read till terminating characters after prompt.

FCM FCM routines
2.2.1 Attach communication port
SYNTAX
Syntax [status=]fcm_seratt(umh_cont, lin_par, name)
Arguments struct umh_context *umh_cont; /*(M)Pointer to umh
context */
char *lin_par; /*(M)Pointer to line
parameters */
char *name; /*(I)Pointer to
port name */
Semantics This function attaches the communication port specified by name and
changes the port characteristics according to the parameters read by
fcm_sersup().
For the syntax of name see the routine fsu_open().
Errors • FSL_E_OPENERROR
Unable to open the port.
• FSL_E_GCHARERROR
Unable to get port characteristics.
• FSL_E_SCHARERROR
Unable to set port characteristics.
• FSL_E_GTIMEERROR
Unable to get port timeout parameters.
• FSL_E_STIMEERROR
Unable to set port timeout parameters.
• CRL_E_*
Standard C runtime library errors.

FCM routines FCM
2.2.2 Detach communication port
SYNTAX
Syntax [status=]fcm_serdet(umh_cont, lin_par)
context */
char *lin_par; /*(I)Pointer to line
parameters */
Semantics This function detaches the communication port.
Errors None.

FCM FCM routines
2.2.3 Initialize line parameters
SYNTAX
Syntax lin_par=fcm_serini(umh_cont, baud, bits, parity, stop,
xon)
Arguments char *lin_par; /*(R)Pointer to line
parameters */
struct umh_context *umh_cont; /*(M)Pointer to umh
context */
int baud; /*(I)Baudrate to use */
int bits; /*(I)Data bits to use */
int parity; /*(I)Parity type to use */
int stop; /*(I)Stop bits to use */
TLS_BOOLEAN xon; /*(I)xon/xoff to use */
Semantics This function creates a line parameters block and stores the arguments
into it. For parity one of the defines FCM_LIN_SER_PAR_NONE,
FCM_LIN_SER_PAR_ODD or FCM_LIN_SER_PAR_EVEN should
be used.
Default values used when 0 or “\0” specified:
baud = 9600
bits = 8
parity = FCM_LIN_SER_PAR_NONE
stop = 1
• FSL_E_NO_SPACE
No malloc() space for allocating the parameters block.
• FSL_E_SERILLBAUD
An illegal baud rate is specified.
• FSL_E_SERILLBITS
An illegal number of bits is specified.
• FSL_E_SERILLPAR
An illegal parity is specified.
• FSL_E_SERILLSTP
An illegal number of stop bits is specified.

FCM routines FCM
2.2.4 Read number of characters
SYNTAX
Syntax [status=]fcm_serrd1(umh_cont, lin_par, in, size)
context */
parameters */
char *in; /*(O)Pointer to input
buffer */
TLS_SHORT *size; /*(M)Pointer to size */
Semantics This function reads characters from the communication port till size is
reached or an error (e.g. timeout) is occurred. The number of characters
read is returned in size.
Errors • FSL_E_LINENOTAT
The port is not attached.
• FSL_E_READERROR
A read error has occurred.
• FSL_E_SERTIMEOUT
A read timeout has occurred.
• FSL_E_SERPARITY
A parity error is detected.
• CRL_E_*

FCM FCM routines
2.2.5 Read till terminating characters
SYNTAX
Syntax [status=]fcm_serrd2(umh_cont, lin_par, in, size)
context */
parameters */
buffer */
TLS_SHORT *size; /*(M)Pointer to size */
Semantics This function reads characters from the communication port till size is
reached or one of the specified break characters is read or an error (e.g.
timeout) is occurred. The number of characters read is returned in size.
• FSL_E_READERROR
A read timeout has occurred.
• FSL_E_SERPARITY
• FSL_E_SERBUF2SMAL
Maximum buffer size is reached before a break character is seen.
• CRL_E_*

FCM routines FCM
2.2.6 Set break characters
SYNTAX
Syntax [status=]fcm_sersbr(umh_cont, lin_par, count, chars)
context */
parameters */
int count; /*(I)Number of break chars
*/
char *chars; /*(I)Break chars list */
Semantics This function modifies the break characters list. It is not needed to
detach and attach the line to make these new break characters active. The
number of break characters is truncated to the define
FCM_MAX_BREAKCHARS.
Errors This routine can not return any error.

FCM FCM routines
2.2.7 Set timeout
SYNTAX
Syntax [status=]fcm_serstm(umh_cont, lin_par, timeout)
context */
parameters */
int timeout; /*(I)New timeout value */
Semantics This function modifies the timeout. The timeout value is in msec. After
changing the timeout it is needed to detach and attach the line to make
the new timeout active.
Errors This routine can not return any error.

FCM routines FCM
2.2.8 Read setup file
SYNTAX
Syntax lin_par=fcm_sersup(dur_cont, umh_cont, line, su_file)
Arguments char *lin_par; /*(R)Pointer to line
parameters */
struct dur_context *dur_cont; /*(I)Pointer to dur
context */
struct umh_context *umh_cont; /*(M)Pointer to umh
context */
int line; /*(I)Line number to use */
char *su_file; /*(I)Setup file to use */
Semantics This function creates a line parameters block and reads from the setup
file specified in su_file the characteristics to be used for the
communication port.
First the keywords LINE are searched till the line number specified in
line is found. If line is -1 than the first LINE keyword found will be
used.
Then all parameters found before the END_LINE keyword will be read
and stored in the line parameters block.
Errors • FSL_E_SUNOLINE
The correct LINE keyword is not found in the setup file.
• FSL_E_SUILLDEVNUM
No correct information is read behind the LINE keyword.
• FSL_E_SULINEINC
No END_LINE keyword is found.
• FSL_E_SERILLBAUD
An illegal baud rate is specified.
• FSL_E_SERILLBITS
An illegal number of bits is specified.
• FSL_E_SERILLPAR
An illegal parity is specified.
• FSL_E_SERILLSTP
An illegal number of stop bits is specified.
• FSL_E_SERILLXON
An illegal XON_OFF parameter is specified.
• FSL_E_SERILLTMO
An illegal timeout is specified.
• FSL_E_SERILLWRW
An illegal write wait time is specified.
• FSL_E_SERILLTAH

FCM FCM routines
An illegal TYPE_AHEAD parameter is specified.

• FSL_E_SERNOTHEX
An illegal break character is specified.
• FSL_E_SUILLKEY
A not supported key is specified.
• FSU_E_*
FSU routine set errors.
• CRL_E_*

FCM routines FCM
2.2.9 Write number of characters
SYNTAX
Syntax [status=]fcm_serwr(umh_cont, lin_par, out, size)
context */
parameters */
char *out; /*(I)Pointer to output
buffer */
int size; /*(I)Size to write */
Semantics This function writes size characters from the output buffer to the
communication port.
• FSL_E_WRTERROR
A write error has occurred.
A write timeout has occurred.
• CRL_E_*

FCM FCM routines
2.2.10 Read number of characters after prompt
SYNTAX
Syntax [status=]fcm_serwrd1( umh_cont, lin_par, out, in,
out_size, in_size)
context */
parameters */
buffer */
buffer */
int out_size; /*(I)Output size */
TLS_SHORT *in_size; /*(M)Pointer to input
size */
Semantics This function writes out_size characters from the output buffer to the
communication port and than reads characters from the communication
port till in_size is reached or an error (e.g. timeout) is occurred. The
number of characters read is returned in in_size.
• FSL_E_WRTERROR
• FSL_E_READERROR
A write or read timeout has occurred.
• FSL_E_SERPARITY
• CRL_E_*

FCM routines FCM
2.2.11 Read till terminating characters
SYNTAX
Syntax [status=]fcm_serwrd2( umh_cont, lin_par, out, in,
out_size, in_size)
context */
parameters */
buffer */
buffer */
int out_size; /*(I)Output size */
TLS_SHORT *in_size; /*(M)Pointer to input
size */
Semantics This function writes out_size characters from the output buffer to the
communication port and than reads characters from the communication
port till in_size is reached or one of the specified break characters is
read or an error (e.g. timeout) is occurred. The number of characters read
is returned in in_size.
• FSL_E_WRTERROR
• FSL_E_READERROR
A write or read timeout has occurred.
• FSL_E_SERPARITY
• FSL_E_SERBUF2SMAL
Maximum buffer size is reached before a break character is seen.
• CRL_E_*

FCM FCM routines

Introduction FCR
3 FCR
3.1 Introduction
This chapter describes the routines present in subdirectory FCR of the
FSL. The routines residing on this directory are more or less standard C-
routines: some systems do not support these routines, others do. In order
to have all C routines available, necessary for FAST software, all
missing routines are gathered here.
Note that the routines in this subdirectory have no relation with each
other, in contrast with the routines in most of the other subdirectories.
3.2 FCR routines

FCR FCR routines
3.2.1 Case insensitive string compare
SYNTAX
Syntax cmp = stricmp (s1, s2)
Arguments int cmp; /*(R) Result of comparison of s1 and s2

neg if s1 < s2
zero if s1 = s2
pos if s1 > s2*/
char *s1, *s2; /* (I) Strings to compare*/
Semantics stricmp() is a case insensitive version of the well known strcmp()

routine. stricmp() lexicographically compares the contents of the null
terminated string s1 with the null terminated string s2. It returns a value
of type int that is:
• less than zero if s1 is less than s2
• equal to zero if s1 is equal to s2
• greater than zero if s1 is greater than s2.
In contradiction to strcmp, the two strings are compared as if all
characters of both strings were lower case.
The two strings are equal if their contents are identical. String s1 is
lexicographically less than string s2 under either of two circumstances:
1 The contents of the strings are equal up to some character position,
and at that first differing character position the character from s1 is
less than the character of s2.
2 The string s1 is shorter than the string s2, and the contents of s1 are
identical to those of s2 up to the length of s1.
Related • strnicmp()
Routines This routine compares the first n characters (case insensitive).
• fmf_strpcmp()
This routine returns the position of the first different character.

FCR routines FCR
3.2.2 Case Insensitive string compare of

N characters
SYNTAX
Syntax cmp = strnicmp (s1, s2, n)
Arguments int cmp; /*(R) Result of comparison of s1 and s2

neg if s1 < s2
zero if s1 = s2
pos if s1 > s2 */
char *s1, *s2; /* (I) Strings to compare*/
int n; /* (I) Number of characters to
compare*/
Semantics strnicmp() is a case insensitive version of the well known strncmp()

routine. strnicmp() lexicographically compares up to n characters of the
null-terminated string s1 with up to n characters of the null-terminated
string s2. It returns a value of type int that is:
• less than zero if s1 is less than s2
• equal to zero if s1 is equal to s2
• greater than zero if s1 is greater than s2.
In contrast with strncmp, the two strings are compared as if all characters
of both strings were lowercase.
In comparing the strings, the entire string is used if it contains fewer than
n characters, and otherwise only the first n characters are considered; the
characters of the string so considered are called ‘restricted contents’.
The two strings are considered equal if their restricted contents are
identical. String s1 is lexicographically less than string s2 under either
of two circumstances:
1 The restricted contents of the strings are equal up to a certain
character position, and at that first differing character position the
character from s1 is less than the character of s2.
2 The string s1 is shorter than the string s2, and the restricted contents
of s1 are identical to those of s2 up to the length of s1.
If the value of n is zero or negative, then the restricted contents of each

string are empty; in this case the two strings are considered to be equal,
and zero is returned.
Related • strnicmp()
Routines This routine is a case insensitive string compare.
• fmf_strpcmp()
This routine returns the position of the first different character.

FCR FCR routines
3.2.3 Memory compare
SYNTAX
Syntax cmp = memcmp (b1, b2, size)
Arguments int cmp; /* (R) Result of comparison of b1 and b2

neg if b1 < b2
zero if b1 = b2
pos if b1 > b2 */
char *b1, *b2;/* (I)Buffers to compare */
int size; /* (I)Nr of bytes to compare */
Semantics memcmp() compares up to n bytes of buffer b1 with up to n bytes of the

buffer s2. It returns a value of type int that is:
• less than zero if b1 is less than b2
• equal to zero if b1 is equal to b2
• greater than zero if b1 is greater than b2.
In comparing the buffers, the entire size is used if it contains fewer than
n bytes, otherwise only the first n bytes are considered; the bytes of the
string so considered are called ‘restricted contents’.
The two buffer contents are considered equal if their restricted contents
are identical. The contents of b1 is less than the contents of b2 under
either of two circumstances:
1 The restricted contents of the buffers are equal up to some byte
position, and at that first differing byte position the byte from b1 is
less than the byte of b2.
2 The size of b1 is shorter than that of b2, and the restricted contents
of b1 are identical to those of b2 up to the size of s1.
If the value of n is zero or negative, then the restricted contents of each

buffer are empty; in this case the two buffer contents are considered to
be equal, and zero is returned.

FCR routines FCR
3.2.4 Memory copy
SYNTAX
Syntax memcpy (to_buf, from_buf, size)
Arguments char *to_buf; /* (O)Buffer to copy to */

char *from_buf; /* (I)Buffer to copy from */
int size; /* (I)Number of bytes to copy */
Semantics memcpy() copies exactly n bytes from from_buf to to_buf.

FCR FCR routines
3.2.5 Initialize struct or char-buffer
SYNTAX
Syntax [adr =] memset(buf,fill_char,size)
Arguments char *adr; /* (R)Address of buf */
char *buf; /* (M)Buffer or struct to initialize */

char fill_char; /* (I)Character to fill buf */
int size; /* (I)Size of buf to fill */
Semantics memset() fills buffer with n bytes as specified by argument fill_char.

Introduction FDF
4 FDF
4.1 Introduction
In this chapter FDF is described. FDF stands for FAST SUPPORT Dis-
play Functions. With the small set of routines in FDF it is possible to
perform cursor manipulations on a display in such a way that it has the
same functionality on several systems and will be useful in many appli-
cations.
In order to get such an environment, an internal representation will be
made of what a display will be. One could think of this as a so called vir-
tual display. In this case simple routines like cursor movements will re-
sult in updating and/or manipulating such a virtual display.
The physical display will only be changed when instructed by means of
a routine call. In order to achieve this, it is necessary to provide a second
set of routines that are the same as the routines manipulating the virtual
display, but now which are able to do the “physical” work. The example
mentioned above leads in this case to a real movement of the text cursor
on the terminal display.
4.2 Categories
The routines can be divided into the following categories:
• A physical link to the output device used.
These routines perform cursor manipulation actions directly upon
the physical display. These actions are visible on the output device
when they are performed.
• A virtual environment in screen manipulation.
These routines perform cursor manipulation actions upon the
virtual display. These actions are only made visible, if a screen
update is made.
The user will typically use the virtual routines. These routines have in-
ternal calls to the physical routines.
The physical routines will only work correctly when the terminal cur-
rently used is one of the terminals supported. The supported terminal
classes are:
• FDF_DEF_TERM Force default terminal

FDF Virtual display
• FDF_DEC_VT Series DEC vt terminals

• FDF_XA_TTY Stratus terminals
• FDF_PRT All paper teletypes
• FDF_SUN_VT Sun windows
• FDF_PS2 PS/2 screen
4.3 Virtual display

A virtual display consists of three parts, which are shown in Figure 4-1.
house keeping
old display
new display
next display
Figure 4-1
The first part (house keeping) keeps track of information concerning the
current state of the new display (third part) currently being built. The old
display represents the current display as it appears on the screen. The
new display represents the display as it appears after a request to update
the screen is invoked.
In addition an arrow is added, which represents the pointer to the next
display, in case more pages are desired in the virtual display.
4.4 Data structures

The following data structures are of importance for the application pro-
grammer in order to use the display functions.

Data structures FDF
4.4.1 Virtual display representation
The data structure of the virtual display, which appears in the virtual rou-
tine descriptions, consists of the following structure:
struct fdf_v_displ
{
struct fdf_housekp info; /* See section 4.4.2
*/
struct fdf_tmp_lin mov_buf; /* Internal used */
struct fdf_display old_display; /* See section 4.4.3
*/
struct fdf_display new_display; /* See section 4.4.3
*/
}
4.4.2 House keeping representation
The data structure of the house keeping part of the virtual display con-
sists of the following structure:
struct fdf_housekp
{
short term_class; /* The terminal class */
struct fdf_characs *term_char_ptr;
/* Pointer to terminal class
characteristics (see section
4.4.4) */
int max_nr_lin; /* Maximum number of lines on
display */
int max_nr_col; /* Maximum number of columns on
display */
int cur_lin; /* Current line of virtual text
cursor */
int cur_col; /* Current column of virtual text
cursor */
TLS_BOOLEAN displ_equal; /*Both old and new display
equal */
int nr_changes; /* Number of changes between the
new and old display */
int displ_dist; /* NOT USED */
int nr_of_pages; /* Number of new display buffers
to update */
int scroll_mode; /* Scroll mode used in updating
pages */
}

FDF Data structures
4.4.3 Screen display representation
The data structure of the screen display consists of the following struc-
ture:
struct fdf_display
{
char text [FDF_MAX_LIN][FDF_MAX_COL+1];
/* Matrix containing the
characters on the display
*/
struct fdf_display *next_displ;
/* Pointer to next display */
}
4.4.4 Terminal class characteristics
The data structure of the terminal class characteristics consists of the fol-
lowing structure:
struct fdf_characs
{
short term_class; /* The terminal class */
char *clear; /* Pointer to operation to clear the
display */
char *mov; /* Pointer to operation to move the
cursor */
char *tobot; /* Pointer to operation to clear the
display down to the bottom line
*/
char *toeol; /* Pointer to operation to clear the
display to the end of line */
char *area; /* Pointer to operation to set a
scroll area for displaying */
char *inverse_attr;/* Pointer to operation to set the
display to inverse video mode */
char *normal_attr; /* Pointer to operation to set the
display to normal video mode */
int home_lin; /* Correction on home-line eq. 1 */
int home_col; /* Correction on home-column eq. 1
*/
}

FDF routines FDF
4.5 FDF routines

Physical and virtual routine names are distinguished by the letter be-
tween the two underscores. A physical routine contains a ‘p’, a virtual
one a ‘v’.

FDF FDF routines
4.5.1 Set scroll area for displaying
SYNTAX
Syntax [status=]fdf_p_area (term_char_ptr,toplin,botlin)
Arguments TLS_BOOLEAN status; /*(R)TRUE or FALSE indicating

success or error*/
/* (I)Address of the characteristics*/
int toplin; /* (I)Top line of the area*/
int botlin; /* (I)Bottom line of the area*/
Semantics This routine is used to set a display scroll area, if and only if the top line
is above the bottom line and the top and bottom line are within the phys-
ical display.
Notes If no area characteristics exist, no scroll area is set, although the TRUE
status is returned.
Errors No scroll area is set and FALSE is returned where:

• The top line is below the bottom line (toplin > botlin), or
• The top line is not within the physical display (toplin <1 OR
toplin > FDF_MAX_LIN), or
• The bottom line is not within the physical display (botlin < 1 OR
botlin > FDF_MAX_LIN).

FDF routines FDF
4.5.2 Set reverse video attribute on/off for

displaying
SYNTAX
Syntax [status=]fdf_p_attrib(term_char_ptr,attrib)
Arguments TLS_BOOLEAN status; /* (R)TRUE or FALSE indicating

success or error */
/* (I) Address of the characteristics
*/
int attrib; /* (I) Desired attribute */
Semantics This routine is used to set display reverse video on and off. Where the
video attribute is inverse (FDF_INVERSE) it is turned to normal
(FDF_NORMAL), otherwise it is turned to inverse.
Notes No action is taken when the terminal class is a printer (FDF_PRT), al-
though the TRUE status is returned.

FDF FDF routines
4.5.3 Clear the physical display down to the bottom

line
SYNTAX
Syntax [status=]fdf_p_clrbot (term_char_ptr)
Arguments TLS_BOOLEAN status;/* (R)TRUE or FALSE

indicating success or error*/
Semantics This routine is used to clear the physical display from and including the
current physical cursor position down to the last line of the display.
Notes • The current physical cursor position is left unchanged.

• No action is taken when the terminal class is a printer (FDF_PRT),
although the TRUE status is returned.
Related • fdf_p_clreol()
Routines This routine clears the physical display from the current cursor
position down to the end of line.
• fdf_p_clrscr()
This routine clears the entire physical display.

FDF routines FDF
4.5.4 Clear the physical display to the end of

line
SYNTAX
Syntax [status=]fdf_p_clreol (term_char_ptr)
Arguments TLS_BOOLEAN status; /* (R)TRUE or FALSE

indicating success or error */
/* (I) Address of the characteristics */
Semantics This routine is used to clear the physical display from and including the
current physical cursor position down to the end of the current line.
Notes • The current physical cursor position is left unchanged.

• No action is taken where the terminal class is a printer (FDF_PRT),
Related • fdf_p_clrbot()
position down to the bottom line.
• fdf_p_clrscr()
This routine clears the entire physical display.

FDF FDF routines
4.5.5 Clear the entire physical display
SYNTAX
Syntax [status=]fdf_p_clrscr (term_char_ptr)

indicating success or error*/
Semantics This routine is used to clear the entire physical display.
Notes • The physical cursor is moved to the home position.

• No action is taken in case the terminal class is a printer (FDF_PRT),
Related • fdf_p_clrbot()
• fdf_p_clreol()
This routine clears the physical display from the current cursor
• fdf_p_movcur()
This routine moves the physical text cursor to a position indicated
by the arguments. This routine is used to move the cursor to the
home position (1,1).

FDF routines FDF
4.5.6 Move the physical text cursor
SYNTAX
Syntax [status=]fdf_p_movcur (term_char_ptr, lin, col)

indicating success or error */
/* (I) Address of the characteristics
*/
int lin; /* (I) Line to move to */
int col; /* (I) Column to move to */
Semantics This routine is used to move the current physical text cursor to the posi-
tion indicated by the arguments lin and col within the physical display,
if and only if the value of term_class allows such an action.
Notes Position (1,1) will be regarded as home position (left-upper corner of the
screen).
Errors No action is taken and FALSE is returned where the position (lin, col) is
outside the physical display. This corresponds with the following cases:
• The line to move to is not within the range of line numbers (lin <
1 OR lin > FDF_MAX_LIN), or
• The column to move to is not within the range of column numbers
(col < 1 OR col > FDF_MAX_COL).

FDF FDF routines
4.5.7 Print text on physical display
SYNTAX
Syntax [status=] fdf_p_prtscr (“as printf,so format and
arguments”)
Arguments As in printf().
Semantics This routine (macro) is used to print text to the specified format and ar-
guments, as given in the well known printf statement, onto the physical
display.
Notes This routine (macro) is no more than a substitution for fdf_p_prtscr by

printf. This is done for purpose of analogy.
Related • fdf_v_prtscr()
Routines This routine prints text onto the virtual display.

FDF routines FDF
4.5.8 Get terminal characteristics
SYNTAX
Syntax [status=]t_ptr= fdf_p_termc ()
Arguments struct fdf_characs *t_ptr;/* (R)Address of the

characteristics*/
Semantics This routine returns a pointer to a struct fdf_characs in which the termi-
nal characteristics are listed accompanied by the terminal used. This rou-
tine will find the terminal class only if the terminal name currently used
is supported..
Errors If this routine fails (because the terminal class has not been found or
memory could not be allocated), NULL is returned.

FDF FDF routines
4.5.9 Clear the virtual display down to the

bottom line
SYNTAX
Syntax [status=]fdf_v_clrbot (v_displ_ptr)

success or error*/
struct fdf_v_displ *v_displ_ptr;
/* (I)Address of the virtual display*/
Semantics This routine is used to clear the new display in a virtual display pointed
by v_displ_ptr from and including the current virtual cursor position
down to the last line of the display.
First the new display is cleared to the end of line (using routine
fdf_v_clreol()), and after that the rest of the display and all consecutive
displays are cleared.
Notes The current virtual cursor position is left unchanged.
Related • fdf_v_clreol()
Routines This routine clears the virtual display from the current cursor
position down to the end of line. This routine is performed first
here.
• fdf_v_clrscr()
This routine clears the entire virtual display.

FDF routines FDF
4.5.10 Clear the virtual display to the end of line
SYNTAX
Syntax [status=]fdf_v_clreol (v_displ_ptr)

success or error */
/* (I) Address of the virtual display
*/
Semantics This routine is used to clear the new display in a virtual display pointed
to by v_displ_ptr from and including the current virtual cursor position
down to the end of line of the display.
Notes The current virtual cursor position is left unchanged.
Related • fdf_v_clrbot()
• fdf_v_clrscr()
This routine clears the entire virtual display.

FDF FDF routines
4.5.11 Clear the entire virtual display
SYNTAX
Syntax [status=]fdf_v_clrscr (v_displ_ptr)
Arguments TLS_BOOLEAN status; /*(R)TRUE or FALSE indicating

success or error*/
/*(I)Address of the virtual display*/
Semantics This routine is used to clear the entire new display of the virtual display
pointed to by v_displ_ptr.
Notes The virtual cursor is moved to the home position.
Related • fdf_v_clrbot()
• fdf_v_clreol()
This routine clears the virtual display from the current cursor

FDF routines FDF
4.5.12 Terminate the usages of the virtual display
SYNTAX
Syntax [status=] fdf_v_endscr (v_displ_ptr)

success or error */
/* (I)Address of the virtual display
*/
Semantics This routine is used to terminate the environment of the virtual display
pointed to by v_displ_ptr, and so the use of the virtual manipulating ac-
tions. It frees any space previously allocated for the virtual display us-
age, space which is (so far) pointed to by v_displ_ptr.
Notes The entire physical display is cleared.
Related • fdf_p_clr().
Routines This routine clears the entire physical display.

FDF FDF routines
4.5.13 Update the physical display
SYNTAX
Syntax [status=] fdf_v_fresh (v_displ_ptr)

success or error */
/* (I)Address of the virtual display
*/
Semantics This routine is used to update the physical display from (changes made
to the new display) in the virtual display. Any changes made to the new
display in the virtual display, pointed to by v_displ_ptr with regard to the
old display, are reproduced on the physical display in use.
Notes If the terminal class allows it, only minimal updates are performed. As
an example, on a paper version teletype the whole new display has to be
written, so no minimal updating can be taken into account here. In other
circumstances only those parts of the physical display are rewritten, in
case changes with the new display of the virtual display appear.
Related • fdf_p_movcur()
Routines This routine moves the physical text cursor to a specified position.
• fdf_p_clreol()
This routine clears the physical display from the current cursor
• fdf_p_prtscr()
This routine prints text on the physical display. It has the same
functionality as printf().

FDF routines FDF
4.5.14 Initialize the virtual display
SYNTAX
Syntax v_displ_ptr= fdf_v_init (term_type)
Arguments struct fdf_v_displ *v_displ_ptr;

/* (R) Address of the virtual display
*/
short term_type; /* (I) Short, to force a terminal to be
of a certain class. */
Semantics This routine is used to initialize a virtual display environment for the use
of subsequent actions on that virtual display. A virtual display buffer is
set up. This routine returns a pointer to the allocated virtual display
(v_displ_ptr).
First space is allocated for a pointer to a v_displ structure. Afterwards
the terminal class characteristics are pointed in the house keeping part of
the virtual display. Finally some default values are set.
Notes The physical display is cleared and the physical cursor position is set to
home.
Defaults • The virtual cursor is set on the home position.

• The number of virtual display pages is set to 1.
• The scroll mode is set to FDF_M_ONE_PAGE.
• The default terminal class is set to FDF_DEF_TERM.
• The number of changes between the new and old display is set to 0.
Errors If the initialization fails NULL is returned. This routine fails when:
• not enough space can be allocated, or
• the terminal class is not supported.
Related • fdf_p_clrscr()
Routines This routine clears the entire physical display.
• fdf_p_termc()
This routine returns a pointer in which the terminal characteristics
are listed accompanied by the terminal used.

FDF FDF routines
4.5.15 Move the virtual text cursor
SYNTAX
Syntax to_pos= fdf_v_movcur (v_displ_ptr, lin, col)
Arguments char *to_pos /* (R) Character pointer to the new

position */
/* (I) Pointer to virtual display */
int lin; /* (I) Line to move to */
int col; /* (I) Column to move to */
Semantics This routine is used to move the current virtual text cursor to the position
indicated by the arguments lin and col within the new display in the vir-
tual display pointed to by v_displ_ptr. It returns a character pointer to the
position of location (lin, col) in the new display.
Notes Where the line to move to (lin) is outside the maximum number of lines
of the display, more displays are allocated.
Errors This routine returns NULL if it fails because the line to move to (lin) is
not positive, or the column to move to (col) is not positive or it is outside
the maximum number of columns.
Example From the position returned by this routine, a fdf_v_prtscr will print text
to this new display.

FDF routines FDF
4.5.16 Print text on virtual display
SYNTAX
Syntax fdf_v_prtscr (“as sprintf,both cur_pos_buf,format and
arguments”)
Arguments As in sprintf().
Semantics This routine (macro) is used to print text according to the specified for-
mat and arguments, as given in the well known sprintf statement, onto
the virtual display.
As indicated the first argument will always be a character pointer point-
ing to the position in the new display of the virtual display on which the
text should be placed (this is the pointer returned by a previous call to
fdf_v_movcur()).
Notes This routine (macro) is no more than a substitution of fdf_v_prtscr by

sprintf.
Related • fdf_v_movcur()
Routines This routine moves the current text cursor to a specified position in
the new display of the virtual display.
• fdf_p_prtscr()
This routine prints text onto the physical display.

FDF FDF routines
4.5.17 Set the scroll mode
SYNTAX
Syntax [status=] fdf_v_scroll (v_displ_ptr, mode)
success or error */
/* (I) Address of the virtual display
*/
int mode; /* (I) Scroll mode */
Semantics This routine is used to set the desired scroll mode, when refreshing the
physical display. The possible scroll modes are:
Scroll mode
FDF_ROLL Every page begins at the home position

when calling the routine fdf_v_fresh().
FDF_SCROLL The first page begins at the home posi-

tion, other pages will call scrolling of the
screen.
FDF_N_PAGES More than one page printing is allowed

when calling the routine fdf_v_fresh().
FDF_ONE_PAGE Just the first page will be printed when

the routine fdf_v_fresh() is called.
Figure 3-2
Errors If the scroll mode, given by mode, is not one of the scroll modes men-
tioned above, then FALSE is returned.
Defaults No default scroll mode is available.

Introduction FGR
5 FGR
5.1 Introduction
This chapter describes the FGR subdirectory of the FSL library. With the
set of routines in FGR it is possible to make graphics on ASCII
terminals. In order to get such a graphic, the graphic context
environment is needed. This consists of, among others, an allocated
buffer which contains a matrix of characters. This buffer can be filled,
by calling FGR routines, to get the desired graphic.
5.2 Description
Before working with graphics some initializations need to be done by
calling the routine fgr_init(). After the initialization the graphic context
is known. Now graphic manipulation can be performed. If the graphic
context needs to be ended, this is done by calling the routine fgr_finish().
An example of what a graphic can look like is shown in Figure 5-1. This
figure shows that it is possible to put several lines in one picture.
5.3 Data structures

The following data structures are of importance for the application
programmer in order to use the graphic routines.
5.3.1 Graphic context
The data structure of the graphic context consists of:
struct fgr_context
{
char *scr; /* Pointer to screen to fill*/
char *stat_buf; /* Pointer to buffer with status
texts*/
struct fgr_line *line; /* Pointer to first line

FGR Data structures
information*/
int h_siz; /* Horizontal graphic size*/
int v_siz; /* Vertical graphic size*/
int h_ras; /* Horizontal raster size*/
int v_ras; /* Vertical raster size*/
char h_char; /* Horizontal raster character
*/
char v_char; /* Vertical raster character*/
int graf_flags; /* Graphic flags*/
int lines; /* Number of lines in graphic*/
int scr_h_siz; /* Horizontal screen size*/
int scr_v_siz; /* Vertical screen size*/
int next_line; /* Next line number to write*/
int shift_siz; /* Graphic shift size*/
int stat_siz; /* Size of each status text*/
int stat_cnt; /* Number of status texts*/
}
All types of sizes mentioned here (h_siz, v_siz, etc.) are in terms of
characters. For example the horizontal screen size (scr_h_siz) is 80
characters.
h_siz (61)
h_ras (10)
scr_v_siz (23)
v_ras (5)
scr_h_siz (79)
lines (2) graf_flags (5

h_char (’|’)
shift_siz (0) v_char (’-’)
Figure 5-1 Graphic on ASCII termina1 (1).
The parameters of the graphic context can be best illustrated with an

Data structures FGR
example. For this reason their meanings and values in between brackets
are illustrated in Figure 5-1.
The graphic flags are discussed in section 5.4.1. The graphic shift size
indicates the number of characters the graphic is shifted within the
screen.
The horizontal and vertical raster character does not concern the
characters of the axes. They can not be updated.:
5.3.2 Graphic line
The data structure of graphic lines consists of:
struct fgr_line
{
struct fgr_line *next; /* Pointer to next line info*/
char *points; /* Pointer to buffer with
graphic points*/
char *name; /* Pointer to name of line*/
char d_char; /* Display character*/
TLS_DOUBLE offset; /* Bottom line value*/
TLS_DOUBLE step; /* Step value*/
int decimals; /* Decimals to print*/
int display_format; /* Method of display, see
section 5.5*/
}
In Figure 5-3, the same example has been used as the example in Figure
5-1 in order to illustrate the parameters from the graphic line structure.
The bottom line value signifies the lower value which will be contained
in the graphic. The step value signifies how much the value changes
when the graphic line raises or decreases one line step. The step value is
calculated with the following formula
*
step = upper_line_value – bottom_line_value -
----------------------------------------------------------------------------------------------
v_siz – 1
*
bottom_line_value = offset
Figure 5-2 Graphic formula
In Figure 5-2, the upper line value is equal to the upper value which will
be contained in the graphic. Take for instance line 1 from Figure 5-3, the
bottom line value is equal to 0 and the upper line value to 200. This
results in a step value equal to 13 1/3 ((200-0)/(16-1)).Line number 2

FGR Routine flags
results in a step value equal to 26.
d_char (’o’) d_char (’=’) step (26)
name (’line 1’) offset (0) display_format (0)

name (’line number 2’) offset (10) step (13 1
Date and time routine flags (13)
Figure 5-3 Graphic on ASCII terminal (2).
The date and time routine flags, mentioned in the figure, are discussed
in section 5.4.2.
5.4 Routine flags

In some routines, flags are set for the presentation of the graphic. In the
following sections these flags are described, and an explanation of how
they need to be set in order to get the desired settings is given.
5.4.1 Graphic
The graphic routine flags are part of the graphic context structure, and
they are set in the routine fgr_grafic() (see section 5.6.4). The bits
corresponding with the integer value, which is input in the routine,
represent the following situations:

Routine flags FGR
Bit Name Meaning

0 FGR_FL_DBL_HATCH # if double point
1 FGR_FL_DBL_NUM Number if double point
2 FGR_FL_LIN_VAL Value before line
Figure 5-4
Bits 0 and 1 correspond with the situation if multiple lines are present in
the graphic. If bit 0 is set, a hatch (#) is put on places where multiple
lines cross each other. If bit 1 is set, in this situation a digit is placed
signifying how many lines are crossing.
Note that bit 0 has a higher priority than bit 1. This means that in case
bit 0 is set, the value of bit 1 is irrelevant.
Bit 2 corresponds with the situation when the graphic contains just one
line. If it is set the values are placed before the line next to the vertical
axis instead of a percentage.
If the graphic contains multiple lines, bit 2 is irrelevant. In this case a
percentage is always placed before the lines.
In Figure 5-5 an example is given of how the integer graphic routine
flags correspond with their situations. Here the flag has been given the
value 5, which corresponds with the situation in Figure 5-3.
value 5 corresponds with the bitstring:
0 0 1 0 1
FGR_FL_LIN_VAL FGR_FL_DBL_NUM FGR_FL_DBL_HATCH

is set is not set is set
Figure 5-5
With these settings it can be concluded that in the case of one line the
values are put before the line, and in the case of multiple crossing lines
a hatch (#) in the graphic corresponds with crossing lines.
Only the last three bits (0, 1 and 2) are relevant for the graphic routine
flags. This means that if the integer value is greater than 7, the effects

FGR Routine flags
concerning the flags are the same as taking the module 8 value.
5.4.2 Date and time
The date and time routine flags (datim) are related to the date/time line
below the graphic. They are set in the routine fgr_datim() (see section
5.6.1). The bits corresponding with the integer value, which is input in
the routine, represent the following situations:
Bit Name Meaning

0 FGR_TM_GMTLCT Convert GMT → LCT
1 FGR_TM_DATE Date line wanted
2 FGR_TM_START_DATE Date before time line
3 FGR_TM_DAY Day number before time
4 FGR_TM_SEC Seconds behind time
If bit 0 is set, the time that is placed in the time line is converted from
Greenwich Mean Time to Local Civil Time (see chapter FTM).
If bit 1 is set, the date/time line consists only of dates. If this bit is not
set, the date/time line consists of time intervals. The presentation of this
time depends on the settings of the other routine flags. This bit has the
highest priority above the other bits. If this bit is set, the other bits are
irrelevant.
If bit 2 is set, the date is presented before the time line. If bit 3 is set, the
day number is presented before the time. Finally the seconds can be
added on the time by setting bit 4.
In Figure 5-6, an example is given of how the date and time routine flags
correspond with their situations. Here the flag has been given the integer

Routine flags FGR
value 13, which corresponds with the situation in Figure 5-3:.
value 13 corresponds with the bitstring:
0 0 0 1 1 0 1
FGR_TM_DAY FGR_TM_DATE
is set is not set
FGR_TM_SEC FGR_TM_START_DATE FGR_TM_GMTLCT
is not set is set is set
Figure 5-6
Only the last five bits (0, 1, 2, 3 and 4) are relevant for the date and time
routine flags. This means that if the integer value is greater than 31, the
effects concerning the flags are the same as taking the module 32 value.
5.4.3 Value
Contrary to the routine flags previously mentioned, the value routine

flag consists of just one bit setting, namely:
Bit Name Meaning

0 FGR_VAL_MINMAX Show min/max only
Figure 5-7
The value routine flag is related to the value table below the graphic. It
is set in the routine fgr_value() (see section 5.6.9).
If bit 0, corresponding with the integer value, is set then only the
minimum and maximum values are shown in the value table. Just the last
bit is relevant for the value routine flag.
In Figure 5-3 the value routine flag is not set.

FGR Display formats for line structure
5.5 Display formats for line structure

The display format of a line is part of the fgr_line structure (see section
5.3.2) represented by the integer value display_format. This integer
value corresponds with one of the following names and values:
Name Value Display

FGR_DF_G_FLOAT 0 g float
FGR_DF_F_FLOAT 1 f float
FGR_DF_E_FLOAT 2 e float
FGR_DF_STATUS 3 statuses
FGR_DF_D_LONG 4 decimal long
FGR_DF_H_LONG 5 hex long
FGR_DF_H0X_LONG 6 hex long Ox
Figure 5-8
Each display format corresponds with a kind of presentation of values of

a line in the graphic. Besides the display format, the way values are
displayed depends on the number of decimals (integer decimals from the
fgr_line structure).
The status display format (FGR_DF_STATUS) means that in the line
below the graphic, instead of the numeric values, their statuses are
displayed
(see routine fgr_stat_tst).
The other formats are discussed in the following subsections. The G, F
and E float can best be illustrated by examples. In Figure 5-9 examples
are given of the three floats. The parameter decimals of the fgr_line
structure is 3.
Number
Float G float F float E float
Example a 6 6 6.000 6.000e+00
Example b 66 2/3 66.7 66.667 6.667e+01
Example c 6000 6.00e+03 6000.000 6.000e+03
Decimals = 3
Figure 5-9 Examples.

FGR routines FGR
5.5.1 G float
In the case of the G float no decimals are considered if the number is an

integer (example a). A condition for this is that the number of digits in
the number is smaller than the value of the parameter “decimals”.
Otherwise the number is put in the E float (example c, see section 5.5.3).
If the number is a real number the parameter “decimals” determines the
number of digits in the number including the decimals (example b).
In the example in Figure 5-3, the display format is set to the G float (0).
5.5.2 F float
If the display format is set to the F float, the parameter “decimals”

determines a fixed number of decimals in the number. Even in the case
of integers, zeroes are added as decimals depending on the value of the
parameter “decimals” (example a).
5.5.3 E float
A number which is set to the E float consists of a number below 10 and

a factor. The parameter “decimals” determines the number of decimals
in this number. The factor is a power of 10.Long representation
5.5.4 Long representation
There are three formats for representing long values. DF_D_LONG

displays the long as a decimal integer. DF_H_LONG displays the long
in hexadecimal. DF_H0X_LONG displays the same as DF_H_LONG
but precedes the value with ‘0x’ to indicate that the value is
hexadecimal. This notation is useful for distinguishing hexadecimal and
decimal values.
5.6 FGR routines

FGR FGR routines
5.6.1 Write date and/or time line
SYNTAX
Syntax [status=] fgr_datim (umh_cont, cont, start, interval,
flags)
Arguments TLS_BOOLEAN status; /*(R) TRUE:success */

struct umh_context *umh_cont; /*(M) Error context */

Binder10 03

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Binder10 03

Uploaded by

Copyright:

Available Formats

Instruction FAST/TOOLS FAST/TOOLS

Manual Installation Manual Linux

YOKOGAWA YOKOGAWA ELECTRIC CORPORATION

FAST/TOOLS Installation Manual Linux and Unix iii

4.3 HMI configuration .................................................... 4-4

iv FAST/TOOLS Installation Manual Linux and Unix

1.3 Supported Unix/Linux platforms

1.4 Structure of this document

FAST/TOOLS Installation Manual Linux and Unix 1-1

• Chapter 4, Setting up a HMI connection, explains how to setup a

1.5 Conventions and abbreviations

1-2 FAST/TOOLS Installation Manual Linux and Unix

2 FAST/TOOLS basic concepts

2.2 FAST/TOOLS configurations

Note: The HMI-node in a FAST/TOOLS configuration is only

FAST/TOOLS Installation Manual Linux and Unix 2-1

In a distributed configuration all the HMI nodes must be Microsoft

2.3 The FAST/TOOLS package

Tool name Description

BUS/FAST Basic support and communications

The difference between the three FAST/TOOLS node types (server,

2-2 FAST/TOOLS Installation Manual Linux and Unix

The installation of FAST/TOOLS is based upon node types. For

2.4 FAST/TOOLS for Linux and Unix

2.4.1 Supported configurations

As explained in section 2.2, the FAST/TOOLS HMI node type is only

FAST/TOOLS Installation Manual Linux and Unix 2-3

based FAST/TOOLS systems can be used as Server or as Front-end

2.4.2 Supported Unix versions

2.5 Required Disk Space

2.5.1 Item definition file

2.5.2 Item history files

2-4 FAST/TOOLS Installation Manual Linux and Unix

to take 100 bytes of disk space.

• Scan based collection/Time based storage

Use compression Store quality code Bytes used per sample

• Event based collection/Item based storage

2.5.3 Alarms history

2.5.4 Classes and object

FAST/TOOLS Installation Manual Linux and Unix 2-5

2.6 Required System Memory

Small stand alone system with Server or Front-end compo- 512

Note that additional non FAST/TOOLS applications may require

2.7 The installation procedure

2.7.1 Read the Release Notes document

2.7.2 FAST/TOOLS installation

During the installation, the FAST/TOOLS software package is

2-6 FAST/TOOLS Installation Manual Linux and Unix

2.7.3 Requesting a FAST/TOOLS licence

Next you need to request a FAST/TOOLS licence from Yokogawa. The

2.7.4 Validating FAST/TOOLS

2.7.5 Setting up you HMI connection

Next you need to setup the connection to your HMI station.

2.8 Where to get your FAST/TOOLS licence

YOKOGAWA ELECTRIC CORPORATION

FAST/TOOLS Installation Manual Linux and Unix 2-7

2-8 FAST/TOOLS Installation Manual Linux and Unix

3.2 Preparing your system

3.2.1 Create a FAST/TOOLS directory (optional)

3.2.2 Create a FAST/TOOLS user and group (optional)

FAST/TOOLS Installation Manual Linux and Unix 3-1

3.3 Installing FAST/TOOLS

The tar file is unpacked into a directory called fasttools<rel_nr>. Enter